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 +