From b1dc5b4712f6630f48f2ac5e904dfd60a551e1f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marie=20P=C3=ADchov=C3=A1?= <11718369+ManickaP@users.noreply.github.com> Date: Wed, 22 Jan 2025 10:28:36 +0100 Subject: [PATCH 1/4] [QUIC] Options classes fixes (#10828) * Listener options fixes * Windows sizes power of 2 constraint * Small fixes * Removed non-existing namespace * Added links to conceptual docs * RFC link * callback details in summary * Links to conceptual docs for options classes * Update xml/System.Net.Quic/QuicClientConnectionOptions.xml Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> * Update xml/System.Net.Quic/QuicConnection.xml Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> * Update xml/System.Net.Quic/QuicConnectionOptions.xml Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --------- Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- xml/System.Net.Quic/QuicClientConnectionOptions.xml | 1 + xml/System.Net.Quic/QuicConnection.xml | 1 + xml/System.Net.Quic/QuicConnectionOptions.xml | 12 +++++++----- xml/System.Net.Quic/QuicListener.xml | 8 +++++--- xml/System.Net.Quic/QuicListenerOptions.xml | 13 +++++++------ xml/System.Net.Quic/QuicReceiveWindowSizes.xml | 8 ++++---- xml/System.Net.Quic/QuicServerConnectionOptions.xml | 1 + xml/System.Net.Quic/QuicStream.xml | 1 + xml/ns-System.Net.Quic.Implementations.xml | 6 ------ xml/ns-System.Net.Quic.xml | 3 ++- 10 files changed, 29 insertions(+), 25 deletions(-) delete mode 100644 xml/ns-System.Net.Quic.Implementations.xml diff --git a/xml/System.Net.Quic/QuicClientConnectionOptions.xml b/xml/System.Net.Quic/QuicClientConnectionOptions.xml index ffbf9460b84..291ea2d4f4d 100644 --- a/xml/System.Net.Quic/QuicClientConnectionOptions.xml +++ b/xml/System.Net.Quic/QuicClientConnectionOptions.xml @@ -24,6 +24,7 @@ Options for client (outbound) Quic connections. To be added. + Detailed documentation for QuicClientConnectionOptions diff --git a/xml/System.Net.Quic/QuicConnection.xml b/xml/System.Net.Quic/QuicConnection.xml index 62319c6c1c1..fdac2187660 100644 --- a/xml/System.Net.Quic/QuicConnection.xml +++ b/xml/System.Net.Quic/QuicConnection.xml @@ -41,6 +41,7 @@ For QUIC prerequisites and supported operating systems, see [Platform dependenci ]]> RFC 9000: Connections + Guidelines for using QuicConnection diff --git a/xml/System.Net.Quic/QuicConnectionOptions.xml b/xml/System.Net.Quic/QuicConnectionOptions.xml index c798b59e21c..d584bcd7613 100644 --- a/xml/System.Net.Quic/QuicConnectionOptions.xml +++ b/xml/System.Net.Quic/QuicConnectionOptions.xml @@ -24,6 +24,7 @@ Shared options for both client (outbound) and server (inbound) Quic connections. To be added. + Detailed documentation for QuicConnectionOptions @@ -164,8 +165,8 @@ To use a different close error code, call System.TimeSpan - Gets or sets the interval at which keep-alive packets are sent on the connection. - The interval at which keep-alive packets are sent on the connection. The default value is , which means keep-alive packets are never sent. + Gets or sets the interval at which PING frames are sent on the connection. + The interval at which PING frames are sent on the connection. The default value is , which means PING frames are never sent. A value of means use the underlying implementation default timeout. @@ -239,11 +240,12 @@ To use a different close error code, call Optional callback that is invoked when new stream limit is released by the peer. Corresponds to receiving a MAX_STREAMS frame. - The callback values represent increments of stream limits, e.g.: current limit is 10 bidirectional streams, callback arguments notify 5 more additional bidirectional streams => 15 bidirectional streams can be opened in total at the moment. - The initial capacity is reported with the first invocation of the callback that might happen before the instance is handed out via either or . To be added. - To be added. + + The callback values represent increments of stream limits. For example, if the current limit is 10 bidirectional streams, and callback arguments notify 5 more additional bidirectional streams, then 15 bidirectional streams can be opened in total at the moment. + The initial capacity is reported with the first invocation of the callback, which might happen before the instance is handed out via either or . + diff --git a/xml/System.Net.Quic/QuicListener.xml b/xml/System.Net.Quic/QuicListener.xml index 34a5a94c001..50d6a520fcf 100644 --- a/xml/System.Net.Quic/QuicListener.xml +++ b/xml/System.Net.Quic/QuicListener.xml @@ -39,6 +39,7 @@ For QUIC prerequisites and supported operating systems, see [Platform dependenci ]]> RFC 9000: Connections + Guidelines for using QuicListener @@ -69,9 +70,10 @@ For QUIC prerequisites and supported operating systems, see [Platform dependenci ## Remarks - doesn't have a mechanism to report inbound connections that fail the handshake process. Such connections are only logged by the listener and never surfaced on the outside. - -This method propagates exceptions from , including validation errors from misconfigured , for example, . It also propagates exceptions from failed connection handshakes, for example, and . +This method also propagates exceptions from the process of establishing a connection, including: +- Errors from as with error type. +- Validation errors from misconfigured returned by as . +- Exceptions from failed connection handshakes as or . ]]> diff --git a/xml/System.Net.Quic/QuicListenerOptions.xml b/xml/System.Net.Quic/QuicListenerOptions.xml index 6d787b65425..213048a832b 100644 --- a/xml/System.Net.Quic/QuicListenerOptions.xml +++ b/xml/System.Net.Quic/QuicListenerOptions.xml @@ -22,8 +22,9 @@ - Options to provide to a . + Options to configure a new . To be added. + Detailed documentation for QuicListenerOptions @@ -65,7 +66,7 @@ Gets or sets the list of application protocols that the listener will accept. At least one must be specified. To be added. - This property is mandatory, and not setting it will result in validation errors when starting the listener. + This property is mandatory. Not setting it or not specifying at least one value will result in validation errors when starting the listener. @@ -92,9 +93,9 @@ System.Func<System.Net.Quic.QuicConnection,System.Net.Security.SslClientHelloInfo,System.Threading.CancellationToken,System.Threading.Tasks.ValueTask<System.Net.Quic.QuicServerConnectionOptions>> - Gets or sets the selection callback to choose inbound connection options dynamically. + Gets or sets the selection callback to choose inbound connection options. To be added. - To be added. + This property is mandatory. Not setting it will result in validation errors when starting the listener. @@ -115,7 +116,7 @@ System.Int32 - Gets or sets the number of connections to be held without accepting any of them, that is, the maximum size of the pending connection queue. + Gets or sets the number of connections to be held without accepting any of them. That is, the maximum size of the pending connection queue. To be added. To be added. @@ -140,7 +141,7 @@ Gets or sets the endpoint to listen on. To be added. - This property is mandatory, and not setting it will result in validation errors when starting the listener. + This property is mandatory. Not setting it will result in validation errors when starting the listener. diff --git a/xml/System.Net.Quic/QuicReceiveWindowSizes.xml b/xml/System.Net.Quic/QuicReceiveWindowSizes.xml index daf3a885273..52413125838 100644 --- a/xml/System.Net.Quic/QuicReceiveWindowSizes.xml +++ b/xml/System.Net.Quic/QuicReceiveWindowSizes.xml @@ -53,7 +53,7 @@ Gets or sets the initial flow-control window size for the connection. To be added. - To be added. + Must be non-negative power of 2. @@ -74,7 +74,7 @@ Gets or sets the initial flow-control window size for locally initiated bidirectional streams. To be added. - To be added. + Must be non-negative power of 2. @@ -95,7 +95,7 @@ Gets or sets the initial flow-control window size for remotely initiated bidirectional streams. To be added. - To be added. + Must be non-negative power of 2. @@ -116,7 +116,7 @@ Gets or sets the initial flow-control window size for (remotely initiated) unidirectional streams. To be added. - To be added. + Must be non-negative power of 2. diff --git a/xml/System.Net.Quic/QuicServerConnectionOptions.xml b/xml/System.Net.Quic/QuicServerConnectionOptions.xml index 487fef054df..d72df564def 100644 --- a/xml/System.Net.Quic/QuicServerConnectionOptions.xml +++ b/xml/System.Net.Quic/QuicServerConnectionOptions.xml @@ -24,6 +24,7 @@ Options for server (inbound) Quic connections. These options are provided by . To be added. + Detailed documentation for QuicServerConnectionOptions diff --git a/xml/System.Net.Quic/QuicStream.xml b/xml/System.Net.Quic/QuicStream.xml index 49a47857460..efaa94798e3 100644 --- a/xml/System.Net.Quic/QuicStream.xml +++ b/xml/System.Net.Quic/QuicStream.xml @@ -30,6 +30,7 @@ Apart from a stream API, also expose Closes the writing side of the stream as a single operation with the write itself.Closes the writing side of the stream.Aborts either the writing or the reading side of the stream.Returns a that will complete when the stream writing side has been closed (gracefully or abortively).Returns a that will complete when the stream reading side has been closed (gracefully or abortively). RFC 9000: Streams + Guidelines for using QuicStream diff --git a/xml/ns-System.Net.Quic.Implementations.xml b/xml/ns-System.Net.Quic.Implementations.xml deleted file mode 100644 index e1a217559e7..00000000000 --- a/xml/ns-System.Net.Quic.Implementations.xml +++ /dev/null @@ -1,6 +0,0 @@ - - - To be added. - To be added. - - diff --git a/xml/ns-System.Net.Quic.xml b/xml/ns-System.Net.Quic.xml index 2dc840c230f..7abb48641fe 100644 --- a/xml/ns-System.Net.Quic.xml +++ b/xml/ns-System.Net.Quic.xml @@ -1,6 +1,7 @@ - Contains types that implement the QUIC protocol specified by RFC 9000. + Contains types that implement the QUIC protocol specified by RFC 9000. To be added. + QUIC in .NET From 82612829bba675fb4c7e949492d9a111f1e79b05 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 22 Jan 2025 06:42:41 -0800 Subject: [PATCH 2/4] code fence command names (#10854) --- xml/System.Web.UI.WebControls/GridView.xml | 4622 ++++++++++---------- 1 file changed, 2310 insertions(+), 2312 deletions(-) diff --git a/xml/System.Web.UI.WebControls/GridView.xml b/xml/System.Web.UI.WebControls/GridView.xml index e00556e0c99..47b2bd1c825 100644 --- a/xml/System.Web.UI.WebControls/GridView.xml +++ b/xml/System.Web.UI.WebControls/GridView.xml @@ -76,510 +76,510 @@ Displays the values of a data source in a table where each column represents a field and each row represents a record. The control enables you to select, sort, and edit these items. - -## Introduction - The control is used to display the values of a data source in a table. Each column represents a field, while each row represents a record. The control supports the following features: - -- Binding to data source controls, such as . - -- Built-in sort capabilities. - -- Built-in update and delete capabilities. - -- Built-in paging capabilities. - -- Built-in row selection capabilities. - -- Programmatic access to the object model to dynamically set properties, handle events, and so on. - -- Multiple key fields. - -- Multiple data fields for the hyperlink columns. - -- Customizable appearance through themes and styles. - -- To learn about the other data-bound controls that are available in ASP.NET, see [Data-Bound Web Server Controls](https://learn.microsoft.com/previous-versions/aspnet/ms228214(v=vs.100)). - + +## Introduction + The control is used to display the values of a data source in a table. Each column represents a field, while each row represents a record. The control supports the following features: + +- Binding to data source controls, such as . + +- Built-in sort capabilities. + +- Built-in update and delete capabilities. + +- Built-in paging capabilities. + +- Built-in row selection capabilities. + +- Programmatic access to the object model to dynamically set properties, handle events, and so on. + +- Multiple key fields. + +- Multiple data fields for the hyperlink columns. + +- Customizable appearance through themes and styles. + +- To learn about the other data-bound controls that are available in ASP.NET, see [Data-Bound Web Server Controls](https://learn.microsoft.com/previous-versions/aspnet/ms228214(v=vs.100)). + > [!NOTE] -> If you are familiar with the control from the .NET Framework version 1.0, the control is the successor to the control. - - -## Column Fields - Each column in the control is represented by a object. By default, the property is set to `true`, which creates an object for each field in the data source. Each field is then rendered as a column in the control in the order that each field appears in the data source. - - You can also manually control which column fields appear in the control by setting the property to `false` and then defining your own column field collection. Different column field types determine the behavior of the columns in the control. The following table lists the different column field types that can be used. - -|Column field type|Description| -|-----------------------|-----------------| -||Displays the value of a field in a data source. This is the default column type of the control.| -||Displays a command button for each item in the control. This enables you to create a column of custom button controls, such as the Add or the Remove button.| -||Displays a check box for each item in the control. This column field type is commonly used to display fields with a Boolean value.| -||Displays predefined command buttons to perform select, edit, or delete operations.| -||Displays the value of a field in a data source as a hyperlink. This column field type enables you to bind a second field to the hyperlink's URL.| -||Displays an image for each item in the control.| -||Displays user-defined content for each item in the control according to a specified template. This column field type enables you to create a custom column field.| - - To define a column field collection declaratively, first add opening and closing `` tags between the opening and closing tags of the control. Next, list the column fields that you want to include between the opening and closing `` tags. The columns specified are added to the collection in the order listed. The collection stores all the column fields in the control and enables you to programmatically manage the column fields in the control. - - Explicitly declared column fields can be displayed in combination with automatically generated column fields. When both are used, explicitly declared column fields are rendered first, followed by the automatically generated column fields. - +> If you are familiar with the control from the .NET Framework version 1.0, the control is the successor to the control. + + +## Column Fields + Each column in the control is represented by a object. By default, the property is set to `true`, which creates an object for each field in the data source. Each field is then rendered as a column in the control in the order that each field appears in the data source. + + You can also manually control which column fields appear in the control by setting the property to `false` and then defining your own column field collection. Different column field types determine the behavior of the columns in the control. The following table lists the different column field types that can be used. + +|Column field type|Description| +|-----------------------|-----------------| +||Displays the value of a field in a data source. This is the default column type of the control.| +||Displays a command button for each item in the control. This enables you to create a column of custom button controls, such as the Add or the Remove button.| +||Displays a check box for each item in the control. This column field type is commonly used to display fields with a Boolean value.| +||Displays predefined command buttons to perform select, edit, or delete operations.| +||Displays the value of a field in a data source as a hyperlink. This column field type enables you to bind a second field to the hyperlink's URL.| +||Displays an image for each item in the control.| +||Displays user-defined content for each item in the control according to a specified template. This column field type enables you to create a custom column field.| + + To define a column field collection declaratively, first add opening and closing `` tags between the opening and closing tags of the control. Next, list the column fields that you want to include between the opening and closing `` tags. The columns specified are added to the collection in the order listed. The collection stores all the column fields in the control and enables you to programmatically manage the column fields in the control. + + Explicitly declared column fields can be displayed in combination with automatically generated column fields. When both are used, explicitly declared column fields are rendered first, followed by the automatically generated column fields. + > [!NOTE] -> Automatically generated column fields are not added to the collection. - - -## Binding to Data - The control can be bound to a data source control (such as the control or control) or to any data source collection that implements the interface, such as , , , or other collection types. Use one of the following methods to bind the control to the appropriate data source type: - -- To bind to a data source control, set the property of the control to the value of the data source control. The control automatically binds to the specified data source control and can take advantage of the data source control's capabilities to perform sorting, updating, deleting, and paging. This is the preferred method to bind to data. - -- To bind to a data source that implements the interface, programmatically set the property of the control to the data source and then call the method. When using this method, the control does not provide built-in sort, update, delete, and paging functionality. You need to provide this functionality by using the appropriate event. - - For more information about data binding, see [ASP.NET Data Access Content Map](https://learn.microsoft.com/previous-versions/aspnet/6759sth4(v=vs.100)). - +> Automatically generated column fields are not added to the collection. + + +## Binding to Data + The control can be bound to a data source control (such as the control or control) or to any data source collection that implements the interface, such as , , , or other collection types. Use one of the following methods to bind the control to the appropriate data source type: + +- To bind to a data source control, set the property of the control to the value of the data source control. The control automatically binds to the specified data source control and can take advantage of the data source control's capabilities to perform sorting, updating, deleting, and paging. This is the preferred method to bind to data. + +- To bind to a data source that implements the interface, programmatically set the property of the control to the data source and then call the method. When using this method, the control does not provide built-in sort, update, delete, and paging functionality. You need to provide this functionality by using the appropriate event. + + For more information about data binding, see [ASP.NET Data Access Content Map](https://learn.microsoft.com/previous-versions/aspnet/6759sth4(v=vs.100)). + > [!NOTE] -> This control can be used to display user input, which might include malicious client script. Check any information that is sent from a client for executable script, SQL statements, or other code before displaying it in your application. Whenever possible, it is strongly recommended that values are HTML-encoded before they are displayed in this control (the class HTML-encodes values by default). ASP.NET provides an input request validation feature to block script and HTML in user input. Validation server controls are also provided to assess user input. For more information, see [Introduction to the Validation Controls](https://learn.microsoft.com/previous-versions/dotnet/netframework-3.0/2e4hd649(v=vs.85)). - - -## Data Operations - The control provides many built-in capabilities that allow the user to sort, update, delete, select, and page through items in the control. When the control is bound to a data source control, the control can take advantage of the data source control's capabilities and provide automatic sort, update, and delete functionality. - +> This control can be used to display user input, which might include malicious client script. Check any information that is sent from a client for executable script, SQL statements, or other code before displaying it in your application. Whenever possible, it is strongly recommended that values are HTML-encoded before they are displayed in this control (the class HTML-encodes values by default). ASP.NET provides an input request validation feature to block script and HTML in user input. Validation server controls are also provided to assess user input. For more information, see [Introduction to the Validation Controls](https://learn.microsoft.com/previous-versions/dotnet/netframework-3.0/2e4hd649(v=vs.85)). + + +## Data Operations + The control provides many built-in capabilities that allow the user to sort, update, delete, select, and page through items in the control. When the control is bound to a data source control, the control can take advantage of the data source control's capabilities and provide automatic sort, update, and delete functionality. + > [!NOTE] -> The control can provide support for sorting, updating, and deleting with other types of data sources. However, you will need to provide an appropriate event handler with the implementation for these operations. - - Sorting allows the user to sort the items in the control with respect to a specific column by clicking on the column's header. To enable sorting, set the property to `true`. - - The automatic updating, deleting, and selection functionalities are enabled when a button in a or column field, with a command name of "Edit", "Delete", and "Select", respectively, is clicked. The control can automatically add a column field with an Edit, Delete, or Select button if the , , or property is set to `true`, respectively. - +> The control can provide support for sorting, updating, and deleting with other types of data sources. However, you will need to provide an appropriate event handler with the implementation for these operations. + + Sorting allows the user to sort the items in the control with respect to a specific column by clicking on the column's header. To enable sorting, set the property to `true`. + + The automatic updating, deleting, and selection functionalities are enabled when a button in a or column field, with a command name of "Edit", "Delete", and "Select", respectively, is clicked. The control can automatically add a column field with an Edit, Delete, or Select button if the , , or property is set to `true`, respectively. + > [!NOTE] -> Inserting records into the data source is not directly supported by the control. However, it is possible to insert records by using the control in conjunction with the `DetailsView` or `FormView` control. For more information, see or , respectively. - - Instead of displaying all the records in the data source at the same time, the control can automatically break the records up into pages. To enable paging, set the property to `true`. - +> Inserting records into the data source is not directly supported by the control. However, it is possible to insert records by using the control in conjunction with the `DetailsView` or `FormView` control. For more information, see or , respectively. + + Instead of displaying all the records in the data source at the same time, the control can automatically break the records up into pages. To enable paging, set the property to `true`. + > [!NOTE] -> The control is re-created on postback based on the information that is stored in . If the control includes a or a with the property set to `true`, then the property must also be set to `true` to ensure that concurrent data operations, such as updates and deletes, apply to the appropriate row. - - -## Customizing the User Interface - You can customize the appearance of the control by setting the style properties for the different parts of the control. The following table lists the different style properties. - -|Style property|Description| -|--------------------|-----------------| -||The style settings for the alternating data rows in the control. When this property is set, the data rows are displayed alternating between the settings and the settings.| -||The style settings for the row being edited in the control.| -||The style settings for the empty data row displayed in the control when the data source does not contain any records.| -||The style settings for the footer row of the control.| -||The style settings for the header row of the control.| -||The style settings for the pager row of the control.| -||The style settings for the data rows in the control. When the property is also set, the data rows are displayed alternating between the settings and the settings.| -||The style settings for the selected row in the control.| -||The style setting for the data column the data is sorted by in the control. When this style is set, the style (for example, highlighted column) is applied to cells when the data is sorted in ascending order.| -||The style setting for the data column the data is sorted by in the control. When this style is set, an arrow indicating the data is sorted ascending is placed on the header of the control when the data is sorted in ascending order.| -||The style setting for the data column the data is sorted by in the control. When this style is set, the style (for example, highlighted column) is applied to cells when the data is sorted in descending order.| -||The style setting for the data column the data is sorted by in the control. When this style is set, an arrow pointing down is placed on the header of the when the data is sorted in descending order.| - - You can also show or hide different parts of the control. The following table lists the properties that control which parts are shown or hidden. - -|Property|Description| -|--------------|-----------------| -||Shows or hides the footer section of the control.| -||Shows or hides the header section of the control.| - - -## Events - The control provides several events that you can program against. This enables you to run a custom routine whenever an event occurs. The following table lists the events that are supported by the control. - -|Event|Description| -|-----------|-----------------| -||Occurs when one of the pager buttons is clicked, but after the control handles the paging operation. This event is commonly used when you need to perform a task after the user navigates to a different page in the control.| -||Occurs when one of the pager buttons is clicked, but before the control handles the paging operation. This event is often used to cancel the paging operation.| -||Occurs when a row's Cancel button is clicked, but before the control exits edit mode. This event is often used to stop the canceling operation.| -||Occurs when a button is clicked in the control. This event is often used to perform a task when a button is clicked in the control.| -||Occurs when a new row is created in the control. This event is often used to modify the contents of a row when the row is created.| -||Occurs when a data row is bound to data in the control. This event is often used to modify the contents of a row when the row is bound to data.| -||Occurs when a row's Delete button is clicked, but after the control deletes the record from the data source. This event is often used to check the results of the delete operation.| -||Occurs when a row's Delete button is clicked, but before the control deletes the record from the data source. This event is often used to cancel the deleting operation.| -||Occurs when a row's Edit button is clicked, but before the control enters edit mode. This event is often used to cancel the editing operation.| -||Occurs when a row's Update button is clicked, but after the control updates the row. This event is often used to check the results of the update operation.| -||Occurs when a row's Update button is clicked, but before the control updates the row. This event is often used to cancel the updating operation.| -||Occurs when a row's Select button is clicked, but after the control handles the select operation. This event is often used to perform a task after a row is selected in the control.| -||Occurs when a row's Select button is clicked, but before the control handles the select operation. This event is often used to cancel the selection operation.| -||Occurs when the hyperlink to sort a column is clicked, but after the control handles the sort operation. This event is commonly used to perform a task after the user clicks a hyperlink to sort a column.| -||Occurs when the hyperlink to sort a column is clicked, but before the control handles the sort operation. This event is often used to cancel the sorting operation or to perform a custom sorting routine.| - - -## Accessibility - For information about how to configure this control so that it generates markup that conforms to accessibility standards, see [Accessibility in Visual Studio and ASP.NET](https://learn.microsoft.com/previous-versions/ms228004(v=vs.140)) and [ASP.NET Controls and Accessibility](https://learn.microsoft.com/previous-versions/ms227996(v=vs.140)). - - -## Declarative Syntax - -``` - -         -         -                 -                         -                         -                         -                         -                 -                 -                         -                         -                         -                         -                 -                 -                         -                         -                         -                         -                 -                 -                         -                         -                         -                         -                 -                 -                         -                         -                         -                         -                 -                 -                         -                         -                         -                         -                 -                 -                         -                         -                         -                         -                 -                 -                             -                             -                             -                             -                         - -                         -                         - -                         -                         - -                         -                         - -                         -                         - -                         -                         - -                         -                 -         -         -         -         - -         -         -         -         -         -         - -         -         -         - -``` - - - -## Examples - A Visual Studio Web site project with source code is available to accompany this topic: [Download](https://go.microsoft.com/fwlink/?LinkId=191882). - - The following example demonstrates how use the control to display the values from the Customers table of the AdventureWorksLT sample database in Microsoft SQL Server. The values are retrieved using a control. - +> The control is re-created on postback based on the information that is stored in . If the control includes a or a with the property set to `true`, then the property must also be set to `true` to ensure that concurrent data operations, such as updates and deletes, apply to the appropriate row. + + +## Customizing the User Interface + You can customize the appearance of the control by setting the style properties for the different parts of the control. The following table lists the different style properties. + +|Style property|Description| +|--------------------|-----------------| +||The style settings for the alternating data rows in the control. When this property is set, the data rows are displayed alternating between the settings and the settings.| +||The style settings for the row being edited in the control.| +||The style settings for the empty data row displayed in the control when the data source does not contain any records.| +||The style settings for the footer row of the control.| +||The style settings for the header row of the control.| +||The style settings for the pager row of the control.| +||The style settings for the data rows in the control. When the property is also set, the data rows are displayed alternating between the settings and the settings.| +||The style settings for the selected row in the control.| +||The style setting for the data column the data is sorted by in the control. When this style is set, the style (for example, highlighted column) is applied to cells when the data is sorted in ascending order.| +||The style setting for the data column the data is sorted by in the control. When this style is set, an arrow indicating the data is sorted ascending is placed on the header of the control when the data is sorted in ascending order.| +||The style setting for the data column the data is sorted by in the control. When this style is set, the style (for example, highlighted column) is applied to cells when the data is sorted in descending order.| +||The style setting for the data column the data is sorted by in the control. When this style is set, an arrow pointing down is placed on the header of the when the data is sorted in descending order.| + + You can also show or hide different parts of the control. The following table lists the properties that control which parts are shown or hidden. + +|Property|Description| +|--------------|-----------------| +||Shows or hides the footer section of the control.| +||Shows or hides the header section of the control.| + + +## Events + The control provides several events that you can program against. This enables you to run a custom routine whenever an event occurs. The following table lists the events that are supported by the control. + +|Event|Description| +|-----------|-----------------| +||Occurs when one of the pager buttons is clicked, but after the control handles the paging operation. This event is commonly used when you need to perform a task after the user navigates to a different page in the control.| +||Occurs when one of the pager buttons is clicked, but before the control handles the paging operation. This event is often used to cancel the paging operation.| +||Occurs when a row's Cancel button is clicked, but before the control exits edit mode. This event is often used to stop the canceling operation.| +||Occurs when a button is clicked in the control. This event is often used to perform a task when a button is clicked in the control.| +||Occurs when a new row is created in the control. This event is often used to modify the contents of a row when the row is created.| +||Occurs when a data row is bound to data in the control. This event is often used to modify the contents of a row when the row is bound to data.| +||Occurs when a row's Delete button is clicked, but after the control deletes the record from the data source. This event is often used to check the results of the delete operation.| +||Occurs when a row's Delete button is clicked, but before the control deletes the record from the data source. This event is often used to cancel the deleting operation.| +||Occurs when a row's Edit button is clicked, but before the control enters edit mode. This event is often used to cancel the editing operation.| +||Occurs when a row's Update button is clicked, but after the control updates the row. This event is often used to check the results of the update operation.| +||Occurs when a row's Update button is clicked, but before the control updates the row. This event is often used to cancel the updating operation.| +||Occurs when a row's Select button is clicked, but after the control handles the select operation. This event is often used to perform a task after a row is selected in the control.| +||Occurs when a row's Select button is clicked, but before the control handles the select operation. This event is often used to cancel the selection operation.| +||Occurs when the hyperlink to sort a column is clicked, but after the control handles the sort operation. This event is commonly used to perform a task after the user clicks a hyperlink to sort a column.| +||Occurs when the hyperlink to sort a column is clicked, but before the control handles the sort operation. This event is often used to cancel the sorting operation or to perform a custom sorting routine.| + + +## Accessibility + For information about how to configure this control so that it generates markup that conforms to accessibility standards, see [Accessibility in Visual Studio and ASP.NET](https://learn.microsoft.com/previous-versions/ms228004(v=vs.140)) and [ASP.NET Controls and Accessibility](https://learn.microsoft.com/previous-versions/ms227996(v=vs.140)). + + +## Declarative Syntax + +``` + +         +         +                 +                         +                         +                         +                         +                 +                 +                         +                         +                         +                         +                 +                 +                         +                         +                         +                         +                 +                 +                         +                         +                         +                         +                 +                 +                         +                         +                         +                         +                 +                 +                         +                         +                         +                         +                 +                 +                         +                         +                         +                         +                 +                 +                             +                             +                             +                             +                         + +                         +                         + +                         +                         + +                         +                         + +                         +                         + +                         +                         + +                         +                 +         +         +         +         + +         +         +         +         +         +         + +         +         +         + +``` + + + +## Examples + A Visual Studio Web site project with source code is available to accompany this topic: [Download](https://go.microsoft.com/fwlink/?LinkId=191882). + + The following example demonstrates how use the control to display the values from the Customers table of the AdventureWorksLT sample database in Microsoft SQL Server. The values are retrieved using a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewSimple/CS/displaycustomers.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSimple/VB/displaycustomers.aspx" id="Snippet1"::: - - The following example demonstrates how to use the control and a control so that you can edit records. - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSimple/VB/displaycustomers.aspx" id="Snippet1"::: + + The following example demonstrates how to use the control and a control so that you can edit records. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewEdit/CS/editorders.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewEdit/VB/editorders.aspx" id="Snippet1"::: - - For an example demonstrating how to access values in cells, see . - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewEdit/VB/editorders.aspx" id="Snippet1"::: + + For an example demonstrating how to access values in cells, see . + ]]> @@ -619,19 +619,19 @@ Initializes a new instance of the class. - class. To dynamically add a control to a page, create a new object, set its properties, and then add it to the collection of a container control, such as . - - - -## Examples - The following example demonstrates how to use the constructor to dynamically add a control to a page. - + class. To dynamically add a control to a page, create a new object, set its properties, and then add it to the collection of a container control, such as . + + + +## Examples + The following example demonstrates how to use the constructor to dynamically add a control to a page. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewCtor/CS/gridviewctorcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewCtor/VB/gridviewctorvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewCtor/VB/gridviewctorvb.aspx" id="Snippet1"::: + ]]> @@ -664,13 +664,13 @@ if custom paging is enabled; otherwise, . The default is . - control in chunks. The number of items on a page is determined by the property. Normally, every row in the data source is read every time the control moves to a different page. This can consume a lot of resources when the total number of items in the data source is very large. Custom paging allows you to read just the items you need for a single page from the data source. - - To enable custom paging, set both the and properties to `true`. In a handler for the event, set the property to the new page index value, set the property to the total number of items in the data source, set the data source to return only the rows needed for the current page, and call the method. The property enables the control to determine the total number of pages; this value is normally determined automatically by reading all of the items. - + control in chunks. The number of items on a page is determined by the property. Normally, every row in the data source is read every time the control moves to a different page. This can consume a lot of resources when the total number of items in the data source is very large. Custom paging allows you to read just the items you need for a single page from the data source. + + To enable custom paging, set both the and properties to `true`. In a handler for the event, set the property to the new page index value, set the property to the total number of items in the data source, set the data source to return only the rows needed for the current page, and call the method. The property enables the control to determine the total number of pages; this value is normally determined automatically by reading all of the items. + ]]> @@ -702,44 +702,44 @@ if the paging feature is enabled; otherwise, . The default is . - control can automatically break the records up into pages. If the data source supports the paging capability, the control can take advantage of that and provide built-in paging functionality. The paging feature can be used with any data source object that supports the interface or a data source that supports paging capability. - - To enable the paging feature, set the property to `true`. By default, the control displays 10 records on a page at a time. You can change the number of records displayed on a page by setting the property. To determine the total number of pages required to display the data source contents, use the property. You can determine the index of the currently displayed page by using the property. - - When paging is enabled, an additional row called the pager row is automatically displayed in the control. The pager row contains controls that allow the user to navigate to the other pages. You can control the settings of the pager row (such as the pager display mode, the number of page links to display at a time, and the pager control's text labels) by using the property. The pager row can be displayed at the top, bottom, or both the top and bottom of the control by setting the property. You can also select from one of four built-in pager display modes by setting the property. The following table describes the built-in display modes. - -|Mode|Description| -|----------|-----------------| -|`PagerButton.NextPrevious`|A set of pagination controls consisting of previous and next buttons.| -|`PagerButton.NextPreviousFirstLast`|A set of pagination controls consisting of previous, next, first, and last buttons.| -|`PagerButton.Numeric`|A set of pagination controls consisting of numbered link buttons to access pages directly. This is the default mode.| -|`PagerButton.NumericFirstLast`|A set of pagination controls consisting of numbered and first and last link buttons.| - - To control the appearance of the pager row (including its background color, font color, and position), use the property. - + control can automatically break the records up into pages. If the data source supports the paging capability, the control can take advantage of that and provide built-in paging functionality. The paging feature can be used with any data source object that supports the interface or a data source that supports paging capability. + + To enable the paging feature, set the property to `true`. By default, the control displays 10 records on a page at a time. You can change the number of records displayed on a page by setting the property. To determine the total number of pages required to display the data source contents, use the property. You can determine the index of the currently displayed page by using the property. + + When paging is enabled, an additional row called the pager row is automatically displayed in the control. The pager row contains controls that allow the user to navigate to the other pages. You can control the settings of the pager row (such as the pager display mode, the number of page links to display at a time, and the pager control's text labels) by using the property. The pager row can be displayed at the top, bottom, or both the top and bottom of the control by setting the property. You can also select from one of four built-in pager display modes by setting the property. The following table describes the built-in display modes. + +|Mode|Description| +|----------|-----------------| +|`PagerButton.NextPrevious`|A set of pagination controls consisting of previous and next buttons.| +|`PagerButton.NextPreviousFirstLast`|A set of pagination controls consisting of previous, next, first, and last buttons.| +|`PagerButton.Numeric`|A set of pagination controls consisting of numbered link buttons to access pages directly. This is the default mode.| +|`PagerButton.NumericFirstLast`|A set of pagination controls consisting of numbered and first and last link buttons.| + + To control the appearance of the pager row (including its background color, font color, and position), use the property. + > [!NOTE] -> The control automatically hides the pager row when the data source contains only one page of records. - - The control also enables you to define a custom template for the pager row. For more information about creating a custom pager row template, see . - - The control provides several events that you can use to perform a custom action when paging occurs. The following table lists the available events. - -|Event|Description| -|-----------|-----------------| -||Occurs when one of the pager buttons is clicked, but after the control handles the paging operation. This event is commonly used when you need to perform a task after the user navigates to a different page in the control.| -||Occurs when one of the pager buttons is clicked, but before the control handles the paging operation. This event is often used to cancel the paging operation.| - - - -## Examples - The following example demonstrates how to use the property to declaratively enable the paging feature in the control. - +> The control automatically hides the pager row when the data source contains only one page of records. + + The control also enables you to define a custom template for the pager row. For more information about creating a custom pager row template, see . + + The control provides several events that you can use to perform a custom action when paging occurs. The following table lists the available events. + +|Event|Description| +|-----------|-----------------| +||Occurs when one of the pager buttons is clicked, but after the control handles the paging operation. This event is commonly used when you need to perform a task after the user navigates to a different page in the control.| +||Occurs when one of the pager buttons is clicked, but before the control handles the paging operation. This event is often used to cancel the paging operation.| + + + +## Examples + The following example demonstrates how to use the property to declaratively enable the paging feature in the control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewAllowPaging/CS/gridviewallowpagingcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewAllowPaging/VB/gridviewallowpagingvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewAllowPaging/VB/gridviewallowpagingvb.aspx" id="Snippet1"::: + ]]> @@ -781,41 +781,41 @@ if the sorting feature is enabled; otherwise, . The default is . - control, the control can take advantage of the data source control's capabilities and provide automatic sorting functionality. When the control is bound to a data source by setting the property programmatically, you must provide the sorting functionality by using the event. - + control, the control can take advantage of the data source control's capabilities and provide automatic sorting functionality. When the control is bound to a data source by setting the property programmatically, you must provide the sorting functionality by using the event. + > [!NOTE] -> Different data sources have different requirements for enabling their sorting capabilities. To determine the requirements, see the documentation for the specific data source. - - To enable sorting, set the property to `true`. When sorting is enabled, the heading text for each column field with its property set is displayed as a link button. - +> Different data sources have different requirements for enabling their sorting capabilities. To determine the requirements, see the documentation for the specific data source. + + To enable sorting, set the property to `true`. When sorting is enabled, the heading text for each column field with its property set is displayed as a link button. + > [!NOTE] -> The property for an automatically generated columns field is automatically populated. If you define your own columns through the collection, you must set the property for each column; otherwise, the column will not display the link button in the header. - - Clicking the link button for a column causes the items in the control to be sorted based on the sort expression. Typically, the sort expression is simply the name of the field displayed in the column, which causes the control to sort with respect to that column. To sort by multiple fields, use a sort expression that contains a comma-separated list of field names. You can determine the sort expression that the control is applying by using the property. Clicking a column's link button repeatedly toggles the sort direction between ascending and descending order. To determine the current sort direction, use the property. - - The control provides several events that you can use to perform a custom action when sorting occurs. The following table lists the available events. - -|Event|Description| -|-----------|-----------------| -||Occurs when the hyperlink to sort a column is clicked, but after the control handles the sort operation. This event is commonly used to perform a task after the user clicks a hyperlink to sort a column.| -||Occurs when the hyperlink to sort a column is clicked, but before the control handles the sort operation. This event is often used to cancel the sorting operation or to perform a custom sorting routine.| - - - -## Examples - The following example demonstrates how to use the property to enable sorting in a control when automatically generated columns are used. - +> The property for an automatically generated columns field is automatically populated. If you define your own columns through the collection, you must set the property for each column; otherwise, the column will not display the link button in the header. + + Clicking the link button for a column causes the items in the control to be sorted based on the sort expression. Typically, the sort expression is simply the name of the field displayed in the column, which causes the control to sort with respect to that column. To sort by multiple fields, use a sort expression that contains a comma-separated list of field names. You can determine the sort expression that the control is applying by using the property. Clicking a column's link button repeatedly toggles the sort direction between ascending and descending order. To determine the current sort direction, use the property. + + The control provides several events that you can use to perform a custom action when sorting occurs. The following table lists the available events. + +|Event|Description| +|-----------|-----------------| +||Occurs when the hyperlink to sort a column is clicked, but after the control handles the sort operation. This event is commonly used to perform a task after the user clicks a hyperlink to sort a column.| +||Occurs when the hyperlink to sort a column is clicked, but before the control handles the sort operation. This event is often used to cancel the sorting operation or to perform a custom sorting routine.| + + + +## Examples + The following example demonstrates how to use the property to enable sorting in a control when automatically generated columns are used. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewAllowSorting/CS/gridviewallowsortingcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewAllowSorting/VB/gridviewallowsortingvb.aspx" id="Snippet1"::: - - The following example demonstrates how to use the property to enable sorting in a control when a collection is defined. An image is also programmatically added to the header of the column being sorted to indicate the sort direction. You must provide your own images for this sample to work. - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewAllowSorting/VB/gridviewallowsortingvb.aspx" id="Snippet1"::: + + The following example demonstrates how to use the property to enable sorting in a control when a collection is defined. An image is also programmatically added to the header of the column being sorted to indicate the sort direction. You must provide your own images for this sample to work. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewAllowSortingColumns/CS/GridViewAllowSortingColumnscs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewAllowSortingColumns/VB/GridViewAllowSortingColumnsvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewAllowSortingColumns/VB/GridViewAllowSortingColumnsvb.aspx" id="Snippet1"::: + ]]> @@ -862,25 +862,25 @@ Gets a reference to the object that enables you to set the appearance of alternating data rows in a control. A reference to the that represents the style of alternating data rows in a control. - property to control the appearance of alternating data rows in a control. When this property is set, the data rows are displayed alternating between the settings and the settings. This property is read-only; however, you can set the properties of the object it returns. The properties can be set declaratively using one of the following methods: - -- Place an attribute in the opening tag of the control in the form `Property-Subproperty`, where `Subproperty` is a property of the object (for example, `AlternatingRowStyle-ForeColor`). - -- Nest an `` element between the opening and closing tags of the control. - - The properties can also be set programmatically in the form `Property.Subproperty` (for example, `AlternatingRowStyle.ForeColor`). Common settings usually include a custom background color, foreground color, and font properties. - - - -## Examples - The following example demonstrates how to use the property to declaratively define the style for alternating data rows in a control. - + property to control the appearance of alternating data rows in a control. When this property is set, the data rows are displayed alternating between the settings and the settings. This property is read-only; however, you can set the properties of the object it returns. The properties can be set declaratively using one of the following methods: + +- Place an attribute in the opening tag of the control in the form `Property-Subproperty`, where `Subproperty` is a property of the object (for example, `AlternatingRowStyle-ForeColor`). + +- Nest an `` element between the opening and closing tags of the control. + + The properties can also be set programmatically in the form `Property.Subproperty` (for example, `AlternatingRowStyle.ForeColor`). Common settings usually include a custom background color, foreground color, and font properties. + + + +## Examples + The following example demonstrates how to use the property to declaratively define the style for alternating data rows in a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewRowStyle/CS/gridviewrowstylecs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowStyle/VB/gridviewrowstylevb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowStyle/VB/gridviewrowstylevb.aspx" id="Snippet1"::: + ]]> @@ -920,33 +920,33 @@ to automatically create bound fields for each field in the data source; otherwise, . The default is . - property is set to `true`, an object is automatically created for each field in the data source. Each field is then displayed as a column in the control in the order that the fields appear in the data source. This option provides a convenient way to display every field in the data source; however, you have limited control of how an automatically generated column field is displayed or behaves. - - Instead of letting the control automatically generate the column fields, you can manually define the column fields by setting the property to `false` and then creating a custom `Columns` collection. In addition to bound column fields, you can also display a button column field, a check box column field, a command field, a hyperlink column field, an image field, or a column field based on your own custom-defined template. - - You can also combine explicitly declared column fields with automatically generated column fields. When both are used, explicitly declared column fields are rendered first, followed by the automatically generated column fields. Automatically generated bound column fields are not added to the collection. For more information, see . - - If you set this property to `true` and set the property to a model type, controls are generated. If you do not set the property, controls are generated. If you do not want controls, you have the following options: - -- Set the property to `null` in the `Page_Load` event handler. In that case, controls are generated. - -- Write custom code to automatically generate fields by creating and assigning your own class and assigning an instance of it to the control. - -- Set to `false`. In that case, no fields are generated, and you must manually specify fields using controls such as or . - -- Do not set the property. In that case, controls are generated. - - - -## Examples - The following example demonstrates how to use the property to automatically create bound field columns in a control for each field in the data source. - + property is set to `true`, an object is automatically created for each field in the data source. Each field is then displayed as a column in the control in the order that the fields appear in the data source. This option provides a convenient way to display every field in the data source; however, you have limited control of how an automatically generated column field is displayed or behaves. + + Instead of letting the control automatically generate the column fields, you can manually define the column fields by setting the property to `false` and then creating a custom `Columns` collection. In addition to bound column fields, you can also display a button column field, a check box column field, a command field, a hyperlink column field, an image field, or a column field based on your own custom-defined template. + + You can also combine explicitly declared column fields with automatically generated column fields. When both are used, explicitly declared column fields are rendered first, followed by the automatically generated column fields. Automatically generated bound column fields are not added to the collection. For more information, see . + + If you set this property to `true` and set the property to a model type, controls are generated. If you do not set the property, controls are generated. If you do not want controls, you have the following options: + +- Set the property to `null` in the `Page_Load` event handler. In that case, controls are generated. + +- Write custom code to automatically generate fields by creating and assigning your own class and assigning an instance of it to the control. + +- Set to `false`. In that case, no fields are generated, and you must manually specify fields using controls such as or . + +- Do not set the property. In that case, controls are generated. + + + +## Examples + The following example demonstrates how to use the property to automatically create bound field columns in a control for each field in the data source. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewSimple/CS/displaycustomers.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSimple/VB/displaycustomers.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSimple/VB/displaycustomers.aspx" id="Snippet1"::: + ]]> @@ -982,34 +982,34 @@ to automatically add a field column with a Delete button for each data row; otherwise, . The default is . - control, the control can take advantage of the data source control's capabilities and provide automatic deleting functionality. - + control, the control can take advantage of the data source control's capabilities and provide automatic deleting functionality. + > [!NOTE] -> For a data source control to delete data, it must be configured to delete data. To configure a data source control to delete records, see the documentation for the specific data source control. - - When the property is set to `true`, a column (represented by a object) with a Delete button for each data row is automatically added to the control. Clicking the Delete button for a row permanently removes that record from the data source. - +> For a data source control to delete data, it must be configured to delete data. To configure a data source control to delete records, see the documentation for the specific data source control. + + When the property is set to `true`, a column (represented by a object) with a Delete button for each data row is automatically added to the control. Clicking the Delete button for a row permanently removes that record from the data source. + > [!NOTE] -> You must also set the property to identify the key field or fields of the data source for the automatic deleting feature to work. - - The control provides several events that you can use to perform a custom action when a row is deleted. The following table lists the available events. - -|Event|Description| -|-----------|-----------------| -||Occurs when a row's Delete button is clicked, but after the control deletes the record from the data source. This event is often used to check the results of the delete operation.| -||Occurs when a row's Delete button is clicked, but before the control deletes the record from the data source. This event is often used to cancel the deleting operation.| - - - -## Examples - The following example demonstrates how to use the property to enable the automatic deleting feature of a control. - +> You must also set the property to identify the key field or fields of the data source for the automatic deleting feature to work. + + The control provides several events that you can use to perform a custom action when a row is deleted. The following table lists the available events. + +|Event|Description| +|-----------|-----------------| +||Occurs when a row's Delete button is clicked, but after the control deletes the record from the data source. This event is often used to check the results of the delete operation.| +||Occurs when a row's Delete button is clicked, but before the control deletes the record from the data source. This event is often used to cancel the deleting operation.| + + + +## Examples + The following example demonstrates how to use the property to enable the automatic deleting feature of a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewEdit/CS/editorders.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewEdit/VB/editorders.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewEdit/VB/editorders.aspx" id="Snippet1"::: + ]]> @@ -1046,42 +1046,42 @@ to automatically add a field column with an Edit button for each data row; otherwise, . The default is . - control, the control can take advantage of the data source control's capabilities and provide automatic updating functionality. - + control, the control can take advantage of the data source control's capabilities and provide automatic updating functionality. + > [!NOTE] -> For a data source control to update data, it must be configured to update data. To configure a data source control to update records, see the documentation for the specific data source control. - - When the property is set to `true`, a column (represented by a object) with an Edit button for each data row is automatically added to the control. Clicking an Edit button for a row puts that row in edit mode. When a row is in edit mode, each column field in the row that is not read-only displays the appropriate input control, such as a control, for the field's data type. This allows the user to modify the field's value. - - When clicked, the Edit button is also replaced with an Update button and a Cancel button. Clicking the Update button updates the row in the data source with any value changes and returns the row to display mode. Clicking the Cancel button abandons any value changes and returns the row to display mode. - +> For a data source control to update data, it must be configured to update data. To configure a data source control to update records, see the documentation for the specific data source control. + + When the property is set to `true`, a column (represented by a object) with an Edit button for each data row is automatically added to the control. Clicking an Edit button for a row puts that row in edit mode. When a row is in edit mode, each column field in the row that is not read-only displays the appropriate input control, such as a control, for the field's data type. This allows the user to modify the field's value. + + When clicked, the Edit button is also replaced with an Update button and a Cancel button. Clicking the Update button updates the row in the data source with any value changes and returns the row to display mode. Clicking the Cancel button abandons any value changes and returns the row to display mode. + > [!NOTE] -> You can programmatically put a row in edit mode by setting the property with the index of the row. To programmatically exit edit mode, set the property to -1. - - When using the built-in updating functionality, you must set the property with a comma-separated list of field names to identify the primary key field or fields of the data source; otherwise, the built-in updating functionality will not be able to update the correct record. When using automatically generated field columns (by setting the property to `true`), the control automatically ensures that the automatically generated field columns that correspond to the field or fields specified in the property are read-only. - - You can control the appearance of a row that is in edit mode by using the property. Common settings usually include a custom background color, foreground color, and font properties. - - The control provides several events that you can use to perform a custom action when a row is updated. The following table lists the available events. - -|Event|Description| -|-----------|-----------------| -||Occurs when a row's Cancel button is clicked, but before the control cancels out of edit mode. This event is often used to stop the canceling operation.| -||Occurs when a row's Edit button is clicked, but before the control enters edit mode. This event is often used to cancel the editing operation.| -||Occurs when a row's Update button is clicked, but after the control updates the row. This event is often used to check the results of the update operation.| -||Occurs when a row's Update button is clicked, but before the control updates the row. This event is often used to cancel the updating operation.| - - - -## Examples - The following example demonstrates how to use the property to enable the automatic editing feature of the control. - +> You can programmatically put a row in edit mode by setting the property with the index of the row. To programmatically exit edit mode, set the property to -1. + + When using the built-in updating functionality, you must set the property with a comma-separated list of field names to identify the primary key field or fields of the data source; otherwise, the built-in updating functionality will not be able to update the correct record. When using automatically generated field columns (by setting the property to `true`), the control automatically ensures that the automatically generated field columns that correspond to the field or fields specified in the property are read-only. + + You can control the appearance of a row that is in edit mode by using the property. Common settings usually include a custom background color, foreground color, and font properties. + + The control provides several events that you can use to perform a custom action when a row is updated. The following table lists the available events. + +|Event|Description| +|-----------|-----------------| +||Occurs when a row's Cancel button is clicked, but before the control cancels out of edit mode. This event is often used to stop the canceling operation.| +||Occurs when a row's Edit button is clicked, but before the control enters edit mode. This event is often used to cancel the editing operation.| +||Occurs when a row's Update button is clicked, but after the control updates the row. This event is often used to check the results of the update operation.| +||Occurs when a row's Update button is clicked, but before the control updates the row. This event is often used to cancel the updating operation.| + + + +## Examples + The following example demonstrates how to use the property to enable the automatic editing feature of the control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewEdit/CS/editorders.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewEdit/VB/editorders.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewEdit/VB/editorders.aspx" id="Snippet1"::: + ]]> @@ -1125,31 +1125,31 @@ to automatically add a field column with a Select button for each data row; otherwise, . The default is . - property is set to `true`, a column (represented by a object) with a Select button for each data row is automatically added to the control. Clicking the Select button for a row selects that row in the control, which sets the property to the index of the row. To retrieve the object that represents the selected row, use the property. You can also get the primary key value for the selected record by using the property. The property contains the values of the key fields specified in the property. - + property is set to `true`, a column (represented by a object) with a Select button for each data row is automatically added to the control. Clicking the Select button for a row selects that row in the control, which sets the property to the index of the row. To retrieve the object that represents the selected row, use the property. You can also get the primary key value for the selected record by using the property. The property contains the values of the key fields specified in the property. + > [!NOTE] -> You can programmatically select a row by setting the property. To cancel the selection of a row, set the property to -1. - - You can control the appearance of the selected row by using the property. Common settings usually include a custom background color, foreground color, and font properties. - - The control provides several events that you can use to perform a custom action when a row is selected. The following table lists the available events. - -|Event|Description| -|-----------|-----------------| -||Occurs when a row's Select button is clicked, but after the control handles the select operation. This event is often used to perform a task after a row is selected in the control.| -||Occurs when a row's Select button is clicked, but before the control handles the select operation. This event is often used to cancel the selecting operation.| - - - -## Examples - The following example demonstrates how to use the property to enable the automatic selection feature of the control. - +> You can programmatically select a row by setting the property. To cancel the selection of a row, set the property to -1. + + You can control the appearance of the selected row by using the property. Common settings usually include a custom background color, foreground color, and font properties. + + The control provides several events that you can use to perform a custom action when a row is selected. The following table lists the available events. + +|Event|Description| +|-----------|-----------------| +||Occurs when a row's Select button is clicked, but after the control handles the select operation. This event is often used to perform a task after a row is selected in the control.| +||Occurs when a row's Select button is clicked, but before the control handles the select operation. This event is often used to cancel the selecting operation.| + + + +## Examples + The following example demonstrates how to use the property to enable the automatic selection feature of the control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewSelect/CS/gridviewselectcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSelect/VB/gridviewselectvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSelect/VB/gridviewselectvb.aspx" id="Snippet1"::: + ]]> @@ -1204,22 +1204,22 @@ Gets or sets the URL to an image to display in the background of a control. The URL of an image to display in the background of the control. The default is an empty string (""), which indicates that this property is not set. - property to specify the URL to an image to display in the background of a control. - + property to specify the URL to an image to display in the background of a control. + > [!NOTE] -> If the specified image is smaller than the control, the image is tiled to fill in the background. If the image is larger than the control, the image is cropped. - - - -## Examples - The following example demonstrates how to use the property to display a custom image in the background of a control. - +> If the specified image is smaller than the control, the image is tiled to fill in the background. If the image is larger than the control, the image is cropped. + + + +## Examples + The following example demonstrates how to use the property to display a custom image in the background of a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewBackImageUrl/CS/gridviewbackimageurlcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewBackImageUrl/VB/gridviewbackimageurlvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewBackImageUrl/VB/gridviewbackimageurlvb.aspx" id="Snippet1"::: + ]]> @@ -1256,24 +1256,24 @@ Gets a object that represents the bottom pager row in a control. A that represents the bottom pager row in the control. - property to `true`), an additional row called the pager row is automatically displayed in the control. The pager row contains controls that allow the user to navigate to the other pages, and can be displayed at the top, the bottom, or both the top and bottom of the control. Use the property to programmatically access the object that represents the bottom pager row in the control. - + property to `true`), an additional row called the pager row is automatically displayed in the control. The pager row contains controls that allow the user to navigate to the other pages, and can be displayed at the top, the bottom, or both the top and bottom of the control. Use the property to programmatically access the object that represents the bottom pager row in the control. + > [!NOTE] -> The property is available only after the control creates the bottom pager row in the event. - - This property is commonly used when you need to programmatically manipulate the bottom pager row, for example when adding custom content. Any modification to the property must be performed after the control has been rendered; otherwise, the control will overwrite any changes. - - - -## Examples - The following example demonstrates how to use the property to access the bottom pager row in a control. The property is used to retrieve a control from the pager row. - +> The property is available only after the control creates the bottom pager row in the event. + + This property is commonly used when you need to programmatically manipulate the bottom pager row, for example when adding custom content. Any modification to the property must be performed after the control has been rendered; otherwise, the control will overwrite any changes. + + + +## Examples + The following example demonstrates how to use the property to access the bottom pager row in a control. The property is used to retrieve a control from the pager row. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewPagerTemplate/CS/gridviewpagertemplatecs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewPagerTemplate/VB/gridviewpagertemplatevb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewPagerTemplate/VB/gridviewpagertemplatevb.aspx" id="Snippet1"::: + ]]> @@ -1313,21 +1313,21 @@ Gets or sets the text to render in an HTML caption element in a control. This property is provided to make the control more accessible to users of assistive technology devices. A string that represents the text to render in an HTML caption element in a control. The default value is an empty string (""). - property to specify the text to render in an HTML caption element in a control. The text that you specify provides assistive technology devices with a description of the table that can be used to make the control more accessible. You can also specify the position at which to render the HTML caption element by using the property. - - The value of this property, when set, can be saved automatically to a resource file by using a designer tool. For more information, see and [Globalization and Localization](https://learn.microsoft.com/previous-versions/aspnet/c6zyy3s9(v=vs.100)). - - - -## Examples - The following example demonstrates how to use the property to specify the caption for a control. - + property to specify the text to render in an HTML caption element in a control. The text that you specify provides assistive technology devices with a description of the table that can be used to make the control more accessible. You can also specify the position at which to render the HTML caption element by using the property. + + The value of this property, when set, can be saved automatically to a resource file by using a designer tool. For more information, see and [Globalization and Localization](https://learn.microsoft.com/previous-versions/aspnet/c6zyy3s9(v=vs.100)). + + + +## Examples + The following example demonstrates how to use the property to specify the caption for a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewCaption/CS/gridviewcaptioncs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewCaption/VB/gridviewcaptionvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewCaption/VB/gridviewcaptionvb.aspx" id="Snippet1"::: + ]]> @@ -1361,34 +1361,34 @@ Gets or sets the horizontal or vertical position of the HTML caption element in a control. This property is provided to make the control more accessible to users of assistive technology devices. One of the values. The default is , which uses the browser's default setting. - property to specify the horizontal or vertical position of the HTML caption element in a control. This property is provided to make the control more accessible to users of assistive technology devices. - - This property is set using one of the enumeration values. The following table lists the possible values. - -|Value|Description| -|-----------|-----------------| -|`TableCaptionAlign.Bottom`|The caption element is aligned with the bottom of the table.| -|`TableCaptionAlign.Left`|The caption element is aligned with the left side of the table.| -|`TableCaptionAlign.NotSet`|The caption element's alignment is not set.| -|`TableCaptionAlign.Right`|The caption element is aligned with the right side of the table.| -|`TableCaptionAlign.Top`|The caption element is aligned with the top of the table.| - + property to specify the horizontal or vertical position of the HTML caption element in a control. This property is provided to make the control more accessible to users of assistive technology devices. + + This property is set using one of the enumeration values. The following table lists the possible values. + +|Value|Description| +|-----------|-----------------| +|`TableCaptionAlign.Bottom`|The caption element is aligned with the bottom of the table.| +|`TableCaptionAlign.Left`|The caption element is aligned with the left side of the table.| +|`TableCaptionAlign.NotSet`|The caption element's alignment is not set.| +|`TableCaptionAlign.Right`|The caption element is aligned with the right side of the table.| +|`TableCaptionAlign.Top`|The caption element is aligned with the top of the table.| + > [!NOTE] -> When this property is set to `TableCaptionAlign.NotSet`, the default value of the browser is used. - - To specify the text for the HTML caption element, use the property. - - - -## Examples - The following example demonstrates how to use the property to specify that the caption element for a control is aligned with the top of the control. - +> When this property is set to `TableCaptionAlign.NotSet`, the default value of the browser is used. + + To specify the text for the HTML caption element, use the property. + + + +## Examples + The following example demonstrates how to use the property to specify that the caption element for a control is aligned with the top of the control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewCaption/CS/gridviewcaptioncs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewCaption/VB/gridviewcaptionvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewCaption/VB/gridviewcaptionvb.aspx" id="Snippet1"::: + ]]> The specified value is not one of the enumeration values. @@ -1424,21 +1424,21 @@ Gets or sets the amount of space between the contents of a cell and the cell's border. The amount of space, in pixels, between the contents of a cell and the cell's border. The default value is -1, which indicates that this property is not set. - property to control the spacing between the contents of a cell and the cell's border. The padding amount specified is added to all four sides of the cell. - - All cells in the same column of a control have the same width. The padding amount is applied to the widest cell and all other cells in the column have this cell width. Similarly, all cells in the same row have the same height. The padding amount is applied to the tallest cell in the row and all other cells in the row have this cell height. Individual cell sizes cannot be specified. - - - -## Examples - The following example demonstrates how to use the property to declaratively set the amount of space between the contents of a cell and the cell's border. - + property to control the spacing between the contents of a cell and the cell's border. The padding amount specified is added to all four sides of the cell. + + All cells in the same column of a control have the same width. The padding amount is applied to the widest cell and all other cells in the column have this cell width. Similarly, all cells in the same row have the same height. The padding amount is applied to the tallest cell in the row and all other cells in the row have this cell height. Individual cell sizes cannot be specified. + + + +## Examples + The following example demonstrates how to use the property to declaratively set the amount of space between the contents of a cell and the cell's border. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewCellPadding/CS/gridviewcellpaddingcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewCellPadding/VB/gridviewcellpaddingvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewCellPadding/VB/gridviewcellpaddingvb.aspx" id="Snippet1"::: + ]]> @@ -1471,22 +1471,22 @@ Gets or sets the amount of space between cells. The amount of space, in pixels, between cells. The default value is 0. - property to control the spacing between adjacent cells in the control. This spacing is applied both vertically and horizontally. The cell spacing is uniform for the entire control. Individual cell spacing between rows or columns cannot be specified. - + property to control the spacing between adjacent cells in the control. This spacing is applied both vertically and horizontally. The cell spacing is uniform for the entire control. Individual cell spacing between rows or columns cannot be specified. + > [!NOTE] -> If you set this property to a value greater than 0 and then set the property to a value that displays the cell borders, a gap is displayed between the borders of adjacent cells. In this situation, the property controls the size of the gap. - - - -## Examples - The following example demonstrates how to use the property to declaratively set the amount of space between the cells of a control. - +> If you set this property to a value greater than 0 and then set the property to a value that displays the cell borders, a gap is displayed between the borders of adjacent cells. In this situation, the property controls the size of the gap. + + + +## Examples + The following example demonstrates how to use the property to declaratively set the amount of space between the cells of a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewCellPadding/CS/gridviewcellpaddingcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewCellPadding/VB/gridviewcellpaddingvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewCellPadding/VB/gridviewcellpaddingvb.aspx" id="Snippet1"::: + ]]> @@ -1522,11 +1522,11 @@ Gets or sets the names of the data fields whose values are appended to the property value to uniquely identify each instance of a data-bound control. The names of the data fields whose values are used to uniquely identify each instance of a data-bound control when ASP.NET generates the value. - control, ASP.NET generates a unique value for each instance. You specify how the value is generated by setting the property. If you set the property to , ASP.NET will generate the by appending a suffix that is derived from the data field or fields that are specified in . If is not set, the suffix is a sequential number. - + control, ASP.NET generates a unique value for each instance. You specify how the value is generated by setting the property. If you set the property to , ASP.NET will generate the by appending a suffix that is derived from the data field or fields that are specified in . If is not set, the suffix is a sequential number. + ]]> @@ -1609,38 +1609,38 @@ Gets a collection of objects that represent the column fields in a control. A that contains all the column fields in the control. - control. The property (collection) is used to store all the explicitly declared column fields that get rendered in the control. You can also use the collection to programmatically manage the collection of column fields. - + control. The property (collection) is used to store all the explicitly declared column fields that get rendered in the control. You can also use the collection to programmatically manage the collection of column fields. + > [!NOTE] -> Explicitly declared column fields can be used in combination with automatically generated column fields. When both are used, explicitly declared column fields are rendered first, followed by the automatically generated column fields. Automatically generated column fields are not added to the collection. - - The column fields are displayed in the control in the order that the column fields appear in the collection. The following table shows the different column field classes that derive from the class and can be used in the collection. - -|Column field type|Description| -|-----------------------|-----------------| -||Displays the value of a field in a data source. This is the default column type of the control.| -||Displays a command button for each item in the control. This enables you to create a column of custom button controls, such as the Add or the Remove button.| -||Displays a check box for each item in the control. This column field type is commonly used to display fields with a Boolean value.| -||Displays predefined command buttons to perform select, edit, or delete operations.| -||Displays the value of a field in a data source as a hyperlink. This column field type enables you to bind a second field to the hyperlink's URL.| -||Displays an image for each item in the control.| -||Displays user-defined content for each item in the control, according to a specified template. This column field type enables you to create a custom column field.| - - Although you can programmatically add column fields to the collection, it is easier to list the column fields declaratively in the control and then use the property of each column field to show or hide each column field. - - If the property of a column field is set to `false`, the column is not displayed in the control and the data for the column does not make a round trip to the client. If you want the data for a column that is not visible to make a round trip, add the field name to the property. - - - -## Examples - The following example demonstrates how to populate the collection declaratively. - +> Explicitly declared column fields can be used in combination with automatically generated column fields. When both are used, explicitly declared column fields are rendered first, followed by the automatically generated column fields. Automatically generated column fields are not added to the collection. + + The column fields are displayed in the control in the order that the column fields appear in the collection. The following table shows the different column field classes that derive from the class and can be used in the collection. + +|Column field type|Description| +|-----------------------|-----------------| +||Displays the value of a field in a data source. This is the default column type of the control.| +||Displays a command button for each item in the control. This enables you to create a column of custom button controls, such as the Add or the Remove button.| +||Displays a check box for each item in the control. This column field type is commonly used to display fields with a Boolean value.| +||Displays predefined command buttons to perform select, edit, or delete operations.| +||Displays the value of a field in a data source as a hyperlink. This column field type enables you to bind a second field to the hyperlink's URL.| +||Displays an image for each item in the control.| +||Displays user-defined content for each item in the control, according to a specified template. This column field type enables you to create a custom column field.| + + Although you can programmatically add column fields to the collection, it is easier to list the column fields declaratively in the control and then use the property of each column field to show or hide each column field. + + If the property of a column field is set to `false`, the column is not displayed in the control and the data for the column does not make a round trip to the client. If you want the data for a column that is not visible to make a round trip, add the field name to the property. + + + +## Examples + The following example demonstrates how to populate the collection declaratively. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewColumnFields/CS/gridviewcolumnfieldscs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewColumnFields/VB/gridviewcolumnfieldsvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewColumnFields/VB/gridviewcolumnfieldsvb.aspx" id="Snippet1"::: + ]]> @@ -1693,11 +1693,11 @@ Gets or sets the control that will automatically generate the columns for a control that uses ASP.NET Dynamic Data features. The control that will automatically generate the columns for a control that uses ASP.NET Dynamic Data features. - control to the page. This enables ASP.NET Dynamic Data features for data-bound controls in a page, such as control. To enable an individual control to use Dynamic Data features, you must associate it with the control by calling the method during the `Page_Init` event. This method automatically sets the property to the object. - + control to the page. This enables ASP.NET Dynamic Data features for data-bound controls in a page, such as control. To enable an individual control to use Dynamic Data features, you must associate it with the control by calling the method during the `Page_Init` event. This method automatically sets the property to the object. + ]]> @@ -1732,14 +1732,14 @@ Creates an automatically generated column field. An that represents the automatically generated column field specified by the parameter. - method is used to create an automatically generated column field when the property is set to `true`. The properties of the automatically generated column field are specified through the object contained in the `fieldProperties` parameter. - + method is used to create an automatically generated column field when the property is set to `true`. The properties of the automatically generated column field are specified through the object contained in the `fieldProperties` parameter. + > [!NOTE] -> This method is used primarily by control developers to extend the control. - +> This method is used primarily by control developers to extend the control. + ]]> @@ -1773,29 +1773,29 @@ Creates the control hierarchy used to render the control using the specified data source. The number of rows created. - method is used to create the control hierarchy of the control. - + method is used to create the control hierarchy of the control. + > [!NOTE] -> This method is used primarily by control developers to extend the control. - +> This method is used primarily by control developers to extend the control. + ]]> - returns a null . - - -or- - - does not implement the interface and cannot return a . - - -or- - - is and does not implement the interface and cannot perform data source paging. - - -or- - + returns a null . + + -or- + + does not implement the interface and cannot return a . + + -or- + + is and does not implement the interface and cannot perform data source paging. + + -or- + does not implement the interface and is set to . @@ -1821,11 +1821,11 @@ Creates a new child table. Always returns a new that represents the child table. - method is a helper method used by the control to create a child table. - + method is a helper method used by the control to create a child table. + ]]> @@ -1858,14 +1858,14 @@ Creates the set of column fields used to build the control hierarchy. A that contains the fields used to build the control hierarchy. - property is set to `true`, a bound column field is automatically created for each field in the data source. Each bound column field is then displayed as a row in the control in the order that the fields appear in the data source. The method is used to create the automatically generated column fields. - + property is set to `true`, a bound column field is automatically created for each field in the data source. Each bound column field is then displayed as a row in the control in the order that the fields appear in the data source. The method is used to create the automatically generated column fields. + > [!NOTE] -> This method is used primarily by control developers to extend the control. - +> This method is used primarily by control developers to extend the control. + ]]> @@ -1893,14 +1893,14 @@ Creates the default style for the control. A that represents the style for the control. - method is used to create the default style for the control. - + method is used to create the default style for the control. + > [!NOTE] -> This method is used primarily by control developers to extend the control. - +> This method is used primarily by control developers to extend the control. + ]]> @@ -1927,11 +1927,11 @@ Creates the object that contains the arguments that get passed to the data source for processing. A that contains the arguments that get passed to the data source. - method is a helper method called by the control to create the object that contains the arguments passed to the data source. In this implementation, the object contains the arguments for paging operations. - + method is a helper method called by the control to create the object that contains the arguments passed to the data source. In this implementation, the object contains the arguments for paging operations. + ]]> @@ -1971,14 +1971,14 @@ Creates a row in the control. A created using the specified parameters. - method is used to create a row in the control. - + method is used to create a row in the control. + > [!NOTE] -> This method is used primarily by control developers to extend the control. A data-bound control automatically generates the rows needed to display the target data. - +> This method is used primarily by control developers to extend the control. A data-bound control automatically generates the rows needed to display the target data. + ]]> @@ -2006,23 +2006,23 @@ Binds the data source to the control. This method cannot be inherited. - method to bind data from a data source to the control. This method resolves all data-binding expressions in the active template of the control. - - The method is called automatically if the property of the control refers to a valid data source control. - - Instead of manually calling the method, you can use model binding with your control by setting the property to the name of a method that returns data for the . The is then automatically populated with the data that is returned from the select method. Model binding can simplify your code for working with data. For more information, see [Model Binding and Web Forms](/aspnet/web-forms/overview/presenting-and-managing-data/model-binding/retrieving-data). - - - -## Examples - The following example demonstrates how to use the method to bind a data source to a control. - + method to bind data from a data source to the control. This method resolves all data-binding expressions in the active template of the control. + + The method is called automatically if the property of the control refers to a valid data source control. + + Instead of manually calling the method, you can use model binding with your control by setting the property to the name of a method that returns data for the . The is then automatically populated with the data that is returned from the select method. Model binding can simplify your code for working with data. For more information, see [Model Binding and Web Forms](/aspnet/web-forms/overview/presenting-and-managing-data/model-binding/retrieving-data). + + + +## Examples + The following example demonstrates how to use the method to bind a data source to a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewDataBind/CS/gridviewdatabindcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewDataBind/VB/gridviewdatabindvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewDataBind/VB/gridviewdatabindvb.aspx" id="Snippet1"::: + ]]> @@ -2066,36 +2066,36 @@ Gets or sets an array that contains the names of the primary key fields for the items displayed in a control. An array that contains the names of the primary key fields for the items displayed in a control. - property to specify the field or fields that represent the primary key of the data source. You should only set this property to the field or fields that are required to uniquely identify each row; for example, the ID column if an integer value uniquely identifies each row. You must set the property in order for the automatic update and delete features of the control to work. The values of these key fields are passed to the data source control in order to specify the row to update or delete. - - If you need to retrieve the data key value when updating or deleting a row, use the `Keys` property of either the or class. For example, `e.Keys[0]` holds the value of the first data key in a or event handler. - - If you need to retrieve the data key value when a row is selected, use the property. - - When the property is set, the control automatically populates its collection with the values from the specified field or fields, which provides a convenient way to access the primary keys of each row. - + property to specify the field or fields that represent the primary key of the data source. You should only set this property to the field or fields that are required to uniquely identify each row; for example, the ID column if an integer value uniquely identifies each row. You must set the property in order for the automatic update and delete features of the control to work. The values of these key fields are passed to the data source control in order to specify the row to update or delete. + + If you need to retrieve the data key value when updating or deleting a row, use the `Keys` property of either the or class. For example, `e.Keys[0]` holds the value of the first data key in a or event handler. + + If you need to retrieve the data key value when a row is selected, use the property. + + When the property is set, the control automatically populates its collection with the values from the specified field or fields, which provides a convenient way to access the primary keys of each row. + > [!NOTE] -> The control stores these key field values in the control state. If these values contain sensitive information, it is strongly recommended that you enable view-state encryption by setting the property to `ViewStateEncryptionMode.Always`. - - When you use automatically generated field columns (by setting the property to `true`), the control makes sure that the columns that correspond to the field or fields specified in the property are read-only. - - If the property of a column field is set to `false`, the column is not displayed in the control and the data for the column does not make a round trip to the client. If you want the data for a column that is not visible to be available to the client, add the field name to the property. - - - -## Examples - The following example demonstrates how to use the property to specify the key field of the data source. In the example, the `DataKeyNames` attribute of the `GridView` element in markup specifies two key fields by using a comma to separate the names. To run this example, create a Web site that has the following: - -- A connection to the AdventureWorksLT sample database and a connection string that is named `AdventureWorksLTConnectionString`. For information about how to set up the AdventureWorksLT sample database, see [How to: Set Up an AdventureWorksLT Sample Database for ASP.NET Development](https://learn.microsoft.com/previous-versions/dd410121(v=vs.140)). - -- A LINQ-to-SQL data context class that is named `AdventureWorksLTDataClassesDataContext`. The data context must have a class for the SalesOrderDetails table. For information about how to create LINQ-to-SQL classes, see [LINQ to SQL](/dotnet/framework/data/adonet/sql/linq/). - +> The control stores these key field values in the control state. If these values contain sensitive information, it is strongly recommended that you enable view-state encryption by setting the property to `ViewStateEncryptionMode.Always`. + + When you use automatically generated field columns (by setting the property to `true`), the control makes sure that the columns that correspond to the field or fields specified in the property are read-only. + + If the property of a column field is set to `false`, the column is not displayed in the control and the data for the column does not make a round trip to the client. If you want the data for a column that is not visible to be available to the client, add the field name to the property. + + + +## Examples + The following example demonstrates how to use the property to specify the key field of the data source. In the example, the `DataKeyNames` attribute of the `GridView` element in markup specifies two key fields by using a comma to separate the names. To run this example, create a Web site that has the following: + +- A connection to the AdventureWorksLT sample database and a connection string that is named `AdventureWorksLTConnectionString`. For information about how to set up the AdventureWorksLT sample database, see [How to: Set Up an AdventureWorksLT Sample Database for ASP.NET Development](https://learn.microsoft.com/previous-versions/dd410121(v=vs.140)). + +- A LINQ-to-SQL data context class that is named `AdventureWorksLTDataClassesDataContext`. The data context must have a class for the SalesOrderDetails table. For information about how to create LINQ-to-SQL classes, see [LINQ to SQL](/dotnet/framework/data/adonet/sql/linq/). + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewEdit/CS/editorders.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewEdit/VB/editorders.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewEdit/VB/editorders.aspx" id="Snippet1"::: + ]]> @@ -2135,22 +2135,22 @@ Gets a collection of objects that represent the data key value of each row in a control. A that contains the data key of each row in a control. - property is set, the control automatically creates a object for each row in the control. The object contains the values of the field or fields specified in the property. The objects are then added to the control's collection. Use the property to retrieve the object for a specific data row in the control. - + property is set, the control automatically creates a object for each row in the control. The object contains the values of the field or fields specified in the property. The objects are then added to the control's collection. Use the property to retrieve the object for a specific data row in the control. + > [!NOTE] -> You can use the property to retrieve the object for the currently selected row. You can also use the property to retrieve the data key value for the currently selected row directly. - - - -## Examples - The following example demonstrates how to use the property to determine the data key value of the selected row in a control. - +> You can use the property to retrieve the object for the currently selected row. You can also use the property to retrieve the data key value for the currently selected row directly. + + + +## Examples + The following example demonstrates how to use the property to determine the data key value of the selected row in a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewDataKeys/CS/gridviewdatakeyscs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewDataKeys/VB/gridviewdatakeysvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewDataKeys/VB/gridviewdatakeysvb.aspx" id="Snippet1"::: + ]]> @@ -2190,13 +2190,13 @@ Gets or sets the name of the method to call in order to delete data. The name of the method. - @@ -2224,19 +2224,19 @@ The index of the row to delete. Deletes the record at the specified index from the data source. - method to programmatically delete the record at the specified index from the data source. This method is commonly used when you need to delete a record from outside of the control, such as from a different control on the page. Calling this method also raises the and events. - - - -## Examples - The following example demonstrates how to use the method to programmatically delete a record in a control. - + method to programmatically delete the record at the specified index from the data source. This method is commonly used when you need to delete a record from outside of the control, such as from a different control on the page. Calling this method also raises the and events. + + + +## Examples + The following example demonstrates how to use the method to programmatically delete a record in a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewDeleteRow/CS/GridViewDeleteRowcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewDeleteRow/VB/GridViewDeleteRowvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewDeleteRow/VB/GridViewDeleteRowvb.aspx" id="Snippet1"::: + ]]> The control is not bound to a data source control. @@ -2277,33 +2277,33 @@ Gets or sets the index of the row to edit. The zero-based index of the row to edit. The default is -1, which indicates that no row is being edited. - control to open in edit mode for a specific row the first time that the page is displayed. To do this, you can set the property in the handler for the event of the class or of the control. - -- You want to know which row was edited after the row was updated. To do this, you can retrieve the row index from the property in the event handler. - -- You are binding the control to a data source by setting the property programmatically. In this case you must set the property in the and event handlers. - - If you set the property after a postback or in handlers for events that are raised later than the event, the control might not enter edit mode for the specified row. If you read the value of this property in other event handlers, the index is not guaranteed to reflect the row that is being edited. - - To determine which row the user has clicked an **Edit** button or hyperlink in before the control enters edit mode, you can retrieve the row index from the property of the object in the event handler. - - To prevent the control from entering edit mode after a user has clicked an **Edit** button or hyperlink, set the property of the object to `true` in the event handler. - - - -## Examples - The following example demonstrates how to use the property to determine which row was updated after it was edited in a control. A message is displayed to indicate that the update was successful. - + control to open in edit mode for a specific row the first time that the page is displayed. To do this, you can set the property in the handler for the event of the class or of the control. + +- You want to know which row was edited after the row was updated. To do this, you can retrieve the row index from the property in the event handler. + +- You are binding the control to a data source by setting the property programmatically. In this case you must set the property in the and event handlers. + + If you set the property after a postback or in handlers for events that are raised later than the event, the control might not enter edit mode for the specified row. If you read the value of this property in other event handlers, the index is not guaranteed to reflect the row that is being edited. + + To determine which row the user has clicked an **Edit** button or hyperlink in before the control enters edit mode, you can retrieve the row index from the property of the object in the event handler. + + To prevent the control from entering edit mode after a user has clicked an **Edit** button or hyperlink, set the property of the object to `true` in the event handler. + + + +## Examples + The following example demonstrates how to use the property to determine which row was updated after it was edited in a control. A message is displayed to indicate that the update was successful. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewRows/CS/gridviewrowscs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRows/VB/gridviewrowsvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRows/VB/gridviewrowsvb.aspx" id="Snippet1"::: + ]]> The specified index is less than -1. @@ -2349,25 +2349,25 @@ Gets a reference to the object that enables you to set the appearance of the row selected for editing in a control. A reference to the that represents the style of the row being edited in a control. - property to control the appearance of the row being edited in a control. This property is read-only; however, you can set the properties of the object it returns. The properties can be set declaratively using one of the following methods: - -- Place an attribute in the opening tag of the control in the form `Property-Subproperty`, where `Subproperty` is a property of the object (for example, `EditRowStyle-ForeColor`). - -- Nest an `` element between the opening and closing tags of the control. - - The properties can also be set programmatically in the form `Property.Subproperty` (for example, `EditRowStyle.ForeColor`). Common settings usually include a custom background color, foreground color, and font properties. - - - -## Examples - The following example demonstrates how to use the property to define a custom style for the row being edited in a control. - + property to control the appearance of the row being edited in a control. This property is read-only; however, you can set the properties of the object it returns. The properties can be set declaratively using one of the following methods: + +- Place an attribute in the opening tag of the control in the form `Property-Subproperty`, where `Subproperty` is a property of the object (for example, `EditRowStyle-ForeColor`). + +- Nest an `` element between the opening and closing tags of the control. + + The properties can also be set programmatically in the form `Property.Subproperty` (for example, `EditRowStyle.ForeColor`). Common settings usually include a custom background color, foreground color, and font properties. + + + +## Examples + The following example demonstrates how to use the property to define a custom style for the row being edited in a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewEditRowStyle/CS/gridvieweditrowstylecs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewEditRowStyle/VB/gridvieweditrowstylevb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewEditRowStyle/VB/gridvieweditrowstylevb.aspx" id="Snippet1"::: + ]]> @@ -2414,25 +2414,25 @@ Gets a reference to the object that enables you to set the appearance of the empty data row rendered when a control is bound to a data source that does not contain any records. A reference to the that enables you to set the appearance of the null row. - property to control the appearance of the null row in a control. The null row is displayed when the data source that is bound to the control does not contain any records. This property is read-only; however, you can set the properties of the object it returns. The properties can be set declaratively using one of the following methods: - -- Place an attribute in the opening tag of the control in the form `Property-Subproperty`, where `Subproperty` is a property of the object (for example, `EmptyDataRowStyle-ForeColor`). - -- Nest an `` element between the opening and closing tags of the control. - - The properties can also be set programmatically in the form `Property.Subproperty` (for example, `EmptyDataRowStyle.ForeColor`). Common settings usually include a custom background color, foreground color, and font properties. - - - -## Examples - The following example demonstrates how to set the property declaratively to specify a light blue background and a red font for the null row. - + property to control the appearance of the null row in a control. The null row is displayed when the data source that is bound to the control does not contain any records. This property is read-only; however, you can set the properties of the object it returns. The properties can be set declaratively using one of the following methods: + +- Place an attribute in the opening tag of the control in the form `Property-Subproperty`, where `Subproperty` is a property of the object (for example, `EmptyDataRowStyle-ForeColor`). + +- Nest an `` element between the opening and closing tags of the control. + + The properties can also be set programmatically in the form `Property.Subproperty` (for example, `EmptyDataRowStyle.ForeColor`). Common settings usually include a custom background color, foreground color, and font properties. + + + +## Examples + The following example demonstrates how to set the property declaratively to specify a light blue background and a red font for the null row. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewNullRowTemplate/CS/gridviewnullrowtemplatecs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewNullRowTemplate/VB/gridviewnullrowtemplatevb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewNullRowTemplate/VB/gridviewnullrowtemplatevb.aspx" id="Snippet1"::: + ]]> @@ -2493,26 +2493,26 @@ Gets or sets the user-defined content for the empty data row rendered when a control is bound to a data source that does not contain any records. A that contains the custom content for the empty data row. The default value is , which indicates that this property is not set. - control when the data source that is bound to the control does not contain any records. You can define your own custom user interface (UI) for the empty data row by using the property. - - To specify a custom template for the empty data row, first place `` tags between the opening and closing tags of the control. You can then list the contents of the template between the opening and closing `` tags. To control the style of the empty data row, use the property. Alternatively, you can use the built-in UI for the empty data row by setting the property instead of this property. - - For information about how to programmatically access controls that you declare in an empty data template, see [How to: Access Server Controls by ID](https://learn.microsoft.com/previous-versions/aspnet/y81z8326(v=vs.100)). - + control when the data source that is bound to the control does not contain any records. You can define your own custom user interface (UI) for the empty data row by using the property. + + To specify a custom template for the empty data row, first place `` tags between the opening and closing tags of the control. You can then list the contents of the template between the opening and closing `` tags. To control the style of the empty data row, use the property. Alternatively, you can use the built-in UI for the empty data row by setting the property instead of this property. + + For information about how to programmatically access controls that you declare in an empty data template, see [How to: Access Server Controls by ID](https://learn.microsoft.com/previous-versions/aspnet/y81z8326(v=vs.100)). + > [!NOTE] -> If both the and properties are set, the property takes precedence. - - - -## Examples - The following example demonstrates how to define a custom template for the empty data row displayed when a control is bound to a data source that does not contain any records. - +> If both the and properties are set, the property takes precedence. + + + +## Examples + The following example demonstrates how to define a custom template for the empty data row displayed when a control is bound to a data source that does not contain any records. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewNullRowTemplate/CS/gridviewnullrowtemplatecs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewNullRowTemplate/VB/gridviewnullrowtemplatevb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewNullRowTemplate/VB/gridviewnullrowtemplatevb.aspx" id="Snippet1"::: + ]]> @@ -2551,24 +2551,24 @@ Gets or sets the text to display in the empty data row rendered when a control is bound to a data source that does not contain any records. The text to display in the empty data row. The default is an empty string (""), which indicates that this property is not set. - control when the data source that is bound to the control does not contain any records. Use the property to specify the text to display in the empty data row. To control the style of the empty data row, use the property. Alternatively, you can define your own custom user interface (UI) for the empty data row by setting the property instead of this property. - + control when the data source that is bound to the control does not contain any records. Use the property to specify the text to display in the empty data row. To control the style of the empty data row, use the property. Alternatively, you can define your own custom user interface (UI) for the empty data row by setting the property instead of this property. + > [!NOTE] -> If both the and properties are set, the property takes precedence. - - The value of this property, when set, can be saved automatically to a resource file by using a designer tool. For more information, see and [Globalization and Localization](https://learn.microsoft.com/previous-versions/aspnet/c6zyy3s9(v=vs.100)). - - - -## Examples - The following example demonstrates how to use the property to specify the text to display in the empty data row. - +> If both the and properties are set, the property takes precedence. + + The value of this property, when set, can be saved automatically to a resource file by using a designer tool. For more information, see and [Globalization and Localization](https://learn.microsoft.com/previous-versions/aspnet/c6zyy3s9(v=vs.100)). + + + +## Examples + The following example demonstrates how to use the property to specify the text to display in the empty data row. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/gridviewemptydatatext/CS/gridviewemptydatatextcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/gridviewemptydatatext/VB/gridviewemptydatatextvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/gridviewemptydatatext/VB/gridviewemptydatatextvb.aspx" id="Snippet1"::: + ]]> @@ -2634,11 +2634,11 @@ if the row selection is based on data-key values; otherwise, . The default value is . - @@ -2670,24 +2670,24 @@ to use client-side callbacks for sorting and paging operations; otherwise, . The default is . - control posts back to the server to perform the operation. When the property is set to `true`, a service is called on the client to perform sorting and paging operations, which eliminates the need to post back to the server. - + control posts back to the server to perform the operation. When the property is set to `true`, a service is called on the client to perform sorting and paging operations, which eliminates the need to post back to the server. + > [!NOTE] -> Not all browsers support this feature. To determine whether a browser supports this feature, use the property. - - All columns in the collection must support callbacks for this feature to work. If the collection contains a column that does not support callbacks, such as , a exception is raised. - - - -## Examples - The following example demonstrates how to use the property to enable client-side callbacks for sorting and paging operations. - +> Not all browsers support this feature. To determine whether a browser supports this feature, use the property. + + All columns in the collection must support callbacks for this feature to work. If the collection contains a column that does not support callbacks, such as , a exception is raised. + + + +## Examples + The following example demonstrates how to use the property to enable client-side callbacks for sorting and paging operations. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/gridviewenablesortingandpagingcallbacks/CS/gridviewenablesortingandpagingcallbackscs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/gridviewenablesortingandpagingcallbacks/VB/gridviewenablesortingandpagingcallbacksvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/gridviewenablesortingandpagingcallbacks/VB/gridviewenablesortingandpagingcallbacksvb.aspx" id="Snippet1"::: + ]]> The collection contains a column that does not support callbacks, such as . @@ -2727,11 +2727,11 @@ to include the primary key field or fields; otherwise, . Retrieves the values of each field declared within the specified row and stores them in the specified object. - method is a helper method called by the control to retrieve the values of each field declared within the row specified by the `row` parameter. You can specify whether the extracted values include read-only fields and key fields by using the `includeReadOnlyFields` and `includePrimaryKey` parameters, respectively. - + method is a helper method called by the control to retrieve the values of each field declared within the row specified by the `row` parameter. You can specify whether the extracted values include read-only fields and key fields by using the `includeReadOnlyFields` and `includePrimaryKey` parameters, respectively. + ]]> @@ -2771,24 +2771,24 @@ Gets a object that represents the footer row in a control. A that represents the footer row in a control. - property to programmatically access the object that represents the footer row in a control. - + property to programmatically access the object that represents the footer row in a control. + > [!NOTE] -> The property is available only after the control creates the footer row in the event. - - This property is commonly used when you need to programmatically manipulate the footer row, for example when adding custom content. Any modification to the property must be performed after the control has been rendered; otherwise, the control will overwrite any changes. - - - -## Examples - The following example demonstrates how to use the property to display the sort direction in the footer row. - +> The property is available only after the control creates the footer row in the event. + + This property is commonly used when you need to programmatically manipulate the footer row, for example when adding custom content. Any modification to the property must be performed after the control has been rendered; otherwise, the control will overwrite any changes. + + + +## Examples + The following example demonstrates how to use the property to display the sort direction in the footer row. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/gridviewfooterrow/CS/gridviewfooterrowcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/gridviewfooterrow/VB/gridviewfooterrowvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/gridviewfooterrow/VB/gridviewfooterrowvb.aspx" id="Snippet1"::: + ]]> @@ -2836,25 +2836,25 @@ Gets a reference to the object that enables you to set the appearance of the footer row in a control. A reference to the that represents the style of the footer row in a control. - property to control the appearance of the footer row in a control. This property is read-only; however, you can set the properties of the object it returns. The properties can be set declaratively using one of the following methods: - -- Place an attribute in the opening tag of the control in the form `Property-Subproperty`, where `Subproperty` is a property of the object (for example, `FooterStyle-ForeColor`). - -- Nest a `` element between the opening and closing tags of the control. - - The properties can also be set programmatically in the form `Property.Subproperty` (for example, `FooterStyle.ForeColor`). Common settings usually include a custom background color, foreground color, and font properties. - - - -## Examples - The following example demonstrates how to use the property to define a custom style for the footer row in a control. - + property to control the appearance of the footer row in a control. This property is read-only; however, you can set the properties of the object it returns. The properties can be set declaratively using one of the following methods: + +- Place an attribute in the opening tag of the control in the form `Property-Subproperty`, where `Subproperty` is a property of the object (for example, `FooterStyle-ForeColor`). + +- Nest a `` element between the opening and closing tags of the control. + + The properties can also be set programmatically in the form `Property.Subproperty` (for example, `FooterStyle.ForeColor`). Common settings usually include a custom background color, foreground color, and font properties. + + + +## Examples + The following example demonstrates how to use the property to define a custom style for the footer row in a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewShowHeader/CS/gridviewshowheadercs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewShowHeader/VB/gridviewshowheadervb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewShowHeader/VB/gridviewshowheadervb.aspx" id="Snippet1"::: + ]]> @@ -2888,11 +2888,11 @@ Returns the result of a callback event that targets a control. The results of the callback. - control implements the interface and uses the to asynchronously retrieve data and the method to return the retrieved data to the control. - + control implements the interface and uses the to asynchronously retrieve data and the method to return the retrieved data to the control. + ]]> @@ -2923,11 +2923,11 @@ Creates the callback script for a button that performs a sorting operation. The callback script for a button that performs a sorting operation. - method is a helper method used by the control to create the callback script for a button that performs a sorting operation. - + method is a helper method used by the control to create the callback script for a button that performs a sorting operation. + ]]> @@ -2959,26 +2959,26 @@ Gets or sets the gridline style for a control. One of the values. The default is . - property to specify the gridline style for a control. The following table lists the available styles. - -|Style|Description| -|-----------|-----------------| -|`GridLines.None`|No gridlines are displayed.| -|`GridLines.Horizontal`|Displays the horizontal gridlines only.| -|`GridLines.Vertical`|Displays the vertical gridlines only.| -|`GridLines.Both`|Displays both the horizontal and vertical gridlines.| - - - -## Examples - The following example demonstrates how to use the property to hide the gridlines in a control. - + property to specify the gridline style for a control. The following table lists the available styles. + +|Style|Description| +|-----------|-----------------| +|`GridLines.None`|No gridlines are displayed.| +|`GridLines.Horizontal`|Displays the horizontal gridlines only.| +|`GridLines.Vertical`|Displays the vertical gridlines only.| +|`GridLines.Both`|Displays both the horizontal and vertical gridlines.| + + + +## Examples + The following example demonstrates how to use the property to hide the gridlines in a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewGridLines/CS/gridviewgridlinescs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewGridLines/VB/gridviewgridlinesvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewGridLines/VB/gridviewgridlinesvb.aspx" id="Snippet1"::: + ]]> @@ -3016,24 +3016,24 @@ Gets a object that represents the header row in a control. A that represents the header row in a control. - property to programmatically access the object that represents the header row in a control. - + property to programmatically access the object that represents the header row in a control. + > [!NOTE] -> The property is available only after the control creates the header row in the event. - - This property is commonly used when you need to programmatically manipulate the header row, for example, when adding custom content. Any modification to the property must be performed after the control has been rendered; otherwise, the control will overwrite any changes. - - - -## Examples - The following example demonstrates how to use the property to programmatically change the font color of the header row based on the sort direction. - +> The property is available only after the control creates the header row in the event. + + This property is commonly used when you need to programmatically manipulate the header row, for example, when adding custom content. Any modification to the property must be performed after the control has been rendered; otherwise, the control will overwrite any changes. + + + +## Examples + The following example demonstrates how to use the property to programmatically change the font color of the header row based on the sort direction. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/gridviewfooterrow/CS/gridviewfooterrowcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/gridviewfooterrow/VB/gridviewfooterrowvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/gridviewfooterrow/VB/gridviewfooterrowvb.aspx" id="Snippet1"::: + ]]> @@ -3081,25 +3081,25 @@ Gets a reference to the object that enables you to set the appearance of the header row in a control. A reference to the that represents the style of the header row in a control. - property to control the appearance of the header row in a control. This property is read-only; however, you can set the properties of the object it returns. The properties can be set declaratively using one of the following methods: - -- Place an attribute in the opening tag of the control in the form `Property-Subproperty`, where `Subproperty` is a property of the object (for example, `HeaderStyle-ForeColor`). - -- Nest a `` element between the opening and closing tags of the control. - - The properties can also be set programmatically in the form `Property.Subproperty` (for example, `HeaderStyle.ForeColor`). Common settings usually include a custom background color, foreground color, and font properties. - - - -## Examples - The following example demonstrates how to use the property to define a custom style for the header row in a control. - + property to control the appearance of the header row in a control. This property is read-only; however, you can set the properties of the object it returns. The properties can be set declaratively using one of the following methods: + +- Place an attribute in the opening tag of the control in the form `Property-Subproperty`, where `Subproperty` is a property of the object (for example, `HeaderStyle-ForeColor`). + +- Nest a `` element between the opening and closing tags of the control. + + The properties can also be set programmatically in the form `Property.Subproperty` (for example, `HeaderStyle.ForeColor`). Common settings usually include a custom background color, foreground color, and font properties. + + + +## Examples + The following example demonstrates how to use the property to define a custom style for the header row in a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewShowHeader/CS/gridviewshowheadercs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewShowHeader/VB/gridviewshowheadervb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewShowHeader/VB/gridviewshowheadervb.aspx" id="Snippet1"::: + ]]> @@ -3142,27 +3142,27 @@ Gets or sets the horizontal alignment of a control on the page. One of the values. The default is . - property to specify the horizontal alignment of a control within the page. The following table lists the different horizontal alignment styles. - -|Alignment value|Description| -|---------------------|-----------------| -|`HorizontalAlign.NotSet`|The horizontal alignment of the control has not been set.| -|`HorizontalAlign.Left`|The control is left-aligned on the page.| -|`HorizontalAlign.Center`|The control is centered on the page.| -|`HorizontalAlign.Right`|The control is right-aligned on the page.| -|`HorizontalAlign.Justify`|The control is aligned with both the left and right margins of the page.| - - - -## Examples - The following example demonstrates how to use the property to align a control on the right side of a page. - + property to specify the horizontal alignment of a control within the page. The following table lists the different horizontal alignment styles. + +|Alignment value|Description| +|---------------------|-----------------| +|`HorizontalAlign.NotSet`|The horizontal alignment of the control has not been set.| +|`HorizontalAlign.Left`|The control is left-aligned on the page.| +|`HorizontalAlign.Center`|The control is centered on the page.| +|`HorizontalAlign.Right`|The control is right-aligned on the page.| +|`HorizontalAlign.Justify`|The control is aligned with both the left and right margins of the page.| + + + +## Examples + The following example demonstrates how to use the property to align a control on the right side of a page. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewHorizontalAlign/CS/gridviewhorizontalaligncs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewHorizontalAlign/VB/gridviewhorizontalalignvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewHorizontalAlign/VB/gridviewhorizontalalignvb.aspx" id="Snippet1"::: + ]]> @@ -3195,14 +3195,14 @@ A that represents the data source. Initializes the pager row displayed when the paging feature is enabled. - method is used to initialize the pager row displayed when the paging feature is enabled. - + method is used to initialize the pager row displayed when the paging feature is enabled. + > [!NOTE] -> This method is used primarily by control developers to extend the control. - +> This method is used primarily by control developers to extend the control. + ]]> @@ -3234,14 +3234,14 @@ An array of objects that represent the column fields in the control. Initializes a row in the control. - method is used to initialize a row in the control. - + method is used to initialize a row in the control. + > [!NOTE] -> This method is used primarily by control developers to extend the control. - +> This method is used primarily by control developers to extend the control. + ]]> @@ -3273,43 +3273,43 @@ if the specified data type can be bound to a column in a control; otherwise, . - method is a helper method that is commonly used by control developers to programmatically determine whether the specified data type can be bound to a column in a control. The following data types can be bound to a column in a control: - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - + method is a helper method that is commonly used by control developers to programmatically determine whether the specified data type can be bound to a column in a control. The following data types can be bound to a column in a control: + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + ]]> @@ -3338,14 +3338,14 @@ An that contains the saved control state values for the control. Loads the state of the properties in the control that need to be persisted, even when the property is set to . - control that need to be persisted, even when the property is set to `false`. - + control that need to be persisted, even when the property is set to `false`. + > [!NOTE] -> This method is used primarily by control developers to extend the control. - +> This method is used primarily by control developers to extend the control. + ]]> @@ -3374,11 +3374,11 @@ An that contains the saved view state values for the control. Loads the previously saved view state of the control. - @@ -3411,11 +3411,11 @@ if the event has been canceled; otherwise, . - method implements the method to pass events from child controls to the page hierarchy. - + method implements the method to pass events from child controls to the page hierarchy. + ]]> @@ -3444,11 +3444,11 @@ Rebinds the control to its data after the , , or property is changed. - method is a helper method used by the control to rebind the control to its data after the , , or property is changed. - + method is a helper method used by the control to rebind the control to its data after the , , or property is changed. + ]]> @@ -3485,15 +3485,15 @@ An that contains the event data. Raises the event. - method notifies a control that the underlying data source has changed and that the control should rebind. Typically, the method is called when a property of the data source view has changed. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - + method notifies a control that the underlying data source has changed and that the control should rebind. Typically, the method is called when a property of the data source view has changed. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + ]]> @@ -3526,15 +3526,15 @@ An that contains event data. Raises the event. - method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - + method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + ]]> @@ -3565,15 +3565,15 @@ An that contains event data. Raises the event. - event is raised when one of the pager buttons is clicked, but after the control handles the paging operation. This enables you to provide an event-handling method that performs a custom routine, such as a custom paging operation, whenever this event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - + event is raised when one of the pager buttons is clicked, but after the control handles the paging operation. This enables you to provide an event-handling method that performs a custom routine, such as a custom paging operation, whenever this event occurs. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + ]]> @@ -3608,15 +3608,15 @@ A that contains event data. Raises the event. - event is raised when one of the pager buttons is clicked, but before the control handles the paging operation. This enables you to provide an event-handling method that performs a custom routine, such as canceling the paging operation, whenever this event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - + event is raised when one of the pager buttons is clicked, but before the control handles the paging operation. This enables you to provide an event-handling method that performs a custom routine, such as canceling the paging operation, whenever this event occurs. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + ]]> There is no handler for the event. @@ -3682,15 +3682,15 @@ An that contains the event data. Raises the event. - method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - + method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + ]]> @@ -3722,15 +3722,15 @@ A that contains event data. Raises the event. - event is raised when the Cancel button of a row in edit mode is clicked, but before the row exits edit mode. This enables you to provide an event-handling method that performs a custom routine, such as stopping the cancel operation if it would put the row in an undesired state, whenever this event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - + event is raised when the Cancel button of a row in edit mode is clicked, but before the row exits edit mode. This enables you to provide an event-handling method that performs a custom routine, such as stopping the cancel operation if it would put the row in an undesired state, whenever this event occurs. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + ]]> There is no handler for the event. @@ -3771,25 +3771,25 @@ A that contains event data. Raises the event. - event is raised when a button is clicked in the control. This enables you to provide an event-handling method that performs a custom routine whenever this event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - - - -## Examples - A Visual Studio Web site project with source code is available to accompany this topic: [Download](https://go.microsoft.com/fwlink/?LinkId=191882). - - The following example demonstrates how provide an event-handling method for the event. When the Add button is clicked for a given row of the control, the name of the selected customer is added to a control. - + event is raised when a button is clicked in the control. This enables you to provide an event-handling method that performs a custom routine whenever this event occurs. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + + + +## Examples + A Visual Studio Web site project with source code is available to accompany this topic: [Download](https://go.microsoft.com/fwlink/?LinkId=191882). + + The following example demonstrates how provide an event-handling method for the event. When the Add button is clicked for a given row of the control, the name of the selected customer is added to a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewRowCommmand/CS/gridviewrowcommandcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowCommmand/VB/gridviewrowcommandvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowCommmand/VB/gridviewrowcommandvb.aspx" id="Snippet1"::: + ]]> @@ -3822,23 +3822,23 @@ A that contains event data. Raises the event. - control can be rendered, a object must be created for each row in the control. The event is raised when each row in the control is created. This enables you to provide an event-handling method that performs a custom routine, such as adding custom content to a row, whenever this event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - - - -## Examples - The following example demonstrates how provide an event-handling method for the event. When a row is being created, its index is stored in the property of a control that is contained in the new row. This enables you to determine the index of the row when the user clicks the command button. - + control can be rendered, a object must be created for each row in the control. The event is raised when each row in the control is created. This enables you to provide an event-handling method that performs a custom routine, such as adding custom content to a row, whenever this event occurs. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + + + +## Examples + The following example demonstrates how provide an event-handling method for the event. When a row is being created, its index is stored in the property of a control that is contained in the new row. This enables you to determine the index of the row when the user clicks the command button. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewRowCreated/CS/gridviewrowcreatedcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowCreated/VB/gridviewrowcreatedvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowCreated/VB/gridviewrowcreatedvb.aspx" id="Snippet1"::: + ]]> @@ -3873,17 +3873,17 @@ A that contains event data. Raises the event. - control can be rendered, each row in the control must be bound to a record in the data source. The event is raised when a data row (represented by a object) is bound to data in the control. This enables you to provide an event-handling method that performs a custom routine, such as modifying the values of the data bound to the row, whenever this event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - - A Visual Studio Web site project with source code is available to accompany this topic: [Download](https://go.microsoft.com/fwlink/?LinkId=191882). - + control can be rendered, each row in the control must be bound to a record in the data source. The event is raised when a data row (represented by a object) is bound to data in the control. This enables you to provide an event-handling method that performs a custom routine, such as modifying the values of the data bound to the row, whenever this event occurs. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + + A Visual Studio Web site project with source code is available to accompany this topic: [Download](https://go.microsoft.com/fwlink/?LinkId=191882). + ]]> @@ -3918,15 +3918,15 @@ A that contains event data. Raises the event. - event is raised when a row's Delete button is clicked, but after the control deletes the row. This enables you to provide an event-handling method that performs a custom routine, such as checking the results of the delete operation, whenever this event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - + event is raised when a row's Delete button is clicked, but after the control deletes the row. This enables you to provide an event-handling method that performs a custom routine, such as checking the results of the delete operation, whenever this event occurs. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + ]]> @@ -3966,15 +3966,15 @@ A that contains event data. Raises the event. - event is raised when a row's Delete button is clicked, but before the control deletes the row. This enables you to provide an event-handling method that performs a custom routine, such as canceling the delete operation, whenever this event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - + event is raised when a row's Delete button is clicked, but before the control deletes the row. This enables you to provide an event-handling method that performs a custom routine, such as canceling the delete operation, whenever this event occurs. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + ]]> There is no handler for the event. @@ -4011,15 +4011,15 @@ A that contains event data. Raises the event. - event is raised when a row's Edit button is clicked, but before the control enters edit mode. This enables you to provide an event-handling method that performs a custom routine, such as canceling the edit operation, whenever this event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - + event is raised when a row's Edit button is clicked, but before the control enters edit mode. This enables you to provide an event-handling method that performs a custom routine, such as canceling the edit operation, whenever this event occurs. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + ]]> There is no handler for the event. @@ -4060,15 +4060,15 @@ A that contains event data. Raises the event. - event is raised when a row's Update button is clicked, but after the control updates the row. This enables you to provide an event-handling method that performs a custom routine, such as checking the results of the update operation, whenever this event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - + event is raised when a row's Update button is clicked, but after the control updates the row. This enables you to provide an event-handling method that performs a custom routine, such as checking the results of the update operation, whenever this event occurs. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + ]]> @@ -4107,15 +4107,15 @@ A that contains event data. Raises the event. - event is raised when a row's Update button is clicked, but before the control updates the row. This enables you to provide an event-handling method that performs a custom routine, such as canceling the update operation, whenever this event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - + event is raised when a row's Update button is clicked, but before the control updates the row. This enables you to provide an event-handling method that performs a custom routine, such as canceling the update operation, whenever this event occurs. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + ]]> There is no handler for the event. @@ -4156,23 +4156,23 @@ An that contains event data. Raises the event. - event is raised when a row's Select button is clicked, but after the control handles the select operation. This enables you to provide an event-handling method that performs a custom routine, such as updating a status label with the currently selected row, whenever this event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - - - -## Examples - The following example shows how create an event handler for the event. In this example, the selected row is persisted in the view state. So even after a sorting or a paging operation, only that row will be selected. - + event is raised when a row's Select button is clicked, but after the control handles the select operation. This enables you to provide an event-handling method that performs a custom routine, such as updating a status label with the currently selected row, whenever this event occurs. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + + + +## Examples + The following example shows how create an event handler for the event. In this example, the selected row is persisted in the view state. So even after a sorting or a paging operation, only that row will be selected. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Web.UI.WebControls.GridView.OnSelectedIndexChanged/CS/Default.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Web.UI.WebControls.GridView.OnSelectedIndexChanged/VB/Default.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Web.UI.WebControls.GridView.OnSelectedIndexChanged/VB/Default.aspx" id="Snippet1"::: + ]]> @@ -4207,15 +4207,15 @@ A that contains event data. Raises the event. - event is raised when a row's Select button is clicked, but before the control handles the select operation. This enables you to provide an event-handling method that performs a custom routine, such as canceling the selection operation, whenever this event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - + event is raised when a row's Select button is clicked, but before the control handles the select operation. This enables you to provide an event-handling method that performs a custom routine, such as canceling the selection operation, whenever this event occurs. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + ]]> @@ -4251,15 +4251,15 @@ An that contains event data. Raises the event. - event is raised when the hyperlink to sort a column is clicked, but after the control handles the sort operation. This enables you to provide an event-handling method that performs a custom routine, such as custom sorting, whenever this event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - + event is raised when the hyperlink to sort a column is clicked, but after the control handles the sort operation. This enables you to provide an event-handling method that performs a custom routine, such as custom sorting, whenever this event occurs. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + ]]> @@ -4296,15 +4296,15 @@ A that contains event data. Raises the event. - event is raised when the hyperlink to sort a column is clicked, but before the control handles the sort operation. This enables you to provide an event-handling method that performs a custom routine, such as canceling the sorting operation, whenever this event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - + event is raised when the hyperlink to sort a column is clicked, but before the control handles the sort operation. This enables you to provide an event-handling method that performs a custom routine, such as canceling the sorting operation, whenever this event occurs. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + ]]> There is no handler for the event. @@ -4350,19 +4350,19 @@ Gets the number of pages required to display the records of the data source in a control. The number of pages in a control. - property to `true`), use the property to determine the total number of pages required to display the records in the data source. This value is calculated by dividing the total number of records in the data source by the number of records displayed in a page (as specified by the property) and rounding up. - - - -## Examples - The following example demonstrates how to use the property to determine the total number of pages displayed in the control. - + property to `true`), use the property to determine the total number of pages required to display the records in the data source. This value is calculated by dividing the total number of records in the data source by the number of records displayed in a page (as specified by the property) and rounding up. + + + +## Examples + The following example demonstrates how to use the property to determine the total number of pages displayed in the control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewPagerTemplate/CS/gridviewpagertemplatecs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewPagerTemplate/VB/gridviewpagertemplatevb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewPagerTemplate/VB/gridviewpagertemplatevb.aspx" id="Snippet1"::: + ]]> @@ -4411,19 +4411,19 @@ Gets or sets the index of the currently displayed page. The zero-based index of the currently displayed page. - property to `true`), use the property to determine the index of the currently displayed page. You can also use this property to programmatically change the displayed page. - - - -## Examples - The following example demonstrates how to use the property to determine the index of the currently displayed page in the control. The example also shows how the property can be used to specify which page is displayed after the user selects a value from the pager row. - + property to `true`), use the property to determine the index of the currently displayed page. You can also use this property to programmatically change the displayed page. + + + +## Examples + The following example demonstrates how to use the property to determine the index of the currently displayed page in the control. The example also shows how the property can be used to specify which page is displayed after the user selects a value from the pager row. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewPagerTemplate/CS/gridviewpagertemplatecs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewPagerTemplate/VB/gridviewpagertemplatevb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewPagerTemplate/VB/gridviewpagertemplatevb.aspx" id="Snippet1"::: + ]]> The property is set to a value less than 0. @@ -4458,23 +4458,23 @@ Occurs when one of the pager buttons is clicked, but after the control handles the paging operation. - event is raised when one of the pager buttons is clicked, but after the control handles the paging operation. This enables you to provide an event-handling method that performs a custom routine, such as a custom paging operation, whenever this event occurs. - - To determine the index of the page selected by the user, use the property of the control. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following example demonstrates how to use the event to display the page number selected by the user from the pager row. - + event is raised when one of the pager buttons is clicked, but after the control handles the paging operation. This enables you to provide an event-handling method that performs a custom routine, such as a custom paging operation, whenever this event occurs. + + To determine the index of the page selected by the user, use the property of the control. + + For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + The following example demonstrates how to use the event to display the page number selected by the user from the pager row. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewPageIndexChanged/CS/gridviewpageindexchangedcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewPageIndexChanged/VB/gridviewpageindexchangedvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewPageIndexChanged/VB/gridviewpageindexchangedvb.aspx" id="Snippet1"::: + ]]> @@ -4502,26 +4502,26 @@ Occurs when one of the pager buttons is clicked, but before the control handles the paging operation. - event is raised when one of the pager buttons is clicked, but before the control handles the paging operation. This enables you to provide an event-handling method that performs a custom routine, such as canceling the paging operation, whenever this event occurs. - + event is raised when one of the pager buttons is clicked, but before the control handles the paging operation. This enables you to provide an event-handling method that performs a custom routine, such as canceling the paging operation, whenever this event occurs. + > [!NOTE] -> This event is not raised when you programmatically set the property. - - A object is passed to the event-handling method, which enables you to determine the index of the page selected by the user and to indicate that the paging operation should be canceled. To cancel the paging operation, set the property of the object to `true`. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following example demonstrates how to use the event to cancel the paging operation if the user attempts to navigate to another page when a control is in edit mode. - +> This event is not raised when you programmatically set the property. + + A object is passed to the event-handling method, which enables you to determine the index of the page selected by the user and to indicate that the paging operation should be canceled. To cancel the paging operation, set the property of the object to `true`. + + For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + The following example demonstrates how to use the event to cancel the paging operation if the user attempts to navigate to another page when a control is in edit mode. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewPageIndexChanging/CS/gridviewpageindexchangingcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewPageIndexChanging/VB/gridviewpageindexchangingvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewPageIndexChanging/VB/gridviewpageindexchangingvb.aspx" id="Snippet1"::: + ]]> @@ -4565,25 +4565,25 @@ Gets a reference to the object that enables you to set the properties of the pager buttons in a control. A reference to the that enables you to set the properties of the pager buttons in a control. - property to control the settings of the pager row in a control. The pager row is displayed when the paging feature is enabled (by setting the property to `true`) and contains the controls that allow the user to navigate to the different pages in the control. This property is read-only; however, you can set the properties of the object it returns. The properties can be set declaratively using one of the following methods: - -- Place an attribute in the opening tag of the control in the form `Property-Subproperty`, where `Subproperty` is a property of the object (for example, `PagerSettings-Mode`). - -- Nest a `` element between the opening and closing tags of the control. - - The properties can also be set programmatically in the form `Property.Subproperty` (for example, `PagerStyle.Mode`). Common settings usually include the pager row's display mode and custom text or images for the navigation controls. - - - -## Examples - The following example demonstrates how to set the property declaratively. It sets the font and background for the pager row to blue and light blue, respectively. - + property to control the settings of the pager row in a control. The pager row is displayed when the paging feature is enabled (by setting the property to `true`) and contains the controls that allow the user to navigate to the different pages in the control. This property is read-only; however, you can set the properties of the object it returns. The properties can be set declaratively using one of the following methods: + +- Place an attribute in the opening tag of the control in the form `Property-Subproperty`, where `Subproperty` is a property of the object (for example, `PagerSettings-Mode`). + +- Nest a `` element between the opening and closing tags of the control. + + The properties can also be set programmatically in the form `Property.Subproperty` (for example, `PagerStyle.Mode`). Common settings usually include the pager row's display mode and custom text or images for the navigation controls. + + + +## Examples + The following example demonstrates how to set the property declaratively. It sets the font and background for the pager row to blue and light blue, respectively. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewAllowPaging/CS/gridviewallowpagingcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewAllowPaging/VB/gridviewallowpagingvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewAllowPaging/VB/gridviewallowpagingvb.aspx" id="Snippet1"::: + ]]> @@ -4632,25 +4632,25 @@ Gets a reference to the object that enables you to set the appearance of the pager row in a control. A reference to the that represents the style of the pager row in a control. - property to control the appearance of the pager row in a control. The pager row is displayed when the paging feature is enabled (by setting the property to `true`) and contains the controls that allow the user to navigate to the different pages in the control. This property is read-only; however, you can set the properties of the object it returns. The properties can be set declaratively using one of the following methods: - -- Place an attribute in the opening tag of the control in the form `Property-Subproperty`, where `Subproperty` is a property of the object (for example, `PagerStyle-ForeColor`). - -- Nest a `` element between the opening and closing tags of the control. - - The properties can also be set programmatically in the form `Property.Subproperty` (for example, `PagerStyle.ForeColor`). Common settings usually include a custom background color, foreground color, and font properties. - - - -## Examples - The following example demonstrates how to set the property declaratively. It sets the font and background for the pager row to blue and light blue, respectively. - + property to control the appearance of the pager row in a control. The pager row is displayed when the paging feature is enabled (by setting the property to `true`) and contains the controls that allow the user to navigate to the different pages in the control. This property is read-only; however, you can set the properties of the object it returns. The properties can be set declaratively using one of the following methods: + +- Place an attribute in the opening tag of the control in the form `Property-Subproperty`, where `Subproperty` is a property of the object (for example, `PagerStyle-ForeColor`). + +- Nest a `` element between the opening and closing tags of the control. + + The properties can also be set programmatically in the form `Property.Subproperty` (for example, `PagerStyle.ForeColor`). Common settings usually include a custom background color, foreground color, and font properties. + + + +## Examples + The following example demonstrates how to set the property declaratively. It sets the font and background for the pager row to blue and light blue, respectively. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewAllowPaging/CS/gridviewallowpagingcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewAllowPaging/VB/gridviewallowpagingvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewAllowPaging/VB/gridviewallowpagingvb.aspx" id="Snippet1"::: + ]]> @@ -4718,34 +4718,34 @@ Gets or sets the custom content for the pager row in a control. A that contains the custom content for the pager row. The default value is null, which indicates that this property is not set. - control when the paging feature is enabled (when the property is set to true). The pager row contains the controls that allow the user to navigate to the different pages in the control. Instead of using the built-in pager row user interface (UI), you can define your own UI by using the property. - + control when the paging feature is enabled (when the property is set to true). The pager row contains the controls that allow the user to navigate to the different pages in the control. Instead of using the built-in pager row user interface (UI), you can define your own UI by using the property. + > [!NOTE] -> When the property is set, it overrides the built-in pager row UI. - - To specify a custom template for the pager row, first place `` tags between the opening and closing tags of the control. You can then list the contents of the template between the opening and closing `` tags. To control the appearance of the pager row, use the property. - - Typically, button controls are added to the pager template to perform the paging operations. The control performs a paging operation when a button control with its `CommandName` property set to "Page" is clicked. The button's `CommandArgument` property determines the type of paging operation to perform. The following table lists the command argument values supported by the control. - -|`CommandArgument` value|Description| -|-----------------------------|-----------------| -|"Next"|Navigates to the next page.| -|"Prev"|Navigates to the previous page.| -|"First"|Navigates to the first page.| -|"Last"|Navigates to the last page.| -|Integer value|Navigates to the specified page number.| - - - -## Examples - The following example demonstrates how to create a custom pager template that allows the user to navigate through a control using a control. - +> When the property is set, it overrides the built-in pager row UI. + + To specify a custom template for the pager row, first place `` tags between the opening and closing tags of the control. You can then list the contents of the template between the opening and closing `` tags. To control the appearance of the pager row, use the property. + + Typically, button controls are added to the pager template to perform the paging operations. The control performs a paging operation when a button control with its `CommandName` property set to "Page" is clicked. The button's `CommandArgument` property determines the type of paging operation to perform. The following table lists the command argument values supported by the control. + +|`CommandArgument` value|Description| +|-----------------------------|-----------------| +|`Next`|Navigates to the next page.| +|`Prev`|Navigates to the previous page.| +|`First`|Navigates to the first page.| +|`Last`|Navigates to the last page.| +|Integer value|Navigates to the specified page number.| + + + +## Examples + The following example demonstrates how to create a custom pager template that allows the user to navigate through a control using a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewPagerTemplate/CS/gridviewpagertemplatecs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewPagerTemplate/VB/gridviewpagertemplatevb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewPagerTemplate/VB/gridviewpagertemplatevb.aspx" id="Snippet1"::: + ]]> @@ -4786,19 +4786,19 @@ Gets or sets the number of records to display on a page in a control. The number of records to display on a single page. The default is 10. - property to `true`), use the property to specify the number of records to display on a single page. - - - -## Examples - The following example demonstrates how to use the property to display 15 records at a time in a control. - + property to `true`), use the property to specify the number of records to display on a single page. + + + +## Examples + The following example demonstrates how to use the property to display 15 records at a time in a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewPageSize/CS/gridviewpagesizecs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewPageSize/VB/gridviewpagesizevb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewPageSize/VB/gridviewpagesizevb.aspx" id="Snippet1"::: + ]]> The property is set to a value less than 1. @@ -4837,11 +4837,11 @@ An that contains the data source. Binds the specified data source to the control. - method is a helper method called by the control to bind the specified data source to the control. - + method is a helper method called by the control to bind the specified data source to the control. + ]]> @@ -4870,14 +4870,14 @@ Establishes the control hierarchy. - control. - + control. + > [!NOTE] -> This method is used primarily by control developers to extend the control. - +> This method is used primarily by control developers to extend the control. + ]]> @@ -4905,11 +4905,11 @@ The argument to pass to the event handler. Creates the arguments for the callback handler in the method. - method is a helper method used by the control to create the arguments for the callback handler in the method. - + method is a helper method used by the control to create the arguments for the callback handler in the method. + ]]> @@ -4938,14 +4938,14 @@ The event argument from which to create a for the event or events that are raised. Raises the appropriate events for the control when it posts back to the server. - method when a postback event occurs that raises the appropriate events for a control. This call occurs in the page life cycle after loading and change notification are complete, but before prerendering occurs. This method has been implemented to create a object for the events that are raised. - + method when a postback event occurs that raises the appropriate events for a control. This call occurs in the page life cycle after loading and change notification are complete, but before prerendering occurs. This method has been implemented to create a object for the events that are raised. + > [!NOTE] -> This method is used primarily by control developers to extend the control. - +> This method is used primarily by control developers to extend the control. + ]]> @@ -4976,14 +4976,14 @@ The used to render the server control content on the client's browser. Renders the Web server control content to the client's browser using the specified object. - method is used to render the server control content to the client's browser using the specified object. - + method is used to render the server control content to the client's browser using the specified object. + > [!NOTE] -> This method is used primarily by control developers to extend the control. - +> This method is used primarily by control developers to extend the control. + ]]> @@ -5008,28 +5008,28 @@ Occurs when the Cancel button of a row in edit mode is clicked, but before the row exits edit mode. - event is raised when the Cancel button of a row in edit mode is clicked, but before the row exits edit mode. This enables you to provide an event-handling method that performs a custom routine, such as stopping the cancel operation if it would put the row in an undesired state, whenever this event occurs. - - A object is passed to the event-handling method, which enables you to determine the index of the current row and to indicate that the cancel operation should be stopped. To stop the cancel operation, set the property of the object to `true`. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following example demonstrates how to use the event to display a cancellation message when the user cancels the update operation of a control. - + event is raised when the Cancel button of a row in edit mode is clicked, but before the row exits edit mode. This enables you to provide an event-handling method that performs a custom routine, such as stopping the cancel operation if it would put the row in an undesired state, whenever this event occurs. + + A object is passed to the event-handling method, which enables you to determine the index of the current row and to indicate that the cancel operation should be stopped. To stop the cancel operation, set the property of the object to `true`. + + For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + The following example demonstrates how to use the event to display a cancellation message when the user cancels the update operation of a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewRowCancellingEdit/CS/gridviewrowcancellingeditcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowCancellingEdit/VB/gridviewrowcancellingeditvb.aspx" id="Snippet1"::: - - The following example demonstrates how to use the event to cancel the update operation when the data source is set programmatically. - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowCancellingEdit/VB/gridviewrowcancellingeditvb.aspx" id="Snippet1"::: + + The following example demonstrates how to use the event to cancel the update operation when the data source is set programmatically. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewRowEditing/CS/GridViewRowEditing2CS.aspx" id="Snippet2"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowEditing/VB/GridViewRowEditing2VB.aspx" id="Snippet2"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowEditing/VB/GridViewRowEditing2VB.aspx" id="Snippet2"::: + ]]> @@ -5062,47 +5062,45 @@ Occurs when a button is clicked in a control. - event is raised when a button is clicked in the control. This enables you to provide an event-handling method that performs a custom routine whenever this event occurs. - - Buttons within a control can also invoke some of the built-in functionality of the control. To perform one of these operations, set the `CommandName` property of a button to one of the values in the following table. - -|`CommandName` value|Description| -|-------------------------|-----------------| -|"Cancel"|Cancels an edit operation and returns the control to read-only mode. Raises the event.| -|"Delete"|Deletes the current record. Raises the and events.| -|"Edit"|Puts the current record in edit mode. Raises the event.| -|"Page"|Performs a paging operation. Sets the `CommandArgument` property of the button to "First", "Last", "Next", "Prev", or a page number to specify the type of paging operation to perform. Raises the and events.| -|"Select"|Selects the current record. Raises the and events.| -|"Sort"|Sorts the control. Raises the and events.| -|"Update"|Updates the current record in the data source. Raises the and events.| - - Although the event is raised when a button listed in the previous table is clicked, it is recommended that you use the events listed in the table for the operation. - - A object is passed to the event-handling method, which enables you to determine the command name and command argument of the button clicked. - + event is raised when a button is clicked in the control. This enables you to provide an event-handling method that performs a custom routine whenever this event occurs. + + Buttons within a control can also invoke some of the built-in functionality of the control. To perform one of these operations, set the `CommandName` property of a button to one of the values in the following table. + +|`CommandName` value|Description| +|-------------------------|-----------------| +|`Cancel`|Cancels an edit operation and returns the control to read-only mode. Raises the event.| +|`Delete`|Deletes the current record. Raises the and events.| +|`Edit`|Puts the current record in edit mode. Raises the event.| +|`Page`|Performs a paging operation. Sets the `CommandArgument` property of the button to "First", "Last", "Next", "Prev", or a page number to specify the type of paging operation to perform. Raises the and events.| +|`Select`|Selects the current record. Raises the and events.| +|`Sort`|Sorts the control. Raises the and events.| +|`Update`|Updates the current record in the data source. Raises the and events.| + + Although the event is raised when a button listed in the previous table is clicked, it is recommended that you use the events listed in the table for the operation. + + A object is passed to the event-handling method, which enables you to determine the command name and command argument of the button clicked. + > [!NOTE] -> To determine the index of the row that raised the event, use the property of the event argument that is passed to the event. The class automatically populates the property with the appropriate index value. For other command buttons, you must manually set the property of the command button. For example, you can set the to `<%# Container.DataItemIndex %>` when the control has no paging enabled. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - A Visual Studio Web site project with source code is available to accompany this topic: [Download](https://go.microsoft.com/fwlink/?LinkId=191882). - - The following example demonstrates how to use the event to add the name of a customer from a control to a control when a row's Add button is clicked. - +> To determine the index of the row that raised the event, use the property of the event argument that is passed to the event. The class automatically populates the property with the appropriate index value. For other command buttons, you must manually set the property of the command button. For example, you can set the to `<%# Container.DataItemIndex %>` when the control has no paging enabled. + + For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). + +## Examples + A Visual Studio Web site project with source code is available to accompany this topic: [Download](https://go.microsoft.com/fwlink/?LinkId=191882). + + The following example demonstrates how to use the event to add the name of a customer from a control to a control when a row's Add button is clicked. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewRowCommmand/CS/gridviewrowcommandcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowCommmand/VB/gridviewrowcommandvb.aspx" id="Snippet1"::: - - The following example demonstrates how to use the event to update the price of a product when a row's button is clicked. This example has the paging functionality enabled for the control and sets the property of the control to the appropriate row index. - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowCommmand/VB/gridviewrowcommandvb.aspx" id="Snippet1"::: + + The following example demonstrates how to use the event to update the price of a product when a row's button is clicked. This example has the paging functionality enabled for the control and sets the property of the control to the appropriate row index. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewRowCommmand/CS/gridviewrowcommand2cs.aspx" id="Snippet2"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowCommmand/VB/gridviewrowcommand2vb.aspx" id="Snippet2"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowCommmand/VB/gridviewrowcommand2vb.aspx" id="Snippet2"::: + ]]> @@ -5128,23 +5126,23 @@ Occurs when a row is created in a control. - control can be rendered, a object must be created for each row in the control. The event is raised when each row in the control is created. This enables you to provide an event-handling method that performs a custom routine, such as adding custom content to a row, whenever this event occurs. - - A object is passed to the event-handling method, which enables you to access the properties of the row being created. To access a specific cell in the row, use the property of the object. You can determine which row type (header row, data row, and so on) is being created by using the property. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following example demonstrates how to use the event to store the index of the row being created in the property of a control contained in the row. This enables you to determine the index of the row that contains the control when the user clicked the button. - + control can be rendered, a object must be created for each row in the control. The event is raised when each row in the control is created. This enables you to provide an event-handling method that performs a custom routine, such as adding custom content to a row, whenever this event occurs. + + A object is passed to the event-handling method, which enables you to access the properties of the row being created. To access a specific cell in the row, use the property of the object. You can determine which row type (header row, data row, and so on) is being created by using the property. + + For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + The following example demonstrates how to use the event to store the index of the row being created in the property of a control contained in the row. This enables you to determine the index of the row that contains the control when the user clicked the button. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewRowCreated/CS/gridviewrowcreatedcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowCreated/VB/gridviewrowcreatedvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowCreated/VB/gridviewrowcreatedvb.aspx" id="Snippet1"::: + ]]> @@ -5172,25 +5170,25 @@ Occurs when a data row is bound to data in a control. - control can be rendered, each row in the control must be bound to a record in the data source. The event is raised when a data row (represented by a object) is bound to data in the control. This enables you to provide an event-handling method that performs a custom routine, such as modifying the values of the data bound to the row, whenever this event occurs. - - A object is passed to the event-handling method, which enables you to access the properties of the row being bound. To access a specific cell in the row, use the property of the object contained in the property of the object. You can determine which row type (header row, data row, and so on) is being bound by using the property. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - A Visual Studio Web site project with source code is available to accompany this topic: [Download](https://go.microsoft.com/fwlink/?LinkId=191882). - - The following example demonstrates how to use the event to modify the value of a field in the data source before it is displayed in a control. - + control can be rendered, each row in the control must be bound to a record in the data source. The event is raised when a data row (represented by a object) is bound to data in the control. This enables you to provide an event-handling method that performs a custom routine, such as modifying the values of the data bound to the row, whenever this event occurs. + + A object is passed to the event-handling method, which enables you to access the properties of the row being bound. To access a specific cell in the row, use the property of the object contained in the property of the object. You can determine which row type (header row, data row, and so on) is being bound by using the property. + + For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + A Visual Studio Web site project with source code is available to accompany this topic: [Download](https://go.microsoft.com/fwlink/?LinkId=191882). + + The following example demonstrates how to use the event to modify the value of a field in the data source before it is displayed in a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewRowDataBound/CS/gridviewrowdataboundcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowDataBound/VB/gridviewrowdataboundvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowDataBound/VB/gridviewrowdataboundvb.aspx" id="Snippet1"::: + ]]> @@ -5218,23 +5216,23 @@ Occurs when a row's Delete button is clicked, but after the control deletes the row. - event is raised when a row's Delete button is clicked, but after the control deletes the row. This enables you to provide an event-handling method that performs a custom routine, such as checking the results of the delete operation, whenever this event occurs. - - A object is passed to the event-handling method, which enables you to determine the number of rows affected and any exceptions that might have occurred. You can also indicate whether the exception was handled in the event-handling method by setting the property of the object. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following example demonstrates how to use the event to check the result of the delete operation. A message is displayed to indicate to the user whether the operation succeeded. - + event is raised when a row's Delete button is clicked, but after the control deletes the row. This enables you to provide an event-handling method that performs a custom routine, such as checking the results of the delete operation, whenever this event occurs. + + A object is passed to the event-handling method, which enables you to determine the number of rows affected and any exceptions that might have occurred. You can also indicate whether the exception was handled in the event-handling method by setting the property of the object. + + For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + The following example demonstrates how to use the event to check the result of the delete operation. A message is displayed to indicate to the user whether the operation succeeded. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewRowDeleted/CS/gridviewrowdeletedcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowDeleted/VB/gridviewrowdeletedvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowDeleted/VB/gridviewrowdeletedvb.aspx" id="Snippet1"::: + ]]> @@ -5267,29 +5265,29 @@ Occurs when a row's Delete button is clicked, but before the control deletes the row. - event is raised when a row's Delete button is clicked, but before the control deletes the row. This enables you to provide an event-handling method that performs a custom routine, such as canceling the delete operation, whenever this event occurs. - - A object is passed to the event-handling method, which enables you to determine the index of the current row and to indicate that the delete operation should be canceled. To cancel the delete operation, set the property of the object to `true`. You can also manipulate the and collections, if necessary, before the values are passed to the data source. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following example demonstrates how to use the event to cancel the delete operation. The page contains a control that displays a list of customer names and addresses from the AdventureWorksLT database. When the user clicks the **Delete** link for a row, the handler for the event checks the last name of the person displayed in the row that the user is trying to delete. If the last name is "Beaver", the delete operation is canceled, and an error message is displayed. For any other name, the delete operation proceeds and the row is deleted. - - The event handler uses the property of the object to find the row that the user is trying to delete. The example examines the contents of the collection. If the value you want to compare to is a key value, you could examine the collection instead. - - Rows are deleted from the CustomerAddress table instead of the Customer table in order to keep the example simple. The control shows the result of joining three tables: Customer, Address, and CustomerAddress. When a CustomerAddress row is deleted, the corresponding row disappears. Referential integrity constraints would make the code for an example that actually deletes rows from the Customer table more complex. - - For information about how to set up the AdventureWorksLT database, see [How to: Set Up an AdventureWorksLT Sample Database for ASP.NET Development](https://msdn.microsoft.com/library/2baad633-9d63-49cc-a6b2-917cafd35356). - + event is raised when a row's Delete button is clicked, but before the control deletes the row. This enables you to provide an event-handling method that performs a custom routine, such as canceling the delete operation, whenever this event occurs. + + A object is passed to the event-handling method, which enables you to determine the index of the current row and to indicate that the delete operation should be canceled. To cancel the delete operation, set the property of the object to `true`. You can also manipulate the and collections, if necessary, before the values are passed to the data source. + + For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + The following example demonstrates how to use the event to cancel the delete operation. The page contains a control that displays a list of customer names and addresses from the AdventureWorksLT database. When the user clicks the **Delete** link for a row, the handler for the event checks the last name of the person displayed in the row that the user is trying to delete. If the last name is "Beaver", the delete operation is canceled, and an error message is displayed. For any other name, the delete operation proceeds and the row is deleted. + + The event handler uses the property of the object to find the row that the user is trying to delete. The example examines the contents of the collection. If the value you want to compare to is a key value, you could examine the collection instead. + + Rows are deleted from the CustomerAddress table instead of the Customer table in order to keep the example simple. The control shows the result of joining three tables: Customer, Address, and CustomerAddress. When a CustomerAddress row is deleted, the corresponding row disappears. Referential integrity constraints would make the code for an example that actually deletes rows from the Customer table more complex. + + For information about how to set up the AdventureWorksLT database, see [How to: Set Up an AdventureWorksLT Sample Database for ASP.NET Development](https://msdn.microsoft.com/library/2baad633-9d63-49cc-a6b2-917cafd35356). + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewRowDeleting/CS/gridviewrowdeleting.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowDeleting/VB/gridviewrowdeleting.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowDeleting/VB/gridviewrowdeleting.aspx" id="Snippet1"::: + ]]> @@ -5318,28 +5316,28 @@ Occurs when a row's Edit button is clicked, but before the control enters edit mode. - event is raised when a row's Edit button is clicked, but before the control enters edit mode. This enables you to provide an event-handling method that performs a custom routine, such as canceling the edit operation, whenever this event occurs. - - A object is passed to the event-handling method, which enables you to determine the index of the current row and to indicate that the edit operation should be canceled. To cancel the edit operation, set the property of the object to `true`. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following example demonstrates how to use the event to put a row in edit mode when the data source is set programmatically. - + event is raised when a row's Edit button is clicked, but before the control enters edit mode. This enables you to provide an event-handling method that performs a custom routine, such as canceling the edit operation, whenever this event occurs. + + A object is passed to the event-handling method, which enables you to determine the index of the current row and to indicate that the edit operation should be canceled. To cancel the edit operation, set the property of the object to `true`. + + For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + The following example demonstrates how to use the event to put a row in edit mode when the data source is set programmatically. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewRowEditing/CS/GridViewRowEditing2CS.aspx" id="Snippet2"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowEditing/VB/GridViewRowEditing2VB.aspx" id="Snippet2"::: - - The following example demonstrates how to use the event to cancel the editing operation if the user attempts to edit the record for a company in the United States. - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowEditing/VB/GridViewRowEditing2VB.aspx" id="Snippet2"::: + + The following example demonstrates how to use the event to cancel the editing operation if the user attempts to edit the record for a company in the United States. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewRowEditing/CS/gridviewroweditingcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowEditing/VB/gridviewroweditingvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowEditing/VB/gridviewroweditingvb.aspx" id="Snippet1"::: + ]]> @@ -5387,27 +5385,27 @@ Gets or sets the name of the column to use as the column header for the control. This property is provided to make the control more accessible to users of assistive technology devices. The name of the column to use as the column header. The default is an empty string (""), which indicates that this property is not set. - ` elements. The control has a built-in header row that can be displayed by setting the property to `true`. You can also optionally specify a header column (usually the first or last column in the control) by setting this property. When this property is set, all cells in the column that corresponds to the specified field name are rendered as `` elements. - + ` elements. The control has a built-in header row that can be displayed by setting the property to `true`. You can also optionally specify a header column (usually the first or last column in the control) by setting this property. When this property is set, all cells in the column that corresponds to the specified field name are rendered as `` elements. + > [!NOTE] -> Although the specified column is treated like a header, the , , and properties do not apply to the header column. - - The default rendering of the `` element is preserved, rendering text as bold and centered horizontally. Developers can override the behavior of the `` element using a cascading style sheet. - +> Although the specified column is treated like a header, the , , and properties do not apply to the header column. + + The default rendering of the `` element is preserved, rendering text as bold and centered horizontally. Developers can override the behavior of the `` element using a cascading style sheet. + > [!NOTE] -> This property works only with bound fields. It does not work with template fields. - - - -## Examples - The following example demonstrates how to use the property to display a header column in a control. - +> This property works only with bound fields. It does not work with template fields. + + + +## Examples + The following example demonstrates how to use the property to display a header column in a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/gridviewrowheadercolumn/CS/GridViewRowHeaderColumncs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/gridviewrowheadercolumn/VB/GridViewRowHeaderColumnvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/gridviewrowheadercolumn/VB/GridViewRowHeaderColumnvb.aspx" id="Snippet1"::: + ]]> @@ -5445,22 +5443,22 @@ Gets a collection of objects that represent the data rows in a control. A that contains all the data rows in a control. - property (collection) is used to store the data rows in a control. The control automatically populates the collection by creating a object for each record in the data source and then adding each object to the collection. This property is commonly used to access a specific row in the control or to iterate though the entire collection of rows. - + property (collection) is used to store the data rows in a control. The control automatically populates the collection by creating a object for each record in the data source and then adding each object to the collection. This property is commonly used to access a specific row in the control or to iterate though the entire collection of rows. + > [!NOTE] -> Only rows with their property set to `DataControlRowType.DataRow` are stored in the collection. The objects that represent the header, footer, and pager rows are not included in the collection. - - - -## Examples - The following example demonstrates how to use the collection to access the row being edited in a control. After a row is updated, a message is displayed to indicate that the update was successful. - +> Only rows with their property set to `DataControlRowType.DataRow` are stored in the collection. The objects that represent the header, footer, and pager rows are not included in the collection. + + + +## Examples + The following example demonstrates how to use the collection to access the row being edited in a control. After a row is updated, a message is displayed to indicate that the update was successful. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewRows/CS/gridviewrowscs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRows/VB/gridviewrowsvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRows/VB/gridviewrowsvb.aspx" id="Snippet1"::: + ]]> @@ -5501,25 +5499,25 @@ Gets a reference to the object that enables you to set the appearance of the data rows in a control. A reference to the that represents the style of the data rows in a control. - property to control the appearance of the data rows in a control. When the property is also set, the data rows are displayed alternating between the settings and the settings. This property is read-only; however, you can set the properties of the object it returns. The properties can be set declaratively using one of the following methods: - -- Place an attribute in the opening tag of the control in the form `Property-Subproperty`, where `Subproperty` is a property of the object (for example, `RowStyle-ForeColor`). - -- Nest a `` element between the opening and closing tags of the control. - - The properties can also be set programmatically in the form `Property.Subproperty` (for example, `RowStyle.ForeColor`). Common settings usually include a custom background color, foreground color, and font properties. - - - -## Examples - The following example demonstrates how to use the property to declaratively define the style for the item rows in a control. - + property to control the appearance of the data rows in a control. When the property is also set, the data rows are displayed alternating between the settings and the settings. This property is read-only; however, you can set the properties of the object it returns. The properties can be set declaratively using one of the following methods: + +- Place an attribute in the opening tag of the control in the form `Property-Subproperty`, where `Subproperty` is a property of the object (for example, `RowStyle-ForeColor`). + +- Nest a `` element between the opening and closing tags of the control. + + The properties can also be set programmatically in the form `Property.Subproperty` (for example, `RowStyle.ForeColor`). Common settings usually include a custom background color, foreground color, and font properties. + + + +## Examples + The following example demonstrates how to use the property to declaratively define the style for the item rows in a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewRowStyle/CS/gridviewrowstylecs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowStyle/VB/gridviewrowstylevb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowStyle/VB/gridviewrowstylevb.aspx" id="Snippet1"::: + ]]> @@ -5551,23 +5549,23 @@ Occurs when a row's Update button is clicked, but after the control updates the row. - event is raised when a row's Update button is clicked, but after the control updates the row. This enables you to provide an event-handling method that performs a custom routine, such as checking the results of the update operation, whenever this event occurs. - - A object is passed to the event-handling method, which enables you to determine the number of rows affected and any exceptions that might have occurred. You can also indicate whether the exception was handled in the event-handling method by setting the property of the object. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following example demonstrates how to use the event to check the result of the update operation. A message is displayed to indicate to the user whether the operation succeeded. - + event is raised when a row's Update button is clicked, but after the control updates the row. This enables you to provide an event-handling method that performs a custom routine, such as checking the results of the update operation, whenever this event occurs. + + A object is passed to the event-handling method, which enables you to determine the number of rows affected and any exceptions that might have occurred. You can also indicate whether the exception was handled in the event-handling method by setting the property of the object. + + For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + The following example demonstrates how to use the event to check the result of the update operation. A message is displayed to indicate to the user whether the operation succeeded. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewRowUpdated/CS/gridviewrowupdatedcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowUpdated/VB/gridviewrowupdatedvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowUpdated/VB/gridviewrowupdatedvb.aspx" id="Snippet1"::: + ]]> @@ -5604,26 +5602,26 @@ Occurs when a row's Update button is clicked, but before the control updates the row. - event is raised when a row's Update button is clicked, but before the control updates the row. This enables you to provide an event-handling method that performs a custom routine, such as canceling the update operation, whenever this event occurs. - - A object is passed to the event-handling method, which enables you to determine the index of the current row and to indicate that the update operation should be canceled. To cancel the update operation, set the property of the object to `true`. You can also manipulate the , , and collections, if necessary, before the values are passed to the data source. A common way to use these collections is to HTML-encode the values supplied by the user before they are stored in the data source. This helps to prevent script injection attacks. - + event is raised when a row's Update button is clicked, but before the control updates the row. This enables you to provide an event-handling method that performs a custom routine, such as canceling the update operation, whenever this event occurs. + + A object is passed to the event-handling method, which enables you to determine the index of the current row and to indicate that the update operation should be canceled. To cancel the update operation, set the property of the object to `true`. You can also manipulate the , , and collections, if necessary, before the values are passed to the data source. A common way to use these collections is to HTML-encode the values supplied by the user before they are stored in the data source. This helps to prevent script injection attacks. + > [!NOTE] -> The , and collections are automatically populated only when the control is bound to data by using the property. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following example demonstrates how to use the event to update the values in the data source object when the data source is set programmatically. - +> The , and collections are automatically populated only when the control is bound to data by using the property. + + For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + The following example demonstrates how to use the event to update the values in the data source object when the data source is set programmatically. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewRowEditing/CS/GridViewRowEditing2CS.aspx" id="Snippet2"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowEditing/VB/GridViewRowEditing2VB.aspx" id="Snippet2"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewRowEditing/VB/GridViewRowEditing2VB.aspx" id="Snippet2"::: + ]]> @@ -5658,14 +5656,14 @@ Saves the state of the properties in the control that need to be persisted, even when the property is set to . Returns the server control's current view state. If there is no view state associated with the control, this method returns . - control that need to be persisted, even when the property is set to `false`. - + control that need to be persisted, even when the property is set to `false`. + > [!NOTE] -> This method is used primarily by control developers to extend the control. - +> This method is used primarily by control developers to extend the control. + ]]> @@ -5724,29 +5722,29 @@ Gets the object that contains the data key value for the selected row in a control. The for the selected row in a control. The default is , which indicates that no row is currently selected. - property is set, the control automatically creates a object for each row in the control using the value or values of the specified field or fields. The objects are then added to the control's collection. Normally, the property is used to retrieve the object for a specific data row in the control. However, if you just need to retrieve the object of the currently selected row, you can simply use the property as a shortcut. - + property is set, the control automatically creates a object for each row in the control using the value or values of the specified field or fields. The objects are then added to the control's collection. Normally, the property is used to retrieve the object for a specific data row in the control. However, if you just need to retrieve the object of the currently selected row, you can simply use the property as a shortcut. + > [!NOTE] -> This is the same as retrieving the object at the index specified by the property from the collection. You can also use the property to retrieve the data key value for the currently selected row directly. - - If you are creating a object and want to access a key field other than the first field, use the indexed property in the property of the object. An example is shown below. - - - -## Examples - The following example demonstrates how to use the property to determine the data key value of the selected row in a control. - +> This is the same as retrieving the object at the index specified by the property from the collection. You can also use the property to retrieve the data key value for the currently selected row directly. + + If you are creating a object and want to access a key field other than the first field, use the indexed property in the property of the object. An example is shown below. + + + +## Examples + The following example demonstrates how to use the property to determine the data key value of the selected row in a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewSelectedDataKey/CS/gridviewselecteddatakeycs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSelectedDataKey/VB/gridviewselecteddatakeyvb.aspx" id="Snippet1"::: - - The following example demonstrates how to use the second key field as a parameter in a master/detail scenario. A control is used to display records from the Order Details table of the Northwind database. When a record is selected in the control, the details of the product from the Products table are displayed in a control. ProductID is the second key name in the control. To access the second key, the value of GridView1.SelectedDataKey[1] is used as the for the object of the control of the control. - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSelectedDataKey/VB/gridviewselecteddatakeyvb.aspx" id="Snippet1"::: + + The following example demonstrates how to use the second key field as a parameter in a master/detail scenario. A control is used to display records from the Order Details table of the Northwind database. When a record is selected in the control, the details of the product from the Products table are displayed in a control. ProductID is the second key name in the control. To access the second key, the value of GridView1.SelectedDataKey[1] is used as the for the object of the control of the control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewSelectedDataKeyIndex/CS/gridviewselecteddatakeycs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSelectedDataKeyIndex/VB/gridviewselecteddatakeyvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSelectedDataKeyIndex/VB/gridviewselecteddatakeyvb.aspx" id="Snippet1"::: + ]]> No data keys are specified in the property. @@ -5790,19 +5788,19 @@ Gets or sets the index of the selected row in a control. The zero-based index of the selected row in a control. The default is -1, which indicates that no row is currently selected. - property to determine the index of the currently selected row in a control. You can also use this property to programmatically select a row in the control. To clear the selection of a row, set this property to -1. The appearance of the currently selected row can be customized by using the property. To access the currently selected row, use the property. - - - -## Examples - The following example demonstrates how to use the property to select the second row in a control when the control is initially displayed. - + property to determine the index of the currently selected row in a control. You can also use this property to programmatically select a row in the control. To clear the selection of a row, set this property to -1. The appearance of the currently selected row can be customized by using the property. To access the currently selected row, use the property. + + + +## Examples + The following example demonstrates how to use the property to select the second row in a control when the control is initially displayed. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewSelect/CS/gridviewselectcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSelect/VB/gridviewselectvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSelect/VB/gridviewselectvb.aspx" id="Snippet1"::: + ]]> The property is set to a value less than -1. @@ -5831,21 +5829,21 @@ Occurs when a row's Select button is clicked, but after the control handles the select operation. - event is raised when a row's Select button is clicked, but after the control handles the select operation. This enables you to provide an event-handling method that performs a custom routine, such as updating a status label with the currently selected row, whenever this event occurs. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following example demonstrates how to use the event to display the name of the customer in the selected row of the control. - + event is raised when a row's Select button is clicked, but after the control handles the select operation. This enables you to provide an event-handling method that performs a custom routine, such as updating a status label with the currently selected row, whenever this event occurs. + + For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + The following example demonstrates how to use the event to display the name of the customer in the selected row of the control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewSelect/CS/gridviewselectcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSelect/VB/gridviewselectvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSelect/VB/gridviewselectvb.aspx" id="Snippet1"::: + ]]> @@ -5873,26 +5871,26 @@ Occurs when a row's Select button is clicked, but before the control handles the select operation. - event is raised when a row's Select button is clicked, but before the control handles the select operation. This enables you to provide an event-handling method that performs a custom routine, such as canceling the selection operation, whenever this event occurs. - + event is raised when a row's Select button is clicked, but before the control handles the select operation. This enables you to provide an event-handling method that performs a custom routine, such as canceling the selection operation, whenever this event occurs. + > [!NOTE] -> This event is not raised when you programmatically set the property. - - A object is passed to the event-handling method, which enables you to determine the index of the row selected by the user and to indicate that the selection operation should be canceled. To cancel the selection operation, set the property of the object to `true`. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following example demonstrates how to use the event to cancel a select operation. - +> This event is not raised when you programmatically set the property. + + A object is passed to the event-handling method, which enables you to determine the index of the row selected by the user and to indicate that the selection operation should be canceled. To cancel the selection operation, set the property of the object to `true`. + + For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + The following example demonstrates how to use the event to cancel a select operation. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewSelect/CS/gridviewselectcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSelect/VB/gridviewselectvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSelect/VB/gridviewselectvb.aspx" id="Snippet1"::: + ]]> @@ -5968,24 +5966,24 @@ Gets a reference to a object that represents the selected row in the control. A that represents the selected row in the control, or `null` if nothing is selected. - control, use the property to retrieve the object that represents that row. - + control, use the property to retrieve the object that represents that row. + > [!NOTE] -> This is the same as retrieving the object at the index specified by the property from the collection. - - This object can then be used to access the properties of the selected row. - - - -## Examples - The following example demonstrates how to use the property to access the properties of the object that represents the selected row in the control. - +> This is the same as retrieving the object at the index specified by the property from the collection. + + This object can then be used to access the properties of the selected row. + + + +## Examples + The following example demonstrates how to use the property to access the properties of the object that represents the selected row in the control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewSelect/CS/gridviewselectcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSelect/VB/gridviewselectvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSelect/VB/gridviewselectvb.aspx" id="Snippet1"::: + ]]> @@ -6028,25 +6026,25 @@ Gets a reference to the object that enables you to set the appearance of the selected row in a control. A reference to the that represents the style of the selected row in a control. - property to control the appearance of the selected row in a control. This property is read-only; however, you can set the properties of the object it returns. The properties can be set declaratively using one of the following methods: - -- Place an attribute in the opening tag of the control in the form `Property-Subproperty`, where `Subproperty` is a property of the object (for example, `SelectedRowStyle-ForeColor`). - -- Nest a `` element between the opening and closing tags of the control. - - The properties can also be set programmatically in the form `Property.Subproperty` (for example, `SelectedRowStyle.ForeColor`). Common settings usually include a custom background color, foreground color, and font properties. - - - -## Examples - The following example demonstrates how to use the property to define a custom style for the selected row in a control. - + property to control the appearance of the selected row in a control. This property is read-only; however, you can set the properties of the object it returns. The properties can be set declaratively using one of the following methods: + +- Place an attribute in the opening tag of the control in the form `Property-Subproperty`, where `Subproperty` is a property of the object (for example, `SelectedRowStyle-ForeColor`). + +- Nest a `` element between the opening and closing tags of the control. + + The properties can also be set programmatically in the form `Property.Subproperty` (for example, `SelectedRowStyle.ForeColor`). Common settings usually include a custom background color, foreground color, and font properties. + + + +## Examples + The following example demonstrates how to use the property to define a custom style for the selected row in a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewSelect/CS/gridviewselectcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSelect/VB/gridviewselectvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSelect/VB/gridviewselectvb.aspx" id="Snippet1"::: + ]]> @@ -6085,21 +6083,21 @@ Gets the data key value of the selected row in a control. The data key value of the selected row in a control. - property is set with a comma-separated list of field names that represent the primary key of the data source, the control automatically creates a object for each row in the control using the value or values of the specified field or fields. The objects are then added to the control's collection. Normally, the property is used to retrieve the object for a specific data row in the control. However, if you just need to retrieve the object of the currently selected row, you can simply use the property as a shortcut. As a further shortcut, you can directly determine the data key value of the first key field of the selected row by using the property. - - If you are creating a object and want to access a key field other than the first field, use the property. For an example, see . - - - -## Examples - The following example demonstrates how to use the property to determine the data key value of the selected row in a control. - + property is set with a comma-separated list of field names that represent the primary key of the data source, the control automatically creates a object for each row in the control using the value or values of the specified field or fields. The objects are then added to the control's collection. Normally, the property is used to retrieve the object for a specific data row in the control. However, if you just need to retrieve the object of the currently selected row, you can simply use the property as a shortcut. As a further shortcut, you can directly determine the data key value of the first key field of the selected row by using the property. + + If you are creating a object and want to access a key field other than the first field, use the property. For an example, see . + + + +## Examples + The following example demonstrates how to use the property to determine the data key value of the selected row in a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewSelectedValue/CS/gridviewselectedvaluecs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSelectedValue/VB/gridviewselectedvaluevb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSelectedValue/VB/gridviewselectedvaluevb.aspx" id="Snippet1"::: + ]]> @@ -6136,11 +6134,11 @@ The index of the row to edit. Selects the row to edit in a control. - event. - + event. + ]]> @@ -6173,11 +6171,11 @@ The index of the row to edit. Puts a row in edit mode in a control by using the specified row index. - event. - + event. + ]]> @@ -6210,11 +6208,11 @@ The index of the row on the page to edit. Sets the page index of the control by using the row index. - event. - + event. + ]]> @@ -6246,19 +6244,19 @@ to display the footer row; otherwise, . The default is . - property to specify whether a control displays the footer row. To control the appearance of the footer row, use the property. - - - -## Examples - The following example demonstrates how to use the property to display the footer row in a control. - + property to specify whether a control displays the footer row. To control the appearance of the footer row, use the property. + + + +## Examples + The following example demonstrates how to use the property to display the footer row in a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewShowHeader/CS/gridviewshowheadercs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewShowHeader/VB/gridviewshowheadervb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewShowHeader/VB/gridviewshowheadervb.aspx" id="Snippet1"::: + ]]> @@ -6292,19 +6290,19 @@ to display the header row; otherwise, . The default is . - property to specify whether a control displays the header row. To control the appearance of the header row, use the property. - - - -## Examples - The following example demonstrates how to use the property to display the header row in a control. - + property to specify whether a control displays the header row. To control the appearance of the header row, use the property. + + + +## Examples + The following example demonstrates how to use the property to display the header row in a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewShowHeader/CS/gridviewshowheadercs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewShowHeader/VB/gridviewshowheadervb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewShowHeader/VB/gridviewshowheadervb.aspx" id="Snippet1"::: + ]]> @@ -6370,19 +6368,19 @@ One of the values. Sorts the control based on the specified sort expression and direction. - method to programmatically sort the control using the specified sort expression and direction. The sort expression specifies the column or columns with which to sort. To sort multiple columns, create a sort expression that contains a comma-separated list of field names. The sort direction indicates whether sorting is performed in ascending or descending order. This method is commonly used when you need to sort the control from outside of the control, such as from a different control on the page. This method is also commonly used to programmatically set a default sort order for the control when it is first rendered. Calling this method also raises the and events. - - - -## Examples - The following example demonstrates how to use the method to programmatically sort the control by multiple columns. - + method to programmatically sort the control using the specified sort expression and direction. The sort expression specifies the column or columns with which to sort. To sort multiple columns, create a sort expression that contains a comma-separated list of field names. The sort direction indicates whether sorting is performed in ascending or descending order. This method is commonly used when you need to sort the control from outside of the control, such as from a different control on the page. This method is also commonly used to programmatically set a default sort order for the control when it is first rendered. Calling this method also raises the and events. + + + +## Examples + The following example demonstrates how to use the method to programmatically sort the control by multiple columns. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewSort/CS/GridViewSortcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSort/VB/GridViewSortvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSort/VB/GridViewSortvb.aspx" id="Snippet1"::: + ]]> The control is bound to a data source control, but the that is associated with the data source is . @@ -6437,22 +6435,22 @@ Gets the sort direction of the column being sorted. One of the values. The default is . - property to determine whether the column being sorted is sorted in ascending or descending order. - + property to determine whether the column being sorted is sorted in ascending or descending order. + > [!NOTE] -> The control has a built-in sorting feature that automatically sets this property. This property is typically used only when you need to programmatically determine the sort direction or when you are adding your own custom sorting functionality to a control. - - - -## Examples - The following example demonstrates how to use the property to programmatically determine the sort direction of a control. - +> The control has a built-in sorting feature that automatically sets this property. This property is typically used only when you need to programmatically determine the sort direction or when you are adding your own custom sorting functionality to a control. + + + +## Examples + The following example demonstrates how to use the property to programmatically determine the sort direction of a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/gridviewfooterrow/CS/gridviewfooterrowcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/gridviewfooterrow/VB/gridviewfooterrowvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/gridviewfooterrow/VB/gridviewfooterrowvb.aspx" id="Snippet1"::: + ]]> @@ -6479,21 +6477,21 @@ Occurs when the hyperlink to sort a column is clicked, but after the control handles the sort operation. - event is raised when the hyperlink to sort a column is clicked, but after the control handles the sort operation. This enables you to provide an event-handling method that performs a custom routine, such as custom sorting, whenever this event occurs. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following example demonstrates how to use the event to display the name of the column being sorted. - + event is raised when the hyperlink to sort a column is clicked, but after the control handles the sort operation. This enables you to provide an event-handling method that performs a custom routine, such as custom sorting, whenever this event occurs. + + For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + The following example demonstrates how to use the event to display the name of the column being sorted. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewSorting/CS/gridviewsortingcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSorting/VB/gridviewsortingvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSorting/VB/gridviewsortingvb.aspx" id="Snippet1"::: + ]]> @@ -6538,11 +6536,11 @@ if a style is applied to the control when the column is sorted in ascending order; otherwise, . - @@ -6581,11 +6579,11 @@ if a style is applied to the heading when the column is sorted in ascending order; otherwise, . - @@ -6624,11 +6622,11 @@ if a style is applied to the when the column is sorted in descending order; otherwise, . - @@ -6667,11 +6665,11 @@ if a style is applied to the heading when the column is sorted in descending order; otherwise, . - @@ -6710,24 +6708,24 @@ Gets the sort expression associated with the column or columns being sorted. The sort expression associated with the column or columns being sorted. - property to determine the sort expression associated with the column or columns being sorted. - + property to determine the sort expression associated with the column or columns being sorted. + > [!NOTE] -> The control has a built-in sorting feature that automatically sets this property. This property is typically used only when you need to programmatically determine the column or columns being sorted or when you are adding your own custom sorting functionality to a control. - - When multiple columns are sorted, this property contains a comma-separated list of the fields by which to sort. - - - -## Examples - The following example demonstrates how to use the property to determine the name of the column being sorted. - +> The control has a built-in sorting feature that automatically sets this property. This property is typically used only when you need to programmatically determine the column or columns being sorted or when you are adding your own custom sorting functionality to a control. + + When multiple columns are sorted, this property contains a comma-separated list of the fields by which to sort. + + + +## Examples + The following example demonstrates how to use the property to determine the name of the column being sorted. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewAllowSortingColumns/CS/GridViewAllowSortingColumnscs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewAllowSortingColumns/VB/GridViewAllowSortingColumnsvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewAllowSortingColumns/VB/GridViewAllowSortingColumnsvb.aspx" id="Snippet1"::: + ]]> @@ -6753,30 +6751,30 @@ Occurs when the hyperlink to sort a column is clicked, but before the control handles the sort operation. - event is raised when the hyperlink to sort a column is clicked, but before the control handles the sort operation. This enables you to provide an event-handling method that performs a custom routine, such as canceling the sorting operation, whenever this event occurs. - - A object is passed to the event-handling method, which enables you to determine the sort expression for the column and to indicate that the selection operation should be canceled. To cancel the selection operation, set the property of the object to `true`. - - For information about how to programmatically initiate a sort operation, see the method. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following example demonstrates how to use the event to perform the sorting functionality when the control is bound to a object by setting the property programmatically. - + event is raised when the hyperlink to sort a column is clicked, but before the control handles the sort operation. This enables you to provide an event-handling method that performs a custom routine, such as canceling the sorting operation, whenever this event occurs. + + A object is passed to the event-handling method, which enables you to determine the sort expression for the column and to indicate that the selection operation should be canceled. To cancel the selection operation, set the property of the object to `true`. + + For information about how to programmatically initiate a sort operation, see the method. + + For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + The following example demonstrates how to use the event to perform the sorting functionality when the control is bound to a object by setting the property programmatically. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewSorting/CS/gridviewsorting2cs.aspx" id="Snippet2"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSorting/VB/gridviewsorting2vb.aspx" id="Snippet2"::: - - The following example demonstrates how to use the event to cancel a sorting operation. - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSorting/VB/gridviewsorting2vb.aspx" id="Snippet2"::: + + The following example demonstrates how to use the event to cancel a sorting operation. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewSorting/CS/gridviewsortingcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSorting/VB/gridviewsortingvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewSorting/VB/gridviewsortingvb.aspx" id="Snippet1"::: + ]]> @@ -6818,11 +6816,11 @@ Returns the result of a callback event that targets a control. The results of the callback. - control implements the interface and uses the to asynchronously retrieve data and the method to return the retrieved data to the control. - + control implements the interface and uses the to asynchronously retrieve data and the method to return the retrieved data to the control. + ]]> @@ -6859,11 +6857,11 @@ The argument to pass to the event handler. Creates the arguments for the callback handler in the method. - is a helper method that is used by the control to create the arguments for the callback handler in the method. - + is a helper method that is used by the control to create the arguments for the callback handler in the method. + ]]> @@ -6897,11 +6895,11 @@ Gets the data values that are used to uniquely identify each instance of a data-bound control when ASP.NET generates the value. The data values that are used to uniquely identify each instance of a data-bound control when ASP.NET generates the value. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -6938,14 +6936,14 @@ The event argument from which to create a for the event or events that are raised. Raises the appropriate events for the control when it posts back to the server. - method when a postback event occurs to raise the appropriate events for a control. This call occurs in the page life cycle after loading and change notification are complete, but before prerendering occurs. This method has been implemented to create a object for the event or events that are raised. - + method when a postback event occurs to raise the appropriate events for a control. This call occurs in the page life cycle after loading and change notification are complete, but before prerendering occurs. This method has been implemented to create a object for the event or events that are raised. + > [!NOTE] -> This method is used primarily by control developers to extend the control. - +> This method is used primarily by control developers to extend the control. + ]]> @@ -6988,11 +6986,11 @@ Creates the callback script for a button that performs a sorting operation. The callback script for a button that performs a sorting operation. - is a helper method that is used by the control to create the callback script for a button that performs a sorting operation. - + is a helper method that is used by the control to create the callback script for a button that performs a sorting operation. + ]]> @@ -7030,15 +7028,15 @@ Gets or sets the names of the primary key fields for the items displayed in a data-bound control. An array that contains the names of the primary-key fields for the items that are displayed in a control. - instance is cast to an interface. - - This property provides access to the property of the control. It is exposed through the Interface. - - ASP.NET Dynamic Data supports this property. - + instance is cast to an interface. + + This property provides access to the property of the control. It is exposed through the Interface. + + ASP.NET Dynamic Data supports this property. + ]]> @@ -7065,15 +7063,15 @@ Gets or sets the table that is exposed by the data source control to bind to the data-bound control. The table that is exposed by the data source control to bind to the data-bound control. - instance is cast to an interface. - - If the data source contains multiple sources of data, use this property to set the specific data table, collection, or other data for the control to bind to. For example, if the data source is a instance that contains multiple tables, you can specify which table to bind the control to by using this property. - - ASP.NET Dynamic Data supports this property. - + instance is cast to an interface. + + If the data source contains multiple sources of data, use this property to set the specific data table, collection, or other data for the control to bind to. For example, if the data source is a instance that contains multiple tables, you can specify which table to bind the control to by using this property. + + ASP.NET Dynamic Data supports this property. + ]]> @@ -7100,13 +7098,13 @@ Gets or sets the data source object from which the data-bound control retrieves the list of data items. The data source object that the data-bound control uses. - instance is cast to an interface. - - ASP.NET Dynamic Data supports this property. - + instance is cast to an interface. + + ASP.NET Dynamic Data supports this property. + ]]> @@ -7133,13 +7131,13 @@ Gets or sets the ID of the data source from which the data-bound control retrieves the list of data items. The ID of the data source from which the data-bound control retrieves data items. - instance is cast to an interface. - - ASP.NET Dynamic Data supports this property. - + instance is cast to an interface. + + ASP.NET Dynamic Data supports this property. + ]]> @@ -7166,13 +7164,13 @@ Gets or sets the data source object from which the data-bound control retrieves the list of data items. The data source object from which the data-bound control retrieves the list of data items. - instance is cast to an interface. - - ASP.NET Dynamic Data supports this property. - + instance is cast to an interface. + + ASP.NET Dynamic Data supports this property. + ]]> @@ -7209,11 +7207,11 @@ Gets or sets the names of the data fields whose values are appended to the property value to uniquely identify each instance of a data-bound control. The names of the data fields whose values are used to uniquely identify each instance of a data-bound control when ASP.NET generates the value. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -7246,13 +7244,13 @@ Gets a collection of objects that represent the value in a data-bound control. An array that contains the data key of each row in a data-bound control. - instance is cast to an interface. - - ASP.NET Dynamic Data supports this property. - + instance is cast to an interface. + + ASP.NET Dynamic Data supports this property. + ]]> @@ -7290,13 +7288,13 @@ if the row selection is based on data-key values; otherwise, . - instance is cast to an interface. - - ASP.NET Dynamic Data supports this property. - + instance is cast to an interface. + + ASP.NET Dynamic Data supports this property. + ]]> @@ -7329,13 +7327,13 @@ Gets the object that contains the data key value for the selected row in a data-bound control. The data-key value for the selected row. - instance is cast to an interface. - - ASP.NET Dynamic Data supports this property. - + instance is cast to an interface. + + ASP.NET Dynamic Data supports this property. + ]]> @@ -7372,13 +7370,13 @@ Gets or sets the index of the selected row in the data-bound control. The index of the selected row in the data-bound control. - instance is cast to an interface. - - ASP.NET Dynamic Data supports this property. - + instance is cast to an interface. + + ASP.NET Dynamic Data supports this property. + ]]> @@ -7415,13 +7413,13 @@ Gets or sets the control that automatically generates the columns for a data-bound control for use by ASP.NET Dynamic Data. The control that automatically generates the columns for a data-bound control. - instance is cast to an interface. - - ASP.NET Dynamic Data supports this property. - + instance is cast to an interface. + + ASP.NET Dynamic Data supports this property. + ]]> @@ -7459,14 +7457,14 @@ For a description of this member, see . The data-key value for the persisted selected record in a data-bound control. - control is in paging mode. By default, row selection is based on row index. The same row (for example, the third row) is selected on each page. Alternatively, you can enable persistence based on the data key of the selected row. In that case, if you select row 3 on page 1 and you move to page 2, no row is selected on page 2. If you move back to page 1, row 3 is still selected. To enable this functionality, set this property to `true`. - + control is in paging mode. By default, row selection is based on row index. The same row (for example, the third row) is selected on each page. Alternatively, you can enable persistence based on the data key of the selected row. In that case, if you select row 3 on page 1 and you move to page 2, no row is selected on page 2. If you move back to page 1, row 3 is still selected. To enable this functionality, set this property to `true`. + > [!NOTE] -> In versions 2.0, 3.0, and 3.5 of ASP.NET, row selection was based only on row index. By default, row selection in ASP.NET 4 is based on index for backward compatibility. - +> In versions 2.0, 3.0, and 3.5 of ASP.NET, row selection was based only on row index. By default, row selection in ASP.NET 4 is based on index for backward compatibility. + ]]> @@ -7523,11 +7521,11 @@ Gets the value for the control. The value for the control. - property allows the output stream to write the appropriate HTML markup for the control. When the property is set to `true`, this property returns `HtmlTextWriterTag.Div`; otherwise, this property returns `HtmlTextWriterTag.Table`. - + property allows the output stream to write the appropriate HTML markup for the control. When the property is set to `true`, this property returns `HtmlTextWriterTag.Div`; otherwise, this property returns `HtmlTextWriterTag.Table`. + ]]> @@ -7567,24 +7565,24 @@ Gets a object that represents the top pager row in a control. A that represents the top pager row in the control. - property to `true`), an additional row called the pager row is automatically displayed in the control. The pager row contains controls that allow the user to navigate to the other pages and can be displayed at the top, the bottom, or both the top and bottom of the control. Use the property to programmatically access the object that represents the top pager row in a control. - + property to `true`), an additional row called the pager row is automatically displayed in the control. The pager row contains controls that allow the user to navigate to the other pages and can be displayed at the top, the bottom, or both the top and bottom of the control. Use the property to programmatically access the object that represents the top pager row in a control. + > [!NOTE] -> The property is available only after the control creates the top pager row in the event. - - This property is commonly used when you need to programmatically manipulate the top pager row, for example when adding custom content. Any modification to the property must be performed after the control has been rendered; otherwise, the control will overwrite any changes. - - - -## Examples - The following example demonstrates how to use the property to access the top pager row in a control. The property is used to retrieve a control from the pager row. - +> The property is available only after the control creates the top pager row in the event. + + This property is commonly used when you need to programmatically manipulate the top pager row, for example when adding custom content. Any modification to the property must be performed after the control has been rendered; otherwise, the control will overwrite any changes. + + + +## Examples + The following example demonstrates how to use the property to access the top pager row in a control. The property is used to retrieve a control from the pager row. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewTopPagerRow/CS/gridviewtoppagerrowcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewTopPagerRow/VB/gridviewtoppagerrowvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewTopPagerRow/VB/gridviewtoppagerrowvb.aspx" id="Snippet1"::: + ]]> @@ -7614,11 +7612,11 @@ Tracks view-state changes to the control so they can be stored in the control's object. This object is accessible through the property. - @@ -7654,13 +7652,13 @@ Gets or sets the name of the method to call in order to update data. The name of the method. - @@ -7691,24 +7689,24 @@ to perform page validation when this method is called; otherwise, . Updates the record at the specified row index using the field values of the row. - method to programmatically update the record at the specified index in the data source. This method is commonly used when you need to update a record from outside of the control, such as from a different control on the page. - + method to programmatically update the record at the specified index in the data source. This method is commonly used when you need to update a record from outside of the control, such as from a different control on the page. + > [!NOTE] -> This method can be called only for the row that is currently in edit mode, or for a row that contains a two-way data-bound input control. For more information about two-way binding expressions, see [Binding to Databases](https://learn.microsoft.com/previous-versions/aspnet/ms178361(v=vs.100)). - - To specify whether page validation is performed before the update operation, use the `causesValidation` parameter. Calling this method also raises the and events. - - - -## Examples - The following example demonstrates how to use the method to programmatically update a record in a control. - +> This method can be called only for the row that is currently in edit mode, or for a row that contains a two-way data-bound input control. For more information about two-way binding expressions, see [Binding to Databases](https://learn.microsoft.com/previous-versions/aspnet/ms178361(v=vs.100)). + + To specify whether page validation is performed before the update operation, use the `causesValidation` parameter. Calling this method also raises the and events. + + + +## Examples + The following example demonstrates how to use the method to programmatically update a record in a control. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewUpdateRow/CS/GridViewUpdateRowcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewUpdateRow/VB/GridViewUpdateRowvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewUpdateRow/VB/GridViewUpdateRowvb.aspx" id="Snippet1"::: + ]]> The control is bound to a data source control, but the associated with the data source is . @@ -7743,21 +7741,21 @@ if the control renders its header in an accessible format; otherwise, . The default is . - property to specify whether the control renders its header row in an accessible format. This property is provided to make the control more accessible to users of assistive technology devices. By default, the value of this property is `true` and the header for the control is rendered using `` table header cell tags. In addition, a `scope="col"` attribute is added to the table header to specify that the header applies to all the cells in the column. The default rendering of the `` element is preserved, rendering text as bold and centered horizontally. Developers can override the style of the `` element using a cascading style sheet. - - If the value of this property is `false`, the header for the control is rendered using `` table cell tags. - - - -## Examples - The following example demonstrates how to use the property to disable the accessible header. - + property to specify whether the control renders its header row in an accessible format. This property is provided to make the control more accessible to users of assistive technology devices. By default, the value of this property is `true` and the header for the control is rendered using `` table header cell tags. In addition, a `scope="col"` attribute is added to the table header to specify that the header applies to all the cells in the column. The default rendering of the `` element is preserved, rendering text as bold and centered horizontally. Developers can override the style of the `` element using a cascading style sheet. + + If the value of this property is `false`, the header for the control is rendered using `` table cell tags. + + + +## Examples + The following example demonstrates how to use the property to disable the accessible header. + :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/GridViewUseAccessibleHeader/CS/gridviewuseaccessibleheadercs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewUseAccessibleHeader/VB/gridviewuseaccessibleheadervb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/GridViewUseAccessibleHeader/VB/gridviewuseaccessibleheadervb.aspx" id="Snippet1"::: + ]]> @@ -7794,11 +7792,11 @@ Gets or sets the virtual number of items in the data source that the control is bound to when custom paging is used. The virtual number of items in the data source that the control is bound to when custom paging is used. - property is `true`. For more information, see the property. - + property is `true`. For more information, see the property. + ]]> From 1c1c32d2318319dedd4b83c0c41cb99cfe751d13 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 22 Jan 2025 17:48:50 -1000 Subject: [PATCH 3/4] Update BoundField.xml (#10865) Fixes #10855 --- xml/System.Web.UI.WebControls/BoundField.xml | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/xml/System.Web.UI.WebControls/BoundField.xml b/xml/System.Web.UI.WebControls/BoundField.xml index bfd70f6a7a9..f3032cac0b5 100644 --- a/xml/System.Web.UI.WebControls/BoundField.xml +++ b/xml/System.Web.UI.WebControls/BoundField.xml @@ -9,6 +9,7 @@ System.Web 2.0.0.0 4.0.0.0 + System.Web.UI.WebControls.DataControlField @@ -422,19 +423,6 @@ For more information and for examples that show formatting for other culture values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings). You can also create custom date and time format strings. For more information, see [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). - - -## Examples - A Visual Studio Web site project with source code is available to accompany this topic: [Download](https://go.microsoft.com/fwlink/?LinkId=191889). - - The following example shows how to use the property to specify a custom display format for the values of a field. - - The following example shows one row of the output that is produced by this example. - -|ProductID|Name|ProductNumber|ListPrice|Weight|ModifiedDate| -|---------------|----------|-------------------|---------------|------------|------------------| -|`000680`|`HL Road Frame - Black, 58`|`#FR-R92B-58`|`$1,431.50`|`1016.040`|`3/11/2004`| - ]]> From 1d13d52f5317080fb3d7adda55472283f572a637 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 22 Jan 2025 20:28:25 -0800 Subject: [PATCH 4/4] Fix up see also links (#10860) --- ...lumnEncryptionCertificateStoreProvider.xml | 6 +- .../SqlColumnEncryptionCngProvider.xml | 22 +- .../SqlColumnEncryptionCspProvider.xml | 22 +- .../SqlColumnEncryptionKeyStoreProvider.xml | 20 +- .../SqlCommandColumnEncryptionSetting.xml | 18 +- .../SqlConnectionColumnEncryptionSetting.xml | 2 +- xml/System.Data/DataTable.xml | 8 +- .../EventLogSession.xml | 8 +- .../EventMetadata.xml | 4 +- xml/System.Drawing/Graphics.xml | 16 +- xml/System.IO.Packaging/PackWebResponse.xml | 74 +- xml/System.Net.Http/HttpClient.xml | 4 +- xml/System.Net.Http/HttpClientHandler.xml | 9 +- .../Peer.xml | 246 +- xml/System.Net.PeerToPeer/PnrpPermission.xml | 134 +- .../PrintTicketConverter.xml | 4 +- .../EnumeratedPrintQueueTypes.xml | 30 +- xml/System.Printing/PrintQueue.xml | 38 +- xml/System.Printing/PrintTicket.xml | 60 +- .../IStream.xml | 4 +- .../ReadOnlyArrayAttribute.xml | 38 +- .../ReturnValueNameAttribute.xml | 114 +- .../WriteOnlyArrayAttribute.xml | 38 +- .../DefaultDllImportSearchPathsAttribute.xml | 44 +- .../Marshal.xml | 8 +- .../ECCurve+NamedCurves.xml | 34 +- .../SrgsRule.xml | 2 +- xml/System.Speech.Recognition/Choices.xml | 660 +++--- xml/System.Speech.Recognition/Grammar.xml | 2022 ++++++++--------- xml/System.Threading.Tasks/Parallel.xml | 4 +- xml/System.Threading.Tasks/Task.xml | 8 +- .../TaskCanceledException.xml | 4 +- .../TaskCreationOptions.xml | 12 +- xml/System.Threading.Tasks/TaskFactory.xml | 1610 ++++++------- .../TaskSchedulerException.xml | 2 +- xml/System.Threading.Tasks/Task`1.xml | 618 ++--- .../BarrierPostPhaseException.xml | 2 +- .../XhtmlControlAdapter.xml | 4 +- xml/System/AggregateException.xml | 2 +- xml/System/Exception.xml | 2 +- xml/ns-System.IO.Packaging.xml | 79 +- xml/ns-System.Net.Http.xml | 3 +- xml/ns-System.Printing.Interop.xml | 14 +- xml/ns-System.Speech.Synthesis.TtsEngine.xml | 50 +- 44 files changed, 3046 insertions(+), 3057 deletions(-) diff --git a/xml/System.Data.SqlClient/SqlColumnEncryptionCertificateStoreProvider.xml b/xml/System.Data.SqlClient/SqlColumnEncryptionCertificateStoreProvider.xml index fd16df14ff6..ca04b762069 100644 --- a/xml/System.Data.SqlClient/SqlColumnEncryptionCertificateStoreProvider.xml +++ b/xml/System.Data.SqlClient/SqlColumnEncryptionCertificateStoreProvider.xml @@ -21,7 +21,7 @@ The implementation of the key store provider for Windows Certificate Store. This class enables using certificates stored in the Windows Certificate Store as column master keys. For details, see Always Encrypted. To be added. Get started with Always Encrypted (blog post) - Develop apps using Always Encrypted + Develop apps using Always Encrypted @@ -66,7 +66,7 @@ The encryption algorithm. Currently, the only valid value is: RSA_OAEP. The encrypted column encryption key. Decrypts the specified encrypted value of a column encryption key. The encrypted value is expected to be encrypted using the certificate with the specified key path and using the specified algorithm. The format of the key path should be "Local Machine/My/<certificate_thumbprint>" or "Current User/My/<certificate_thumbprint>". - Returns . + Returns . The decrypted column encryption key. To be added. @@ -96,7 +96,7 @@ The decrypted column encryption key. The encryption algorithm. Currently, the only valid value is: RSA_OAEP. The encrypted column encryption key. Encrypts a column encryption key using the certificate with the specified key path and using the specified algorithm. The format of the key path should be "Local Machine/My/<certificate_thumbprint>" or "Current User/My/<certificate_thumbprint>". - Returns . + Returns . The encrypted column encryption key. To be added. diff --git a/xml/System.Data.SqlClient/SqlColumnEncryptionCngProvider.xml b/xml/System.Data.SqlClient/SqlColumnEncryptionCngProvider.xml index 71fb3cde08b..37cbdc9c76e 100644 --- a/xml/System.Data.SqlClient/SqlColumnEncryptionCngProvider.xml +++ b/xml/System.Data.SqlClient/SqlColumnEncryptionCngProvider.xml @@ -16,15 +16,15 @@ The CMK Store provider implementation for using the Microsoft Cryptography API: Next Generation (CNG) with Always Encrypted. - Get started with Always Encrypted (blog post) - Develop apps using Always Encrypted + Develop apps using Always Encrypted @@ -148,11 +148,11 @@ Throws a exception in all cases. The signature of the column master key metadata. - method must be implemented by the corresponding key store providers. should use an asymmetric key identified by a key path and sign the masterkey metadata consisting of `masterKeyPath`, `allowEnclaveComputations`, and providerName. - + method must be implemented by the corresponding key store providers. should use an asymmetric key identified by a key path and sign the masterkey metadata consisting of `masterKeyPath`, `allowEnclaveComputations`, and providerName. + ]]> In all cases. diff --git a/xml/System.Data.SqlClient/SqlColumnEncryptionCspProvider.xml b/xml/System.Data.SqlClient/SqlColumnEncryptionCspProvider.xml index 8252058876d..47476d07bb1 100644 --- a/xml/System.Data.SqlClient/SqlColumnEncryptionCspProvider.xml +++ b/xml/System.Data.SqlClient/SqlColumnEncryptionCspProvider.xml @@ -16,15 +16,15 @@ The CMK Store provider implementation for using Microsoft CAPI based Cryptographic Service Providers (CSP) with Always Encrypted. - Get started with Always Encrypted (blog post) - Develop apps using Always Encrypted + Develop apps using Always Encrypted @@ -148,11 +148,11 @@ Throws a exception in all cases. The signature of the column master key metadata. - method must be implemented by the corresponding key store providers. should use an asymmetric key identified by a key path and sign the masterkey metadata consisting of `masterKeyPath`, `allowEnclaveComputations`, and providerName. - + method must be implemented by the corresponding key store providers. should use an asymmetric key identified by a key path and sign the masterkey metadata consisting of `masterKeyPath`, `allowEnclaveComputations`, and providerName. + ]]> In all cases. diff --git a/xml/System.Data.SqlClient/SqlColumnEncryptionKeyStoreProvider.xml b/xml/System.Data.SqlClient/SqlColumnEncryptionKeyStoreProvider.xml index 162fedc8f27..7b47d76c9ac 100644 --- a/xml/System.Data.SqlClient/SqlColumnEncryptionKeyStoreProvider.xml +++ b/xml/System.Data.SqlClient/SqlColumnEncryptionKeyStoreProvider.xml @@ -17,7 +17,7 @@ Base class for all key store providers. A custom provider must derive from this class and override its member functions and then register it using SqlConnection.RegisterColumnEncryptionKeyStoreProviders(). For details see, Always Encrypted. To be added. Get started with Always Encrypted (blog post) - Develop apps using Always Encrypted + Develop apps using Always Encrypted @@ -62,7 +62,7 @@ The encryption algorithm. The encrypted column encryption key. Decrypts the specified encrypted value of a column encryption key. The encrypted value is expected to be encrypted using the column master key with the specified key path and using the specified algorithm. - Returns . + Returns . The decrypted column encryption key. To be added. @@ -92,7 +92,7 @@ The decrypted column encryption key. The encryption algorithm. The encrypted column encryption key. Encrypts a column encryption key using the column master key with the specified key path and using the specified algorithm. - Returns . + Returns . The encrypted column encryption key. To be added. @@ -123,13 +123,13 @@ The encrypted column encryption key. When implemented in a derived class, digitally signs the column master key metadata with the column master key referenced by the parameter. The input values used to generate the signature should be the specified values of the and parameters. The signature of the column master key metadata. - method doesn't break applications that rely on an old API, it throws a exception by default. - - The method will be used by client tools that generate Column Master Keys (CMK) for customers. must be implemented by the corresponding key store providers that wish to use enclaves with [Always Encrypted](https://learn.microsoft.com/sql/relational-databases/security/encryption/always-encrypted-database-engine). - + method doesn't break applications that rely on an old API, it throws a exception by default. + + The method will be used by client tools that generate Column Master Keys (CMK) for customers. must be implemented by the corresponding key store providers that wish to use enclaves with [Always Encrypted](https://learn.microsoft.com/sql/relational-databases/security/encryption/always-encrypted-database-engine). + ]]> In all cases. diff --git a/xml/System.Data.SqlClient/SqlCommandColumnEncryptionSetting.xml b/xml/System.Data.SqlClient/SqlCommandColumnEncryptionSetting.xml index 132d02cba41..9c36ba0767b 100644 --- a/xml/System.Data.SqlClient/SqlCommandColumnEncryptionSetting.xml +++ b/xml/System.Data.SqlClient/SqlCommandColumnEncryptionSetting.xml @@ -16,18 +16,18 @@ Specifies how data will be sent and received when reading and writing encrypted columns. Depending on your specific query, performance impact may be reduced by bypassing the Always Encrypted driver's processing when non-encrypted columns are being used. Note that these settings cannot be used to bypass encryption and gain access to plaintext data. For details, see Always Encrypted (Database Engine). - Getting Started with Always Encrypted (blog post) - Always Encrypted (client development) + Always Encrypted (client development) diff --git a/xml/System.Data.SqlClient/SqlConnectionColumnEncryptionSetting.xml b/xml/System.Data.SqlClient/SqlConnectionColumnEncryptionSetting.xml index 260ee7c1737..ea46907dce4 100644 --- a/xml/System.Data.SqlClient/SqlConnectionColumnEncryptionSetting.xml +++ b/xml/System.Data.SqlClient/SqlConnectionColumnEncryptionSetting.xml @@ -17,7 +17,7 @@ Specifies that Always Encrypted functionality is enabled in a connection. Note that these settings cannot be used to bypass encryption and gain access to plaintext data. For details, see Always Encrypted (Database Engine). To be added. Getting Started with Always Encrypted (blog post) - Always Encrypted (client development) + Always Encrypted (client development) diff --git a/xml/System.Data/DataTable.xml b/xml/System.Data/DataTable.xml index 6f61f213023..5ba2591a9c3 100644 --- a/xml/System.Data/DataTable.xml +++ b/xml/System.Data/DataTable.xml @@ -6046,7 +6046,7 @@ public class A { DataTables - Null Values + Null Values @@ -6124,7 +6124,7 @@ To ensure the proper sort order, specify sort criteria with DataTables - Null Values + Null Values @@ -6195,7 +6195,7 @@ To ensure the proper sort order, specify sort criteria with DataTables - Null Values + Null Values @@ -6267,7 +6267,7 @@ To ensure the proper sort order, specify sort criteria with DataTables - Null Values + Null Values diff --git a/xml/System.Diagnostics.Eventing.Reader/EventLogSession.xml b/xml/System.Diagnostics.Eventing.Reader/EventLogSession.xml index fe5b1b664df..5b82ab49976 100644 --- a/xml/System.Diagnostics.Eventing.Reader/EventLogSession.xml +++ b/xml/System.Diagnostics.Eventing.Reader/EventLogSession.xml @@ -592,8 +592,8 @@ ]]> - Technology Summary for Reading and Managing Event Logs - Event Log Scenarios + Technology Summary for Reading and Managing Event Logs + Event Log Scenarios @@ -647,8 +647,8 @@ ]]> - Technology Summary for Reading and Managing Event Logs - Event Log Scenarios + Technology Summary for Reading and Managing Event Logs + Event Log Scenarios diff --git a/xml/System.Diagnostics.Eventing.Reader/EventMetadata.xml b/xml/System.Diagnostics.Eventing.Reader/EventMetadata.xml index d55b5b1562b..5a3676ce62a 100644 --- a/xml/System.Diagnostics.Eventing.Reader/EventMetadata.xml +++ b/xml/System.Diagnostics.Eventing.Reader/EventMetadata.xml @@ -157,8 +157,8 @@ ]]> - Technology Summary for Reading and Managing Event Logs - Event Log Scenarios + Technology Summary for Reading and Managing Event Logs + Event Log Scenarios diff --git a/xml/System.Drawing/Graphics.xml b/xml/System.Drawing/Graphics.xml index 4e7f2caf425..417dca4e84b 100644 --- a/xml/System.Drawing/Graphics.xml +++ b/xml/System.Drawing/Graphics.xml @@ -60,13 +60,13 @@ [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.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](/dotnet/framework/winforms/advanced/how-to-create-graphics-objects-for-drawing). + 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](https://learn.microsoft.com/dotnet/framework/winforms/advanced/how-to-create-graphics-objects-for-drawing). - 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](/dotnet/desktop/winforms/advanced/using-a-pen-to-draw-lines-and-shapes) and [Using a Brush to Fill Shapes](/dotnet/framework/winforms/advanced/using-a-brush-to-fill-shapes). + 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](https://learn.microsoft.com/dotnet/desktop/winforms/advanced/using-a-pen-to-draw-lines-and-shapes) and [Using a Brush to Fill Shapes](https://learn.microsoft.com/dotnet/framework/winforms/advanced/using-a-brush-to-fill-shapes). - You can also draw images and icons by using the and methods, respectively. To perform a bit-block transfer of color data from the screen to the drawing surface of the object, see . For more information about how to draw images with a object, see [Working with Images, Bitmaps, Icons, and Metafiles](/dotnet/desktop/winforms/advanced/images-bitmaps-and-metafiles). + You can also draw images and icons by using the and methods, respectively. To perform a bit-block transfer of color data from the screen to the drawing surface of the object, see . For more information about how to draw images with a object, see [Working with Images, Bitmaps, Icons, and Metafiles](https://learn.microsoft.com/dotnet/desktop/winforms/advanced/images-bitmaps-and-metafiles). - In addition, you can manipulate the coordinate system used by the object. For more information on the coordinate system and how to manipulate it, see [Coordinate Systems and Transformations](/dotnet/framework/winforms/advanced/coordinate-systems-and-transformations). + In addition, you can manipulate the coordinate system used by the object. For more information on the coordinate system and how to manipulate it, see [Coordinate Systems and Transformations](https://learn.microsoft.com/dotnet/framework/winforms/advanced/coordinate-systems-and-transformations). ## Examples The following code example is designed for use with Windows Forms and requires a object. The object is named `e` and is a parameter of the event handler. The code performs the following actions: @@ -1002,7 +1002,7 @@ The following code example is designed for use with Windows Forms, and it requir ## Remarks For more information about creating high-resolution applications, see - [High DPI](https://go.microsoft.com/fwlink/?LinkId=159804). + [High DPI](https://learn.microsoft.com/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows). @@ -1015,7 +1015,7 @@ The following code example is designed for use with Windows Forms, and it requir ]]> - High DPI + High DPI @@ -1054,7 +1054,7 @@ The following code example is designed for use with Windows Forms, and it requir ## Remarks For more information about creating high-resolution applications, see - [High DPI](https://go.microsoft.com/fwlink/?LinkId=159804). + [High DPI](https://learn.microsoft.com/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows). @@ -1067,7 +1067,7 @@ The following code example is designed for use with Windows Forms, and it requir ]]> - High DPI + High DPI diff --git a/xml/System.IO.Packaging/PackWebResponse.xml b/xml/System.IO.Packaging/PackWebResponse.xml index 7f59b81a14d..673c9202f04 100644 --- a/xml/System.IO.Packaging/PackWebResponse.xml +++ b/xml/System.IO.Packaging/PackWebResponse.xml @@ -23,17 +23,16 @@ Represents a response of a . - - The Addressing Model of the Open Packaging Conventions @@ -67,11 +66,11 @@ Closes the stream for this request. - @@ -101,13 +100,13 @@ Gets the content length of the response. The content length, in bytes. - [!NOTE] -> Checking this property on an actual Web request and matching response has performance implications because in some circumstances it requires that the whole response stream is read. - +> Checking this property on an actual Web request and matching response has performance implications because in some circumstances it requires that the whole response stream is read. + ]]> @@ -137,19 +136,19 @@ Gets the Multipurpose Internet Mail Extensions (MIME) content type of the response stream's content. The MIME type of the stream's content. - value, the value is returned. - -2. If the requested part contains no value but the stream name contains a recognized MIME extension type, the MIME type corresponding to the extension is returned. - -3. If the requested part does not contain a value nor a recognized MIME extension type, returns an empty string. - + value, the value is returned. + +2. If the requested part contains no value but the stream name contains a recognized MIME extension type, the MIME type corresponding to the extension is returned. + +3. If the requested part does not contain a value nor a recognized MIME extension type, returns an empty string. + ]]> @@ -273,11 +272,11 @@ Gets the inner object for the response. The response data as a . - returns `null` when the response is from the package cache (when is `true`). - + returns `null` when the response is from the package cache (when is `true`). + ]]> @@ -335,7 +334,6 @@ Gets the uniform resource identifier (URI) of the response. The URI of the response. To be added. - The Addressing Model of the Open Packaging Conventions diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index 9820a116965..dd8e06f9136 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -51,8 +51,8 @@ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.net.http.httpclient/vb/source.vb" id="Snippet1"::: ]]> - Guidelines for using HttpClient - HttpClient Sample + Guidelines for using HttpClient + HttpClient Sample diff --git a/xml/System.Net.Http/HttpClientHandler.xml b/xml/System.Net.Http/HttpClientHandler.xml index a0f8c8586f4..2c11ac7239e 100644 --- a/xml/System.Net.Http/HttpClientHandler.xml +++ b/xml/System.Net.Http/HttpClientHandler.xml @@ -49,11 +49,10 @@ :::code language="csharp" source="~/snippets/csharp/System.Net.Http/HttpClientHandler/Overview/source.cs" id="Snippet1"::: ]]> - Connecting to a web service - Quickstart: Connecting using HttpClient - How to use HttpClient handlers - How to secure HttpClient connections - HttpClient Sample + Connecting to a web service + Quickstart: Connecting using HttpClient + How to use HttpClient handlers + How to secure HttpClient connections diff --git a/xml/System.Net.PeerToPeer.Collaboration/Peer.xml b/xml/System.Net.PeerToPeer.Collaboration/Peer.xml index ed51c9bbbdb..85ca2b420f9 100644 --- a/xml/System.Net.PeerToPeer.Collaboration/Peer.xml +++ b/xml/System.Net.PeerToPeer.Collaboration/Peer.xml @@ -33,18 +33,18 @@ This class represents a remote peer. - class is to provide a common base class definition that can be shared by derived classes, such as and . It cannot be directly constructed, since it is abstract. Developers should use the subclasses `PeerNearMe` or `PeerContact` instead. - - Contact, peer, remote peer, , , and are synonymous terms, based on context. - - "Calling peer" and "remote peer" are commonly synonymous. Calling peer does not refer to the application calling a given method. - + class is to provide a common base class definition that can be shared by derived classes, such as and . It cannot be directly constructed, since it is abstract. Developers should use the subclasses `PeerNearMe` or `PeerContact` instead. + + Contact, peer, remote peer, , , and are synonymous terms, based on context. + + "Calling peer" and "remote peer" are commonly synonymous. Calling peer does not refer to the application calling a given method. + ]]> - Windows ContactManager class + Windows ContactManager class @@ -69,11 +69,11 @@ Context that provides the means for deserializing the data. Also referred to as the source of the serialized data. Initializes a new instance of the type. - object, subclassed on or . The PeerContact or the PeerNearMe contain unique references to the name of the new peer object. - + object, subclassed on or . The PeerContact or the PeerNearMe contain unique references to the name of the new peer object. + ]]> @@ -168,11 +168,11 @@ if the supplied instance has the same as this peer instance, otherwise, . This method also returns if the peer parameter is . - properties. Usage scenarios do not involve this class directly, but rather the derived or the classes. - + properties. Usage scenarios do not involve this class directly, but rather the derived or the classes. + ]]> @@ -215,13 +215,13 @@ Gets the collection of data objects that were registered by the peer from a local cache. - class. This functionality is not exposed on any other type of peer for security reasons. - - If no objects are found for the endpoint, a collection of size zero (0) is returned. - + class. This functionality is not exposed on any other type of peer for security reasons. + + If no objects are found for the endpoint, a collection of size zero (0) is returned. + ]]> @@ -256,19 +256,19 @@ Gets the collection of data objects from a local cache. The collection for the peer or endpoint specified by this instance. - class. This functionality is not exposed on any other type of peer for security reasons. - - If the peer collaboration session did not instantiate with a of , this method cannot access objects on the local computer. The same is true of the applications registered into the collaboration session. - - The collection of peer objects consists of application, data object, and presence information for the peer or endpoint specified by this instance. If no objects are found for the endpoint, a collection of size zero (0) is returned. If the calling peer is subscribed to this endpoint, the cache is automatically updated; otherwise must be called prior to calling this method. - - The caller is not required to be signed into the collaboration infrastructure for this method to complete successfully. A successful call to or one of the methods must have been completed while the caller was signed in previous to calling this method. - - NOTE: Additional overloads are defined on the class instead of the subclasses and . - + class. This functionality is not exposed on any other type of peer for security reasons. + + If the peer collaboration session did not instantiate with a of , this method cannot access objects on the local computer. The same is true of the applications registered into the collaboration session. + + The collection of peer objects consists of application, data object, and presence information for the peer or endpoint specified by this instance. If no objects are found for the endpoint, a collection of size zero (0) is returned. If the calling peer is subscribed to this endpoint, the cache is automatically updated; otherwise must be called prior to calling this method. + + The caller is not required to be signed into the collaboration infrastructure for this method to complete successfully. A successful call to or one of the methods must have been completed while the caller was signed in previous to calling this method. + + NOTE: Additional overloads are defined on the class instead of the subclasses and . + ]]> The caller is not subscribed to the endpoint or has not yet called . @@ -308,17 +308,17 @@ object associated with the supplied . If an object is not found, a collection of size zero (0) is returned. - class. This functionality is not exposed on any other type of peer for security reasons. - - The collection of peer objects consists of application, data object, and presence information for the peer or endpoint specified by this instance. If no objects are found for the endpoint, a collection of size zero (0) is returned. When the calling peer is subscribed to this endpoint, the cache is automatically updated; otherwise must be called prior to calling this method. - - The caller is not required to be signed into the collaboration infrastructure for this method to complete successfully. A successful call to or one of the methods must have been completed while the caller was signed in previous to calling this method. Calling this method requires a of . This state is created when the collaboration session begins. - - NOTE: Additional overloads are defined on the class instead of the derived classes and . - + class. This functionality is not exposed on any other type of peer for security reasons. + + The collection of peer objects consists of application, data object, and presence information for the peer or endpoint specified by this instance. If no objects are found for the endpoint, a collection of size zero (0) is returned. When the calling peer is subscribed to this endpoint, the cache is automatically updated; otherwise must be called prior to calling this method. + + The caller is not required to be signed into the collaboration infrastructure for this method to complete successfully. A successful call to or one of the methods must have been completed while the caller was signed in previous to calling this method. Calling this method requires a of . This state is created when the collaboration session begins. + + NOTE: Additional overloads are defined on the class instead of the derived classes and . + ]]> The object ID is . @@ -359,13 +359,13 @@ Gets the available presence information for a . A object which contains presence information for an available endpoint if it is available; otherwise, . - of . - + of . + ]]> @@ -409,15 +409,15 @@ Sends an invitation to a to start a specific . A from the peer that received the invitation. - of . This state is created when the Peer Collaboration session begins. - + of . This state is created when the Peer Collaboration session begins. + ]]> - - An error occurred during the invitation process. - + - An error occurred during the invitation process. + - The currently executing application is not registered with the Peer Collaboration infrastructure. @@ -451,18 +451,18 @@ Sends an invitation to a to start a specific . A from the peer that received the invitation. - of . This state is created when the peer collaboration session begins. - + of . This state is created when the peer collaboration session begins. + ]]> The application is not registered for collaboration. is larger than 16,384 bytes. - - An error occurred during the invitation process. - + - An error occurred during the invitation process. + - The currently executing application is not registered with the peer collaboration infrastructure. @@ -501,17 +501,17 @@ User-defined object to pass to the callback of the asynchronous operation for identification. This required parameter must be unique across all asynchronous invitation operations in progress. Begins an asynchronous invitation operation which sends an invitation to a to start a specific . - of . This state is created when the peer collaboration session begins. - + of . This state is created when the peer collaboration session begins. + ]]> is . - - An error occurred during the invitation process. - + - An error occurred during the invitation process. + - The currently executing application is not registered with the collaboration infrastructure. @@ -547,11 +547,11 @@ User-defined object to pass to the callback of the asynchronous operation for identification. This required parameter must be unique across all asynchronous invitation operations in progress. Begins an asynchronous invitation operation which sends an invitation to a to start a specific . - of . This state is created when the peer collaboration session begins. - + of . This state is created when the peer collaboration session begins. + ]]> The application is not registered with the collaboration infrastructure. @@ -559,8 +559,8 @@ is . is larger than 16,384 bytes. - - An error occurred during the invitation process. - + - An error occurred during the invitation process. + - The currently executing application is not registered with the collaboration infrastructure. @@ -596,17 +596,17 @@ User defined object to pass to the callback of the operation for identification. This required parameter must be unique across all asynchronous invitation operations in progress. Cancels the invitation that was sent with the method. - from the peer associated with the InviteAsync request. - - Multiple invitations may be outstanding at any given time. If the method is called when an asynchronous operation identified by the `userToken` is not in existence, an exception is thrown. The `userToken` object must be provided since it is used to track a specific asynchronous call. This host application-supplied object is unique for each invite request. - - When this method is used, the event can still be raised, but the Cancelled property on the associated object will be set to `true`. - - Calling this method requires a of . - + from the peer associated with the InviteAsync request. + + Multiple invitations may be outstanding at any given time. If the method is called when an asynchronous operation identified by the `userToken` is not in existence, an exception is thrown. The `userToken` object must be provided since it is used to track a specific asynchronous call. This host application-supplied object is unique for each invite request. + + When this method is used, the event can still be raised, but the Cancelled property on the associated object will be set to `true`. + + Calling this method requires a of . + ]]> The parameter cannot be . @@ -636,13 +636,13 @@ Raised when the invitation process for a remote peer has completed. - specifies the result of the invitation operation. - - Calling this method requires a of . - + specifies the result of the invitation operation. + + Calling this method requires a of . + ]]> This object has been disposed. @@ -669,8 +669,8 @@ Gets a value specifying if the is currently 'online'. - if the is online at any of the endpoints associated with it; otherwise, . - + if the is online at any of the endpoints associated with it; otherwise, . + Unless specified, the default value for this property is . To be added. The object has been disposed. @@ -702,11 +702,11 @@ The object containing the event data to be passed to delegates associated with the event. Raises the event. - event is raised. - + event is raised. + ]]> @@ -734,11 +734,11 @@ Gets the associated with the . The associated with the . - objects contained in associate with the local contacts for the remote peer. - + objects contained in associate with the local contacts for the remote peer. + ]]> The object has been disposed. @@ -781,13 +781,13 @@ When this property value is set, all events not fired as the result of an asynchronous operation will have the associated event handlers called back on the thread that created the specific . Object that implements the interface and is used by instances of this type for event handler synchronization on the thread that created it. - instance. - + instance. + ]]> The calling object has been disposed. diff --git a/xml/System.Net.PeerToPeer/PnrpPermission.xml b/xml/System.Net.PeerToPeer/PnrpPermission.xml index b5237f18a92..f1e092d3fa0 100644 --- a/xml/System.Net.PeerToPeer/PnrpPermission.xml +++ b/xml/System.Net.PeerToPeer/PnrpPermission.xml @@ -43,23 +43,23 @@ Specifies the values that are used in object permissions. - - PNRP Namespace Provider API + PNRP Namespace Provider API @@ -92,13 +92,13 @@ One of the values in the enumeration. Initializes a new instance of the class with the supplied initial permission state. - @@ -138,13 +138,13 @@ Creates and returns an identical copy of the current . An object with an IPermission interface, whose instance contains a copy of the current instance of . - The parameter is not a valid element. @@ -156,7 +156,7 @@ The parameter's version number is not supported. - PNRP Namespace Provider API + PNRP Namespace Provider API @@ -192,13 +192,13 @@ The parameter's version number is not supported. The XML encoding to use to reconstruct the permission. Reconstructs a security object with a specified state from an XML encoding. - The parameter is not a valid element. @@ -246,19 +246,19 @@ The parameter's version number is not supported. Creates and returns a permission that is the intersection of the current and the specified permission. A new permission that represents the intersection of the current and the specified permission. This new permission is a reference ( in Visual Basic) if the intersection is empty. - object references that are not a `null` reference (Nothing in Visual Basic). - -- X.Intersect(X) returns a value equal to X. - -- X.Intersect(Y) returns the same value as Y.Intersect(X). - -- X.Intersect(a `null` reference (`Nothing` in Visual Basic)) returns a `null` reference (`Nothing` in Visual Basic). - + object references that are not a `null` reference (Nothing in Visual Basic). + +- X.Intersect(X) returns a value equal to X. + +- X.Intersect(Y) returns the same value as Y.Intersect(X). + +- X.Intersect(a `null` reference (`Nothing` in Visual Basic)) returns a `null` reference (`Nothing` in Visual Basic). + ]]> The target parameter is not a reference ( in Visual Basic) and is not an instance of the same class as the current permission. @@ -302,12 +302,12 @@ The parameter's version number is not supported. if the current is a subset of the specified permission; otherwise, . - is a subset of the specified permission if the current permission specifies a set of operations that is wholly contained by the specified permission. For example, a permission that represents access to "*C:\example.txt*" is a subset of a permission that represents access to "*C:\\*". If this method returns `true`, the current permission represents no more access to the protected resource than does the specified permission. -The current is a subset of the specified permission if the current permission specifies a set of operations that is wholly contained by the specified permission. For example, a permission that represents access to "*C:\example.txt*" is a subset of a permission that represents access to "*C:\\*". If this method returns `true`, the current permission represents no more access to the protected resource than does the specified permission. - The following statements are required to be `true` for all implementations of the IsSubsetOf method. X, Y, and Z represent objects that are not a `null` reference (`Nothing` in Visual Basic). - `X.IsSubsetOf(X)` returns `true`. @@ -315,9 +315,9 @@ The following statements are required to be `true` for all implementations of th - `X.IsSubsetOf(Y)` returns the same value as `Y.IsSubsetOf(X)` if and only if X and Y represent the same set of permissions. - If `X.IsSubsetOf(Y)` and `Y.IsSubsetOf(Z)` both return `true`, `X.IsSubsetOf(Z)` returns `true`. - + If X represents an empty object with a permission state of *None*, and Y represents an object that is a `null` reference (`Nothing` in Visual Basic), `X.IsSubsetOf(Y)` returns `true`. If Z is also an empty permission, the compound set operation `X.Union(Z).IsSubsetOf(Y)` also returns `true` because the of two empty permissions is an empty permission. - + ]]> The target parameter is not a reference ( in Visual Basic) and is not an instance of the same class as the current permission. @@ -361,11 +361,11 @@ If X represents an empty object with a permis if the current permission is unrestricted; otherwise, . - @@ -443,19 +443,19 @@ If X represents an empty object with a permis Creates a permission that is the union of the current and the specified permission. A new permission that represents the of the current and the specified permission. - is a permission that represents all the operations represented by both the current and the specified permission. Any demand that passes either permission passes their union. - - The following statements are required to be `true` for all implementations of the Union method. X and Y represent objects that are not a `null` reference (`Nothing` in Visual Basic). - -- X.Union(X) returns an object that has the same value as X. - -- X.Union(Y) returns an object that has the same value as the object returned by Y.Union(X). - -- X.Union(a `null` reference (`Nothing` in Visual Basic)) returns an object that has the same value as X. - + is a permission that represents all the operations represented by both the current and the specified permission. Any demand that passes either permission passes their union. + + The following statements are required to be `true` for all implementations of the Union method. X and Y represent objects that are not a `null` reference (`Nothing` in Visual Basic). + +- X.Union(X) returns an object that has the same value as X. + +- X.Union(Y) returns an object that has the same value as the object returned by Y.Union(X). + +- X.Union(a `null` reference (`Nothing` in Visual Basic)) returns an object that has the same value as X. + ]]> diff --git a/xml/System.Printing.Interop/PrintTicketConverter.xml b/xml/System.Printing.Interop/PrintTicketConverter.xml index 66deda8740f..d7038a0b413 100644 --- a/xml/System.Printing.Interop/PrintTicketConverter.xml +++ b/xml/System.Printing.Interop/PrintTicketConverter.xml @@ -80,7 +80,7 @@ is 0 or less. The converter was unable to bind to . - Print Schema + Print Schema @@ -372,7 +372,7 @@ Gets the maximum Print Schema version that can support. The maximum Print Schema version that can support. To be added. - Print Schema + Print Schema diff --git a/xml/System.Printing/EnumeratedPrintQueueTypes.xml b/xml/System.Printing/EnumeratedPrintQueueTypes.xml index 9981e3728ff..a9523bcb50e 100644 --- a/xml/System.Printing/EnumeratedPrintQueueTypes.xml +++ b/xml/System.Printing/EnumeratedPrintQueueTypes.xml @@ -28,26 +28,26 @@ Specifies attributes of print queues. - method to list subsets of available print queues. - -`PushedMachineConnection` and `PushedUserConnection` refer to policies that enable automated connection of machines and users to printers. See the section ["Deploying Printers to Users or Computers by Using Group Policy"](https://learn.microsoft.com/previous-versions/windows/it-pro/windows-server-2008-r2-and-2008/cc753109(v=ws.10)#to-deploy-printers-to-users-or-computers-by-using-group-policy) in the [Step-by-Step Guide for Print Management](https://learn.microsoft.com/previous-versions/windows/it-pro/windows-server-2008-r2-and-2008/cc753109(v=ws.10)). - - - -## Examples - The following example shows how to use the `EnumeratedPrintQueueTypes` enumeration to get a subset of available print queues. - + method to list subsets of available print queues. + +`PushedMachineConnection` and `PushedUserConnection` refer to policies that enable automated connection of machines and users to printers. See the section ["Deploying Printers to Users or Computers by Using Group Policy"](https://learn.microsoft.com/previous-versions/windows/it-pro/windows-server-2008-r2-and-2008/cc753109(v=ws.10)#to-deploy-printers-to-users-or-computers-by-using-group-policy) in the [Step-by-Step Guide for Print Management](https://learn.microsoft.com/previous-versions/windows/it-pro/windows-server-2008-r2-and-2008/cc753109(v=ws.10)). + + + +## Examples + The following example shows how to use the `EnumeratedPrintQueueTypes` enumeration to get a subset of available print queues. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Wpf/EnumerateSubsetOfPrintQueues/CPP/Program.cpp" id="Snippetlistsubsetofprintqueues"::: :::code language="csharp" source="~/snippets/csharp/System.Printing/EnumeratedPrintQueueTypes/Overview/Program.cs" id="Snippetlistsubsetofprintqueues"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/EnumerateSubsetOfPrintQueues/visualbasic/program.vb" id="Snippetlistsubsetofprintqueues"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/EnumerateSubsetOfPrintQueues/visualbasic/program.vb" id="Snippetlistsubsetofprintqueues"::: + ]]> - Step-by-Step Guide for Print Management + Step-by-Step Guide for Print Management diff --git a/xml/System.Printing/PrintQueue.xml b/xml/System.Printing/PrintQueue.xml index a1102ec71ef..50becc98310 100644 --- a/xml/System.Printing/PrintQueue.xml +++ b/xml/System.Printing/PrintQueue.xml @@ -129,7 +129,7 @@ ## Remarks constructors that do not include a parameter default to access. - The [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) version released with Windows Vista is "1". + The [Print Schema](https://learn.microsoft.com/windows/win32/printdocs/printschema) version released with Windows Vista is "1". ]]> @@ -306,7 +306,7 @@ @@ -634,7 +634,7 @@ method throws an exception. + If `fastCopy` is `true`, then the printer must be an [Printing Overview](https://learn.microsoft.com/dotnet/framework/wpf/advanced/printing-overview). If it is not, the method throws an exception. If `fastCopy` is `false`, then it is not necessary to use an XPSDrv printer. The XPS file being added to the queue is converted to the printer's page description language, such as PCL or Postscript. However, this kind of printing makes a call to Component Object Model (COM). The call to COM requires that the calling thread have a single-threaded apartment () instead of multiple-threaded apartment () which is the default in Microsoft .NET 2.0 and later. (For more on threading and apartment states, see [Managed and Unmanaged Threading](https://msdn.microsoft.com/library/db425c20-4b2f-4433-bf96-76071c7881e5), and .) There are two ways of doing this: @@ -763,16 +763,16 @@ Gets the version of the Print Schema. - The version of the Print Schema in use. + The version of the Print Schema in use. - Print Schema + Print Schema @@ -1528,7 +1528,7 @@ parameter is used as the basis on which to construct the object. For example, suppose the printer supported only media types A and B from input bin 1 and it only supported media type C from input bin 2. If the `printTicket` parameter specified input bin 1, then the object that is returned would include all three media types, but it would report type C as "constrained." If the `printTicket` parameter specified input bin 2, then the object that is returned would include all three media types, but it would report types A and B as "constrained." See the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) for more information on constraints. + The parameter is used as the basis on which to construct the object. For example, suppose the printer supported only media types A and B from input bin 1 and it only supported media type C from input bin 2. If the `printTicket` parameter specified input bin 1, then the object that is returned would include all three media types, but it would report type C as "constrained." If the `printTicket` parameter specified input bin 2, then the object that is returned would include all three media types, but it would report types A and B as "constrained." See the [Print Schema](https://learn.microsoft.com/windows/win32/printdocs/printschema) for more information on constraints. If `printTicket` is `null`, the is used. @@ -1545,12 +1545,12 @@ 4.0.0.0 - Gets a object that specifies the printer's capabilities as an XML stream that complies with the Print Schema. + Gets a object that specifies the printer's capabilities as an XML stream that complies with the Print Schema. @@ -1585,7 +1585,7 @@ - Gets a object that specifies the printer's capabilities as an XML stream that complies with the Print Schema. + Gets a object that specifies the printer's capabilities as an XML stream that complies with the Print Schema. A specifying the printer's capabilities by using the XML schema "PrintCapabilities," a part of the Print Schema system. To be added. The print capabilities could not be retrieved. @@ -1623,13 +1623,13 @@ A print ticket that provides the basis on which the print capabilities are reported. - Gets a object that specifies the printer's capabilities in an XML format that complies with the Print Schema. + Gets a object that specifies the printer's capabilities in an XML format that complies with the Print Schema. A specifying the printer's capabilities by using the XML schema "PrintCapabilities," a part of the Print Schema system. parameter is used as the basis on which to construct the print capabilities XML. For example, suppose the printer supported only media types A and B from input bin 1 and it only supported media type C from input bin 2. If the `printTicket` parameter specified input bin 1, then the print capabilities XML that is returned would include all three media types, but it would report type C as "constrained." If the `printTicket` parameter specified input bin 2, then the print capabilities XML that is returned would include all three media types, but it would report types A and B as "constrained." See the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) for more information on constraints. + The parameter is used as the basis on which to construct the print capabilities XML. For example, suppose the printer supported only media types A and B from input bin 1 and it only supported media type C from input bin 2. If the `printTicket` parameter specified input bin 1, then the print capabilities XML that is returned would include all three media types, but it would report type C as "constrained." If the `printTicket` parameter specified input bin 2, then the print capabilities XML that is returned would include all three media types, but it would report types A and B as "constrained." See the [Print Schema](https://learn.microsoft.com/windows/win32/printdocs/printschema) for more information on constraints. If `printTicket` is `null`, the is used. @@ -3114,17 +3114,17 @@ System.Int32 - Gets the most recent possible version number of the Print Schema that the queue can use. - The most recent version number of the Print Schema that the queue can use. + Gets the most recent possible version number of the Print Schema that the queue can use. + The most recent version number of the Print Schema that the queue can use. - Print Schema + Print Schema @@ -3176,7 +3176,7 @@ can include [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) parameters with Job, Document, and Page prefixes. If the `scope` is a document, then per-job settings in `deltaPrintTicket` are ignored, and the returned ticket can include parameters with Document and Page prefixes. If the `scope` is a page, then the per-job settings and the per-document settings in `deltaPrintTicket` are ignored, and the returned ticket can include parameters with only the Page prefix. + If the `scope` is a job, then the print ticket returned in the can include [Print Schema](https://learn.microsoft.com/windows/win32/printdocs/printschema) parameters with Job, Document, and Page prefixes. If the `scope` is a document, then per-job settings in `deltaPrintTicket` are ignored, and the returned ticket can include parameters with Document and Page prefixes. If the `scope` is a page, then the per-job settings and the per-document settings in `deltaPrintTicket` are ignored, and the returned ticket can include parameters with only the Page prefix. ]]> diff --git a/xml/System.Printing/PrintTicket.xml b/xml/System.Printing/PrintTicket.xml index e4aebdf1147..496a4ca269a 100644 --- a/xml/System.Printing/PrintTicket.xml +++ b/xml/System.Printing/PrintTicket.xml @@ -29,13 +29,13 @@ object is an easy-to-work-with representation of a certain type of XML document called a *PrintTicket document*. The latter is a set of instructions telling a printer how to set its various features (such as duplexing, collating, and stapling). For example, to instruct the printer to turn on its stapler and staple print jobs in the upper left corner, the document would have a `` element that specifies **StapleTopLeft**. The element is, in turn, represented by the property of the object. The PrintTicket document must conform to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397). + A object is an easy-to-work-with representation of a certain type of XML document called a *PrintTicket document*. The latter is a set of instructions telling a printer how to set its various features (such as duplexing, collating, and stapling). For example, to instruct the printer to turn on its stapler and staple print jobs in the upper left corner, the document would have a `` element that specifies **StapleTopLeft**. The element is, in turn, represented by the property of the object. The PrintTicket document must conform to the [Print Schema](/windows/win32/printdocs/printschema). The class enables your application to configure the printer's features without having to engage in any direct writing of XML objects. - All of the most popular features of home and business file and photo printers are represented by properties of the class. But the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) defines many more, less common, features and it can be extended to handle features of specialty printing devices. So, although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. For more information see [How to: Extend the Print Schema and Create New Print System Classes](https://learn.microsoft.com/previous-versions/aa970573(v=vs.100)). + All of the most popular features of home and business file and photo printers are represented by properties of the class. But the [Print Schema](/windows/win32/printdocs/printschema) defines many more, less common, features and it can be extended to handle features of specialty printing devices. So, although the and classes cannot be inherited, you can extend the [Print Schema](/windows/win32/printdocs/printschema) to recognize print device features that are not accounted for in the or classes. For more information see [How to: Extend the Print Schema and Create New Print System Classes](https://learn.microsoft.com/previous-versions/aa970573(v=vs.100)). - **Note** When the object is created with the constructor that takes a PrintTicket document (as a ) parameter, that entire document is stored in a non-public field in the object, including the XML elements within it that express less common features that are not represented by any of the public properties of the class. In fact, if the driver that produced the PrintTicket document is using a private extension of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397), that privately defined markup is also stored as part of the non-public PrintTicket document. + **Note** When the object is created with the constructor that takes a PrintTicket document (as a ) parameter, that entire document is stored in a non-public field in the object, including the XML elements within it that express less common features that are not represented by any of the public properties of the class. In fact, if the driver that produced the PrintTicket document is using a private extension of the [Print Schema](/windows/win32/printdocs/printschema), that privately defined markup is also stored as part of the non-public PrintTicket document. > [!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. @@ -120,14 +120,14 @@ An XML stream that describes a print job and conforms to the Print Schema. - Initializes a new instance of the class by using an XML stream (that contains a PrintTicket document) that complies with the XML Print Schema. + Initializes a new instance of the class by using an XML stream (that contains a PrintTicket document) that complies with the XML Print Schema. class. In fact, if the driver that produced the PrintTicket document is using a private extension of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397), that privately defined markup is also stored as part of the non-public PrintTicket document. + The entire PrintTicket document is stored in a non-public field in the object, including the XML elements within it that express less common features that are not represented by any of the public properties of the class. In fact, if the driver that produced the PrintTicket document is using a private extension of the [Print Schema](/windows/win32/printdocs/printschema), that privately defined markup is also stored as part of the non-public PrintTicket document. The private parts of the document, if any, are not validated by the constructor, but all **Print Schema**-defined parts are validated, including the parts that are not represented by any of the public properties of the class. Accordingly, the could be thrown even if all of the XML markup that corresponds to the public properties is valid. @@ -141,7 +141,7 @@ is . is not valid XML. - Print Schema + Print Schema @@ -202,7 +202,7 @@ ## Remarks A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `DocumentCollate` keyword, not the `JobCollateAllDocuments` keyword. + This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `DocumentCollate` keyword, not the `JobCollateAllDocuments` keyword. You can test for the options that the printer supports by using the property. @@ -250,7 +250,7 @@ ## Remarks A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `JobCopiesAllDocuments` keyword, not the `DocumentCopiesAllPages` keyword, or the `PageCopies` keyword. + This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `JobCopiesAllDocuments` keyword, not the `DocumentCopiesAllPages` keyword, or the `PageCopies` keyword. You can test for the printer's maximum by using the property. @@ -289,7 +289,7 @@ ## Remarks A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageDeviceFontSubstitution` keyword. + This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageDeviceFontSubstitution` keyword. You can test for the options that the printer supports by using the property. @@ -328,7 +328,7 @@ ## Remarks A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `JobDuplexAllDocumentsContiguously` keyword, not the `DocumentDuplex` keyword. + This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `JobDuplexAllDocumentsContiguously` keyword, not the `DocumentDuplex` keyword. You can test for the options that the printer supports by using the property. @@ -368,7 +368,7 @@ - Returns a object that represents the property values of a as an XML stream that conforms to the Print Schema. + Returns a object that represents the property values of a as an XML stream that conforms to the Print Schema. A object that describes the print ticket with XML that conforms to the Print Schema. - Print Schema + Print Schema @@ -411,9 +411,9 @@ (see and ) will not contain any markup for this feature. That is, there will be no markup for the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s features `JobInputBin`, `DocumentInputBin`, or `PageInputBin`. + A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. That is, there will be no markup for the [Print Schema](/windows/win32/printdocs/printschema)'s features `JobInputBin`, `DocumentInputBin`, or `PageInputBin`. - When this property is not `null`, it will have the following relationships to the features defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397). + When this property is not `null`, it will have the following relationships to the features defined in the [Print Schema](/windows/win32/printdocs/printschema). - If the XML form of the contains `JobInputBin`, then this property has the same value as `JobInputBin` (regardless of whether or not there is also `DocumentInputBin` or `PageInputBin`. markup in the XML version of the ). @@ -460,7 +460,7 @@ ## Remarks A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageOutputColor` keyword. + This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageOutputColor` keyword. You can test for the options that the printer supports by using the property. @@ -507,7 +507,7 @@ ## Remarks A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageOutputQuality` keyword. + This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageOutputQuality` keyword. You can test for the options that the printer supports by using the property. @@ -546,7 +546,7 @@ ## Remarks A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageBorderless` keyword. + This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageBorderless` keyword. You can test for the options that the printer supports by using the property. @@ -583,7 +583,7 @@ property. @@ -638,7 +638,7 @@ ## Remarks A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageMediaType` keyword. + This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageMediaType` keyword. You can test for the options that the printer supports by using the property. @@ -677,7 +677,7 @@ ## Remarks A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `JobPageOrder` keyword. + This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `JobPageOrder` keyword. You can test for the options that the printer supports by using the property. @@ -716,7 +716,7 @@ ## Remarks A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageOrientation` keyword. + This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageOrientation` keyword. You can test for the options that the printer supports by using the property. @@ -763,7 +763,7 @@ ## Remarks The class has properties in which you can specify the dots-per-inch for the X and Y dimensions and a property where you can give a qualitative expression to the resolution. - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageResolution` keyword. + This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageResolution` keyword. You can test for the options that the printer supports by using the property. @@ -813,7 +813,7 @@ A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. - This property generally represents the **Scale** `ScoredProperty` of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageScaling` keyword. But there are some complexities as follows. + This property generally represents the **Scale** `ScoredProperty` of the [Print Schema](/windows/win32/printdocs/printschema)'s `PageScaling` keyword. But there are some complexities as follows. When reading the property, the property behaves as follows. @@ -866,7 +866,7 @@ A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. - This property corresponds to the **PagesPerSheet**`ScoredProperty` of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `JobNUpAllDocumentsContiguously` keyword, not the `DocumentNUp` keyword. + This property corresponds to the **PagesPerSheet**`ScoredProperty` of the [Print Schema](/windows/win32/printdocs/printschema)'s `JobNUpAllDocumentsContiguously` keyword, not the `DocumentNUp` keyword. You can test for the options that the printer supports by using the property. @@ -907,7 +907,7 @@ A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. - This property corresponds to the **PresentationDirection** subfeature of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `JobNUpAllDocumentsContiguously` keyword, not the `DocumentNUp` keyword. + This property corresponds to the **PresentationDirection** subfeature of the [Print Schema](/windows/win32/printdocs/printschema)'s `JobNUpAllDocumentsContiguously` keyword, not the `DocumentNUp` keyword. You can test for the options that the printer supports by using the property. @@ -948,7 +948,7 @@ A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PagePhotoPrintingIntent` keyword. + This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PagePhotoPrintingIntent` keyword. You can test for the options that the printer supports by using the property. @@ -1013,7 +1013,7 @@ The that holds the saved . - Saves the settings to a object by using an XML format that conforms to the Print Schema. + Saves the settings to a object by using an XML format that conforms to the Print Schema. - Print Schema + Print Schema @@ -1061,7 +1061,7 @@ A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `JobStapleAllDocuments` keyword, not the `DocumentStaple` keyword. + This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `JobStapleAllDocuments` keyword, not the `DocumentStaple` keyword. You can test for the options that the printer supports by using the property. @@ -1109,7 +1109,7 @@ ## Remarks A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageTrueTypeFontMode` keyword. + This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageTrueTypeFontMode` keyword. You can test for the options that the printer supports by using the property. diff --git a/xml/System.Runtime.InteropServices.ComTypes/IStream.xml b/xml/System.Runtime.InteropServices.ComTypes/IStream.xml index 58beb8a4cfb..ecbaa8adf34 100644 --- a/xml/System.Runtime.InteropServices.ComTypes/IStream.xml +++ b/xml/System.Runtime.InteropServices.ComTypes/IStream.xml @@ -69,8 +69,8 @@ ]]> - IStream - ISequentialStream + IStream + ISequentialStream diff --git a/xml/System.Runtime.InteropServices.WindowsRuntime/ReadOnlyArrayAttribute.xml b/xml/System.Runtime.InteropServices.WindowsRuntime/ReadOnlyArrayAttribute.xml index 906c1c2082e..f614d5f9a97 100644 --- a/xml/System.Runtime.InteropServices.WindowsRuntime/ReadOnlyArrayAttribute.xml +++ b/xml/System.Runtime.InteropServices.WindowsRuntime/ReadOnlyArrayAttribute.xml @@ -32,30 +32,30 @@ When applied to an array parameter in a Windows Runtime component, specifies that the contents of the array that is passed to that parameter are used only for input. The caller expects the array to be unchanged by the call. - attribute if you intend the contents of the array to be used for input only. - -- Apply the attribute if you intend the contents of the array to be used for output only (that is, the method sets the contents of the array but does not read them). - - Applying both attributes to a parameter causes an error. For more information, including the standard pattern for making changes to an array, see [Passing arrays to a Windows Runtime component](https://go.microsoft.com/fwlink/?LinkId=251026) in the Windows Dev Center. - + attribute if you intend the contents of the array to be used for input only. + +- Apply the attribute if you intend the contents of the array to be used for output only (that is, the method sets the contents of the array but does not read them). + + Applying both attributes to a parameter causes an error. For more information, including the standard pattern for making changes to an array, see [Passing arrays to a Windows Runtime component](https://go.microsoft.com/fwlink/?LinkId=251026) in the Windows Dev Center. + > [!IMPORTANT] -> Parameters that have the attribute behave differently depending on whether the caller is written in native code or managed code. If the caller is native code (JavaScript or Visual C++ component extensions), the array is copied when the call crosses the application binary interface (ABI) boundary. Elements are converted if necessary. Therefore, any accidental changes the method makes to an input-only array are not visible to the caller. -> -> If the caller is managed code, the array is not copied. The original array is available to the called method, as it would be in any method call in the .NET Framework. Array contents are mutable in .NET Framework code, so any changes the method makes to the array are visible to the caller. This is important to remember because it affects unit tests written for a Windows Runtime component. If the tests are written in managed code, the contents of an array will appear to be mutable during testing. - - Applying this attribute to a parameter that has the or attribute causes an error when the module is exported. Applying the attribute to an `out` parameter also causes an error. - +> Parameters that have the attribute behave differently depending on whether the caller is written in native code or managed code. If the caller is native code (JavaScript or Visual C++ component extensions), the array is copied when the call crosses the application binary interface (ABI) boundary. Elements are converted if necessary. Therefore, any accidental changes the method makes to an input-only array are not visible to the caller. +> +> If the caller is managed code, the array is not copied. The original array is available to the called method, as it would be in any method call in the .NET Framework. Array contents are mutable in .NET Framework code, so any changes the method makes to the array are visible to the caller. This is important to remember because it affects unit tests written for a Windows Runtime component. If the tests are written in managed code, the contents of an array will appear to be mutable during testing. + + Applying this attribute to a parameter that has the or attribute causes an error when the module is exported. Applying the attribute to an `out` parameter also causes an error. + ]]> Winmdexp.exe (Windows Runtime Metadata Export Tool) - Creating Windows Runtime Components in C# and Visual Basic - Passing arrays to a Windows Runtime component + Creating Windows Runtime Components in C# and Visual Basic + Passing arrays to a Windows Runtime component diff --git a/xml/System.Runtime.InteropServices.WindowsRuntime/ReturnValueNameAttribute.xml b/xml/System.Runtime.InteropServices.WindowsRuntime/ReturnValueNameAttribute.xml index 6529ba65a23..3cb61f51f1a 100644 --- a/xml/System.Runtime.InteropServices.WindowsRuntime/ReturnValueNameAttribute.xml +++ b/xml/System.Runtime.InteropServices.WindowsRuntime/ReturnValueNameAttribute.xml @@ -32,65 +32,65 @@ Specifies the name of the return value of a method in a Windows Runtime component. - attribute in Visual Basic): - -```csharp -public static int ComputeAverage([ReadOnlyArray()] int[] input, - out int minValue, out int maxValue) -{ - … -} -``` - -```vb -Public Shared Function ComputeAverage( _ - ByVal input As Integer, _ - ByRef minValue As Integer, _ - ByRef maxValue As Integer) As Integer - … -End Function - -``` - - When you call the function from JavaScript, you can access the return value by its default name (`value`): - -```javascript -var data = [5, 13, 23, 37]; -var results = SampleComponent.TestStuff.computeAverage(data); -var formattedResults = "Min=" + results.minValue + ", Avg=" + - results.value + ", Max=" + results.maxValue; - -``` - - You must give the return value a different name if you already have a parameter named "value". Or you might simply want to use a more meaningful name (such as "average" in this example). Apply the attribute to your method and specify a new name. - -```csharp -[return: ReturnValueName("average")] -public static int ComputeAverage([ReadOnlyArray()] int[] input, - out int minValue, out int maxValue) -{ - … -} - -``` - -```vb -Public Shared Function ComputeAverage( _ - ByVal input As Integer, _ - ByRef minValue As Integer, _ - ByRef maxValue As Integer) _ - As Integer - … -End Function - -``` - + attribute in Visual Basic): + +```csharp +public static int ComputeAverage([ReadOnlyArray()] int[] input, + out int minValue, out int maxValue) +{ + … +} +``` + +```vb +Public Shared Function ComputeAverage( _ + ByVal input As Integer, _ + ByRef minValue As Integer, _ + ByRef maxValue As Integer) As Integer + … +End Function + +``` + + When you call the function from JavaScript, you can access the return value by its default name (`value`): + +```javascript +var data = [5, 13, 23, 37]; +var results = SampleComponent.TestStuff.computeAverage(data); +var formattedResults = "Min=" + results.minValue + ", Avg=" + + results.value + ", Max=" + results.maxValue; + +``` + + You must give the return value a different name if you already have a parameter named "value". Or you might simply want to use a more meaningful name (such as "average" in this example). Apply the attribute to your method and specify a new name. + +```csharp +[return: ReturnValueName("average")] +public static int ComputeAverage([ReadOnlyArray()] int[] input, + out int minValue, out int maxValue) +{ + … +} + +``` + +```vb +Public Shared Function ComputeAverage( _ + ByVal input As Integer, _ + ByRef minValue As Integer, _ + ByRef maxValue As Integer) _ + As Integer + … +End Function + +``` + ]]> - Creating Windows Runtime Components in C# and Visual Basic + Creating Windows Runtime Components in C# and Visual Basic diff --git a/xml/System.Runtime.InteropServices.WindowsRuntime/WriteOnlyArrayAttribute.xml b/xml/System.Runtime.InteropServices.WindowsRuntime/WriteOnlyArrayAttribute.xml index d390eb4835a..c4f8d1eec25 100644 --- a/xml/System.Runtime.InteropServices.WindowsRuntime/WriteOnlyArrayAttribute.xml +++ b/xml/System.Runtime.InteropServices.WindowsRuntime/WriteOnlyArrayAttribute.xml @@ -32,30 +32,30 @@ When applied to an array parameter in a Windows Runtime component, specifies that the contents of an array that is passed to that parameter are used only for output. The caller does not guarantee that the contents are initialized, and the called method should not read the contents. - attribute if you intend the contents of the array to be used for input only. - -- Apply the attribute if you intend the contents of the array to be used for output only (that is, the method sets the contents of the array but does not read them). - - Applying both attributes to a parameter causes an error. For more information, including the standard pattern for making changes to an array, see [Passing arrays to a Windows Runtime component](https://go.microsoft.com/fwlink/?LinkId=251026) in the Windows Dev Center. - + attribute if you intend the contents of the array to be used for input only. + +- Apply the attribute if you intend the contents of the array to be used for output only (that is, the method sets the contents of the array but does not read them). + + Applying both attributes to a parameter causes an error. For more information, including the standard pattern for making changes to an array, see [Passing arrays to a Windows Runtime component](https://go.microsoft.com/fwlink/?LinkId=251026) in the Windows Dev Center. + > [!IMPORTANT] -> Parameters that have the attribute behave differently depending on whether the caller is written in native code or managed code. If the caller is native code (JavaScript or Visual C++ component extensions), the called method can't make any assumptions about the contents of the original array. For example, the array the method receives might not be initialized, or might contain default values. The method is expected to set the values of all the elements in the array. -> -> If the caller is managed code, the caller's original array is passed to the called method, as it would be in any method call in the .NET Framework. Array contents are mutable in managed code, so the method can selectively read and change those values. This is important to remember because it affects unit tests written for a Windows Runtime component. If the tests are written in managed code, the contents of an array will appear to be mutable during testing, and the results are likely to be different if the method is called from native code later. - - Applying this attribute to an `out` parameter or to a parameter that has the attribute causes an error when the module is exported. Applying the attribute to a parameter that has the attribute causes an error unless the parameter also has the Visual Basic `ByRef` modifier. In that case, the attribute is redundant but allowed. - +> Parameters that have the attribute behave differently depending on whether the caller is written in native code or managed code. If the caller is native code (JavaScript or Visual C++ component extensions), the called method can't make any assumptions about the contents of the original array. For example, the array the method receives might not be initialized, or might contain default values. The method is expected to set the values of all the elements in the array. +> +> If the caller is managed code, the caller's original array is passed to the called method, as it would be in any method call in the .NET Framework. Array contents are mutable in managed code, so the method can selectively read and change those values. This is important to remember because it affects unit tests written for a Windows Runtime component. If the tests are written in managed code, the contents of an array will appear to be mutable during testing, and the results are likely to be different if the method is called from native code later. + + Applying this attribute to an `out` parameter or to a parameter that has the attribute causes an error when the module is exported. Applying the attribute to a parameter that has the attribute causes an error unless the parameter also has the Visual Basic `ByRef` modifier. In that case, the attribute is redundant but allowed. + ]]> Winmdexp.exe (Windows Runtime Metadata Export Tool) - Creating Windows Runtime Components in C# and Visual Basic - Passing arrays to a Windows Runtime component + Creating Windows Runtime Components in C# and Visual Basic + Passing arrays to a Windows Runtime component diff --git a/xml/System.Runtime.InteropServices/DefaultDllImportSearchPathsAttribute.xml b/xml/System.Runtime.InteropServices/DefaultDllImportSearchPathsAttribute.xml index 906f77d0d21..a07d8dd535c 100644 --- a/xml/System.Runtime.InteropServices/DefaultDllImportSearchPathsAttribute.xml +++ b/xml/System.Runtime.InteropServices/DefaultDllImportSearchPathsAttribute.xml @@ -57,28 +57,28 @@ Specifies the paths that are used to search for DLLs that provide functions for platform invokes. - - LoadLibraryEx + LoadLibraryEx @@ -165,11 +165,11 @@ Gets a bitwise combination of enumeration values that specify the paths that the LoadLibraryEx function searches during platform invokes. A bitwise combination of enumeration values that specify search paths for platform invokes. - attribute is applied to an assembly, the paths are used by default to search for the targets of any platform invokes that are performed by code in the assembly. When the attribute is applied to an individual platform invoke, the paths are used to search for the target of the individual platform invoke and override the paths that are specified for the assembly. - + attribute is applied to an assembly, the paths are used by default to search for the targets of any platform invokes that are performed by code in the assembly. When the attribute is applied to an individual platform invoke, the paths are used to search for the target of the individual platform invoke and override the paths that are specified for the assembly. + ]]> diff --git a/xml/System.Runtime.InteropServices/Marshal.xml b/xml/System.Runtime.InteropServices/Marshal.xml index 8e193a13712..132134f9edc 100644 --- a/xml/System.Runtime.InteropServices/Marshal.xml +++ b/xml/System.Runtime.InteropServices/Marshal.xml @@ -157,7 +157,7 @@ - IUnknown::AddRef + IUnknown::AddRef @@ -3728,7 +3728,7 @@ The code retrieves a reference to an instance of Microsoft Word successfully. Ho ]]> - IErrorInfo Interface + IErrorInfo Interface @@ -3798,7 +3798,7 @@ The code retrieves a reference to an instance of Microsoft Word successfully. Ho ]]> - IErrorInfo Interface + IErrorInfo Interface @@ -9514,7 +9514,7 @@ On .NET 6 and later versions, this method is functionally equivalent to There is insufficient memory to satisfy the request. - GlobalAlloc Function + GlobalAlloc Function diff --git a/xml/System.Security.Cryptography/ECCurve+NamedCurves.xml b/xml/System.Security.Cryptography/ECCurve+NamedCurves.xml index a89634ccffe..81a4ce7f26c 100644 --- a/xml/System.Security.Cryptography/ECCurve+NamedCurves.xml +++ b/xml/System.Security.Cryptography/ECCurve+NamedCurves.xml @@ -89,7 +89,7 @@ Gets a brainpoolP160r1 named curve. A brainpoolP160r1 named curve. To be added. - CNG Named Elliptic Curves + CNG Named Elliptic Curves @@ -132,7 +132,7 @@ Gets a brainpoolP160t1 named curve. A brainpoolP160t1 named curve. To be added. - CNG Named Elliptic Curves + CNG Named Elliptic Curves @@ -175,7 +175,7 @@ Gets a brainpoolP192r1 named curve. A brainpoolP192r1 named curve. To be added. - CNG Named Elliptic Curves + CNG Named Elliptic Curves @@ -218,7 +218,7 @@ Gets a brainpoolP192t1 named curve. A brainpoolP192t1 named curve. To be added. - CNG Named Elliptic Curves + CNG Named Elliptic Curves @@ -261,7 +261,7 @@ Gets a brainpoolP224r1 named curve. A brainpoolP224r1 named curve. To be added. - CNG Named Elliptic Curves + CNG Named Elliptic Curves @@ -304,7 +304,7 @@ Gets a brainpoolP224t1 named curve. A brainpoolP224t1 named curve. To be added. - CNG Named Elliptic Curves + CNG Named Elliptic Curves @@ -347,7 +347,7 @@ Gets a brainpoolP256r1 named curve. A brainpoolP256r1 named curve. To be added. - CNG Named Elliptic Curves + CNG Named Elliptic Curves @@ -390,7 +390,7 @@ Gets a brainpoolP256t1 named curve. A brainpoolP256t1 named curve. To be added. - CNG Named Elliptic Curves + CNG Named Elliptic Curves @@ -433,7 +433,7 @@ Gets a brainpoolP320r1 named curve. A brainpoolP320r1 named curve. To be added. - CNG Named Elliptic Curves + CNG Named Elliptic Curves @@ -476,7 +476,7 @@ Gets a brainpoolP320t1 named curve. A brainpoolP320t1 named curve. To be added. - CNG Named Elliptic Curves + CNG Named Elliptic Curves @@ -519,7 +519,7 @@ Gets a brainpoolP384r1 named curve. A brainpoolP384r1 named curve. To be added. - CNG Named Elliptic Curves + CNG Named Elliptic Curves @@ -562,7 +562,7 @@ Gets a brainpoolP384t1 named curve. A brainpoolP384t1 named curve. To be added. - CNG Named Elliptic Curves + CNG Named Elliptic Curves @@ -605,7 +605,7 @@ Gets a brainpoolP512r1 named curve. A brainpoolP512r1 named curve. To be added. - CNG Named Elliptic Curves + CNG Named Elliptic Curves @@ -648,7 +648,7 @@ Gets a brainpoolP512t1 named curve. A brainpoolP512t1 named curve. To be added. - CNG Named Elliptic Curves + CNG Named Elliptic Curves @@ -691,7 +691,7 @@ Gets a nistP256 named curve. A nistP256 named curve. To be added. - CNG Named Elliptic Curves + CNG Named Elliptic Curves @@ -734,7 +734,7 @@ Gets a nistP384 named curve. A nistP384 named curve. To be added. - CNG Named Elliptic Curves + CNG Named Elliptic Curves @@ -777,7 +777,7 @@ Gets a nistP521 named curve. A nistP521 named curve. To be added. - CNG Named Elliptic Curves + CNG Named Elliptic Curves diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsRule.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsRule.xml index 8e22744d1ef..339af76d8c9 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsRule.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsRule.xml @@ -670,7 +670,7 @@ document.Root = winnerRule; ]]> Create Grammars Using SrgsGrammar - Speech Recognition Grammar Specification Version 1.0 + Speech Recognition Grammar Specification diff --git a/xml/System.Speech.Recognition/Choices.xml b/xml/System.Speech.Recognition/Choices.xml index 8cfc1330987..4aab4c0dfc6 100644 --- a/xml/System.Speech.Recognition/Choices.xml +++ b/xml/System.Speech.Recognition/Choices.xml @@ -25,51 +25,47 @@ Represents a set of alternatives in the constraints of a speech recognition grammar. - object represents a component of a phrase that can have one of several values. Use this class when creating a speech recognition grammar from a object. - - 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". - + object represents a component of a phrase that can have one of several values. Use this class when creating a speech recognition grammar from a object. + + 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. - - The class serves the same function as the `one-of` XML element defined by the [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://www.w3.org/TR/speech-grammar/) and is similar to the class in the namespace. - - For more information about defining a speech recognition grammar, see [Speech Recognition](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh361633(v=office.14)). - - - -## Examples - The following example creates a speech recognition grammar for the phrase, "Set background to *colorChoice*", where *colorChoice* can be one of the defined colors. The is used to define the constraints for the grammar. - -```csharp - -private Grammar CreateColorGrammar() -{ - - // Create a Choices object that contains a set of alternative colors. - Choices colorChoice = new Choices(new string[] {"red", "green", "blue"}); - colorChoice.Add(new string[] {"cyan", "yellow", "magenta"}); - - // Construct the phrase. - GrammarBuilder builder = new GrammarBuilder("Set background to"); - builder.Append(colorChoice); - - // Create a grammar for the phrase. - Grammar colorGrammar = new Grammar(builder); - colorGrammar.Name = "SetBackground"; - - return colorGrammar; -} -``` - +> 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](https://www.w3.org/TR/speech-grammar/) and is similar to the class in the namespace. + + For more information about defining a speech recognition grammar, see [Speech Recognition](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh361633(v=office.14)). + +## Examples + The following example creates a speech recognition grammar for the phrase, "Set background to *colorChoice*", where *colorChoice* can be one of the defined colors. The is used to define the constraints for the grammar. + +```csharp +private Grammar CreateColorGrammar() +{ + // Create a Choices object that contains a set of alternative colors. + Choices colorChoice = new Choices(new string[] {"red", "green", "blue"}); + colorChoice.Add(new string[] {"cyan", "yellow", "magenta"}); + + // Construct the phrase. + GrammarBuilder builder = new GrammarBuilder("Set background to"); + builder.Append(colorChoice); + + // Create a grammar for the phrase. + Grammar colorGrammar = new Grammar(builder); + colorGrammar.Name = "SetBackground"; + + return colorGrammar; +} +``` + ]]> - Speech Recognition Grammar Specification (SRGS) + Speech Recognition Grammar Specification (SRGS) @@ -80,37 +76,37 @@ private Grammar CreateColorGrammar() Initializes a new instance of the class. - object using a parameterless constructor (which returns an empty object), from a group of objects, or a from set of objects. - - Because the object supports implicit conversion from and , a can be constructed from an array of these objects using a cast. - - - -## Examples - The following example uses objects to create two lists of alternatives. - - The first object is constructed from an array of objects. The other object is constructed from an array of objects which have been implicitly converted by a cast. - - The example uses a object to assemble a phrase, using the objects and two additional strings, that can be used to recognize speech input in the form of "Call [contactlList] on [phoneType] phone" , for example "Call Jane on cell phone". - + object using a parameterless constructor (which returns an empty object), from a group of objects, or a from set of objects. + + Because the object supports implicit conversion from and , a can be constructed from an array of these objects using a cast. + + + +## Examples + The following example uses objects to create two lists of alternatives. + + The first object is constructed from an array of objects. The other object is constructed from an array of objects which have been implicitly converted by a cast. + + The example uses a object to assemble a phrase, using the objects and two additional strings, that can be used to recognize speech input in the form of "Call [contactlList] on [phoneType] phone" , for example "Call Jane on cell phone". + ```csharp -public GrammarBuilder ChoicesConstructor2 () -{ - GrammarBuilder gb = new GrammarBuilder (); - Choices phoneType = new Choices (new string[] {"cell", "home", "work"}); - Choices contactList = new Choices (new GrammarBuilder[] {(GrammarBuilder) "Mark", (GrammarBuilder) "Jane", (GrammarBuilder) "Frank"}); - gb.Append ("Call"); - gb.Append (contactList); - gb.Append ("on"); - gb.Append (phoneType); - gb.Append ("phone"); - return gb; -} -``` - +public GrammarBuilder ChoicesConstructor2 () +{ + GrammarBuilder gb = new GrammarBuilder (); + Choices phoneType = new Choices (new string[] {"cell", "home", "work"}); + Choices contactList = new Choices (new GrammarBuilder[] {(GrammarBuilder) "Mark", (GrammarBuilder) "Jane", (GrammarBuilder) "Frank"}); + gb.Append ("Call"); + gb.Append (contactList); + gb.Append ("on"); + gb.Append (phoneType); + gb.Append ("phone"); + return gb; +} +``` + ]]> @@ -132,48 +128,48 @@ public GrammarBuilder ChoicesConstructor2 () Initializes a new instance of the class that contains an empty set of alternatives. - methods. - - - -## Examples - The following example uses and objects to create a phrase that can be used to recognize speech input such as "Call Anne on her cell" and "Call James on his work phone". The example uses implicit casts from and to . - -```csharp -public Grammar CreatePhonePhrase() -{ - - // Create alternatives for female names and add a phrase. - GrammarBuilder females = new Choices(new string[] { "Anne", "Mary" }); - females.Append("on her"); - - // Create alternatives for male names and add a phrase. - GrammarBuilder males = new Choices(new string[] { "James", "Sam" }); - males.Append("on his"); - - // Create a Choices object that contains an array of alternative - // GrammarBuilder objects. - Choices people = new Choices(); - people.Add(new Choices(new GrammarBuilder[] {females, males})); - - // Create a Choices object that contains a set of alternative phone types. - Choices phoneType = new Choices(); - phoneType.Add(new string[] { "cell", "home", "work" }); - - // Construct the phrase. - GrammarBuilder gb = new GrammarBuilder(); - gb.Append("call"); - gb.Append(people); - gb.Append(phoneType); - gb.Append(new GrammarBuilder("phone"), 0, 1); - - return new Grammar(gb); -} -``` - + methods. + + + +## Examples + The following example uses and objects to create a phrase that can be used to recognize speech input such as "Call Anne on her cell" and "Call James on his work phone". The example uses implicit casts from and to . + +```csharp +public Grammar CreatePhonePhrase() +{ + + // Create alternatives for female names and add a phrase. + GrammarBuilder females = new Choices(new string[] { "Anne", "Mary" }); + females.Append("on her"); + + // Create alternatives for male names and add a phrase. + GrammarBuilder males = new Choices(new string[] { "James", "Sam" }); + males.Append("on his"); + + // Create a Choices object that contains an array of alternative + // GrammarBuilder objects. + Choices people = new Choices(); + people.Add(new Choices(new GrammarBuilder[] {females, males})); + + // Create a Choices object that contains a set of alternative phone types. + Choices phoneType = new Choices(); + phoneType.Add(new string[] { "cell", "home", "work" }); + + // Construct the phrase. + GrammarBuilder gb = new GrammarBuilder(); + gb.Append("call"); + gb.Append(people); + gb.Append(phoneType); + gb.Append(new GrammarBuilder("phone"), 0, 1); + + return new Grammar(gb); +} +``` + ]]> @@ -208,52 +204,52 @@ public Grammar CreatePhonePhrase() An array containing the set of alternatives. Initializes a new instance of the class from an array containing one or more objects. - in `alternateChoices` defines one alternative. If `alternateChoices` is an empty array, the constructor returns an empty set of alternatives. You can add alternatives using any of the methods. - - The constructor throws an when `alternateChoices` is `null` or when any of the array elements are `null`. - - Because the class provides support for implicit conversion of , , and objects to instances, by properly using casts, this constructor can also be used to create a object from a list of any combination of these objects. - - - -## Examples - The following example uses `Choices` and objects to create a for phrases such as, "Call Anne on her cell" and "Call James on his work phone". The example uses implicit casts from `Choices` and to . - -```csharp -public Grammar CreatePhonePhrase() -{ - - // Create alternatives for female names and add a phrase. - GrammarBuilder females = new Choices(new string[] { "Anne", "Mary" }); - females.Append("on her"); - - // Create alternatives for male names and add a phrase. - GrammarBuilder males = new Choices(new string[] { "James", "Sam" }); - males.Append("on his"); - - // Create a Choices object that contains an array of alternative - // GrammarBuilder objects. - Choices people = new Choices(); - people.Add(new Choices(new GrammarBuilder[] {females, males})); - - // Create a Choices object that contains a set of alternative phone types. - Choices phoneType = new Choices(); - phoneType.Add(new string[] { "cell", "home", "work" }); - - // Construct the phrase. - GrammarBuilder gb = new GrammarBuilder(); - gb.Append("call"); - gb.Append(people); - gb.Append(phoneType); - gb.Append(new GrammarBuilder("phone"), 0, 1); - - return new Grammar(gb); -} -``` - + in `alternateChoices` defines one alternative. If `alternateChoices` is an empty array, the constructor returns an empty set of alternatives. You can add alternatives using any of the methods. + + The constructor throws an when `alternateChoices` is `null` or when any of the array elements are `null`. + + Because the class provides support for implicit conversion of , , and objects to instances, by properly using casts, this constructor can also be used to create a object from a list of any combination of these objects. + + + +## Examples + The following example uses `Choices` and objects to create a for phrases such as, "Call Anne on her cell" and "Call James on his work phone". The example uses implicit casts from `Choices` and to . + +```csharp +public Grammar CreatePhonePhrase() +{ + + // Create alternatives for female names and add a phrase. + GrammarBuilder females = new Choices(new string[] { "Anne", "Mary" }); + females.Append("on her"); + + // Create alternatives for male names and add a phrase. + GrammarBuilder males = new Choices(new string[] { "James", "Sam" }); + males.Append("on his"); + + // Create a Choices object that contains an array of alternative + // GrammarBuilder objects. + Choices people = new Choices(); + people.Add(new Choices(new GrammarBuilder[] {females, males})); + + // Create a Choices object that contains a set of alternative phone types. + Choices phoneType = new Choices(); + phoneType.Add(new string[] { "cell", "home", "work" }); + + // Construct the phrase. + GrammarBuilder gb = new GrammarBuilder(); + gb.Append("call"); + gb.Append(people); + gb.Append(phoneType); + gb.Append(new GrammarBuilder("phone"), 0, 1); + + return new Grammar(gb); +} +``` + ]]> @@ -288,50 +284,50 @@ public Grammar CreatePhonePhrase() An array containing the set of alternatives. Initializes a new instance of the class from an array containing one or more objects. - in `phrases` defines one alternative. The speech recognition engine can use any one of the items in the string array to match speech input. If `phrases` is an empty array, the constructor returns an empty set of alternatives. You can add alternatives using any of the methods. - - The constructor throws an when `phrases` is `null` or any of the array elements are `null`. The constructor throws an if any element in the array is an empty string (""). - - - -## Examples - The following example uses and objects to create a for the phrases such as, "Call Anne on her cell" and "Call James on his work phone". The example uses implicit casts from `Choices` and to . - -```csharp -public Grammar CreatePhonePhrase() -{ - - // Create alternatives for female names and add a phrase. - GrammarBuilder females = new Choices(new string[] { "Anne", "Mary" }); - females.Append("on her"); - - // Create alternatives for male names and add a phrase. - GrammarBuilder males = new Choices(new string[] { "James", "Sam" }); - males.Append("on his"); - - // Create a Choices object that contains an array of alternative - // GrammarBuilder objects. - Choices people = new Choices(); - people.Add(new Choices(new GrammarBuilder[] {females, males})); - - // Create a Choices object that contains a set of alternative phone types. - Choices phoneType = new Choices(); - phoneType.Add(new string[] { "cell", "home", "work" }); - - // Construct the phrase. - GrammarBuilder gb = new GrammarBuilder(); - gb.Append("call"); - gb.Append(people); - gb.Append(phoneType); - gb.Append(new GrammarBuilder("phone"), 0, 1); - - return new Grammar(gb); -} -``` - + in `phrases` defines one alternative. The speech recognition engine can use any one of the items in the string array to match speech input. If `phrases` is an empty array, the constructor returns an empty set of alternatives. You can add alternatives using any of the methods. + + The constructor throws an when `phrases` is `null` or any of the array elements are `null`. The constructor throws an if any element in the array is an empty string (""). + + + +## Examples + The following example uses and objects to create a for the phrases such as, "Call Anne on her cell" and "Call James on his work phone". The example uses implicit casts from `Choices` and to . + +```csharp +public Grammar CreatePhonePhrase() +{ + + // Create alternatives for female names and add a phrase. + GrammarBuilder females = new Choices(new string[] { "Anne", "Mary" }); + females.Append("on her"); + + // Create alternatives for male names and add a phrase. + GrammarBuilder males = new Choices(new string[] { "James", "Sam" }); + males.Append("on his"); + + // Create a Choices object that contains an array of alternative + // GrammarBuilder objects. + Choices people = new Choices(); + people.Add(new Choices(new GrammarBuilder[] {females, males})); + + // Create a Choices object that contains a set of alternative phone types. + Choices phoneType = new Choices(); + phoneType.Add(new string[] { "cell", "home", "work" }); + + // Construct the phrase. + GrammarBuilder gb = new GrammarBuilder(); + gb.Append("call"); + gb.Append(people); + gb.Append(phoneType); + gb.Append(new GrammarBuilder("phone"), 0, 1); + + return new Grammar(gb); +} +``` + ]]> @@ -378,54 +374,54 @@ public Grammar CreatePhonePhrase() The objects to add to this object. Adds an array containing one or more objects to the set of alternatives. - , , and objects to , these three classes may be added to a instance as well. - - If `alternateChoices` is an empty array, this method does not update the set of alternatives. - - Applications can use both and to add alternatives to a object. - - This method throws an when `alternateChoices` is `null` or any of the array elements are `null`. - - - -## Examples - The following example creates a speech recognition grammar for phrases such as "Call Anne on her cell" and "Call James on his work phone". The example uses both overloads of the method to build the grammar. - -```csharp -public Grammar CreatePhonePhrase() -{ - - // Create alternatives for female names and add a phrase. - GrammarBuilder females = new Choices(new string[] { "Anne", "Mary" }); - females.Append("on her"); - - // Create alternatives for male names and add a phrase. - GrammarBuilder males = new Choices(new string[] { "James", "Sam" }); - males.Append("on his"); - - // Create a Choices object that contains an array of alternative - // GrammarBuilder objects. - Choices people = new Choices(); - people.Add(new Choices(new GrammarBuilder[] {females, males})); - - // Create a Choices object that contains a set of alternative phone types. - Choices phoneType = new Choices(); - phoneType.Add(new string[] { "cell", "home", "work" }); - - // Construct the phrase. - GrammarBuilder gb = new GrammarBuilder(); - gb.Append("call"); - gb.Append(people); - gb.Append(phoneType); - gb.Append(new GrammarBuilder("phone"), 0, 1); - - return new Grammar(gb); -} -``` - + , , and objects to , these three classes may be added to a instance as well. + + If `alternateChoices` is an empty array, this method does not update the set of alternatives. + + Applications can use both and to add alternatives to a object. + + This method throws an when `alternateChoices` is `null` or any of the array elements are `null`. + + + +## Examples + The following example creates a speech recognition grammar for phrases such as "Call Anne on her cell" and "Call James on his work phone". The example uses both overloads of the method to build the grammar. + +```csharp +public Grammar CreatePhonePhrase() +{ + + // Create alternatives for female names and add a phrase. + GrammarBuilder females = new Choices(new string[] { "Anne", "Mary" }); + females.Append("on her"); + + // Create alternatives for male names and add a phrase. + GrammarBuilder males = new Choices(new string[] { "James", "Sam" }); + males.Append("on his"); + + // Create a Choices object that contains an array of alternative + // GrammarBuilder objects. + Choices people = new Choices(); + people.Add(new Choices(new GrammarBuilder[] {females, males})); + + // Create a Choices object that contains a set of alternative phone types. + Choices phoneType = new Choices(); + phoneType.Add(new string[] { "cell", "home", "work" }); + + // Construct the phrase. + GrammarBuilder gb = new GrammarBuilder(); + gb.Append("call"); + gb.Append(people); + gb.Append(phoneType); + gb.Append(new GrammarBuilder("phone"), 0, 1); + + return new Grammar(gb); +} +``` + ]]> @@ -463,52 +459,52 @@ public Grammar CreatePhonePhrase() The strings to add to this object. Adds an array containing one or more objects to the set of alternatives. - and to add alternatives to a object. - - If `phrases` is an empty array, this method does not update the set of alternates. - - This method throws an when `phrases` is `null` or any of the array elements are `null`. This method throws an if any element in the array is the empty string (""). - - - -## Examples - The following example creates a speech recognition grammar for phrases similar to "Call Anne on her cell" and "Call James on his work phone". The example uses both overloads of the method to build the grammar. - -```csharp -public Grammar CreatePhonePhrase() -{ - - // Create alternatives for female names and add a phrase. - GrammarBuilder females = new Choices(new string[] { "Anne", "Mary" }); - females.Append("on her"); - - // Create alternatives for male names and add a phrase. - GrammarBuilder males = new Choices(new string[] { "James", "Sam" }); - males.Append("on his"); - - // Create a Choices object that contains an array of alternative - // GrammarBuilder objects. - Choices people = new Choices(); - people.Add(new Choices(new GrammarBuilder[] {females, males})); - - // Create a Choices object that contains a set of alternative phone types. - Choices phoneType = new Choices(); - phoneType.Add(new string[] { "cell", "home", "work" }); - - // Construct the phrase. - GrammarBuilder gb = new GrammarBuilder(); - gb.Append("call"); - gb.Append(people); - gb.Append(phoneType); - gb.Append(new GrammarBuilder("phone"), 0, 1); - - return new Grammar(gb); -} -``` - + and to add alternatives to a object. + + If `phrases` is an empty array, this method does not update the set of alternates. + + This method throws an when `phrases` is `null` or any of the array elements are `null`. This method throws an if any element in the array is the empty string (""). + + + +## Examples + The following example creates a speech recognition grammar for phrases similar to "Call Anne on her cell" and "Call James on his work phone". The example uses both overloads of the method to build the grammar. + +```csharp +public Grammar CreatePhonePhrase() +{ + + // Create alternatives for female names and add a phrase. + GrammarBuilder females = new Choices(new string[] { "Anne", "Mary" }); + females.Append("on her"); + + // Create alternatives for male names and add a phrase. + GrammarBuilder males = new Choices(new string[] { "James", "Sam" }); + males.Append("on his"); + + // Create a Choices object that contains an array of alternative + // GrammarBuilder objects. + Choices people = new Choices(); + people.Add(new Choices(new GrammarBuilder[] {females, males})); + + // Create a Choices object that contains a set of alternative phone types. + Choices phoneType = new Choices(); + phoneType.Add(new string[] { "cell", "home", "work" }); + + // Construct the phrase. + GrammarBuilder gb = new GrammarBuilder(); + gb.Append("call"); + gb.Append(people); + gb.Append(phoneType); + gb.Append(new GrammarBuilder("phone"), 0, 1); + + return new Grammar(gb); +} +``` + ]]> @@ -537,42 +533,42 @@ public Grammar CreatePhonePhrase() Returns a object from this object. A that matches this object. - returned by this method is equivalent to one returned by either of the following. - -- Calling the constructor with this object as the parameter. - -- Using the implicit or explicit cast of this object to a . - - - -## Examples - The following example creates a speech recognition grammar for changing the background color. - -```csharp - -private Grammar CreateColorChoice() -{ - - // Create a Choices object that contains a set of alternative colors. - Choices colorChoice = new Choices(new string[] {"red", "green", "blue"}); - - // Construct the phrase. - GrammarBuilder gb = new GrammarBuilder(); - gb.Append(new Choices(new string[] {"Set", "Change"})); - gb.Append("background to"); - gb.Append(colorChoice.ToGrammarBuilder()); - - Grammar grammar = new Grammar(gb); - grammar.Name = "modify background color"; - - return grammar; -} - -``` - + returned by this method is equivalent to one returned by either of the following. + +- Calling the constructor with this object as the parameter. + +- Using the implicit or explicit cast of this object to a . + + + +## Examples + The following example creates a speech recognition grammar for changing the background color. + +```csharp + +private Grammar CreateColorChoice() +{ + + // Create a Choices object that contains a set of alternative colors. + Choices colorChoice = new Choices(new string[] {"red", "green", "blue"}); + + // Construct the phrase. + GrammarBuilder gb = new GrammarBuilder(); + gb.Append(new Choices(new string[] {"Set", "Change"})); + gb.Append("background to"); + gb.Append(colorChoice.ToGrammarBuilder()); + + Grammar grammar = new Grammar(gb); + grammar.Name = "modify background color"; + + return grammar; +} + +``` + ]]> diff --git a/xml/System.Speech.Recognition/Grammar.xml b/xml/System.Speech.Recognition/Grammar.xml index ca5b6fd2fcf..682b80e728b 100644 --- a/xml/System.Speech.Recognition/Grammar.xml +++ b/xml/System.Speech.Recognition/Grammar.xml @@ -25,83 +25,83 @@ A runtime object that references a speech recognition grammar, which an application can use to define the constraints for speech recognition. - object that a speech recognition engine can load and that your application can use at runtime to manage speech recognition. You can use a constructor to create a instance from a or a object, or from a file or a that contains a description of a grammar in a supported format. Supported formats include the following: - -- XML-format files that conform to the W3C [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761) - -- Grammars that have been compiled to a binary file with a .cfg file extension - - Grammar constructors that accept XML-format grammar files in their arguments compile the XML grammars to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. - - An application's speech recognition engine, as managed by a or object, can load multiple speech recognition grammars. The application can independently enable or disable individual grammars by setting the property, and modify recognition behavior through properties, such as the and properties. - - The grammar's event is raised when input matches a path through the grammar. - + object that a speech recognition engine can load and that your application can use at runtime to manage speech recognition. You can use a constructor to create a instance from a or a object, or from a file or a that contains a description of a grammar in a supported format. Supported formats include the following: + +- XML-format files that conform to the W3C [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761) + +- Grammars that have been compiled to a binary file with a .cfg file extension + + Grammar constructors that accept XML-format grammar files in their arguments compile the XML grammars to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. + + An application's speech recognition engine, as managed by a or object, can load multiple speech recognition grammars. The application can independently enable or disable individual grammars by setting the property, and modify recognition behavior through properties, such as the and properties. + + The grammar's event is raised when input matches a path through the grammar. + > [!NOTE] -> It is a best practice to verify the safety of any URI or DLL used to build a object. -> -> Windows and the Speech platform provide security for applications constructing a instance from a DLL or from a grammar that supports scripting. -> -> Scripts in objects are always run as if downloaded from a web page in the `Internet Zone`. The Common Language Runtime (CLR) isolates any DLL loaded to obtain a grammar definition. - - - -## Examples - The following example constructs a object from a speech recognition grammar defined in a XML file (cities.xml). The content of the cities.xml file appears in the following XML example. - -```csharp -// Load a cities grammar from a local file and return the grammar object. -private static Grammar CreateGrammarFromFile() -{ - Grammar citiesGrammar = new Grammar(@"c:\temp\cities.xml"); - citiesGrammar.Name = "SRGS File Cities Grammar"; - return citiesGrammar; -} - -``` - -```xml - - - - - - - - - I would like to fly from - to - - - - - - Seattle - Los Angeles - New York - Miami - - - -``` - +> It is a best practice to verify the safety of any URI or DLL used to build a object. +> +> Windows and the Speech platform provide security for applications constructing a instance from a DLL or from a grammar that supports scripting. +> +> Scripts in objects are always run as if downloaded from a web page in the `Internet Zone`. The Common Language Runtime (CLR) isolates any DLL loaded to obtain a grammar definition. + + + +## Examples + The following example constructs a object from a speech recognition grammar defined in a XML file (cities.xml). The content of the cities.xml file appears in the following XML example. + +```csharp +// Load a cities grammar from a local file and return the grammar object. +private static Grammar CreateGrammarFromFile() +{ + Grammar citiesGrammar = new Grammar(@"c:\temp\cities.xml"); + citiesGrammar.Name = "SRGS File Cities Grammar"; + return citiesGrammar; +} + +``` + +```xml + + + + + + + + + I would like to fly from + to + + + + + + Seattle + Los Angeles + New York + Miami + + + +``` + ]]> - Speech Recognition Grammar Specification + Speech Recognition Grammar Specification @@ -112,21 +112,21 @@ private static Grammar CreateGrammarFromFile() Initializes a new instance of the class. - constructor to create a instance from a or object, or from a file or a that contains a description of a grammar in a supported format. Supported formats include the following: - -- XML-format files that conform to the W3C [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761) - -- Grammars that have been compiled to a binary file with a .cfg file extension - - Grammar constructors that accept XML-format grammar files in their arguments compile the XML grammars to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. - - A speech recognition grammar can define a root rule. To create a object that specifies which rule to use as its root rule, use a constructor that accepts the `ruleName` parameter. - - To create a object that specifies a base URI to resolve relative rule references, use a constructor that takes the `baseUri` parameter. - + constructor to create a instance from a or object, or from a file or a that contains a description of a grammar in a supported format. Supported formats include the following: + +- XML-format files that conform to the W3C [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761) + +- Grammars that have been compiled to a binary file with a .cfg file extension + + Grammar constructors that accept XML-format grammar files in their arguments compile the XML grammars to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. + + A speech recognition grammar can define a root rule. To create a object that specifies which rule to use as its root rule, use a constructor that accepts the `ruleName` parameter. + + To create a object that specifies a base URI to resolve relative rule references, use a constructor that takes the `baseUri` parameter. + ]]> @@ -177,72 +177,72 @@ private static Grammar CreateGrammarFromFile() A stream that describes a speech recognition grammar in a supported format. Initializes a new instance of the class from a . - instance from the following formats: - -- XML-format files that conform to the W3C [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761) - -- Grammars that have been compiled to a binary file with a .cfg file extension - - This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. - - An SRGS grammar can define a root rule. To create a object from a stream and specify a root rule, use the or constructor. - - To create a object from a stream and specify a base URI to use to resolve relative rule references, use the constructor. - - - -## Examples - The following example creates a speech recognition grammar from a local SRGS file (cities.xml) using a file stream. The content of the cities.xml file appears following C# example. - -```csharp - -// Load a cities grammar from an I/O stream and -// return the new grammar. -private static Grammar CreateGrammarFromStream() -{ - string fileName = @"c:\temp\cities.xml"; - Grammar citiesGrammar = - new Grammar(new FileStream(fileName, FileMode.Open)); - citiesGrammar.Name = "Stream Cities Grammar"; - return citiesGrammar; -} -``` - -```xml - - - - - - - - - I would like to fly from - to - - - - - - Seattle - Los Angeles - New York - Miami - - - -``` - + instance from the following formats: + +- XML-format files that conform to the W3C [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761) + +- Grammars that have been compiled to a binary file with a .cfg file extension + + This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. + + An SRGS grammar can define a root rule. To create a object from a stream and specify a root rule, use the or constructor. + + To create a object from a stream and specify a base URI to use to resolve relative rule references, use the constructor. + + + +## Examples + The following example creates a speech recognition grammar from a local SRGS file (cities.xml) using a file stream. The content of the cities.xml file appears following C# example. + +```csharp + +// Load a cities grammar from an I/O stream and +// return the new grammar. +private static Grammar CreateGrammarFromStream() +{ + string fileName = @"c:\temp\cities.xml"; + Grammar citiesGrammar = + new Grammar(new FileStream(fileName, FileMode.Open)); + citiesGrammar.Name = "Stream Cities Grammar"; + return citiesGrammar; +} +``` + +```xml + + + + + + + + + I would like to fly from + to + + + + + + Seattle + Los Angeles + New York + Miami + + + +``` + ]]> @@ -253,7 +253,7 @@ private static Grammar CreateGrammarFromStream() - Speech Recognition Grammar Specification + Speech Recognition Grammar Specification @@ -277,32 +277,32 @@ private static Grammar CreateGrammarFromStream() An instance of that contains the constraints for the speech recognition grammar. Initializes a new instance of the class from a object. - and objects. The constructor creates a object from the object. - + and objects. The constructor creates a object from the object. + ```csharp -// Create a grammar using a GrammarBuilder and return the new grammar. -private static Grammar CreateGrammarBuilderGrammar() -{ - GrammarBuilder builder = new GrammarBuilder(); - - Choices cityChoice = new Choices (new string[] - {"Seattle", "New York", "Miami", "Los Angeles"}); - - builder.Append("I would like to fly from"); - builder.Append(cityChoice); - builder.Append("to"); - builder.Append(cityChoice); - - Grammar citiesGrammar = new Grammar(builder); - citiesGrammar.Name = "GrammarBuilder Cities Grammar"; - - return citiesGrammar; -} -``` - +// Create a grammar using a GrammarBuilder and return the new grammar. +private static Grammar CreateGrammarBuilderGrammar() +{ + GrammarBuilder builder = new GrammarBuilder(); + + Choices cityChoice = new Choices (new string[] + {"Seattle", "New York", "Miami", "Los Angeles"}); + + builder.Append("I would like to fly from"); + builder.Append(cityChoice); + builder.Append("to"); + builder.Append(cityChoice); + + Grammar citiesGrammar = new Grammar(builder); + citiesGrammar.Name = "GrammarBuilder Cities Grammar"; + + return citiesGrammar; +} +``` + ]]> @@ -337,62 +337,62 @@ private static Grammar CreateGrammarBuilderGrammar() The constraints for the speech recognition grammar. Initializes a new instance of the class from an object. - should not contain an initialization handler that requires arguments. - - A can have a root rule. To create a object that specifies a root rule, use the or constructor. - - To create a speech recognition from an and specify a base URI to use to resolve relative rule references, use the constructor. - - - -## Examples - The following example creates a speech recognition grammar in an instance, which is then used to construct a object. - -```csharp -private static Grammar CreateSrgsDocumentGrammar() -{ - // Create the SrgsDocument. - SrgsDocument document = new SrgsDocument(); - - // Create the Cities rule and add it to the document. - SrgsRule citiesRule = new SrgsRule("Cities"); - - SrgsOneOf cityChoice = new SrgsOneOf(); - cityChoice.Add(new SrgsItem("Seattle")); - cityChoice.Add(new SrgsItem("Los Angeles")); - cityChoice.Add(new SrgsItem("New York")); - cityChoice.Add(new SrgsItem("Miami")); - - citiesRule.Add(cityChoice); - document.Rules.Add(citiesRule); - - // Create the Main rule and add it to the document. - SrgsRule mainRule = new SrgsRule("Main"); - mainRule.Scope = SrgsRuleScope.Public; - - SrgsItem item = new SrgsItem("I would like to fly from"); - item.Add(new SrgsRuleRef(citiesRule)); - item.Add(new SrgsText("to")); - item.Add(new SrgsRuleRef(citiesRule)); - - mainRule.Add(item); - document.Rules.Add(mainRule); - - // Set the root rule. - document.Root = mainRule; - - // Create the Grammar object. - Grammar citiesGrammar = new Grammar(document); - citiesGrammar.Name = "SrgsDocument Cities Grammar"; - - return citiesGrammar; -} - -``` - + should not contain an initialization handler that requires arguments. + + A can have a root rule. To create a object that specifies a root rule, use the or constructor. + + To create a speech recognition from an and specify a base URI to use to resolve relative rule references, use the constructor. + + + +## Examples + The following example creates a speech recognition grammar in an instance, which is then used to construct a object. + +```csharp +private static Grammar CreateSrgsDocumentGrammar() +{ + // Create the SrgsDocument. + SrgsDocument document = new SrgsDocument(); + + // Create the Cities rule and add it to the document. + SrgsRule citiesRule = new SrgsRule("Cities"); + + SrgsOneOf cityChoice = new SrgsOneOf(); + cityChoice.Add(new SrgsItem("Seattle")); + cityChoice.Add(new SrgsItem("Los Angeles")); + cityChoice.Add(new SrgsItem("New York")); + cityChoice.Add(new SrgsItem("Miami")); + + citiesRule.Add(cityChoice); + document.Rules.Add(citiesRule); + + // Create the Main rule and add it to the document. + SrgsRule mainRule = new SrgsRule("Main"); + mainRule.Scope = SrgsRuleScope.Public; + + SrgsItem item = new SrgsItem("I would like to fly from"); + item.Add(new SrgsRuleRef(citiesRule)); + item.Add(new SrgsText("to")); + item.Add(new SrgsRuleRef(citiesRule)); + + mainRule.Add(item); + document.Rules.Add(mainRule); + + // Set the root rule. + document.Root = mainRule; + + // Create the Grammar object. + Grammar citiesGrammar = new Grammar(document); + citiesGrammar.Name = "SrgsDocument Cities Grammar"; + + return citiesGrammar; +} + +``` + ]]> @@ -405,7 +405,7 @@ private static Grammar CreateSrgsDocumentGrammar() - Speech Recognition Grammar Specification + Speech Recognition Grammar Specification @@ -435,70 +435,70 @@ private static Grammar CreateSrgsDocumentGrammar() The path of the file that describes a speech recognition grammar in a supported format. Initializes a new instance of the class from a file. - instance from the following formats: - -- XML-format files that conform to the W3C [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761) - -- Grammars that have been compiled to a binary file with a .cfg file extension - - This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. - - 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. - - - -## Examples - The following example loads a speech recognition grammar from a local SRGS file to build a object. The content of the cities.xml file appears in the XML example that follows the C# example. - -```csharp -// Load a cities grammar from a local file and -// return the new grammar. -private static Grammar CreateGrammarFromFile() -{ - Grammar citiesGrammar = new Grammar(@"c:\temp\cities.xml"); - citiesGrammar.Name = "SRGS File Cities Grammar"; - return citiesGrammar; -} - -``` - -```xml - - - - - - - - - I would like to fly from - to - - - - - - Seattle - Los Angeles - New York - Miami - - - -``` - + instance from the following formats: + +- XML-format files that conform to the W3C [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761) + +- Grammars that have been compiled to a binary file with a .cfg file extension + + This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. + + 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. + + + +## Examples + The following example loads a speech recognition grammar from a local SRGS file to build a object. The content of the cities.xml file appears in the XML example that follows the C# example. + +```csharp +// Load a cities grammar from a local file and +// return the new grammar. +private static Grammar CreateGrammarFromFile() +{ + Grammar citiesGrammar = new Grammar(@"c:\temp\cities.xml"); + citiesGrammar.Name = "SRGS File Cities Grammar"; + return citiesGrammar; +} + +``` + +```xml + + + + + + + + + I would like to fly from + to + + + + + + Seattle + Los Angeles + New York + Miami + + + +``` + ]]> @@ -508,7 +508,7 @@ private static Grammar CreateGrammarFromFile() The file does not contain a valid description, or describes a grammar that contains a rule reference that cannot be resolved. - Speech Recognition Grammar Specification + Speech Recognition Grammar Specification @@ -540,69 +540,69 @@ private static Grammar CreateGrammarFromFile() The identifier of the rule to use as the entry point of the speech recognition grammar, or to use the default root rule of the grammar description. Initializes a new instance of the class from a and specifies a root rule. - instance from the following formats: - -- XML-format files that conform to the W3C [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761) - -- Grammars that have been compiled to a binary file with a .cfg file extension - - This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. - - To create a from a stream and specify a base URI to use to resolve relative rule references, use the constructor. - - - -## Examples - The following example loads a local SRGS file (cities.xml) from a file stream and specifies a rule to use as the root of the grammar. The content of the cities.xml file appears in the XML example that follows the C# example. - -```csharp - -// Load a cities grammar from an I/O stream, use a specific -// rule as the root of the grammar, and return the new grammar. -private static Grammar CreateGrammarFromStream2() -{ - FileInfo file = new FileInfo(@"c:\temp\cities.xml"); - Grammar citiesGrammar = new Grammar(file.OpenRead(), "Main"); - citiesGrammar.Name = "Stream Cities Grammar 2"; - return citiesGrammar; -} -``` - -```xml - - - - - - - - - I would like to fly from - to - - - - - - Seattle - Los Angeles - New York - Miami - - - -``` - + instance from the following formats: + +- XML-format files that conform to the W3C [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761) + +- Grammars that have been compiled to a binary file with a .cfg file extension + + This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. + + To create a from a stream and specify a base URI to use to resolve relative rule references, use the constructor. + + + +## Examples + The following example loads a local SRGS file (cities.xml) from a file stream and specifies a rule to use as the root of the grammar. The content of the cities.xml file appears in the XML example that follows the C# example. + +```csharp + +// Load a cities grammar from an I/O stream, use a specific +// rule as the root of the grammar, and return the new grammar. +private static Grammar CreateGrammarFromStream2() +{ + FileInfo file = new FileInfo(@"c:\temp\cities.xml"); + Grammar citiesGrammar = new Grammar(file.OpenRead(), "Main"); + citiesGrammar.Name = "Stream Cities Grammar 2"; + return citiesGrammar; +} +``` + +```xml + + + + + + + + + I would like to fly from + to + + + + + + Seattle + Los Angeles + New York + Miami + + + +``` + ]]> @@ -613,7 +613,7 @@ private static Grammar CreateGrammarFromStream2() - Speech Recognition Grammar Specification + Speech Recognition Grammar Specification @@ -645,94 +645,94 @@ private static Grammar CreateGrammarFromStream2() The identifier of the rule to use as the entry point of the speech recognition grammar, or to use the default root rule of the . Initializes a new instance of the class from an object and specifies a root rule. - should not contain an initialization handler that requires arguments. - - To create a object from a and specify a base URI to use to resolve relative rule references, use the constructor. - - - -## Examples - The following example creates a speech recognition grammar in an instance and specifies a rule to use as the root rule of the grammar. The example constructs a object from the instance and loads it into the speech recognition engine. - -```csharp -using System; -using System.Speech.Recognition; -using System.Speech.Recognition.SrgsGrammar; - -namespace SampleRecognition -{ - class Program - { - static void Main(string[] args) - - // Initialize an in-process speech recognition engine. - { - using (SpeechRecognitionEngine recognizer = - new SpeechRecognitionEngine()) - { - - // Create the SrgsDocument. - SrgsDocument document = new SrgsDocument(); - - // Create the Cities rule and add it to the document. - SrgsRule citiesRule = new SrgsRule("Cities"); - citiesRule.Scope = SrgsRuleScope.Public; - - SrgsOneOf cityChoice = new SrgsOneOf(); - cityChoice.Add(new SrgsItem("Seattle")); - cityChoice.Add(new SrgsItem("Los Angeles")); - cityChoice.Add(new SrgsItem("New York")); - cityChoice.Add(new SrgsItem("Miami")); - - citiesRule.Add(cityChoice); - document.Rules.Add(citiesRule); - - // Create the Main rule and add it to the document. - SrgsRule mainRule = new SrgsRule("Main"); - mainRule.Scope = SrgsRuleScope.Public; - - mainRule.Add(new SrgsItem("I would like to fly from")); - mainRule.Add(new SrgsRuleRef(citiesRule)); - mainRule.Add(new SrgsItem("to")); - mainRule.Add(new SrgsRuleRef(citiesRule)); - - document.Rules.Add(mainRule); - - // Create the Grammar object and specify which rule to use as the root. - Grammar citiesGrammar = new Grammar(document,"Main"); - - // Load the grammar object to the recognizer. - recognizer.LoadGrammarAsync(citiesGrammar); - - // Attach a handler for the SpeechRecognized event. - recognizer.SpeechRecognized += - new EventHandler(recognizer_SpeechRecognized); - - // Set the input to the recognizer. - recognizer.SetInputToDefaultAudioDevice(); - - // Start recognition. - recognizer.RecognizeAsync(); - Console.WriteLine("Starting asynchronous recognition..."); - - // Keep the console window open. - Console.ReadLine(); - } - } - - // Handle the SpeechRecognized event. - static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) - { - Console.WriteLine(" Speech recognized: " + e.Result.Text); - } - } -} - -``` - + should not contain an initialization handler that requires arguments. + + To create a object from a and specify a base URI to use to resolve relative rule references, use the constructor. + + + +## Examples + The following example creates a speech recognition grammar in an instance and specifies a rule to use as the root rule of the grammar. The example constructs a object from the instance and loads it into the speech recognition engine. + +```csharp +using System; +using System.Speech.Recognition; +using System.Speech.Recognition.SrgsGrammar; + +namespace SampleRecognition +{ + class Program + { + static void Main(string[] args) + + // Initialize an in-process speech recognition engine. + { + using (SpeechRecognitionEngine recognizer = + new SpeechRecognitionEngine()) + { + + // Create the SrgsDocument. + SrgsDocument document = new SrgsDocument(); + + // Create the Cities rule and add it to the document. + SrgsRule citiesRule = new SrgsRule("Cities"); + citiesRule.Scope = SrgsRuleScope.Public; + + SrgsOneOf cityChoice = new SrgsOneOf(); + cityChoice.Add(new SrgsItem("Seattle")); + cityChoice.Add(new SrgsItem("Los Angeles")); + cityChoice.Add(new SrgsItem("New York")); + cityChoice.Add(new SrgsItem("Miami")); + + citiesRule.Add(cityChoice); + document.Rules.Add(citiesRule); + + // Create the Main rule and add it to the document. + SrgsRule mainRule = new SrgsRule("Main"); + mainRule.Scope = SrgsRuleScope.Public; + + mainRule.Add(new SrgsItem("I would like to fly from")); + mainRule.Add(new SrgsRuleRef(citiesRule)); + mainRule.Add(new SrgsItem("to")); + mainRule.Add(new SrgsRuleRef(citiesRule)); + + document.Rules.Add(mainRule); + + // Create the Grammar object and specify which rule to use as the root. + Grammar citiesGrammar = new Grammar(document,"Main"); + + // Load the grammar object to the recognizer. + recognizer.LoadGrammarAsync(citiesGrammar); + + // Attach a handler for the SpeechRecognized event. + recognizer.SpeechRecognized += + new EventHandler(recognizer_SpeechRecognized); + + // Set the input to the recognizer. + recognizer.SetInputToDefaultAudioDevice(); + + // Start recognition. + recognizer.RecognizeAsync(); + Console.WriteLine("Starting asynchronous recognition..."); + + // Keep the console window open. + Console.ReadLine(); + } + } + + // Handle the SpeechRecognized event. + static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) + { + Console.WriteLine(" Speech recognized: " + e.Result.Text); + } + } +} + +``` + ]]> @@ -745,7 +745,7 @@ namespace SampleRecognition - Speech Recognition Grammar Specification + Speech Recognition Grammar Specification @@ -777,68 +777,68 @@ namespace SampleRecognition The identifier of the rule to use as the entry point of the speech recognition grammar, or to use the default root rule of the grammar description. Initializes a new instance of the class from a file and specifies a root rule. - instance from the following formats: - -- XML-format files that conform to the W3C [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761) - -- Grammars that have been compiled to a binary file with a .cfg file extension - - This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. - - To create a that specifies a base URI to use to resolve relative rule references, open a file stream for the file and use the constructor. - - - -## Examples - The following example loads a local SRGS file (cities.xml) from a file and specifies a rule to use as the root of the grammar. The content of the cities.xml file appears in the XML example that follows the C# example. - -```csharp - -// Load a cities grammar from a local file, use a specific -// rule as the root of the grammar, and return the new grammar. -private static Grammar CreateGrammarFromFile2() -{ - Grammar citiesGrammar = new Grammar(@"c:\temp\cities.xml", "Main"); - citiesGrammar.Name = "SRGS File Cities Grammar 2"; - return citiesGrammar; -} -``` - -```xml - - - - - - - - - I would like to fly from - to - - - - - - Seattle - Los Angeles - New York - Miami - - - -``` - + instance from the following formats: + +- XML-format files that conform to the W3C [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761) + +- Grammars that have been compiled to a binary file with a .cfg file extension + + This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. + + To create a that specifies a base URI to use to resolve relative rule references, open a file stream for the file and use the constructor. + + + +## Examples + The following example loads a local SRGS file (cities.xml) from a file and specifies a rule to use as the root of the grammar. The content of the cities.xml file appears in the XML example that follows the C# example. + +```csharp + +// Load a cities grammar from a local file, use a specific +// rule as the root of the grammar, and return the new grammar. +private static Grammar CreateGrammarFromFile2() +{ + Grammar citiesGrammar = new Grammar(@"c:\temp\cities.xml", "Main"); + citiesGrammar.Name = "SRGS File Cities Grammar 2"; + return citiesGrammar; +} +``` + +```xml + + + + + + + + + I would like to fly from + to + + + + + + Seattle + Los Angeles + New York + Miami + + + +``` + ]]> @@ -848,7 +848,7 @@ private static Grammar CreateGrammarFromFile2() The file does not contain a valid description or describes a grammar that contains a rule reference that cannot be resolved. - Speech Recognition Grammar Specification + Speech Recognition Grammar Specification @@ -882,20 +882,20 @@ private static Grammar CreateGrammarFromFile2() Parameters to be passed to the initialization handler specified by the property for the entry point or the root rule of the to be created. This parameter may be null. Initializes a new instance of the class from a and specifies a root rule. - - is connected to a grammar that: - -- Does not contain the rule specified in - -- Requires initialization parameters different from those specified in - + is connected to a grammar that: + +- Does not contain the rule specified in + +- Requires initialization parameters different from those specified in + - Contains a relative rule reference that cannot be resolved by the default base rule for grammars. @@ -938,88 +938,88 @@ private static Grammar CreateGrammarFromFile2() The base URI to use to resolve any relative rule reference in the grammar description, or . Initializes a new instance of the class from a stream, specifies a root rule, and defines a base Uniform Resource Identifier (URI) to resolve relative rule references. - instance from the following formats: - -- XML-format files that conform to the W3C [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761) - -- Grammars that have been compiled to a binary file with a .cfg file extension - - This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. - - This constructor does not validate `baseUri`. However, the `LoadGrammar` method of a or object throws an exception if it cannot resolve all of the rule references in the grammar description. If `baseUri` is not `null`, the `LoadGrammar` method uses the URI to resolve any rule references that it cannot otherwise resolve. If `baseUri` represents a file, then the `LoadGrammar` uses both the designated file and the file's directory when it attempts to resolve relative rule references. - - - -## Examples - The following example loads a local SRGS file (shuttle.xml) from a file stream. The file contains a relative rule reference to a rule in the cities.xml file, and specifies a base URI to use to resolve the rule reference. The content of the shuttle.xml and cities.xml files appears in the XML examples that follow the C# example. - -```csharp - -private static Grammar CreateGrammarFromStream3() -{ - FileInfo file = new FileInfo(@".\shuttle.xml"); - Uri baseUri = new Uri(@"file://c:\temp\"); - Grammar citiesGrammar = new Grammar(file.OpenRead(), null, baseUri); - citiesGrammar.Name = "Stream Cities Grammar 3"; - return citiesGrammar; -} -``` - -```xml - - - - - - - - - Can I get a shuttle in - - - - -``` - -```xml - - - - - - - - - I would like to fly from - to - - - - - - Seattle - Los Angeles - New York - Miami - - - -``` - + instance from the following formats: + +- XML-format files that conform to the W3C [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761) + +- Grammars that have been compiled to a binary file with a .cfg file extension + + This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. + + This constructor does not validate `baseUri`. However, the `LoadGrammar` method of a or object throws an exception if it cannot resolve all of the rule references in the grammar description. If `baseUri` is not `null`, the `LoadGrammar` method uses the URI to resolve any rule references that it cannot otherwise resolve. If `baseUri` represents a file, then the `LoadGrammar` uses both the designated file and the file's directory when it attempts to resolve relative rule references. + + + +## Examples + The following example loads a local SRGS file (shuttle.xml) from a file stream. The file contains a relative rule reference to a rule in the cities.xml file, and specifies a base URI to use to resolve the rule reference. The content of the shuttle.xml and cities.xml files appears in the XML examples that follow the C# example. + +```csharp + +private static Grammar CreateGrammarFromStream3() +{ + FileInfo file = new FileInfo(@".\shuttle.xml"); + Uri baseUri = new Uri(@"file://c:\temp\"); + Grammar citiesGrammar = new Grammar(file.OpenRead(), null, baseUri); + citiesGrammar.Name = "Stream Cities Grammar 3"; + return citiesGrammar; +} +``` + +```xml + + + + + + + + + Can I get a shuttle in + + + + +``` + +```xml + + + + + + + + + I would like to fly from + to + + + + + + Seattle + Los Angeles + New York + Miami + + + +``` + ]]> @@ -1030,7 +1030,7 @@ private static Grammar CreateGrammarFromStream3() - Speech Recognition Grammar Specification + Speech Recognition Grammar Specification @@ -1064,17 +1064,17 @@ private static Grammar CreateGrammarFromStream3() Parameters to be passed to the initialization handler specified by the property for the entry point or the root rule of the to be created. This parameter may be null. Initializes a new instance of the class from an instance of , and specifies the name of a rule to be the entry point to the grammar. - - - Any of the parameters contain an invalid value. - -- The specified by does not contain the rule specified by . - + - Any of the parameters contain an invalid value. + +- The specified by does not contain the rule specified by . + - The contents of the array parameters do not match the arguments of any of the rule's initialization handlers. @@ -1117,82 +1117,82 @@ private static Grammar CreateGrammarFromStream3() The base URI to use to resolve any relative rule reference in the , or . Initializes a new instance of the class from an object, specifies a root rule, and defines a base Uniform Resource Identifier (URI) to resolve relative rule references. - should not contain an initialization handler that requires arguments. - - This constructor does not validate `baseUri`. However, the `LoadGrammar` method of a or object throws an exception if it cannot resolve all of the rule references in the grammar description. If `baseUri` is not `null`, the `LoadGrammar` method uses the URI to resolve any rule references that it cannot otherwise resolve. If `baseUri` represents a file, then the `LoadGrammar` method uses both the designated file and the file's directory when it attempts to resolve relative rule references. - - - -## Examples - The following example creates a speech recognition grammar in an that contains a relative rule reference to the cities.xml file, and specifies a URI to use to resolve the rule reference. The content of the cities.xml file appears in the XML example that follows the C# example. - -```csharp - -private static Grammar CreateSrgsDocumentGrammar3() -{ - // Create the SrgsDocument. - SrgsDocument document = new SrgsDocument(); - - // Create the Main rule and add it to the document. - SrgsRule mainRule = new SrgsRule("Main"); - mainRule.Scope = SrgsRuleScope.Public; - - SrgsItem item = new SrgsItem("Can I get a shuttle in"); - - // Create a relative URI for the cities rule. - Uri ruleUri = new Uri("cities.xml#Cities", UriKind.Relative); - - item.Add(new SrgsRuleRef(ruleUri)); - - mainRule.Add(item); - document.Rules.Add(mainRule); - - // Set the root rule. - document.Root = mainRule; - - // Create the grammar. - Uri baseUri = new Uri(@"file://c:\temp\"); - Grammar citiesGrammar = new Grammar(document, null, baseUri); - citiesGrammar.Name = "SrgsDocument Cities Grammar 3"; - - return citiesGrammar; -} - -``` - -```xml - - - - - - - - - I would like to fly from - to - - - - - - Seattle - Los Angeles - New York - Miami - - - -``` - + should not contain an initialization handler that requires arguments. + + This constructor does not validate `baseUri`. However, the `LoadGrammar` method of a or object throws an exception if it cannot resolve all of the rule references in the grammar description. If `baseUri` is not `null`, the `LoadGrammar` method uses the URI to resolve any rule references that it cannot otherwise resolve. If `baseUri` represents a file, then the `LoadGrammar` method uses both the designated file and the file's directory when it attempts to resolve relative rule references. + + + +## Examples + The following example creates a speech recognition grammar in an that contains a relative rule reference to the cities.xml file, and specifies a URI to use to resolve the rule reference. The content of the cities.xml file appears in the XML example that follows the C# example. + +```csharp + +private static Grammar CreateSrgsDocumentGrammar3() +{ + // Create the SrgsDocument. + SrgsDocument document = new SrgsDocument(); + + // Create the Main rule and add it to the document. + SrgsRule mainRule = new SrgsRule("Main"); + mainRule.Scope = SrgsRuleScope.Public; + + SrgsItem item = new SrgsItem("Can I get a shuttle in"); + + // Create a relative URI for the cities rule. + Uri ruleUri = new Uri("cities.xml#Cities", UriKind.Relative); + + item.Add(new SrgsRuleRef(ruleUri)); + + mainRule.Add(item); + document.Rules.Add(mainRule); + + // Set the root rule. + document.Root = mainRule; + + // Create the grammar. + Uri baseUri = new Uri(@"file://c:\temp\"); + Grammar citiesGrammar = new Grammar(document, null, baseUri); + citiesGrammar.Name = "SrgsDocument Cities Grammar 3"; + + return citiesGrammar; +} + +``` + +```xml + + + + + + + + + I would like to fly from + to + + + + + + Seattle + Los Angeles + New York + Miami + + + +``` + ]]> @@ -1205,7 +1205,7 @@ private static Grammar CreateSrgsDocumentGrammar3() - Speech Recognition Grammar Specification + Speech Recognition Grammar Specification @@ -1233,19 +1233,19 @@ private static Grammar CreateSrgsDocumentGrammar3() Parameters to be passed to the initialization handler specified by the property for the entry point or the root rule of the to be created. This parameter may be null. Initializes a new instance of the class from a file that contains a grammar definition, and specifies the name of a rule to be the entry point to the grammar. - - - Any of the parameters contain an invalid value. - -- The file specified by does not contain a valid grammar or the rule specified in . - -- The contents of the array parameters do not match the arguments of any of the rule's initialization handlers. - + - Any of the parameters contain an invalid value. + +- The file specified by does not contain a valid grammar or the rule specified in . + +- The contents of the array parameters do not match the arguments of any of the rule's initialization handlers. + - The grammar has a relative rule reference that cannot be resolved by the default base rule for grammars. @@ -1286,19 +1286,19 @@ private static Grammar CreateSrgsDocumentGrammar3() Parameters to be passed to the initialization handler specified by the property for the entry point or the root rule of the to be created. This parameter may be null. Initializes a new instance of the class a and specifies a root rule and a base URI to resolve relative references. - - - Any of the parameters contain an invalid value. - -- The is connected to a grammar that does not contain the rule specified by . - -- The contents of the array parameters do not match the arguments of any of the rule's initialization handlers. - + - Any of the parameters contain an invalid value. + +- The is connected to a grammar that does not contain the rule specified by . + +- The contents of the array parameters do not match the arguments of any of the rule's initialization handlers. + - The grammar contains a relative rule reference that cannot be resolved by the default base rule for grammars or the URI supplied by . @@ -1339,19 +1339,19 @@ private static Grammar CreateSrgsDocumentGrammar3() Parameters to be passed to the initialization handler specified by the property for the entry point or the root rule of the to be created. This parameter may be null. Initializes a new instance of the class from an instance of , and specifies the name of a rule to be the entry point to the grammar and a base URI to resolve relative references. - - - Any of the parameters contain an invalid value. - -- The specified by does not contain the rule specified in . - -- The contents of the array parameters do not match the arguments of any of the rule's initialization handlers. - + - Any of the parameters contain an invalid value. + +- The specified by does not contain the rule specified in . + +- The contents of the array parameters do not match the arguments of any of the rule's initialization handlers. + - The grammar has a relative rule reference that cannot be resolved by the default base rule for grammars or the URI supplied by . @@ -1382,42 +1382,42 @@ private static Grammar CreateSrgsDocumentGrammar3() Gets or sets a value that controls whether a can be used by a speech recognizer to perform recognition. The property returns if a speech recognizer can perform recognition using the speech recognition grammar; otherwise the property returns . The default is . - may be enabled or disabled independently of being loaded by a speech recognition engine. - - - -## Examples - The following example writes information about a object to the [console](https://go.microsoft.com/fwlink/?LinkId=159613). - -```csharp - -private static void DumpGrammarStatus(Grammar item) -{ - Console.WriteLine("Grammar name is {0}:", item.Name); - Console.WriteLine(" The Grammar {0} loaded.", - item.Loaded ? "is" : "is not"); - Console.WriteLine(" The Grammar {0} enabled.", - item.Enabled ? "is" : "is not"); - if (item.RuleName != null) - { - Console.WriteLine(" The root rule is {0}.", item.RuleName); - } - else - { - Console.WriteLine(" The Grammar does not specify a root rule."); - } -} -``` - + may be enabled or disabled independently of being loaded by a speech recognition engine. + + + +## Examples + The following example writes information about a object to the [console](https://go.microsoft.com/fwlink/?LinkId=159613). + +```csharp + +private static void DumpGrammarStatus(Grammar item) +{ + Console.WriteLine("Grammar name is {0}:", item.Name); + Console.WriteLine(" The Grammar {0} loaded.", + item.Loaded ? "is" : "is not"); + Console.WriteLine(" The Grammar {0} enabled.", + item.Enabled ? "is" : "is not"); + if (item.RuleName != null) + { + Console.WriteLine(" The root rule is {0}.", item.RuleName); + } + else + { + Console.WriteLine(" The Grammar does not specify a root rule."); + } +} +``` + ]]> - Speech Recognition Grammar Specification + Speech Recognition Grammar Specification @@ -1447,15 +1447,15 @@ private static void DumpGrammarStatus(Grammar item) Gets whether a grammar is strongly typed. The property returns if the grammar is strongly-typed; otherwise the property returns . - object (`IsStg` equals `true`) can return strongly-typed results (objects, rather than raw text) to a client application. For example, a strongly-typed grammar might return objects rather than raw recognized input. - - You can implement strongly-typed grammars by attaching code to the rules of a grammar. As a recognition engine processes any given rule, taking as input the current partial results, the associated code is executed and the textual information becomes rich type objects. This allows a client to more easily make use of enhanced semantic checking, support for multiple cultures, and internal grammar logic. - - Instances of strongly-typed objects are typically obtained from resources in an assembly as a of the Common Language Runtime (CLR). The localized types used to support different languages are examples of such objects. - + object (`IsStg` equals `true`) can return strongly-typed results (objects, rather than raw text) to a client application. For example, a strongly-typed grammar might return objects rather than raw recognized input. + + You can implement strongly-typed grammars by attaching code to the rules of a grammar. As a recognition engine processes any given rule, taking as input the current partial results, the associated code is executed and the textual information becomes rich type objects. This allows a client to more easily make use of enhanced semantic checking, support for multiple cultures, and internal grammar logic. + + Instances of strongly-typed objects are typically obtained from resources in an assembly as a of the Common Language Runtime (CLR). The localized types used to support different languages are examples of such objects. + ]]> @@ -1484,36 +1484,36 @@ private static void DumpGrammarStatus(Grammar item) Gets whether a has been loaded by a speech recognizer. The property returns if the referenced speech recognition grammar is currently loaded in a speech recognizer; otherwise the property returns . The default is . - has been loaded, the values of , and cannot be changed. - - - -## Examples - The following example writes information about a object to the [console](https://go.microsoft.com/fwlink/?LinkId=159613). - -```csharp - -private static void DumpGrammarStatus(Grammar item) -{ - Console.WriteLine("Grammar name is {0}:", item.Name); - Console.WriteLine(" The Grammar {0} loaded.", - item.Loaded ? "is" : "is not"); - Console.WriteLine(" The Grammar {0} enabled.", - item.Enabled ? "is" : "is not"); - if (item.RuleName != null) - { - Console.WriteLine(" The root rule is {0}.", item.RuleName); - } - else - { - Console.WriteLine(" The Grammar does not specify a root rule."); - } -} -``` - + has been loaded, the values of , and cannot be changed. + + + +## Examples + The following example writes information about a object to the [console](https://go.microsoft.com/fwlink/?LinkId=159613). + +```csharp + +private static void DumpGrammarStatus(Grammar item) +{ + Console.WriteLine("Grammar name is {0}:", item.Name); + Console.WriteLine(" The Grammar {0} loaded.", + item.Loaded ? "is" : "is not"); + Console.WriteLine(" The Grammar {0} enabled.", + item.Enabled ? "is" : "is not"); + if (item.RuleName != null) + { + Console.WriteLine(" The root rule is {0}.", item.RuleName); + } + else + { + Console.WriteLine(" The Grammar does not specify a root rule."); + } +} +``` + ]]> @@ -1555,11 +1555,11 @@ private static void DumpGrammarStatus(Grammar item) The method returns a localized instance of a object derived from . The method returns a valid object based on , or if there has been an error. - for more information on strongly typed grammars). If `onInitParameters` is a null reference (Nothing in Visual Basic) the localized grammar should have either no initialization method, or a method that takes no arguments. - + for more information on strongly typed grammars). If `onInitParameters` is a null reference (Nothing in Visual Basic) the localized grammar should have either no initialization method, or a method that takes no arguments. + ]]> @@ -1591,41 +1591,41 @@ private static void DumpGrammarStatus(Grammar item) Gets or sets the name of a object. The property returns the name of the object. The default is . - objects, one for digits and one for fractions. The Grammar objects are assigned names and relative weights and priorities, and loaded by an in-process speech recognizer. The `CreateDigitsGrammar`, `CreateFractionsGrammar`, and `recognizer_SpeechRecognized` methods are not shown here. - -```csharp - -// Create a Grammar for recognizing numeric digits. -Grammar digitsGrammar = CreateDigitsGrammar(); -digitsGrammar.Name = "Digits Grammar"; -digitsGrammar.Priority = 2; -digitsGrammar.Weight = 0.6f; - -// Create a Grammar for recognizing fractions. -Grammar fractionsGrammar = CreateFractionsGrammar(); -fractionsGrammar.Name = "Fractions Grammar"; -fractionsGrammar.Priority = 1; -fractionsGrammar.Weight = 1f; - -// Create an in-process speech recognizer. -SpeechRecognitionEngine recognizer = new SpeechRecognitionEngine(); - -recognizer.SpeechRecognized += - new EventHandler( - recognizer_SpeechRecognized); - -// Load the digits and fractions Grammar objects. -recognizer.LoadGrammar(digitsGrammar); -recognizer.LoadGrammar(fractionsGrammar); - -// Start recognition. -recognizer.SetInputToDefaultAudioDevice(); -recognizer.RecognizeAsync(RecognizeMode.Multiple); -``` - + objects, one for digits and one for fractions. The Grammar objects are assigned names and relative weights and priorities, and loaded by an in-process speech recognizer. The `CreateDigitsGrammar`, `CreateFractionsGrammar`, and `recognizer_SpeechRecognized` methods are not shown here. + +```csharp + +// Create a Grammar for recognizing numeric digits. +Grammar digitsGrammar = CreateDigitsGrammar(); +digitsGrammar.Name = "Digits Grammar"; +digitsGrammar.Priority = 2; +digitsGrammar.Weight = 0.6f; + +// Create a Grammar for recognizing fractions. +Grammar fractionsGrammar = CreateFractionsGrammar(); +fractionsGrammar.Name = "Fractions Grammar"; +fractionsGrammar.Priority = 1; +fractionsGrammar.Weight = 1f; + +// Create an in-process speech recognizer. +SpeechRecognitionEngine recognizer = new SpeechRecognitionEngine(); + +recognizer.SpeechRecognized += + new EventHandler( + recognizer_SpeechRecognized); + +// Load the digits and fractions Grammar objects. +recognizer.LoadGrammar(digitsGrammar); +recognizer.LoadGrammar(fractionsGrammar); + +// Start recognition. +recognizer.SetInputToDefaultAudioDevice(); +recognizer.RecognizeAsync(RecognizeMode.Multiple); +``` + ]]> @@ -1659,46 +1659,46 @@ recognizer.RecognizeAsync(RecognizeMode.Multiple); Gets or sets the priority value of a object. The property returns an integer value that represents the relative priority of a specific . The range is from -128 to 127 inclusive. The default is 0. - objects, one for digits and one for fractions. The objects are assigned names and relative weights and priorities, and loaded by an in-process speech recognizer. The `CreateDigitsGrammar`, `CreateFractionsGrammar`, and `recognizer_SpeechRecognized` methods are not shown here. - -```csharp - -// Create a Grammar for recognizing numeric digits. -Grammar digitsGrammar = CreateDigitsGrammar(); -digitsGrammar.Name = "Digits Grammar"; -digitsGrammar.Priority = 2; -digitsGrammar.Weight = 0.6f; - -// Create a Grammar for recognizing fractions. -Grammar fractionsGrammar = CreateFractionsGrammar(); -fractionsGrammar.Name = "Fractions Grammar"; -fractionsGrammar.Priority = 1; -fractionsGrammar.Weight = 1f; - -// Create an in-process speech recognizer. -SpeechRecognitionEngine recognizer = new SpeechRecognitionEngine(); - -recognizer.SpeechRecognized += - new EventHandler( - recognizer_SpeechRecognized); - -// Load the digits and fractions Grammar objects. -recognizer.LoadGrammar(digitsGrammar); -recognizer.LoadGrammar(fractionsGrammar); - -// Start recognition. -recognizer.SetInputToDefaultAudioDevice(); -recognizer.RecognizeAsync(RecognizeMode.Multiple); -``` - + objects, one for digits and one for fractions. The objects are assigned names and relative weights and priorities, and loaded by an in-process speech recognizer. The `CreateDigitsGrammar`, `CreateFractionsGrammar`, and `recognizer_SpeechRecognized` methods are not shown here. + +```csharp + +// Create a Grammar for recognizing numeric digits. +Grammar digitsGrammar = CreateDigitsGrammar(); +digitsGrammar.Name = "Digits Grammar"; +digitsGrammar.Priority = 2; +digitsGrammar.Weight = 0.6f; + +// Create a Grammar for recognizing fractions. +Grammar fractionsGrammar = CreateFractionsGrammar(); +fractionsGrammar.Name = "Fractions Grammar"; +fractionsGrammar.Priority = 1; +fractionsGrammar.Weight = 1f; + +// Create an in-process speech recognizer. +SpeechRecognitionEngine recognizer = new SpeechRecognitionEngine(); + +recognizer.SpeechRecognized += + new EventHandler( + recognizer_SpeechRecognized); + +// Load the digits and fractions Grammar objects. +recognizer.LoadGrammar(digitsGrammar); +recognizer.LoadGrammar(fractionsGrammar); + +// Start recognition. +recognizer.SetInputToDefaultAudioDevice(); +recognizer.RecognizeAsync(RecognizeMode.Multiple); +``` + ]]> @@ -1764,40 +1764,40 @@ recognizer.RecognizeAsync(RecognizeMode.Multiple); Gets the name of the root rule or entry point of a object. The property returns the identifier for the root rule of the referenced speech recognition grammar. The default is . - object and set the name for its root rule, use one of the constructors that takes the `ruleName` parameter. - - If the root rule of a has no name, the property returns `null`. - - The root rules of instances constructed from objects typically have no name, so returns `null`. - - - -## Examples - The following example writes information about a object to the [console](https://go.microsoft.com/fwlink/?LinkId=159613). - -```csharp - -private static void DumpGrammarStatus(Grammar item) -{ - Console.WriteLine("Grammar name is {0}:", item.Name); - Console.WriteLine(" The Grammar {0} loaded.", - item.Loaded ? "is" : "is not"); - Console.WriteLine(" The Grammar {0} enabled.", - item.Enabled ? "is" : "is not"); - if (item.RuleName != null) - { - Console.WriteLine(" The root rule is {0}.", item.RuleName); - } - else - { - Console.WriteLine(" The Grammar does not specify a root rule."); - } -} -``` - + object and set the name for its root rule, use one of the constructors that takes the `ruleName` parameter. + + If the root rule of a has no name, the property returns `null`. + + The root rules of instances constructed from objects typically have no name, so returns `null`. + + + +## Examples + The following example writes information about a object to the [console](https://go.microsoft.com/fwlink/?LinkId=159613). + +```csharp + +private static void DumpGrammarStatus(Grammar item) +{ + Console.WriteLine("Grammar name is {0}:", item.Name); + Console.WriteLine(" The Grammar {0} loaded.", + item.Loaded ? "is" : "is not"); + Console.WriteLine(" The Grammar {0} enabled.", + item.Enabled ? "is" : "is not"); + if (item.RuleName != null) + { + Console.WriteLine(" The root rule is {0}.", item.RuleName); + } + else + { + Console.WriteLine(" The Grammar does not specify a root rule."); + } +} +``` + ]]> @@ -1826,52 +1826,52 @@ private static void DumpGrammarStatus(Grammar item) Raised when a speech recognizer performs recognition using the object. - 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. - - - -## Examples - The following example shows the use of an event handler for the object's event. It outputs the recognition results to the [console](https://go.microsoft.com/fwlink/?LinkId=159613). - -```csharp -public partial class Form1 : Form -{ - SpeechRecognitionEngine sre; - - public Form1() - { - InitializeComponent(); - - // Create an in-process speech recognizer. - sre = new SpeechRecognitionEngine(); - - // Configure input to the speech recognizer. - sre.SetInputToDefaultAudioDevice(); - - // Create a simple grammar and load it. - Grammar testGrammar = new Grammar(new GrammarBuilder("testing")); - sre.LoadGrammarAsync(testGrammar); - - // Add a handler for the grammar's speech recognized event. - testGrammar.SpeechRecognized += new EventHandler(testGrammar_SpeechRecognized); - - // Start asynchronous speech recognition. - sre.RecognizeAsync(); - } - - // Handle the grammar's SpeechRecognized event, output the recognized text. - void testGrammar_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) - { - Console.WriteLine("Recognized text: " + e.Result.Text); - } -} -``` - + 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. + + + +## Examples + The following example shows the use of an event handler for the object's event. It outputs the recognition results to the [console](https://go.microsoft.com/fwlink/?LinkId=159613). + +```csharp +public partial class Form1 : Form +{ + SpeechRecognitionEngine sre; + + public Form1() + { + InitializeComponent(); + + // Create an in-process speech recognizer. + sre = new SpeechRecognitionEngine(); + + // Configure input to the speech recognizer. + sre.SetInputToDefaultAudioDevice(); + + // Create a simple grammar and load it. + Grammar testGrammar = new Grammar(new GrammarBuilder("testing")); + sre.LoadGrammarAsync(testGrammar); + + // Add a handler for the grammar's speech recognized event. + testGrammar.SpeechRecognized += new EventHandler(testGrammar_SpeechRecognized); + + // Start asynchronous speech recognition. + sre.RecognizeAsync(); + } + + // Handle the grammar's SpeechRecognized event, output the recognized text. + void testGrammar_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) + { + Console.WriteLine("Recognized text: " + e.Result.Text); + } +} +``` + ]]> @@ -1902,15 +1902,15 @@ public partial class Form1 : Form Parameters to be passed to initialize the strongly-typed grammar. This parameter may be null. The method initializes a strongly-typed grammar. - object (`IsStg` equals `true`) can return strongly-typed results (objects, rather than raw text) to a client application. For example, a strongly-typed grammar might return objects rather than raw recognized input. - - You can implement strongly-typed grammars by attaching code to the rules of a grammar. As a recognition engine processes any given rule, taking as input the current partial results, the associated code is executed and the textual information becomes rich type objects. This allows a client to more easily make use of enhanced semantic checking, support for multiple cultures, and internal grammar logic. - - Instances of strongly-typed objects are typically obtained from resources in an assembly as a of the Common Language Runtime (CLR). The localized types used to support different languages are examples of such objects. - + object (`IsStg` equals `true`) can return strongly-typed results (objects, rather than raw text) to a client application. For example, a strongly-typed grammar might return objects rather than raw recognized input. + + You can implement strongly-typed grammars by attaching code to the rules of a grammar. As a recognition engine processes any given rule, taking as input the current partial results, the associated code is executed and the textual information becomes rich type objects. This allows a client to more easily make use of enhanced semantic checking, support for multiple cultures, and internal grammar logic. + + Instances of strongly-typed objects are typically obtained from resources in an assembly as a of the Common Language Runtime (CLR). The localized types used to support different languages are examples of such objects. + ]]> @@ -1945,50 +1945,50 @@ public partial class Form1 : Form Gets or sets the weight value of a object. The property returns a floating point value indicating the relative weight that a recognition engine instance should assign to the grammar when processing speech input. The range is from 0.0 to 1.0 inclusive. The default is 1.0. - . - - Speech recognition is a weighted system. It evaluates all possible recognition paths based on a combination of the weight of the grammar, the weights defined for alternatives within the grammar, and the probabilities defined by speech models. The speech recognition engine uses the combination of these weights and probabilities to rank potential alternative recognitions. Grammars with higher weights will contribute more to the ranking of recognition alternatives than grammars with lower weights. - - The effect of the property on a speech recognizer is dependent on the implementation of the recognizer. Although the property can be used to tune the accuracy of speech recognition for an application, it should be used only after controlled diagnostic study of a particular recognition environment and with full information about the recognition engine under use. - - - -## Examples - The following example creates two objects, one for digits and one for fractions. The objects are assigned names and relative weights and priorities, and loaded by an in-process speech recognizer. The `CreateDigitsGrammar`, `CreateFractionsGrammar`, and `recognizer_SpeechRecognized` methods are not shown here. - -```csharp - -// Create a Grammar for recognizing numeric digits. -Grammar digitsGrammar = CreateDigitsGrammar(); -digitsGrammar.Name = "Digits Grammar"; -digitsGrammar.Priority = 2; -digitsGrammar.Weight = 0.6f; - -// Create a Grammar for recognizing fractions. -Grammar fractionsGrammar = CreateFractionsGrammar(); -fractionsGrammar.Name = "Fractions Grammar"; -fractionsGrammar.Priority = 1; -fractionsGrammar.Weight = 1f; - -// Create an in-process speech recognizer. -SpeechRecognitionEngine recognizer = new SpeechRecognitionEngine(); - -recognizer.SpeechRecognized += - new EventHandler( - recognizer_SpeechRecognized); - -// Load the digits and fractions Grammar objects. -recognizer.LoadGrammar(digitsGrammar); -recognizer.LoadGrammar(fractionsGrammar); - -// Start recognition. -recognizer.SetInputToDefaultAudioDevice(); -recognizer.RecognizeAsync(RecognizeMode.Multiple); -``` - + . + + Speech recognition is a weighted system. It evaluates all possible recognition paths based on a combination of the weight of the grammar, the weights defined for alternatives within the grammar, and the probabilities defined by speech models. The speech recognition engine uses the combination of these weights and probabilities to rank potential alternative recognitions. Grammars with higher weights will contribute more to the ranking of recognition alternatives than grammars with lower weights. + + The effect of the property on a speech recognizer is dependent on the implementation of the recognizer. Although the property can be used to tune the accuracy of speech recognition for an application, it should be used only after controlled diagnostic study of a particular recognition environment and with full information about the recognition engine under use. + + + +## Examples + The following example creates two objects, one for digits and one for fractions. The objects are assigned names and relative weights and priorities, and loaded by an in-process speech recognizer. The `CreateDigitsGrammar`, `CreateFractionsGrammar`, and `recognizer_SpeechRecognized` methods are not shown here. + +```csharp + +// Create a Grammar for recognizing numeric digits. +Grammar digitsGrammar = CreateDigitsGrammar(); +digitsGrammar.Name = "Digits Grammar"; +digitsGrammar.Priority = 2; +digitsGrammar.Weight = 0.6f; + +// Create a Grammar for recognizing fractions. +Grammar fractionsGrammar = CreateFractionsGrammar(); +fractionsGrammar.Name = "Fractions Grammar"; +fractionsGrammar.Priority = 1; +fractionsGrammar.Weight = 1f; + +// Create an in-process speech recognizer. +SpeechRecognitionEngine recognizer = new SpeechRecognitionEngine(); + +recognizer.SpeechRecognized += + new EventHandler( + recognizer_SpeechRecognized); + +// Load the digits and fractions Grammar objects. +recognizer.LoadGrammar(digitsGrammar); +recognizer.LoadGrammar(fractionsGrammar); + +// Start recognition. +recognizer.SetInputToDefaultAudioDevice(); +recognizer.RecognizeAsync(RecognizeMode.Multiple); +``` + ]]> diff --git a/xml/System.Threading.Tasks/Parallel.xml b/xml/System.Threading.Tasks/Parallel.xml index efaed104c86..3aecf5ebb58 100644 --- a/xml/System.Threading.Tasks/Parallel.xml +++ b/xml/System.Threading.Tasks/Parallel.xml @@ -52,8 +52,6 @@ ## Remarks The class provides library-based data parallel replacements for common operations such as for loops, for each loops, and execution of a set of statements. - - ## Examples This example demonstrates several approaches to implementing a parallel loop using multiple language constructs. @@ -64,7 +62,7 @@ All public and protected members of are thread-safe and may be used concurrently from multiple threads. Data Parallelism (Task Parallel Library) - Samples for Parallel Programming with the .NET Core and .NET Standard + Samples for parallel programming with .NET diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index 1b9b7d11f99..b80e8d6b3e9 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -86,7 +86,7 @@ Task Parallel Library (TPL) Task-based asynchronous pattern (TAP) in .NET: Introduction and overview Task-based Asynchronous Programming - Samples for Parallel Programming with the .NET Core and .NET Standard + Samples for parallel programming with .NET @@ -2948,7 +2948,7 @@ Task t Status: RanToCompletion, Result: 42 class implements the interface because internally it uses resources that also implement . However, particularly if your app targets the .NET Framework 4.5 or later, there is no need to call unless performance or scalability testing indicates that, based on your usage patterns, your app's performance would be improved by disposing of tasks. For more information, see [Do I need to dispose of Tasks?](https://devblogs.microsoft.com/pfxteam/do-i-need-to-dispose-of-tasks/) in the Parallel Programming with .NET blog. + The class implements the interface because internally it uses resources that also implement . However, particularly if your app targets .NET Framework 4.5 or later, there is no need to call unless performance or scalability testing indicates that, based on your usage patterns, your app's performance would be improved by disposing of tasks. For more information, see [Do I need to dispose of Tasks?](https://devblogs.microsoft.com/pfxteam/do-i-need-to-dispose-of-tasks/) in the Parallel Programming with .NET blog. ]]> @@ -3000,7 +3000,7 @@ Task t Status: RanToCompletion, Result: 42 class implements the interface because internally it uses resources that also implement . However, particularly if your app targets the .NET Framework 4.5 or later, there is no need to call unless performance or scalability testing indicates that, based on your usage patterns, your app's performance would be improved by disposing of tasks. For more information, see [Do I need to dispose of Tasks?](https://devblogs.microsoft.com/pfxteam/do-i-need-to-dispose-of-tasks/) in the Parallel Programming with .NET blog. + The class implements the interface because internally it uses resources that also implement . However, particularly if your app targets .NET Framework 4.5 or later, there is no need to call unless performance or scalability testing indicates that, based on your usage patterns, your app's performance would be improved by disposing of tasks. For more information, see [Do I need to dispose of Tasks?](https://devblogs.microsoft.com/pfxteam/do-i-need-to-dispose-of-tasks/) in the Parallel Programming with .NET blog. ]]> @@ -3121,7 +3121,7 @@ Task t Status: RanToCompletion, Result: 42 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 .NET Framework 4.5, the method provides the easiest way to create a object with default configuration values. +> Starting with .NET Framework 4.5, 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. diff --git a/xml/System.Threading.Tasks/TaskCanceledException.xml b/xml/System.Threading.Tasks/TaskCanceledException.xml index bd32d6015f8..003ccb5cb56 100644 --- a/xml/System.Threading.Tasks/TaskCanceledException.xml +++ b/xml/System.Threading.Tasks/TaskCanceledException.xml @@ -298,7 +298,7 @@ @@ -306,7 +306,7 @@ Task-based Asynchronous Programming Task Cancellation How to: Cancel a Task and Its Children - XML and SOAP Serialization + XML and SOAP Serialization diff --git a/xml/System.Threading.Tasks/TaskCreationOptions.xml b/xml/System.Threading.Tasks/TaskCreationOptions.xml index 0b957336abb..d9687723131 100644 --- a/xml/System.Threading.Tasks/TaskCreationOptions.xml +++ b/xml/System.Threading.Tasks/TaskCreationOptions.xml @@ -69,19 +69,19 @@ ## Remarks The enumeration is used with the following methods: -- The and constructors with a `creationOptions` parameter, to specify the default options for tasks created by the task factory. +- The and constructors with a `creationOptions` parameter, to specify the default options for tasks created by the task factory. -- The and constructors with a `creationOptions` parameter, to specify the options used to customize the task's behavior. +- The and constructors with a `creationOptions` parameter, to specify the options used to customize the task's behavior. -- The and methods with a `creationOptions` parameter, to specify the options used to customize the task's behavior. +- The and methods with a `creationOptions` parameter, to specify the options used to customize the task's behavior. -- The and methods with a `creationOptions` parameter, to specify the options used to customize the behavior of the task that executes an end method when a specified completes. +- The and methods with a `creationOptions` parameter, to specify the options used to customize the behavior of the task that executes an end method when a specified completes. -- The constructors with a `creationOptions` parameter, to specify the options used to customize the behavior of the underlying task. +- The constructors with a `creationOptions` parameter, to specify the options used to customize the behavior of the underlying task. ]]> - Samples for Parallel Programming with the .NET Core and .NET Standard + Samples for parallel programming with .NET diff --git a/xml/System.Threading.Tasks/TaskFactory.xml b/xml/System.Threading.Tasks/TaskFactory.xml index 453468d5a0f..3033306e28e 100644 --- a/xml/System.Threading.Tasks/TaskFactory.xml +++ b/xml/System.Threading.Tasks/TaskFactory.xml @@ -60,48 +60,48 @@ Provides support for creating and scheduling objects. - class, which creates and objects. You can call the overloads of this method to create and execute a task that requires non-default arguments. - + 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 .NET Framework 4.5, the method provides the easiest way to create a task with default configuration values and start it immediately. - -- The class, which creates objects. - - The class allows you to do the following: - -- Create a task and start it immediately by calling the method. - + > Starting with .NET Framework 4.5, the method provides the easiest way to create a task with default configuration values and start it immediately. + +- The class, which creates objects. + + The class allows you to do the following: + +- Create a task and start it immediately by calling the method. + > [!WARNING] - > Starting with .NET Framework 4.5, 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. - + > Starting with .NET Framework 4.5, 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. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskFactory/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl_factories/vb/factories_vb.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl_factories/vb/factories_vb.vb" id="Snippet1"::: + 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. - + +## 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. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Factory/factory1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.factory/vb/factory1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.factory/vb/factory1.vb" id="Snippet1"::: + ]]> All public and protected members of are thread-safe and may be used concurrently from multiple threads. Task Parallel Library (TPL) - Samples for Parallel Programming with the .NET Core and .NET Standard + Samples for parallel programming with .NET @@ -152,11 +152,11 @@ Initializes a instance with the default configuration. - instance with a default configuration. The property is initialized to , the property is initialized to , and the property is initialized to the current scheduler (see ). - + instance with a default configuration. The property is initialized to , the property is initialized to , and the property is initialized to the current scheduler (see ). + ]]> Task Parallel Library (TPL) @@ -203,11 +203,11 @@ The that will be assigned to tasks created by this unless another CancellationToken is explicitly specified while calling the factory methods. Initializes a instance with the specified configuration. - instance with a default configuration. The property is initialized to , the property is initialized to , and the property is initialized to the current scheduler (see ). - + instance with a default configuration. The property is initialized to , the property is initialized to , and the property is initialized to the current scheduler (see ). + ]]> Task Parallel Library (TPL) @@ -256,11 +256,11 @@ The to use to schedule any tasks created with this TaskFactory. A null value indicates that the current TaskScheduler should be used. Initializes a instance with the specified configuration. - property is initialized to , the property is initialized to , and the property is initialized to `scheduler`, unless it's null, in which case the property is initialized to the current scheduler (see ). - + property is initialized to , the property is initialized to , and the property is initialized to `scheduler`, unless it's null, in which case the property is initialized to the current scheduler (see ). + ]]> @@ -311,17 +311,17 @@ The default to use when creating continuation tasks with this TaskFactory. Initializes a instance with the specified configuration. - property is initialized to `creationOptions`, the property is initialized to `continuationOptions`, and the property is initialized to the current scheduler (see ). - + property is initialized to `creationOptions`, the property is initialized to `continuationOptions`, and the property is initialized to the current scheduler (see ). + ]]> - The argument specifies an invalid value. For more information, see the Remarks for . - - -or- - + The argument specifies an invalid value. For more information, see the Remarks for . + + -or- + The argument specifies an invalid value. Task Parallel Library (TPL) Chaining Tasks by Using Continuation Tasks @@ -375,17 +375,17 @@ The default to use to schedule any Tasks created with this TaskFactory. A null value indicates that TaskScheduler.Current should be used. Initializes a instance with the specified configuration. - property is initialized to `creationOptions`, the property is initialized to `continuationOptions`, and the property is initialized to `scheduler`, unless it's null, in which case the property is initialized to the current scheduler (see ). - + property is initialized to `creationOptions`, the property is initialized to `continuationOptions`, and the property is initialized to `scheduler`, unless it's null, in which case the property is initialized to the current scheduler (see ). + ]]> - The argument specifies an invalid value. For more information, see the Remarks for . - - -or- - + The argument specifies an invalid value. For more information, see the Remarks for . + + -or- + The argument specifies an invalid value. Task Parallel Library (TPL) Chaining Tasks by Using Continuation Tasks @@ -432,11 +432,11 @@ Gets the default cancellation token for this task factory. The default task cancellation token for this task factory. - that will be assigned to all tasks created by this factory, unless another value is explicitly specified during the call to the factory methods. - + that will be assigned to all tasks created by this factory, unless another value is explicitly specified during the call to the factory methods. + ]]> Task Parallel Library (TPL) @@ -485,11 +485,11 @@ Gets the default task continuation options for this task factory. The default task continuation options for this task factory. - Task Parallel Library (TPL) @@ -504,7 +504,7 @@ Creates a continuation task that starts when a set of specified tasks has completed. - Samples for Parallel Programming with the .NET Core and .NET Standard + Samples for parallel programming with .NET @@ -554,30 +554,30 @@ Creates a continuation task that starts when a set of specified tasks has completed. The new continuation task. - 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. - - - -## Examples - The following example launches separate tasks that use a regular expression to count the number of words in a set of text files. The method is used to launch a task that displays the total word count when all the antecedent tasks have completed. - + 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. + + + +## Examples + The following example launches separate tasks that use a regular expression to count the number of words in a set of text files. The method is used to launch a task that displays the total word count when all the antecedent tasks have completed. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskFactory/ContinueWhenAll/continuewhenall1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.continuewhenall/vb/continuewhenall1.vb" id="Snippet1"::: - - 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. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.continuewhenall/vb/continuewhenall1.vb" id="Snippet1"::: + + 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. + ]]> An element in the array has been disposed. - The array is . - - -or- - + The array is . + + -or- + The argument is . The array is empty or contains a null value. Task Parallel Library (TPL) @@ -633,30 +633,30 @@ Creates a continuation task that starts when a set of specified tasks has completed. The new continuation task. - exception and displays an error message. - +The following example creates a cancellation token, which it passes to separate tasks that use a regular expression to count the number of words in a set of text files. The cancellation token is set if a file cannot be found. The `ContinueWhenAll(Task[], Action{Task[]}, CancellationToken)` method is used to launch a task that displays the total word count when all the antecedent tasks have completed. If the cancellation token is set, which indicates that one or more tasks have been cancelled, it handles the exception and displays an error message. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskFactory/ContinueWhenAll/continuewhenall2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.continuewhenall/vb/continuewhenall2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.continuewhenall/vb/continuewhenall2.vb" id="Snippet2"::: + ]]> - An element in the array has been disposed. - - -or- - + An element in the array has been disposed. + + -or- + The that created has already been disposed. - The array is . - - -or- - + The array is . + + -or- + The argument is . The array is empty or contains a null value. Task Parallel Library (TPL) @@ -721,10 +721,10 @@ The NotOn\* and OnlyOn\* , ]]> An element in the array has been disposed. - The array is . - - -or- - + The array is . + + -or- + The argument is . The argument specifies an invalid value. The array is empty or contains a null value. @@ -793,14 +793,14 @@ The NotOn\* and OnlyOn\* , ]]> - The array is . - - -or- - - The argument is . - - -or- - + The array is . + + -or- + + The argument is . + + -or- + The argument is . The array is empty or contains a null value. Task Parallel Library (TPL) @@ -869,10 +869,10 @@ The NotOn\* and OnlyOn\* , The new continuation task. To be added. An element in the array has been disposed. - The array is . - - -or- - + The array is . + + -or- + The argument is . The array is empty or contains a null value. Task Parallel Library (TPL) @@ -940,15 +940,15 @@ The NotOn\* and OnlyOn\* , Creates a continuation task that starts when a set of specified tasks has completed. The new continuation task. To be added. - An element in the array has been disposed. - - -or- - + An element in the array has been disposed. + + -or- + The that created has already been disposed. - The array is . - - -or- - + The array is . + + -or- + The argument is . The array is empty or contains a null value. Task Parallel Library (TPL) @@ -1025,10 +1025,10 @@ The NotOn\* and OnlyOn\* , ]]> An element in the array has been disposed. - The array is . - - -or- - + The array is . + + -or- + The argument is . The argument specifies an invalid value. The array is empty or contains a null value. @@ -1109,14 +1109,14 @@ The NotOn\* and OnlyOn\* , ]]> - The array is . - - -or- - - The argument is . - - -or- - + The array is . + + -or- + + The argument is . + + -or- + The argument is . The array is empty or contains a null value. Task Parallel Library (TPL) @@ -1186,10 +1186,10 @@ The NotOn\* and OnlyOn\* , The new continuation task. To be added. An element in the array has been disposed. - The array is . - - -or- - + The array is . + + -or- + The argument is . The array is empty or contains a null value. Task Parallel Library (TPL) @@ -1256,15 +1256,15 @@ The NotOn\* and OnlyOn\* , Creates a continuation task that starts when a set of specified tasks has completed. The new continuation task. To be added. - An element in the array has been disposed. - - -or- - + An element in the array has been disposed. + + -or- + The that created has already been disposed. - The array is . - - -or- - + The array is . + + -or- + The argument is . The array is empty or contains a null value. Task Parallel Library (TPL) @@ -1341,10 +1341,10 @@ The NotOn\* and OnlyOn\* , ]]> An element in the array has been disposed. - The array is . - - -or- - + The array is . + + -or- + The argument is . The argument specifies an invalid value. The array is empty or contains a null value. @@ -1425,14 +1425,14 @@ The NotOn\* and OnlyOn\* , ]]> - The array is . - - -or- - - The argument is . - - -or- - + The array is . + + -or- + + The argument is . + + -or- + The argument is . The array is empty or contains a null value. Task Parallel Library (TPL) @@ -1511,10 +1511,10 @@ The NotOn\* and OnlyOn\* , The new continuation task. To be added. An element in the array has been disposed. - The array is . - - -or- - + The array is . + + -or- + The argument is . The array is empty or contains a null value. Task Parallel Library (TPL) @@ -1591,15 +1591,15 @@ The NotOn\* and OnlyOn\* , Creates a continuation task that starts when a set of specified tasks has completed. The new continuation task. To be added. - An element in the array has been disposed. - - -or- - + An element in the array has been disposed. + + -or- + The that created has already been disposed. - The array is . - - -or- - + The array is . + + -or- + The argument is . The array is empty or contains a null value. Task Parallel Library (TPL) @@ -1685,10 +1685,10 @@ The NotOn\* and OnlyOn\* , ]]> An element in the array has been disposed. - The array is . - - -or- - + The array is . + + -or- + The argument is . The argument specifies an invalid value. The array is empty or contains a null value. @@ -1778,21 +1778,21 @@ The NotOn\* and OnlyOn\* , ]]> - The array is . - - -or- - - The argument is . - - -or- - + The array is . + + -or- + + The argument is . + + -or- + The argument is . The array is empty or contains a null value. The argument specifies an invalid value. - An element in the array has been disposed. - - -or- - + An element in the array has been disposed. + + -or- + The that created has already been disposed. Task Parallel Library (TPL) Chaining Tasks by Using Continuation Tasks @@ -1810,7 +1810,7 @@ The NotOn\* and OnlyOn\* , Task Parallel Library (TPL) Chaining Tasks by Using Continuation Tasks Task Cancellation - Samples for Parallel Programming with the .NET Core and .NET Standard + Samples for parallel programming with .NET @@ -1860,26 +1860,26 @@ The NotOn\* and OnlyOn\* , Creates a continuation that will be started upon the completion of any Task in the provided set. The new continuation . - One of the elements in the array has been disposed. - The array is . - - -or- - + The array is . + + -or- + The argument is . - The array contains a value. - - -or- - + The array contains a value. + + -or- + The array is empty. Task Parallel Library (TPL) Chaining Tasks by Using Continuation Tasks @@ -1935,20 +1935,20 @@ The NotOn\* and OnlyOn\* , Creates a continuation that will be started upon the completion of any Task in the provided set. The new continuation . To be added. - One of the elements in the array has been disposed. - - -or- - + One of the elements in the array has been disposed. + + -or- + has already been disposed. - The array is . - - -or- - + The array is . + + -or- + The argument is . - The array contains a value. - - -or- - + The array contains a value. + + -or- + The array is empty . Task Parallel Library (TPL) Chaining Tasks by Using Continuation Tasks @@ -2004,26 +2004,26 @@ The NotOn\* and OnlyOn\* , Creates a continuation that will be started upon the completion of any Task in the provided set. The new continuation . - , which constrain for which states a continuation will be executed, are illegal with `ContinueWhenAny`. - + + The NotOn\* and OnlyOn\* , which constrain for which states a continuation will be executed, are illegal with `ContinueWhenAny`. + ]]> One of the elements in the array has been disposed. - The array is . - - -or- - + The array is . + + -or- + is . specifies an invalid TaskContinuationOptions value. - The array contains a value. - - -or- - + The array contains a value. + + -or- + The array is empty. Task Parallel Library (TPL) Chaining Tasks by Using Continuation Tasks @@ -2091,19 +2091,19 @@ The NotOn\* and OnlyOn\* , ]]> - The array is . - - -or- - - is . - - -or- - + The array is . + + -or- + + is . + + -or- + is . - The array contains a value. - - -or- - + The array contains a value. + + -or- + The array is empty. specifies an invalid TaskContinuationOptions value. @@ -2172,15 +2172,15 @@ The NotOn\* and OnlyOn\* , The new continuation . To be added. One of the elements in the array has been disposed. - The array is . - - -or- - + The array is . + + -or- + is . - The array contains a value. - - -or- - + The array contains a value. + + -or- + The array is empty. Task Parallel Library (TPL) Chaining Tasks by Using Continuation Tasks @@ -2247,20 +2247,20 @@ The NotOn\* and OnlyOn\* , Creates a continuation that will be started upon the completion of any Task in the provided set. The new continuation . To be added. - One of the elements in the array has been disposed. - - -or- - + One of the elements in the array has been disposed. + + -or- + The provided has already been disposed. - The array is . - - -or- - + The array is . + + -or- + is . - The array contains a null value. - - -or- - + The array contains a null value. + + -or- + The array is empty. Task Parallel Library (TPL) Chaining Tasks by Using Continuation Tasks @@ -2327,26 +2327,26 @@ The array is empty. Creates a continuation that will be started upon the completion of any Task in the provided set. The new continuation . - , which constrain for which states a continuation will be executed, are illegal with `ContinueWhenAny`. - The NotOn\* and OnlyOn\* , which constrain for which states a continuation will be executed, are illegal with `ContinueWhenAny`. - ]]> One of the elements in the array has been disposed. - The array is . - - -or- - + The array is . + + -or- + is . specifies an invalid TaskContinuationOptions value. - The array contains a null value. - - -or- - + The array contains a null value. + + -or- + The array is empty. Task Parallel Library (TPL) Chaining Tasks by Using Continuation Tasks @@ -2417,27 +2417,27 @@ The array is empty. Creates a continuation that will be started upon the completion of any Task in the provided set. The new continuation . - , which constrain for which states a continuation will be executed, are illegal with `ContinueWhenAny`. - + + The NotOn\* and OnlyOn\* , which constrain for which states a continuation will be executed, are illegal with `ContinueWhenAny`. + ]]> - The array is . - - -or- - - is . - - -or- - + The array is . + + -or- + + is . + + -or- + paramref name="scheduler" /> is . - The array contains a value. - - -or- - + The array contains a value. + + -or- + The array is empty. specifies an invalid value. @@ -2506,15 +2506,15 @@ The array is empty. The new continuation . To be added. One of the elements in the array has been disposed. - The array is . - - -or- - + The array is . + + -or- + is . - The array contains a null value. - - -or- - + The array contains a null value. + + -or- + The array is empty. Task Parallel Library (TPL) Chaining Tasks by Using Continuation Tasks @@ -2581,20 +2581,20 @@ The array is empty. Creates a continuation that will be started upon the completion of any Task in the provided set. The new continuation . To be added. - One of the elements in the array has been disposed. - - -or- - + One of the elements in the array has been disposed. + + -or- + The provided has already been disposed. - The array is . - - -or- - + The array is . + + -or- + is . - The array contains a value. - - -or- - + The array contains a value. + + -or- + The array is empty. Task Parallel Library (TPL) Chaining Tasks by Using Continuation Tasks @@ -2661,26 +2661,26 @@ The array is empty. Creates a continuation that will be started upon the completion of any Task in the provided set. The new continuation . - , which constrain for which states a continuation will be executed, are illegal with `ContinueWhenAny`. - +The NotOn\* and OnlyOn\* , which constrain for which states a continuation will be executed, are illegal with `ContinueWhenAny`. + ]]> One of the elements in the array has been disposed. - The array is . - - -or- - + The array is . + + -or- + is . specifies an invalid TaskContinuationOptions value. - The array contains a value. - - -or- - + The array contains a value. + + -or- + The array is empty. Task Parallel Library (TPL) Chaining Tasks by Using Continuation Tasks @@ -2751,27 +2751,27 @@ The NotOn\* and OnlyOn\* , Creates a continuation that will be started upon the completion of any Task in the provided set. The new continuation . - , which constrain for which states a continuation will be executed, are illegal with `ContinueWhenAny`. ]]> - The array is . - - -or- - - is . - - -or- - + The array is . + + -or- + + is . + + -or- + is . - The array contains a value. - - -or- - + The array contains a value. + + -or- + The array is empty. specifies an invalid TaskContinuationOptions value. @@ -2849,15 +2849,15 @@ The NotOn\* and OnlyOn\* , The new continuation . To be added. One of the elements in the array has been disposed. - The array is . - - -or- - + The array is . + + -or- + is . - The array contains a null value. - - -or- - + The array contains a null value. + + -or- + The array is empty. Task Parallel Library (TPL) Chaining Tasks by Using Continuation Tasks @@ -2933,20 +2933,20 @@ The NotOn\* and OnlyOn\* , Creates a continuation that will be started upon the completion of any Task in the provided set. The new continuation . To be added. - One of the elements in the array has been disposed. - - -or- - + One of the elements in the array has been disposed. + + -or- + The provided has already been disposed. - The array is . - - -or- - + The array is . + + -or- + is . - The array contains a value. - - -or- - + The array contains a value. + + -or- + The array is empty. Task Parallel Library (TPL) Chaining Tasks by Using Continuation Tasks @@ -3022,26 +3022,26 @@ The array is empty. Creates a continuation that will be started upon the completion of any Task in the provided set. The new continuation . - , which constrain for which states a continuation will be executed, are illegal with `ContinueWhenAny`. - + ]]> One of the elements in the array has been disposed. - The array is . - - -or- - + The array is . + + -or- + is . specifies an invalid TaskContinuationOptions value. - The array contains a null value. - - -or- - + The array contains a null value. + + -or- + The array is empty. Task Parallel Library (TPL) Chaining Tasks by Using Continuation Tasks @@ -3121,27 +3121,27 @@ The NotOn\* and OnlyOn\* , Creates a continuation that will be started upon the completion of any Task in the provided set. The new continuation . - , which constrain for which states a continuation will be executed, are illegal with `ContinueWhenAny`. - +The NotOn\* and OnlyOn\* , which constrain for which states a continuation will be executed, are illegal with `ContinueWhenAny`. + ]]> - The array is . - - -or- - - is . - - -or- - + The array is . + + -or- + + is . + + -or- + is . - The array contains a null value. - - -or- - + The array contains a null value. + + -or- + The array is empty. Task Parallel Library (TPL) Chaining Tasks by Using Continuation Tasks @@ -3192,11 +3192,11 @@ The NotOn\* and OnlyOn\* , Gets the default task creation options for this task factory. The default task creation options for this task factory. - Task Parallel Library (TPL) @@ -3261,20 +3261,20 @@ The NotOn\* and OnlyOn\* , Creates a that executes an end method action when a specified completes. A that represents the asynchronous operation. - [!TIP] -> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. - +> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. + ]]> - is . - - -or- - + is . + + -or- + is . Task Parallel Library (TPL) Using TPL with Other Asynchronous Patterns @@ -3344,18 +3344,18 @@ The NotOn\* and OnlyOn\* , Creates a that represents a pair of begin and end methods that conform to the Asynchronous Programming Model pattern. The created that represents the asynchronous operation. - is running on. This method throws any exceptions thrown by the `beginMethod`. - + is running on. This method throws any exceptions thrown by the `beginMethod`. + ]]> - is . - - -or- - + is . + + -or- + is . Task Parallel Library (TPL) Using TPL with Other Asynchronous Patterns @@ -3410,20 +3410,20 @@ The NotOn\* and OnlyOn\* , Creates a that executes an end method action when a specified completes. A that represents the asynchronous operation. - [!TIP] -> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. - +> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. + ]]> - is . - - -or- - + is . + + -or- + is . paramref name="creationOptions" /> specifies an invalid value. For more information, see the Remarks for Task Parallel Library (TPL) @@ -3496,18 +3496,18 @@ The NotOn\* and OnlyOn\* , Creates a that represents a pair of begin and end methods that conform to the Asynchronous Programming Model pattern. The created that represents the asynchronous operation. - is running on. This method throws any exceptions thrown by the `beginMethod`. The values , and are all mutually exclusive. In the FromAsync methods, either `LongRunning` or `AttachedToParent` by themselves will cause an to be thrown. - + is running on. This method throws any exceptions thrown by the `beginMethod`. The values , and are all mutually exclusive. In the FromAsync methods, either `LongRunning` or `AttachedToParent` by themselves will cause an to be thrown. + ]]> - is . - - -or- - + is . + + -or- + is . specifies an invalid TaskCreationOptions value. @@ -3566,24 +3566,24 @@ The NotOn\* and OnlyOn\* , Creates a that executes an end method action when a specified completes. The created that represents the asynchronous operation. - [!TIP] -> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. - +> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. + ]]> - is . - - -or- - - is . - - -or- - + is . + + -or- + + is . + + -or- + is . specifies an invalid value. For more information, see the Remarks for @@ -3668,18 +3668,18 @@ The NotOn\* and OnlyOn\* , Creates a that represents a pair of begin and end methods that conform to the Asynchronous Programming Model pattern. The created that represents the asynchronous operation. - is running on. This method throws any exceptions thrown by the `beginMethod`. - + is running on. This method throws any exceptions thrown by the `beginMethod`. + ]]> - is . - - -or- - + is . + + -or- + is . Task Parallel Library (TPL) Using TPL with Other Asynchronous Patterns @@ -3764,18 +3764,18 @@ The NotOn\* and OnlyOn\* , Creates a that represents a pair of begin and end methods that conform to the Asynchronous Programming Model pattern. The created that represents the asynchronous operation. - is running on. This method throws any exceptions thrown by the `beginMethod`. - + is running on. This method throws any exceptions thrown by the `beginMethod`. + ]]> - is . - - -or- - + is . + + -or- + is . specifies an invalid value. For more information, see the Remarks for @@ -3841,20 +3841,20 @@ The NotOn\* and OnlyOn\* , Creates a that executes an end method function when a specified completes. A that represents the asynchronous operation. - [!TIP] -> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. - +> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. + ]]> - is . - - -or- - + is . + + -or- + is . Task Parallel Library (TPL) Chaining Tasks by Using Continuation Tasks @@ -3936,18 +3936,18 @@ The NotOn\* and OnlyOn\* , Creates a that represents a pair of begin and end methods that conform to the Asynchronous Programming Model pattern. The created that represents the asynchronous operation. - - is . - - -or- - + is . + + -or- + is . Task Parallel Library (TPL) Using TPL with Other Asynchronous Patterns @@ -4013,20 +4013,20 @@ The NotOn\* and OnlyOn\* , Creates a that executes an end method function when a specified completes. A that represents the asynchronous operation. - [!TIP] -> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. - +> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. + ]]> - is . - - -or- - + is . + + -or- + is . specifies an invalid value. For more information, see the Remarks for @@ -4111,18 +4111,18 @@ The NotOn\* and OnlyOn\* , Creates a that represents a pair of begin and end methods that conform to the Asynchronous Programming Model pattern. The created that represents the asynchronous operation. - - is . - - -or- - + is . + + -or- + is . specifies an invalid value. For more information, see the Remarks for @@ -4192,24 +4192,24 @@ The NotOn\* and OnlyOn\* , Creates a that executes an end method function when a specified completes. A that represents the asynchronous operation. - [!TIP] -> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. - +> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. + ]]> - is . - - -or- - - is . - - -or- - + is . + + -or- + + is . + + -or- + is . specifies an invalid TaskCreationOptions value. For more information, see the Remarks for @@ -4305,18 +4305,18 @@ The NotOn\* and OnlyOn\* , Creates a that represents a pair of begin and end methods that conform to the Asynchronous Programming Model pattern. The created that represents the asynchronous operation. - is running on. This method throws any exceptions thrown by the `beginMethod`. - + is running on. This method throws any exceptions thrown by the `beginMethod`. + ]]> - is . - - -or- - + is . + + -or- + is . Task Parallel Library (TPL) Using TPL with Other Asynchronous Patterns @@ -4412,18 +4412,18 @@ The NotOn\* and OnlyOn\* , Creates a that represents a pair of begin and end methods that conform to the Asynchronous Programming Model pattern. The created that represents the asynchronous operation. - is running on. This method throws any exceptions thrown by the `beginMethod`. - + is running on. This method throws any exceptions thrown by the `beginMethod`. + ]]> - is . - - -or- - + is . + + -or- + is . specifies an invalid value. For more information, see the Remarks for @@ -4517,18 +4517,18 @@ The NotOn\* and OnlyOn\* , Creates a that represents a pair of begin and end methods that conform to the Asynchronous Programming Model pattern. The created that represents the asynchronous operation. - is running on. This method throws any exceptions thrown by the `beginMethod`. - + is running on. This method throws any exceptions thrown by the `beginMethod`. + ]]> - is . - - -or- - + is . + + -or- + is . Task Parallel Library (TPL) Using TPL with Other Asynchronous Patterns @@ -4622,18 +4622,18 @@ The NotOn\* and OnlyOn\* , Creates a that represents a pair of begin and end methods that conform to the Asynchronous Programming Model pattern. The created that represents the asynchronous operation. - is running on. This method throws any exceptions thrown by the `beginMethod`. - + is running on. This method throws any exceptions thrown by the `beginMethod`. + ]]> - is . - - -or- - + is . + + -or- + is . specifies an invalid value. For more information, see the Remarks for @@ -4740,18 +4740,18 @@ The NotOn\* and OnlyOn\* , Creates a that represents a pair of begin and end methods that conform to the Asynchronous Programming Model pattern. The created that represents the asynchronous operation. - is running on. This method throws any exceptions thrown by the `beginMethod`. - + is running on. This method throws any exceptions thrown by the `beginMethod`. + ]]> - is . - - -or- - + is . + + -or- + is . Task Parallel Library (TPL) Using TPL with Other Asynchronous Patterns @@ -4858,18 +4858,18 @@ The NotOn\* and OnlyOn\* , Creates a that represents a pair of begin and end methods that conform to the Asynchronous Programming Model pattern. The created that represents the asynchronous operation. - is running on. This method throws any exceptions thrown by the `beginMethod`. - + is running on. This method throws any exceptions thrown by the `beginMethod`. + ]]> - is . - - -or- - + is . + + -or- + is . specifies an invalid value. For more information, see the Remarks for @@ -4974,18 +4974,18 @@ The NotOn\* and OnlyOn\* , Creates a that represents a pair of begin and end methods that conform to the Asynchronous Programming Model pattern. The created that represents the asynchronous operation. - is running on. This method throws any exceptions thrown by the `beginMethod`. - + is running on. This method throws any exceptions thrown by the `beginMethod`. + ]]> - is . - - -or- - + is . + + -or- + is . Task Parallel Library (TPL) Using TPL with Other Asynchronous Patterns @@ -5090,18 +5090,18 @@ The NotOn\* and OnlyOn\* , Creates a that represents a pair of begin and end methods that conform to the Asynchronous Programming Model pattern. The created that represents the asynchronous operation. - is running on. This method throws any exceptions thrown by the `beginMethod`. - + is running on. This method throws any exceptions thrown by the `beginMethod`. + ]]> - is . - - -or- - + is . + + -or- + is . specifies an invalid value. For more information, see the Remarks for @@ -5217,18 +5217,18 @@ The NotOn\* and OnlyOn\* , Creates a that represents a pair of begin and end methods that conform to the Asynchronous Programming Model pattern. The created that represents the asynchronous operation. - is running on. This method throws any exceptions thrown by the `beginMethod`. - + is running on. This method throws any exceptions thrown by the `beginMethod`. + ]]> - is . - - -or- - + is . + + -or- + is . Task Parallel Library (TPL) Using TPL with Other Asynchronous Patterns @@ -5344,18 +5344,18 @@ The NotOn\* and OnlyOn\* , Creates a that represents a pair of begin and end methods that conform to the Asynchronous Programming Model pattern. The created that represents the asynchronous operation. - is running on. This method throws any exceptions thrown by the `beginMethod`. - + is running on. This method throws any exceptions thrown by the `beginMethod`. + ]]> - is . - - -or- - + is . + + -or- + is . specifies an invalid value. For more information, see the Remarks for @@ -5411,13 +5411,13 @@ The NotOn\* and OnlyOn\* , Gets the default task scheduler for this task factory. The default task scheduler for this task factory. - property is used. - + property is used. + ]]> @@ -5433,20 +5433,20 @@ The NotOn\* and OnlyOn\* , Creates and starts a task. - 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. - -- 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 . - + 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. + +- 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 . + ]]> - Samples for Parallel Programming with the .NET Core and .NET Standard + Samples for parallel programming with .NET @@ -5494,21 +5494,21 @@ The NotOn\* and OnlyOn\* , Creates and starts a task for the specified action delegate. The started task. - 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 .NET Framework 4.5, 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](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. - - - -## Examples - The following example uses the method to repeatedly invoke an delegate that generates a random number, interprets it as a Unicode code point, converts it to a UTF16-encoded code unit, and displays information about the resulting character or characters. - + 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 .NET Framework 4.5, 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](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + + + +## Examples + The following example uses the method to repeatedly invoke an delegate that generates a random number, interprets it as a Unicode code point, converts it to a UTF16-encoded code unit, and displays information about the resulting character or characters. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskFactory/StartNew/startnew1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.taskfactory.startnew/vb/startnew1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.taskfactory.startnew/vb/startnew1.vb" id="Snippet1"::: + ]]> The argument is . @@ -5564,21 +5564,21 @@ The NotOn\* and OnlyOn\* , Creates and starts a task for the specified action delegate and cancellation token. The started task. - to schedule it for execution. - - Starting with the .NET Framework 4.5, 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](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) 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. - + to schedule it for execution. + + Starting with the .NET Framework 4.5, 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](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) 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. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskFactory/StartNew/startnew2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.taskfactory.startnew/vb/startnew2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.taskfactory.startnew/vb/startnew2.vb" id="Snippet2"::: + ]]> The provided has already been disposed. @@ -5636,13 +5636,13 @@ The NotOn\* and OnlyOn\* , Creates and starts a task for the specified action delegate and creation options. The started task. - to schedule it for execution. - - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. - + to schedule it for execution. + + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + ]]> @@ -5716,23 +5716,23 @@ The NotOn\* and OnlyOn\* , Creates and starts a task for the specified action delegate and state. The started task. - is functionally equivalent to creating a using one of its constructors and then calling the method to schedule it for execution. - - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. - - - -## Examples - The following example defines an array of 6-letter words. Each word is then passed to an delegate, which scrambles the word and displays the original word and its scrambled version. - + is functionally equivalent to creating a using one of its constructors and then calling the method to schedule it for execution. + + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + + + +## Examples + The following example defines an array of 6-letter words. Each word is then passed to an delegate, which scrambles the word and displays the original word and its scrambled version. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskFactory/StartNew/startnew3.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.taskfactory.startnew/vb/startnew3.vb" id="Snippet3"::: - - 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. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.taskfactory.startnew/vb/startnew3.vb" id="Snippet3"::: + + 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. + ]]> The argument is . @@ -5805,23 +5805,23 @@ The NotOn\* and OnlyOn\* , Creates and starts a task for the specified action delegate, state and cancellation token. The started task. - to schedule it for execution. - - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. - - - -## Examples - The following example defines an array of 6-letter words. Each word is then passed to an delegate, which scrambles the word and displays the original word and its scrambled version. - + to schedule it for execution. + + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + + + +## Examples + The following example defines an array of 6-letter words. Each word is then passed to an delegate, which scrambles the word and displays the original word and its scrambled version. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskFactory/StartNew/startnew4.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.taskfactory.startnew/vb/startnew4.vb" id="Snippet4"::: - - 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. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.taskfactory.startnew/vb/startnew4.vb" id="Snippet4"::: + + 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. + ]]> The provided has already been disposed. @@ -5896,13 +5896,13 @@ The NotOn\* and OnlyOn\* , Creates and starts a task for the specified action delegate, state and creation options. The started task. - to schedule it for execution. - - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. - + to schedule it for execution. + + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + ]]> @@ -5965,21 +5965,21 @@ The NotOn\* and OnlyOn\* , Creates and starts a task for the specified action delegate, cancellation token, creation options and state. The started task. - to schedule it for execution. - - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. - + to schedule it for execution. + + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + ]]> The provided has already been disposed. - is . - - -or- - + is . + + -or- + is . specifies an invalid TaskCreationOptions value. For more information, see the Remarks for @@ -6056,19 +6056,19 @@ The NotOn\* and OnlyOn\* , Creates and starts a task for the specified action delegate, state, cancellation token, creation options and task scheduler. The started task. - to schedule it for execution. - - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. - + to schedule it for execution. + + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + ]]> The provided has already been disposed. - is . - + is . + -or- is . @@ -6135,21 +6135,21 @@ The NotOn\* and OnlyOn\* , Creates and starts a task of type for the specified function delegate. The started task. - is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - - Starting with the .NET Framework 4.5, 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](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. - - - -## Examples - The following example is a simple addition app that generates two random numbers and prompts the user to enter their sum. It then indicates whether the answer is correct or, if the user's response is not a valid number, prompts the user to re-enter a valid number. The is used to create the objects that return the random numbers to add. - + is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. + + Starting with the .NET Framework 4.5, 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](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + + + +## Examples + The following example is a simple addition app that generates two random numbers and prompts the user to enter their sum. It then indicates whether the answer is correct or, if the user's response is not a valid number, prompts the user to re-enter a valid number. The is used to create the objects that return the random numbers to add. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run5.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/run5.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/run5.vb" id="Snippet5"::: + ]]> The argument is . @@ -6217,13 +6217,13 @@ The NotOn\* and OnlyOn\* , Creates and starts a task of type for the specified function delegate and state. The started task. - using one of its constructors and then calling to schedule it for execution. - - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. - + using one of its constructors and then calling to schedule it for execution. + + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + ]]> @@ -6291,21 +6291,21 @@ The NotOn\* and OnlyOn\* , Creates and starts a task of type for the specified function delegate and cancellation token. The started task. - is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - - Starting with the .NET Framework 4.5, 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](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. - - - -## Examples - The following example uses two tasks to compute the Fibonacci sequence ending in F100 = F100-1 + F100-2 with seed values F1= 1, F2 = 1 and F1 = 0, F2= 1. Approximately half of the time, a cancellation token is set as the operations execute. The output from the example shows the result if the two tasks complete successfully and if the token is cancelled. - + is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. + + Starting with the .NET Framework 4.5, 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](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + + + +## Examples + The following example uses two tasks to compute the Fibonacci sequence ending in F100 = F100-1 + F100-2 with seed values F1= 1, F2 = 1 and F1 = 0, F2= 1. Approximately half of the time, a cancellation token is set as the operations execute. The output from the example shows the result if the two tasks complete successfully and if the token is cancelled. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/Run9.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/Run9.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/Run9.vb" id="Snippet9"::: + ]]> The provided has already been disposed. @@ -6374,13 +6374,13 @@ The NotOn\* and OnlyOn\* , Creates and starts a task of type for the specified function delegate and creation options. The started task. - using one of its constructors and then calling to schedule it for execution. - - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. - + using one of its constructors and then calling to schedule it for execution. + + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + ]]> @@ -6453,13 +6453,13 @@ The NotOn\* and OnlyOn\* , Creates and starts a task of type for the specified function delegate, state and cancellation token. The started task. - using one of its constructors and then calling to schedule it for execution. - - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. - + using one of its constructors and then calling to schedule it for execution. + + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + ]]> The provided has already been disposed. @@ -6531,13 +6531,13 @@ The NotOn\* and OnlyOn\* , Creates and starts a task of type for the specified function delegate, state and creation options. The started task. - using one of its constructors and then calling to schedule it for execution. - - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. - + using one of its constructors and then calling to schedule it for execution. + + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + ]]> @@ -6611,21 +6611,21 @@ The NotOn\* and OnlyOn\* , Creates and starts a task of type for the specified function delegate, cancellation token, creation options and task scheduler. The started task. - using one of its constructors and then calling to schedule it for execution. - - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. - + using one of its constructors and then calling to schedule it for execution. + + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + ]]> The provided has already been disposed. - is . - - -or- - + is . + + -or- + is . specifies an invalid value. For more information, see the Remarks for @@ -6713,21 +6713,21 @@ The NotOn\* and OnlyOn\* , Creates and starts a task of type for the specified function delegate, state, cancellation token, creation options and task scheduler. The started task. - using one of its constructors and then calling to schedule it for execution. - - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. - + using one of its constructors and then calling to schedule it for execution. + + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + ]]> The provided has already been disposed. - is . - - -or- - + is . + + -or- + is . specifies an invalid value. For more information, see the Remarks for diff --git a/xml/System.Threading.Tasks/TaskSchedulerException.xml b/xml/System.Threading.Tasks/TaskSchedulerException.xml index b3b25d9cef7..dfe494c9299 100644 --- a/xml/System.Threading.Tasks/TaskSchedulerException.xml +++ b/xml/System.Threading.Tasks/TaskSchedulerException.xml @@ -298,7 +298,7 @@ ]]> - XML and SOAP Serialization + XML and SOAP Serialization diff --git a/xml/System.Threading.Tasks/Task`1.xml b/xml/System.Threading.Tasks/Task`1.xml index 877a54bb046..0ae52bb564a 100644 --- a/xml/System.Threading.Tasks/Task`1.xml +++ b/xml/System.Threading.Tasks/Task`1.xml @@ -79,36 +79,36 @@ The type of the result produced by this . Represents an asynchronous operation that can return a value. - 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](/dotnet/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap) 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 .NET Framework 4.5, 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 language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskTResult/Overview/run1.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task`1/vb/run1.vb" id="Snippet6"::: - - An alternative, and the most common way to start a task in the .NET Framework 4, 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 language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskTResult/Overview/startnew1.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task`1/vb/startnew1.vb" id="Snippet7"::: - - For more complete examples, see [Task-based Asynchronous Programming](/dotnet/standard/parallel-programming/task-based-asynchronous-programming). - - 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 .NET Framework 4.6, 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 .NET Framework 4.6, 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. Starting with C# 7.0, for a more lightweight task that is a value type rather than a reference type, use the structure. - + 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](https://learn.microsoft.com/dotnet/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap) first introduced in .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 .NET Framework 4.5, 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 language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskTResult/Overview/run1.cs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task`1/vb/run1.vb" id="Snippet6"::: + + An alternative, and the most common way to start a task in .NET Framework 4, 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 language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskTResult/Overview/startnew1.cs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task`1/vb/startnew1.vb" id="Snippet7"::: + + For more complete examples, see [Task-based Asynchronous Programming](https://learn.microsoft.com/dotnet/standard/parallel-programming/task-based-asynchronous-programming). + + 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 .NET Framework 4.6, 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 .NET Framework prior to .NET Framework 4.6, 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. Starting with C# 7.0, for a more lightweight task that is a value type rather than a reference type, use the structure. + ]]> All members of , except for , are thread-safe and may be used from multiple threads concurrently. Task Parallel Library (TPL) Task-based Asynchronous Programming - Samples for Parallel Programming with the .NET Core and .NET Standard + Samples for parallel programming with .NET @@ -162,27 +162,27 @@ For operations that do not return a value, you use the The delegate that represents the code to execute in the task. When the function has completed, the task's property will be set to return the result value of the function. Initializes a new with the specified function. - object and launch a task is by calling the static and methods. - - If a task with no action is needed just for the consumer of an API to have something to await, a should be used. - - - -## 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. - - 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 language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run3.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.ctor/vb/run3.vb" id="Snippet2"::: - - The regular expression pattern `\p{P}*\s+` matches zero, one, or more punctuation characters followed by one or more white-space characters. It assumes that the total number of matches equals the approximate word count. - + object and launch a task is by calling the static and methods. + + If a task with no action is needed just for the consumer of an API to have something to await, a should be used. + + + +## 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. + + 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 language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run3.cs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.ctor/vb/run3.vb" id="Snippet2"::: + + The regular expression pattern `\p{P}*\s+` matches zero, one, or more punctuation characters followed by one or more white-space characters. It assumes that the total number of matches equals the approximate word count. + ]]> The argument is . @@ -242,11 +242,11 @@ For operations that do not return a value, you use the An object representing data to be used by the action. Initializes a new with the specified function and state. - 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. - + 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. + ]]> The argument is . @@ -298,11 +298,11 @@ For operations that do not return a value, you use the The to be assigned to this task. Initializes a new with the specified function. - 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. - + 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. + ]]> The that created has already been disposed. @@ -355,11 +355,11 @@ For operations that do not return a value, you use the The used to customize the task's behavior. Initializes a new with the specified function and creation options. - 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. - + 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. + ]]> The argument specifies an invalid value for . @@ -422,11 +422,11 @@ For operations that do not return a value, you use the The to be assigned to the new task. Initializes a new with the specified action, state, and options. - 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. - + 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. + ]]> The that created has already been disposed. @@ -489,11 +489,11 @@ For operations that do not return a value, you use the The used to customize the task's behavior. Initializes a new with the specified action, state, and options. - 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. - + 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. + ]]> The argument specifies an invalid value for . @@ -548,11 +548,11 @@ For operations that do not return a value, you use the The used to customize the task's behavior. Initializes a new with the specified function and creation options. - 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. - + 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. + ]]> The that created has already been disposed. @@ -618,11 +618,11 @@ For operations that do not return a value, you use the The used to customize the task's behavior. Initializes a new with the specified action, state, and options. - 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. - + 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. + ]]> The that created has already been disposed. @@ -786,19 +786,19 @@ For operations that do not return a value, you use the Creates a continuation that executes asynchronously when the target task completes. A new continuation task. - 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 early due to being canceled. - - - -## Examples - The following example creates an antecedent task that uses the Sieve of Eratosthenes to calculate the prime numbers between 1 and a value entered by the user. An array is used to hold information about the prime numbers. The array index represents the number, and the element's value indicates whether that number is composite (its value is `true`) or prime (its value is `false`). This task is then passed to a continuation task, which is responsible for extracting the prime numbers from the integer array and displaying them. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskTResult/ContinueWith/continue2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task`1.continuewith/vb/continue2.vb" id="Snippet2"::: - + 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 early due to being canceled. + + + +## Examples + The following example creates an antecedent task that uses the Sieve of Eratosthenes to calculate the prime numbers between 1 and a value entered by the user. An array is used to hold information about the prime numbers. The array index represents the number, and the element's value indicates whether that number is composite (its value is `true`) or prime (its value is `false`). This task is then passed to a continuation task, which is responsible for extracting the prime numbers from the integer array and displaying them. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskTResult/ContinueWith/continue2.cs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task`1.continuewith/vb/continue2.vb" id="Snippet2"::: + ]]> The has been disposed. @@ -870,19 +870,19 @@ For operations that do not return a value, you use the Creates a continuation that is passed state information and that executes when the target completes. A new continuation . - 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. - - - -## Examples - The following example creates a task that is passed an integer between 2 and 20 and returns an array that contains the first ten exponents (from n1 to n10) of that number. A continuation task is then responsible for displaying the exponents. It is passed both the antecedent and the original number whose exponents the antecedent generates. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskTResult/ContinueWith/continuewith3.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task`1.continuewith/vb/continuewith3.vb" id="Snippet3"::: - + 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. + + + +## Examples + The following example creates a task that is passed an integer between 2 and 20 and returns an array that contains the first ten exponents (from n1 to n10) of that number. A continuation task is then responsible for displaying the exponents. It is passed both the antecedent and the original number whose exponents the antecedent generates. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskTResult/ContinueWith/continuewith3.cs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task`1.continuewith/vb/continuewith3.vb" id="Snippet3"::: + ]]> The argument is . @@ -936,29 +936,29 @@ For operations that do not return a value, you use the Creates a cancelable continuation that executes asynchronously when the target completes. A new continuation task. - 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. - - - -## Examples - The following example creates an antecedent task that uses the Sieve of Eratosthenes to calculate the prime numbers between 1 and a value entered by the user. An array is used to hold information about the prime numbers. The array index represents the number, and the element's value indicates whether that number is composite (its value is `true`) or prime (its value is `false`). This task is then passed to a continuation task, which is responsible for extracting the prime numbers from the integer array and displaying them. - - 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 language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskTResult/ContinueWith/continue1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task`1.continuewith/vb/continue1.vb" id="Snippet1"::: - - 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. - + 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. + + + +## Examples + The following example creates an antecedent task that uses the Sieve of Eratosthenes to calculate the prime numbers between 1 and a value entered by the user. An array is used to hold information about the prime numbers. The array index represents the number, and the element's value indicates whether that number is composite (its value is `true`) or prime (its value is `false`). This task is then passed to a continuation task, which is responsible for extracting the prime numbers from the integer array and displaying them. + + 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 language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskTResult/ContinueWith/continue1.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task`1.continuewith/vb/continue1.vb" id="Snippet1"::: + + 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. + ]]> - The has been disposed. - - -or- - + The has been disposed. + + -or- + The that created has been disposed. The argument is . Task Parallel Library (TPL) @@ -1013,13 +1013,13 @@ For operations that do not return a value, you use the Creates a continuation that executes according the condition specified in . A new continuation . - will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. - - For more information, see [Chaining Tasks by Using Continuation Tasks](/dotnet/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks). - + will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. + + For more information, see [Chaining Tasks by Using Continuation Tasks](https://learn.microsoft.com/dotnet/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks). + ]]> The has been disposed. @@ -1077,18 +1077,18 @@ For operations that do not return a value, you use the Creates a continuation that executes asynchronously when the target completes. A new continuation . - 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. - + 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 has been disposed. - The argument is . - - -or- - + The argument is . + + -or- + The argument is . Task Parallel Library (TPL) Task-based Asynchronous Programming @@ -1159,11 +1159,11 @@ For operations that do not return a value, you use the Creates a continuation that executes when the target completes. A new continuation . - 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. - + 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 argument is . @@ -1235,11 +1235,11 @@ For operations that do not return a value, you use the Creates a continuation that executes when the target completes. A new continuation . - will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. - + will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. + ]]> The argument is . @@ -1311,11 +1311,11 @@ For operations that do not return a value, you use the Creates a continuation that executes when the target completes. A new continuation . - 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. - + 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 argument is . @@ -1373,22 +1373,22 @@ For operations that do not return a value, you use the Creates a continuation that executes according the condition specified in . A new continuation . - will not be scheduled for execution until the current task has completed. If the criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. For more information, see [Chaining Tasks by Using Continuation Tasks](/dotnet/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks). - + will not be scheduled for execution until the current task has completed. If the criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. For more information, see [Chaining Tasks by Using Continuation Tasks](https://learn.microsoft.com/dotnet/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks). + ]]> - The has been disposed. - - -or- - + The has been disposed. + + -or- + The that created has already been disposed. - The argument is . - - -or- - + The argument is . + + -or- + The argument is . The argument specifies an invalid value for . Task Parallel Library (TPL) @@ -1464,11 +1464,11 @@ For operations that do not return a value, you use the Creates a continuation that executes when the target completes. A new continuation . - will not be scheduled for execution until the current task has completed. If the criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. - + will not be scheduled for execution until the current task has completed. If the criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. + ]]> The argument is . @@ -1533,11 +1533,11 @@ For operations that do not return a value, you use the Creates a continuation that executes asynchronously when the target completes. A new continuation . - 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. - + 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 has been disposed. @@ -1606,19 +1606,19 @@ For operations that do not return a value, you use the Creates a continuation that executes when the target completes. A new continuation . - 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. - - - -## Examples - The following example creates a chain of continuation tasks. Each task provides the current time, a object, for the state argument of the method. Each value represents the time at which the continue task is created. Each task produces as its result a second value that represents the time at which the task finishes. After all tasks finish, the example displays the date and times at which each continuation task starts and finishes. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task`1/ContinueWith/continuationstate.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl_continuationstate/vb/continuationstate.vb" id="Snippet1"::: - + 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. + + + +## Examples + The following example creates a chain of continuation tasks. Each task provides the current time, a object, for the state argument of the method. Each value represents the time at which the continue task is created. Each task produces as its result a second value that represents the time at which the task finishes. After all tasks finish, the example displays the date and times at which each continuation task starts and finishes. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task`1/ContinueWith/continuationstate.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl_continuationstate/vb/continuationstate.vb" id="Snippet1"::: + ]]> The argument is . @@ -1683,17 +1683,17 @@ For operations that do not return a value, you use the Creates a continuation that executes asynchronously when the target completes. A new continuation . - 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. - + 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 has been disposed. - - -or- - + The has been disposed. + + -or- + The that created has already been disposed. The argument is . Task Parallel Library (TPL) @@ -1754,20 +1754,20 @@ For operations that do not return a value, you use the The type of the result produced by the continuation. - A function to run according the condition specified in . - + A function to run according the condition specified in . + When run, the delegate will be passed the completed task as an argument. Options for when the continuation is scheduled and how it behaves. This includes criteria, such as , as well as execution options, such as . Creates a continuation that executes according the condition specified in . A new continuation . - 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 . - + 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 . + ]]> The has been disposed. @@ -1836,18 +1836,18 @@ For operations that do not return a value, you use the Creates a continuation that executes asynchronously when the target completes. A new continuation . - 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. - + 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 has been disposed. - The argument is . - - -or- - + The argument is . + + -or- + The argument is . Task Parallel Library (TPL) @@ -1916,11 +1916,11 @@ For operations that do not return a value, you use the Creates a continuation that executes when the target completes. A new continuation . - 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. - + 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 argument is . @@ -1989,13 +1989,13 @@ For operations that do not return a value, you use the Creates a continuation that executes when the target completes. A new continuation . - 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 ContinueWith call. - + 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 ContinueWith call. + ]]> The argument is . @@ -2078,11 +2078,11 @@ For operations that do not return a value, you use the Creates a continuation that executes when the target completes. A new continuation . - 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. - + 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 argument is . @@ -2144,8 +2144,8 @@ For operations that do not return a value, you use the The type of the result produced by the continuation. - A function to run according the condition specified in . - + A function to run according the condition specified in . + When run, the delegate will be passed as an argument this completed task. The that will be assigned to the new task. Options for when the continuation is scheduled and how it behaves. This includes criteria, such as , as well as execution options, such as . @@ -2153,24 +2153,24 @@ For operations that do not return a value, you use the Creates a continuation that executes according the condition specified in . A new continuation . - 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 . - + 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 . + ]]> - The has been disposed. - - -or- - + The has been disposed. + + -or- + The that created has already been disposed. - The argument is . - - -or- - + The argument is . + + -or- + The argument is . The argument specifies an invalid value for . Task Parallel Library (TPL) @@ -2257,13 +2257,13 @@ For operations that do not return a value, you use the Creates a continuation that executes when the target completes. A new continuation . - 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. - + 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 argument is . @@ -2313,28 +2313,28 @@ For operations that do not return a value, you use the Gets a factory method for creating and configuring instances. A factory object that can create a variety of objects. - class that is identical to the one created by calling the parameterless constructor. It has the following property values: - -|Property|Value| -|--------------|-----------| -||| -||| -||| -||`null`, or | - - 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 .NET Framework 4.5, 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. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task`1/Factory/returnavalue10.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl/vb/10_returnavalue.vb" id="Snippet10"::: - + class that is identical to the one created by calling the parameterless constructor. It has the following property values: + +|Property|Value| +|--------------|-----------| +||| +||| +||| +||`null`, or | + + 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 .NET Framework 4.5, 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. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task`1/Factory/returnavalue10.cs" id="Snippet10"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl/vb/10_returnavalue.vb" id="Snippet10"::: + ]]> Task Parallel Library (TPL) @@ -2389,12 +2389,12 @@ For operations that do not return a value, you use the Gets an awaiter used to await this . An awaiter instance. - @@ -2450,27 +2450,27 @@ This method is intended for compiler use rather than use directly in code. Gets the result value of this . The result value of this , which is of the same type as the task's type parameter. - method. - - Once the result of an operation is available, it is stored and is returned immediately on subsequent calls to the property. Note that, if an exception occurred during the operation of the task, or if the task has been cancelled, the property does not return a value. Instead, attempting to access the property value throws an exception. - - - -## 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. 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 language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.fromresult/vb/fromresult1.vb" id="Snippet1"::: - + method. + + Once the result of an operation is available, it is stored and is returned immediately on subsequent calls to the property. Note that, if an exception occurred during the operation of the task, or if the task has been cancelled, the property does not return a value. Instead, attempting to access the property value throws an exception. + + + +## 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. 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 language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.fromresult/vb/fromresult1.vb" id="Snippet1"::: + ]]> - The task was canceled. The collection contains a object. - - -or- - + The task was canceled. The collection contains a object. + + -or- + An exception was thrown during the execution of the task. The collection contains information about the exception or exceptions. Task Parallel Library (TPL) Task-based Asynchronous Programming diff --git a/xml/System.Threading/BarrierPostPhaseException.xml b/xml/System.Threading/BarrierPostPhaseException.xml index 2efbf1b2386..eed4cdce0f2 100644 --- a/xml/System.Threading/BarrierPostPhaseException.xml +++ b/xml/System.Threading/BarrierPostPhaseException.xml @@ -305,7 +305,7 @@ ]]> - XML and SOAP Serialization + XML and SOAP Serialization diff --git a/xml/System.Web.UI.MobileControls.Adapters.XhtmlAdapters/XhtmlControlAdapter.xml b/xml/System.Web.UI.MobileControls.Adapters.XhtmlAdapters/XhtmlControlAdapter.xml index bc8925023de..01448d540ca 100644 --- a/xml/System.Web.UI.MobileControls.Adapters.XhtmlAdapters/XhtmlControlAdapter.xml +++ b/xml/System.Web.UI.MobileControls.Adapters.XhtmlAdapters/XhtmlControlAdapter.xml @@ -566,8 +566,8 @@ Architectural Overview of Adaptive Control Behavior - Adapter Sets Functionality - Control and Adapter Interaction + Adapter Sets Functionality + Control and Adapter Interaction diff --git a/xml/System/AggregateException.xml b/xml/System/AggregateException.xml index 2013054e32f..4f37d0c41a0 100644 --- a/xml/System/AggregateException.xml +++ b/xml/System/AggregateException.xml @@ -630,7 +630,7 @@ ]]> Exception Handling (Task Parallel Library) - Aggregating Exceptions + Aggregating Exceptions diff --git a/xml/System/Exception.xml b/xml/System/Exception.xml index b0ef698dae3..67f69336911 100644 --- a/xml/System/Exception.xml +++ b/xml/System/Exception.xml @@ -800,7 +800,7 @@ The following example demonstrates how to add and retrieve information using the ]]> How to: Map HRESULTs and Exceptions - Common HRESULT Values + Common HRESULT Values diff --git a/xml/ns-System.IO.Packaging.xml b/xml/ns-System.IO.Packaging.xml index 8e27c87023a..82c294572f5 100644 --- a/xml/ns-System.IO.Packaging.xml +++ b/xml/ns-System.IO.Packaging.xml @@ -2,50 +2,49 @@ Provides classes that support storage of multiple data objects in a single container. - is an abstract class that can be used to organize objects into a single entity of a defined physical format for portability and efficient access. - - A ZIP file is the primary physical format for the . Other implementations might use other physical formats such as an XML document, a database, or Web service. - - Like a file system, items contained in a are referenced in a hierarchical organization of folders and files. - - Although is an abstract class, the derived class is used as default by the method. - - A ("part") is the abstract class that represents an object that is stored in a . - - 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: - -- Package-level relationship (created by ) - - - Between a and a target part in the package. - - - Between a and a target resource outside the package. - -- Part-level relationship (created by ) - - - Between a source and another target part in the package. - - - Between a source and a target resource outside the package. - - The relationship's source or source is considered the "owner" of the relationship. When the source object is deleted, all the relationships owned by the source object are also deleted. The process of creating or deleting a relationship does not physically change either the source or target objects in any way. - - A ("digital signature") is a composition of parts and relationships representing a digital signature included with a . The digital signature identifies the originator and validates that the signed parts and relationships contained in the have not been modified. - - Packages also support Digital Rights Management (DRM), which allows content elements in a to be encrypted with specific access rights granted to authorized users. - - Based on the architecture, an is a package type designed for storing documents based on the open [XML Paper Specification (XPS)](https://www.ecma-international.org/publications-and-standards/standards/ecma-388/). - - Windows Presentation Foundation uses packages to store content, resources, and relationships for pages and documents using a standard ZIP file by default. As with any ZIP file, your application can use the classes to store and optionally protect any type or number of data files in a single efficient-to-access container. - - For more information, see the [Open Packaging Conventions (OPC) specification](https://www.ecma-international.org/publications-and-standards/standards/ecma-376/). - + is an abstract class that can be used to organize objects into a single entity of a defined physical format for portability and efficient access. + + A ZIP file is the primary physical format for the . Other implementations might use other physical formats such as an XML document, a database, or Web service. + + Like a file system, items contained in a are referenced in a hierarchical organization of folders and files. + + Although is an abstract class, the derived class is used as default by the method. + + A ("part") is the abstract class that represents an object that is stored in a . + + 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: + +- Package-level relationship (created by ) + + - Between a and a target part in the package. + + - Between a and a target resource outside the package. + +- Part-level relationship (created by ) + + - Between a source and another target part in the package. + + - Between a source and a target resource outside the package. + + The relationship's source or source is considered the "owner" of the relationship. When the source object is deleted, all the relationships owned by the source object are also deleted. The process of creating or deleting a relationship does not physically change either the source or target objects in any way. + + A ("digital signature") is a composition of parts and relationships representing a digital signature included with a . The digital signature identifies the originator and validates that the signed parts and relationships contained in the have not been modified. + + Packages also support Digital Rights Management (DRM), which allows content elements in a to be encrypted with specific access rights granted to authorized users. + + Based on the architecture, an is a package type designed for storing documents based on the open [XML Paper Specification (XPS)](https://www.ecma-international.org/publications-and-standards/standards/ecma-388/). + + Windows Presentation Foundation uses packages to store content, resources, and relationships for pages and documents using a standard ZIP file by default. As with any ZIP file, your application can use the classes to store and optionally protect any type or number of data files in a single efficient-to-access container. + + For more information, see the [Open Packaging Conventions (OPC) specification](https://www.ecma-international.org/publications-and-standards/standards/ecma-376/). + ]]> Open Packaging Conventions (OPC) Specification - The Addressing Model of the Open Packaging Conventions diff --git a/xml/ns-System.Net.Http.xml b/xml/ns-System.Net.Http.xml index d44819b20cd..4f8a32e574f 100644 --- a/xml/ns-System.Net.Http.xml +++ b/xml/ns-System.Net.Http.xml @@ -54,7 +54,6 @@ ]]> - Connecting to a web service - HttpClient Sample + Connecting to a web service diff --git a/xml/ns-System.Printing.Interop.xml b/xml/ns-System.Printing.Interop.xml index be5b2e762ec..5d735e6a2b0 100644 --- a/xml/ns-System.Printing.Interop.xml +++ b/xml/ns-System.Printing.Interop.xml @@ -2,16 +2,16 @@ Provides interconversion of managed objects and unmanaged Graphics Device Interface (GDI) DEVMODE structures. - namespace. - + namespace. + ]]> - Documents and Printing - Print Spooler + Documents and Printing + Print Spooler diff --git a/xml/ns-System.Speech.Synthesis.TtsEngine.xml b/xml/ns-System.Speech.Synthesis.TtsEngine.xml index 7020015726e..dd790c0fe2e 100644 --- a/xml/ns-System.Speech.Synthesis.TtsEngine.xml +++ b/xml/ns-System.Speech.Synthesis.TtsEngine.xml @@ -2,32 +2,32 @@ Supports the creation of Speech Synthesis Markup Language (SSML) based custom engines for rendering text to speech (TTS). - namespace make available Windows Desktop Speech Technology support for Speech Synthesis Markup Language (SSML) based markup language and the construction of synthetic speech engines. - - The SSML markup language is the industry standard to provide a rich, XML-based language for assisting the synthetic speech engines. It is endorsed by Microsoft and our competitors. For more information on SSML, see [Speech Synthesis Markup Language Specification](https://go.microsoft.com/fwlink/?LinkId=15144). - - Creating of a new of synthetic speech engine using requires the implementation and registration of an object derived from the abstract base class . - - based synthetic speech engines are accessed through Windows Desktop Speech Technology infrastructure, using the tools in the namespace, in particular object, and are never directly used by applications. - - The Windows Desktop Speech Technology infrastructures ensures that all parameters passed to a synthetic speech engine are validated and thread synchronized. - - A of synthetic speech engine implemented using technology can: - -- Receive input, (see ,., , and ) - -- Queue events, and specify actions (see , , , ). - -- Control the control the pitch, speaking rate and volume of the speech output (see , , , , , , , , , , and ) - -- Determine usage and output target of speech synthesis (see , ) - + namespace make available Windows Desktop Speech Technology support for Speech Synthesis Markup Language (SSML) based markup language and the construction of synthetic speech engines. + + The SSML markup language is the industry standard to provide a rich, XML-based language for assisting the synthetic speech engines. It is endorsed by Microsoft and our competitors. For more information on SSML, see [Speech Synthesis Markup Language Specification](https://go.microsoft.com/fwlink/?LinkId=15144). + + Creating of a new of synthetic speech engine using requires the implementation and registration of an object derived from the abstract base class . + + based synthetic speech engines are accessed through Windows Desktop Speech Technology infrastructure, using the tools in the namespace, in particular object, and are never directly used by applications. + + The Windows Desktop Speech Technology infrastructures ensures that all parameters passed to a synthetic speech engine are validated and thread synchronized. + + A of synthetic speech engine implemented using technology can: + +- Receive input, (see ,., , and ) + +- Queue events, and specify actions (see , , , ). + +- Control the control the pitch, speaking rate and volume of the speech output (see , , , , , , , , , , and ) + +- Determine usage and output target of speech synthesis (see , ) + ]]> - Speech Synthesis Markup Language Specification + Speech Synthesis Markup Language Specification - \ No newline at end of file +