diff --git a/xml/System.Collections.Concurrent/BlockingCollection`1.xml b/xml/System.Collections.Concurrent/BlockingCollection`1.xml index c4cb146903c..687e1deaeeb 100644 --- a/xml/System.Collections.Concurrent/BlockingCollection`1.xml +++ b/xml/System.Collections.Concurrent/BlockingCollection`1.xml @@ -85,33 +85,31 @@ is a thread-safe collection class that provides the following: -- An implementation of the producer/consumer pattern; is a wrapper for the interface. + is a thread-safe collection class that provides the following: +- An implementation of the producer/consumer pattern; is a wrapper for the interface. - Concurrent addition and removal of items from multiple threads with the and methods. - - A bounded collection that blocks and operations when the collection is full or empty. - - Cancellation of or operations by using a object in the or method. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. Also, note that the method is not thread-safe. All other public and protected members of are thread-safe and may be used concurrently from multiple threads. +> +> - This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). +> - The method is not thread-safe. All other public and protected members of are thread-safe and can be used concurrently from multiple threads. - represents a collection that allows for thread-safe adding and removal of data. is used as a wrapper for an instance, and allows removal attempts from the collection to block until data is available to be removed. Similarly, you can create a to enforce an upper bound on the number of data elements allowed in the ; addition attempts to the collection may then block until space is available to store the added items. In this manner, is similar to a traditional blocking queue data structure, except that the underlying data storage mechanism is abstracted away as an . + represents a collection that allows for thread-safe adding and removal of data. is used as a wrapper for an instance, and allows removal attempts from the collection to block until data is available to be removed. Similarly, you can create a to enforce an upper bound on the number of data elements allowed in the ; addition attempts to the collection may then block until space is available to store the added items. In this manner, is similar to a traditional blocking queue data structure, except that the underlying data storage mechanism is abstracted away as an . - supports bounding and blocking. Bounding means that you can set the maximum capacity of the collection. Bounding is important in certain scenarios because it enables you to control the maximum size of the collection in memory, and it prevents the producing threads from moving too far ahead of the consuming threads.Multiple threads or tasks can add items to the collection concurrently, and if the collection reaches its specified maximum capacity, the producing threads will block until an item is removed. Multiple consumers can remove items concurrently, and if the collection becomes empty, the consuming threads will block until a producer adds an item. A producing thread can call the method to indicate that no more items will be added. Consumers monitor the property to know when the collection is empty and no more items will be added. + supports bounding and blocking. Bounding means that you can set the maximum capacity of the collection. Bounding is important in certain scenarios because it enables you to control the maximum size of the collection in memory, and it prevents the producing threads from moving too far ahead of the consuming threads. Multiple threads or tasks can add items to the collection concurrently, and if the collection reaches its specified maximum capacity, the producing threads will block until an item is removed. Multiple consumers can remove items concurrently, and if the collection becomes empty, the consuming threads will block until a producer adds an item. A producing thread can call the method to indicate that no more items will be added. Consumers monitor the property to know when the collection is empty and no more items will be added. - and operations are typically performed in a loop. You can cancel a loop by passing in a object to the or method, and then checking the value of the token's property on each iteration. If the value is `true`, it is up to you to respond the cancellation request by cleaning up any resources and exiting the loop. + and operations are typically performed in a loop. You can cancel a loop by passing in a object to the or method, and then checking the value of the token's property on each iteration. If the value is `true`, it is up to you to respond the cancellation request by cleaning up any resources and exiting the loop. - When you create a object, you can specify not only the bounded capacity but also the type of collection to use. For example, you could specify a object for first in, first out (FIFO) behavior, or a object for last in, first out (LIFO) behavior. You can use any collection class that implements the interface. The default collection type for is . +When you create a object, you can specify not only the bounded capacity but also the type of collection to use. For example, you could specify a object for first in, first out (FIFO) behavior, or a object for last in, first out (LIFO) behavior. You can use any collection class that implements the interface. The default collection type for is . - Do not modify the underlying collection directly. Use methods to add or remove elements. The object can become corrupted if you change the underlying collection directly. +Do not modify the underlying collection directly. Use methods to add or remove elements. The object can become corrupted if you change the underlying collection directly. was not designed with asynchronous access in mind. If your application requires asynchronous producer/consumer scenarios, consider using instead. - - ## Examples The following example shows how to add and take items concurrently from a blocking collection: diff --git a/xml/System.ComponentModel.Composition.Hosting/AggregateCatalog.xml b/xml/System.ComponentModel.Composition.Hosting/AggregateCatalog.xml index 8e6fe39df40..c75b4dbddbe 100644 --- a/xml/System.ComponentModel.Composition.Hosting/AggregateCatalog.xml +++ b/xml/System.ComponentModel.Composition.Hosting/AggregateCatalog.xml @@ -40,7 +40,7 @@ ## Remarks > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ]]> diff --git a/xml/System.ComponentModel.Composition.Hosting/AggregateExportProvider.xml b/xml/System.ComponentModel.Composition.Hosting/AggregateExportProvider.xml index 0eb003d4e10..d34b3940053 100644 --- a/xml/System.ComponentModel.Composition.Hosting/AggregateExportProvider.xml +++ b/xml/System.ComponentModel.Composition.Hosting/AggregateExportProvider.xml @@ -40,7 +40,7 @@ ## Remarks > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ]]> diff --git a/xml/System.ComponentModel.Composition.Hosting/ApplicationCatalog.xml b/xml/System.ComponentModel.Composition.Hosting/ApplicationCatalog.xml index 1ee4990be5e..d40236adf6c 100644 --- a/xml/System.ComponentModel.Composition.Hosting/ApplicationCatalog.xml +++ b/xml/System.ComponentModel.Composition.Hosting/ApplicationCatalog.xml @@ -40,7 +40,7 @@ ## Remarks > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ]]> diff --git a/xml/System.ComponentModel.Composition.Hosting/AssemblyCatalog.xml b/xml/System.ComponentModel.Composition.Hosting/AssemblyCatalog.xml index fda6f05e655..dfa40a040e5 100644 --- a/xml/System.ComponentModel.Composition.Hosting/AssemblyCatalog.xml +++ b/xml/System.ComponentModel.Composition.Hosting/AssemblyCatalog.xml @@ -45,7 +45,7 @@ An is used to parse all the parts present in a specified assembly. The target assembly can be indicated either by object reference or by path. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). This type is thread safe. diff --git a/xml/System.ComponentModel.Composition.Hosting/AtomicComposition.xml b/xml/System.ComponentModel.Composition.Hosting/AtomicComposition.xml index 9d82faef55f..9e5e6bad717 100644 --- a/xml/System.ComponentModel.Composition.Hosting/AtomicComposition.xml +++ b/xml/System.ComponentModel.Composition.Hosting/AtomicComposition.xml @@ -40,7 +40,7 @@ ## Remarks > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ]]> diff --git a/xml/System.ComponentModel.Composition.Hosting/CatalogExportProvider.xml b/xml/System.ComponentModel.Composition.Hosting/CatalogExportProvider.xml index 594cceb4e91..c147201de68 100644 --- a/xml/System.ComponentModel.Composition.Hosting/CatalogExportProvider.xml +++ b/xml/System.ComponentModel.Composition.Hosting/CatalogExportProvider.xml @@ -40,7 +40,7 @@ ## Remarks > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ]]> diff --git a/xml/System.ComponentModel.Composition.Hosting/ComposablePartExportProvider.xml b/xml/System.ComponentModel.Composition.Hosting/ComposablePartExportProvider.xml index 6ca751759c7..186cb012bbc 100644 --- a/xml/System.ComponentModel.Composition.Hosting/ComposablePartExportProvider.xml +++ b/xml/System.ComponentModel.Composition.Hosting/ComposablePartExportProvider.xml @@ -40,7 +40,7 @@ ## Remarks > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ]]> diff --git a/xml/System.ComponentModel.Composition.Hosting/CompositionContainer.xml b/xml/System.ComponentModel.Composition.Hosting/CompositionContainer.xml index 816579c6039..c2c3f08e341 100644 --- a/xml/System.ComponentModel.Composition.Hosting/CompositionContainer.xml +++ b/xml/System.ComponentModel.Composition.Hosting/CompositionContainer.xml @@ -44,7 +44,7 @@ A object serves two major purposes in an application. First, it keeps track of which parts are available for composition and what their dependencies are, and performs composition whenever the set of available parts changes. Second, it provides the methods by which the application gets instances of composed parts or fills the dependencies of a composable part. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). Parts can be made available to the container either directly or through the property. All the parts discoverable in this are available to the container to fulfill imports, along with any parts added directly. diff --git a/xml/System.ComponentModel.Composition.Hosting/CompositionScopeDefinition.xml b/xml/System.ComponentModel.Composition.Hosting/CompositionScopeDefinition.xml index e4a487c04ba..58bd25d1a5d 100644 --- a/xml/System.ComponentModel.Composition.Hosting/CompositionScopeDefinition.xml +++ b/xml/System.ComponentModel.Composition.Hosting/CompositionScopeDefinition.xml @@ -44,7 +44,7 @@ ## Remarks > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ]]> diff --git a/xml/System.ComponentModel.Composition.Hosting/CompositionService.xml b/xml/System.ComponentModel.Composition.Hosting/CompositionService.xml index 8fcd61ce4dd..ecd9dae0012 100644 --- a/xml/System.ComponentModel.Composition.Hosting/CompositionService.xml +++ b/xml/System.ComponentModel.Composition.Hosting/CompositionService.xml @@ -37,7 +37,7 @@ ## Remarks > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ]]> diff --git a/xml/System.ComponentModel.Composition.Hosting/DirectoryCatalog.xml b/xml/System.ComponentModel.Composition.Hosting/DirectoryCatalog.xml index 7fd48518da8..582e65ce803 100644 --- a/xml/System.ComponentModel.Composition.Hosting/DirectoryCatalog.xml +++ b/xml/System.ComponentModel.Composition.Hosting/DirectoryCatalog.xml @@ -48,11 +48,10 @@ You can use a object to parse the contents of a designated directory. Any attributed parts contained in dynamic link library (DLL) files are extracted and made available through the catalog.To restrict parsing to specific DLLs, you can specify a search pattern by using the same syntax as the method. > [!WARNING] -> The designated directory should not allow access to non-administrators. For example, using a folder that contains temporary Internet files could create vulnerabilities in your application. - - This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - +> The designated directory should not allow access to non-administrators. For example, using a folder that contains temporary Internet files could create vulnerabilities in your application. +> [!IMPORTANT] +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ## Examples The following example creates a object that searches the directory the application runs from for parts. It uses a simple import to test the catalog. To fulfill this import, a DLL in the directory must have a matching export, as illustrated in the second code block. diff --git a/xml/System.ComponentModel.Composition.Hosting/FilteredCatalog.xml b/xml/System.ComponentModel.Composition.Hosting/FilteredCatalog.xml index 5fa2ff6df2f..e18963db411 100644 --- a/xml/System.ComponentModel.Composition.Hosting/FilteredCatalog.xml +++ b/xml/System.ComponentModel.Composition.Hosting/FilteredCatalog.xml @@ -40,7 +40,7 @@ ## Remarks > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ]]> diff --git a/xml/System.ComponentModel.Composition.Hosting/ImportEngine.xml b/xml/System.ComponentModel.Composition.Hosting/ImportEngine.xml index ab6aa53b35e..c25cbc28a2d 100644 --- a/xml/System.ComponentModel.Composition.Hosting/ImportEngine.xml +++ b/xml/System.ComponentModel.Composition.Hosting/ImportEngine.xml @@ -44,7 +44,7 @@ This class is used internally by . You should generally not use it unless you are authoring a container. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ]]> diff --git a/xml/System.ComponentModel.Composition.Hosting/TypeCatalog.xml b/xml/System.ComponentModel.Composition.Hosting/TypeCatalog.xml index 2f2250752a3..c463e5fbe9a 100644 --- a/xml/System.ComponentModel.Composition.Hosting/TypeCatalog.xml +++ b/xml/System.ComponentModel.Composition.Hosting/TypeCatalog.xml @@ -44,7 +44,7 @@ ## Remarks > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). This class is thread safe. diff --git a/xml/System.ComponentModel.Composition.Primitives/ComposablePartCatalog.xml b/xml/System.ComponentModel.Composition.Primitives/ComposablePartCatalog.xml index ec151feeeee..9caeb1c53f7 100644 --- a/xml/System.ComponentModel.Composition.Primitives/ComposablePartCatalog.xml +++ b/xml/System.ComponentModel.Composition.Primitives/ComposablePartCatalog.xml @@ -50,7 +50,7 @@ ## Remarks > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). This type is thread safe. diff --git a/xml/System.ComponentModel.Composition/ExportLifetimeContext`1.xml b/xml/System.ComponentModel.Composition/ExportLifetimeContext`1.xml index f47fd568da6..231a2933f3c 100644 --- a/xml/System.ComponentModel.Composition/ExportLifetimeContext`1.xml +++ b/xml/System.ComponentModel.Composition/ExportLifetimeContext`1.xml @@ -51,7 +51,7 @@ ## Remarks > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ]]> diff --git a/xml/System.Diagnostics/DelimitedListTraceListener.xml b/xml/System.Diagnostics/DelimitedListTraceListener.xml index 2f76a8b3e15..3823f7a0592 100644 --- a/xml/System.Diagnostics/DelimitedListTraceListener.xml +++ b/xml/System.Diagnostics/DelimitedListTraceListener.xml @@ -61,13 +61,13 @@ > This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface docs. > [!NOTE] -> The delimits only text that is emitted by using the methods that have names starting with the word `Trace`, such as or . Trace data that is emitted by using the and methods is not delimited. +> The delimits only text that is emitted by using the methods that have names starting with the word `Trace`, such as or . Trace data that is emitted by using the and methods is not delimited. > [!NOTE] -> If you try to write to a file that is in use or unavailable, the file name is automatically prefixed by a GUID. +> If you try to write to a file that is in use or unavailable, the file name is automatically prefixed by a GUID. > [!NOTE] -> Listeners are intended to be used by methods of the , , and classes to write trace information. Listener methods, except for constructors, should not be called directly from application code. +> Listeners are intended to be used by methods of the , , and classes to write trace information. Listener methods, except for constructors, should not be called directly from application code. ]]> @@ -414,7 +414,7 @@ This constructor initializes a new instance of the class for the specified file on the specified path, using encoding. If the file exists, it is appended to. If the file does not exist, a new file is created. > [!NOTE] -> To reduce the chance of an exception, any character that might invalidate the output is replaced with a "?" character. +> To reduce the chance of an exception, any character that might invalidate the output is replaced with a "?" character. The property is set to the value of the `name` parameter, or to an empty string ("") if the `name` parameter is `null`. The property can be used as an index into the `Listeners` collection to programmatically change the properties for the listener. For example, the following code sets the property for the instance of that has the name "delimListener": @@ -597,7 +597,7 @@ A custom attribute is an attribute that is not inherited from the base class tha The values of the `source`, `eventType`, and `id` parameters are written as a header. The data object is converted to a string using the `ToString` method of the object. The `eventCache` data is written as a footer whose content depends on the value of the property. > [!IMPORTANT] -> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. +> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. ]]> @@ -675,7 +675,7 @@ A custom attribute is an attribute that is not inherited from the base class tha The values of the `source`, `eventType`, and `id` parameters are written as a header. The data objects are converted to strings using the `ToString` method of each object. The `eventCache` data is written as a footer whose content depends on the value of the property. > [!IMPORTANT] -> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. +> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. ]]> @@ -756,7 +756,7 @@ A custom attribute is an attribute that is not inherited from the base class tha The values of the `source`, `eventType`, and `id` parameters are written as a header, followed by the `message` data. The `eventCache` data is written as a footer whose content depends on the value of the property. > [!IMPORTANT] -> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. +> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. ]]> @@ -844,7 +844,7 @@ A custom attribute is an attribute that is not inherited from the base class tha The values of the `source`, `eventType`, and `id` parameters are written as a header. The `args` object array is converted to a string using the method, passing the `format` string and `args` array to format the string as the message portion of the trace. The `eventCache` data is written as a footer whose content depends on the value of the property. > [!IMPORTANT] -> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. +> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. ]]> diff --git a/xml/System.Diagnostics/EventLogEntry.xml b/xml/System.Diagnostics/EventLogEntry.xml index d27d2daf273..f5d5232e69d 100644 --- a/xml/System.Diagnostics/EventLogEntry.xml +++ b/xml/System.Diagnostics/EventLogEntry.xml @@ -58,9 +58,7 @@ You usually will not create instances of directly when working with the class. The member of the class contains a collection of instances, which you iterate over when reading by using the class index member. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - - +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ## Examples The following code example demonstrates the use of the class. In this example, a `switch` statement uses console input to search for event log entries for the specified event type. If a match is found, log entry source information is displayed at the console. diff --git a/xml/System.Diagnostics/Process.xml b/xml/System.Diagnostics/Process.xml index 6340f5d932a..21ac5addef6 100644 --- a/xml/System.Diagnostics/Process.xml +++ b/xml/System.Diagnostics/Process.xml @@ -84,7 +84,7 @@ [!INCLUDE [untrusted-data-class-note](~/includes/untrusted-data-class-note.md)] > [!NOTE] -> 32-bit processes cannot access the modules of a 64-bit process. If you try to get information about a 64-bit process from a 32-bit process, you will get a exception. A 64-bit process, on the other hand, can access the modules of a 32-bit process. +> 32-bit processes cannot access the modules of a 64-bit process. If you try to get information about a 64-bit process from a 32-bit process, you will get a exception. A 64-bit process, on the other hand, can access the modules of a 32-bit process. The process component obtains information about a group of properties all at once. After the component has obtained information about one member of any group, it will cache the values for the other properties in that group and not obtain new information about the other members of the group until you call the method. Therefore, a property value is not guaranteed to be any newer than the last call to the method. The group breakdowns are operating-system dependent. @@ -333,7 +333,7 @@ On macOS, the following properties return 0: You can cancel an asynchronous read operation by calling . The read operation can be canceled by the caller or by the event handler. After canceling, you can call again to resume asynchronous read operations. > [!NOTE] -> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. +> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. @@ -426,7 +426,7 @@ On macOS, the following properties return 0: You can cancel an asynchronous read operation by calling . The read operation can be canceled by the caller or by the event handler. After canceling, you can call again to resume asynchronous read operations. > [!NOTE] -> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. +> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. @@ -523,7 +523,7 @@ process.BeginErrorReadLine(); ``` > [!NOTE] -> You cannot mix asynchronous and synchronous read operations on the redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. If you cancel an asynchronous read operation on and then need to read from the stream again, you must use to resume asynchronous read operations. Do not follow with a call to the synchronous read methods of such as , , or . +> You cannot mix asynchronous and synchronous read operations on the redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. If you cancel an asynchronous read operation on and then need to read from the stream again, you must use to resume asynchronous read operations. Do not follow with a call to the synchronous read methods of such as , , or . @@ -610,7 +610,7 @@ process.BeginOutputReadLine(); ``` > [!NOTE] -> You cannot mix asynchronous and synchronous read operations on the redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. If you cancel an asynchronous read operation on and then need to read from the stream again, you must use to resume asynchronous read operations. Do not follow with a call to the synchronous read methods of such as , , or . +> You cannot mix asynchronous and synchronous read operations on the redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. If you cancel an asynchronous read operation on and then need to read from the stream again, you must use to resume asynchronous read operations. Do not follow with a call to the synchronous read methods of such as , , or . @@ -677,7 +677,7 @@ process.BeginOutputReadLine(); The method causes the process to stop waiting for exit if it was waiting, closes the process handle, and clears process-specific properties. does not close the standard output, input, and error readers and writers in case they are being referenced externally. > [!NOTE] -> The method calls . Placing the object in a `using` block disposes of resources without the need to call . +> The method calls . Placing the object in a `using` block disposes of resources without the need to call . @@ -1030,7 +1030,7 @@ The following code example creates a process that prints a file. It sets the . To start asynchronous read operations, you must redirect the stream of a , add your event handler to the event, and call . Thereafter, the event signals each time the process writes a line to the redirected stream, until the process exits or calls . > [!NOTE] -> The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. Note that specifying a timeout by using the overload does *not* ensure the output buffer has been flushed. +> The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. Note that specifying a timeout by using the overload does *not* ensure the output buffer has been flushed. @@ -1103,7 +1103,7 @@ The following code example creates a process that prints a file. It sets the before the process has exited, the attempt throws an exception. Examine the property first to verify whether the associated process has terminated. > [!NOTE] -> When standard output has been redirected to asynchronous event handlers, it is possible that output processing will not have completed when returns `true`. To ensure that asynchronous event handling has been completed, call the overload that takes no parameter before checking . +> When standard output has been redirected to asynchronous event handlers, it is possible that output processing will not have completed when returns `true`. To ensure that asynchronous event handling has been completed, call the overload that takes no parameter before checking . You can use the or the method to cause an associated process to exit. @@ -1183,7 +1183,7 @@ The following code example creates a process that prints a file. It sets the and that the operating system maintains until it releases that handle completely. > [!NOTE] -> Even if you have a handle to an exited process, you cannot call again to reconnect to the same process. Calling automatically releases the associated process and connects to a process with the same file but an entirely new . +> Even if you have a handle to an exited process, you cannot call again to reconnect to the same process. Calling automatically releases the associated process and connects to a process with the same file but an entirely new . For more information about the use of the event in Windows Forms applications, see the property. @@ -1561,7 +1561,7 @@ The following code example creates a process that prints a file. It sets the or method. creates a component that is associated with the process identified on the system by the process identifier that you pass to the method. creates an array of components whose associated process resources share the executable file you pass to the method. > [!NOTE] -> Multiple Windows services can be loaded within the same instance of the Service Host process (svchost.exe). GetProcesses does not identify those individual services; for that, see . +> Multiple Windows services can be loaded within the same instance of the Service Host process (svchost.exe). GetProcesses does not identify those individual services; for that, see . @@ -1649,7 +1649,7 @@ The following code example creates a process that prints a file. It sets the method is generally used to retrieve the list of process resources running on a remote computer on the network, but you can specify the local computer by passing ".". > [!NOTE] -> Multiple Windows services can be loaded within the same instance of the Service Host process (svchost.exe). GetProcesses does not identify those individual services; for that, see . +> Multiple Windows services can be loaded within the same instance of the Service Host process (svchost.exe). GetProcesses does not identify those individual services; for that, see . @@ -2056,7 +2056,7 @@ There are problems accessing the performance counter APIs used to get process in A process can terminate independently of your code. If you started the process using this component, the system updates the value of automatically, even if the associated process exits independently. > [!NOTE] -> When standard output has been redirected to asynchronous event handlers, it is possible that output processing will not have completed when this property returns `true`. To ensure that asynchronous event handling has been completed, call the overload that takes no parameter before checking . +> When standard output has been redirected to asynchronous event handlers, it is possible that output processing will not have completed when this property returns `true`. To ensure that asynchronous event handling has been completed, call the overload that takes no parameter before checking . @@ -2417,7 +2417,7 @@ The calling process is a member of the associated process's descendant tree., , or on remote computers. > [!NOTE] -> When the associated process is executing on the local machine, this property returns a period (".") for the machine name. You should use the property to get the correct machine name. +> When the associated process is executing on the local machine, this property returns a period (".") for the machine name. You should use the property to get the correct machine name. @@ -2611,7 +2611,7 @@ If no main module is found, it could be because the process hasn't finished load If you have just started a process and want to use its main window title, consider using the method to allow the process to finish starting, ensuring that the main window handle has been created. Otherwise, the system throws an exception. > [!NOTE] -> The main window is the window that currently has the focus; note that this might not be the primary window for the process. You must use the method to refresh the object to get the most up to date main window handle if it has changed. +> The main window is the window that currently has the focus; note that this might not be the primary window for the process. You must use the method to refresh the object to get the most up to date main window handle if it has changed. @@ -2711,7 +2711,7 @@ If no main module is found, it could be because the process hasn't finished load The system sets the default working set sizes. You can modify these sizes using the and members. However, setting these values does not guarantee that the memory will be reserved or resident. > [!NOTE] -> When you increase the working set size of a process, you take physical memory away from the rest of the system. Ensure that you do not request a minimum or maximum working set size that is too large, because doing so can degrade system performance. +> When you increase the working set size of a process, you take physical memory away from the rest of the system. Ensure that you do not request a minimum or maximum working set size that is too large, because doing so can degrade system performance. ]]> @@ -2815,7 +2815,7 @@ If no main module is found, it could be because the process hasn't finished load The system sets the default working set sizes. You can modify these sizes using the and members. However, setting these values does not guarantee that the memory will be reserved or resident. > [!NOTE] -> When you increase the working set size of a process, you take physical memory away from the rest of the system. Ensure that you do not request a minimum or maximum working set size that is too large, because doing so can degrade system performance. +> When you increase the working set size of a process, you take physical memory away from the rest of the system. Ensure that you do not request a minimum or maximum working set size that is too large, because doing so can degrade system performance. ]]> @@ -3065,7 +3065,7 @@ If no main module is found, it could be because the process hasn't finished load As an alternative to , you can write your own event handler. You create your own event handler delegate and your own event-handling method. > [!NOTE] -> If you are using the Visual Studio environment, an event handler delegate (AddOnExited) and an event-handling method (Process1_Exited) are created for you when you drag a component onto a form and double-click the icon. The code you create to run when the event occurs is entered into the Process1_Exited procedure. You do not need to create the member, because it is implemented for you. +> If you are using the Visual Studio environment, an event handler delegate (AddOnExited) and an event-handling method (Process1_Exited) are created for you when you drag a component onto a form and double-click the icon. The code you create to run when the event occurs is entered into the Process1_Exited procedure. You do not need to create the member, because it is implemented for you. Raising an event invokes the event handler through a delegate. For an overview, see [Handling and Raising Events](/dotnet/standard/events/). @@ -3137,7 +3137,7 @@ If no main module is found, it could be because the process hasn't finished load The event is enabled during asynchronous read operations on . To start asynchronous read operations, you must redirect the stream of a , add your event handler to the event, and call . Thereafter, the event signals each time the process writes a line to the redirected stream, until the process exits or calls . > [!NOTE] -> The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. +> The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. @@ -3819,7 +3819,7 @@ If no main module is found, it could be because the process hasn't finished load When a thread runs in a process for which the priority class has one of the dynamic priority enumeration values (, , or ), the system temporarily boosts the thread's priority when it is taken out of a wait state. This action prevents other processes from interrupting the processing of the current thread. The setting affects all the existing threads and any threads subsequently created by the process. To restore normal behavior, set the property to `false`. > [!NOTE] -> Boosting the priority too high can drain resources from essential operating system and network functions, causing problems with other operating system tasks. +> Boosting the priority too high can drain resources from essential operating system and network functions, causing problems with other operating system tasks. ]]> @@ -4148,7 +4148,7 @@ If no main module is found, it could be because the process hasn't finished load The property holds an executable file name, such as Outlook, that does not include the .exe extension or the path. It is helpful for getting and manipulating all the processes that are associated with the same executable file. > [!NOTE] -> On Windows 2000 operating systems, the property may be truncated to 15 characters if the process module information cannot be obtained. +> On Windows 2000 operating systems, the property may be truncated to 15 characters if the process module information cannot be obtained. You can call , passing it an executable file name, to retrieve an array that contains every running instance on the specified computer. You can use this array, for example, to shut down all the running instances of the executable file. @@ -5108,7 +5108,7 @@ If no main module is found, it could be because the process hasn't finished load When a writes text to its standard error stream, that text is normally displayed on the console. By redirecting the stream, you can manipulate or suppress the error output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file. > [!NOTE] -> To use , you must set to `false`, and you must set to `true`. Otherwise, reading from the stream throws an exception. +> To use , you must set to `false`, and you must set to `true`. Otherwise, reading from the stream throws an exception. The redirected stream can be read synchronously or asynchronously. Methods such as , , and perform synchronous read operations on the error output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. @@ -5136,7 +5136,7 @@ There is a similar issue when you read all text from both the standard output an You can use asynchronous read operations to avoid these dependencies and their deadlock potential. Alternately, you can avoid the deadlock condition by creating two threads and reading the output of each stream on a separate thread. > [!NOTE] -> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. +> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. @@ -5206,7 +5206,7 @@ You can use asynchronous read operations to avoid these dependencies and their d A can read input text from its standard input stream, typically the keyboard. By redirecting the stream, you can programmatically specify the input. For example, instead of using keyboard input, you can provide text from the contents of a designated file or output from another application. > [!NOTE] -> To use , you must set to `false`, and you must set to `true`. Otherwise, writing to the stream throws an exception. +> To use , you must set to `false`, and you must set to `true`. Otherwise, writing to the stream throws an exception. @@ -5272,7 +5272,7 @@ You can use asynchronous read operations to avoid these dependencies and their d When a writes text to its standard stream, that text is normally displayed on the console. By redirecting the stream, you can manipulate or suppress the output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file. > [!NOTE] -> To use , you must set to `false`, and you must set to `true`. Otherwise, reading from the stream throws an exception. +> To use , you must set to `false`, and you must set to `true`. Otherwise, reading from the stream throws an exception. The redirected stream can be read synchronously or asynchronously. Methods such as , , and perform synchronous read operations on the output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. @@ -5300,7 +5300,7 @@ There is a similar issue when you read all text from both the standard output an You can use asynchronous read operations to avoid these dependencies and their deadlock potential. Alternately, you can avoid the deadlock condition by creating two threads and reading the output of each stream on a separate thread. > [!NOTE] -> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. +> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. @@ -5400,7 +5400,7 @@ There is a similar issue when you read all text from both the standard output an [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] > [!NOTE] -> If you are using Visual Studio, this overload of the method is the one that you insert into your code after you drag a component onto the designer. Use the `Properties` window to expand the `StartInfo` category and write the appropriate value into the `FileName` property. Your changes will appear in the form's `InitializeComponent` procedure. +> If you are using Visual Studio, this overload of the method is the one that you insert into your code after you drag a component onto the designer. Use the `Properties` window to expand the `StartInfo` category and write the appropriate value into the `FileName` property. Your changes will appear in the form's `InitializeComponent` procedure. This overload of is not a `static` method. You must call it from an instance of the class. Before calling , you must first specify property information for this instance, because that information is used to determine the process resource to start. @@ -5413,7 +5413,7 @@ There is a similar issue when you read all text from both the standard output an If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. > [!NOTE] -> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. +> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. @@ -5519,7 +5519,7 @@ The member [!INCLUDE [untrusted-data-method-note](~/includes/untrusted-data-method-note.md)] > [!NOTE] -> If the address of the executable file to start is a URL, the process is not started and `null` is returned. +> If the address of the executable file to start is a URL, the process is not started and `null` is returned. This overload lets you start a process without first creating a new instance. Using this overload with a parameter is an alternative to the explicit steps of creating a new instance, setting its properties, and calling for the instance. @@ -5534,7 +5534,7 @@ The member If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. > [!NOTE] -> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. +> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. @@ -5648,7 +5648,7 @@ The member [!INCLUDE [untrusted-data-method-note](~/includes/untrusted-data-method-note.md)] > [!NOTE] -> If the address of the executable file to start is a URL, the process is not started and `null` is returned. +> If the address of the executable file to start is a URL, the process is not started and `null` is returned. This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the member of the property, and calling for the instance. @@ -5663,7 +5663,7 @@ The member If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. > [!NOTE] -> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. +> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. @@ -5829,7 +5829,7 @@ The file specified in the could not be found. [!NOTE] -> If the address of the executable file to start is a URL, the process is not started and `null` is returned. +> If the address of the executable file to start is a URL, the process is not started and `null` is returned. This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the and members of the property, and calling for the instance. @@ -5840,7 +5840,7 @@ The file specified in the could not be found. [!NOTE] -> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. +> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. @@ -5950,17 +5950,17 @@ The file specified in the could not be found. [!INCLUDE [untrusted-data-method-note](~/includes/untrusted-data-method-note.md)] > [!NOTE] -> When the executable file is located on a remote drive, you must identify the network share by using a uniform resource identifier (URI), not a linked drive letter. +> When the executable file is located on a remote drive, you must identify the network share by using a uniform resource identifier (URI), not a linked drive letter. > [!NOTE] -> If the address of the executable file to start is a URL, the process is not started and `null` is returned. +> If the address of the executable file to start is a URL, the process is not started and `null` is returned. This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the , , , and properties of the property, and calling for the instance. Similarly, in the same way that the **Run** dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the `fileName` parameter. For example, you can set the `fileName` parameter to either "Notepad.exe" or "Notepad". If the `fileName` parameter represents an executable file, the `arguments` parameter might represent a file to act upon, such as the text file in `Notepad.exe myfile.txt`. > [!NOTE] -> The file name must represent an executable file in the overloads that have `userName`, `password`, and `domain` parameters. +> The file name must represent an executable file in the overloads that have `userName`, `password`, and `domain` parameters. Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. @@ -6061,17 +6061,17 @@ The file specified in the could not be found. [!NOTE] -> When the executable file is located on a remote drive, you must identify the network share by using a uniform resource identifier (URI), not a linked drive letter. +> When the executable file is located on a remote drive, you must identify the network share by using a uniform resource identifier (URI), not a linked drive letter. > [!NOTE] -> If the address of the executable file to start is a URL, the process is not started and `null` is returned. +> If the address of the executable file to start is a URL, the process is not started and `null` is returned. This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the , , , , and properties of the property, and calling for the instance. Similarly, in the same way that the **Run** dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the `fileName` parameter. For example, you can set the `fileName` parameter to either "Notepad.exe" or "Notepad". If the `fileName` parameter represents an executable file, the `arguments` parameter might represent a file to act upon, such as the text file in `Notepad.exe myfile.txt`. > [!NOTE] -> The file name must represent an executable file in the overloads that have `userName`, `password`, and `domain` parameters. +> The file name must represent an executable file in the overloads that have `userName`, `password`, and `domain` parameters. Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. diff --git a/xml/System.Diagnostics/ProcessModule.xml b/xml/System.Diagnostics/ProcessModule.xml index 3afb91bbd41..8d47dfe09ca 100644 --- a/xml/System.Diagnostics/ProcessModule.xml +++ b/xml/System.Diagnostics/ProcessModule.xml @@ -69,9 +69,7 @@ A module is an executable file or a dynamic link library (DLL). Each process consists of one or more modules. You can use this class to get information about the module. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - - +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ## Examples The following code sample demonstrates how to use the class to get and display information about all the modules that are used by the Notepad.exe application. @@ -183,7 +181,7 @@ The module's entry point is the location of the function that is called during process startup, thread startup, process shutdown, and thread shutdown. While the entry point is not the address of the DllMain function, it should be close enough for most purposes. > [!NOTE] -> Due to changes in the way that Windows loads assemblies, will always return 0 on Windows 8 or Windows 8.1 and should not be relied on for those platforms. +> Due to changes in the way that Windows loads assemblies, will always return 0 on Windows 8 or Windows 8.1 and should not be relied on for those platforms. diff --git a/xml/System.Diagnostics/ProcessThread.xml b/xml/System.Diagnostics/ProcessThread.xml index 8aabd6e141b..42e03443cea 100644 --- a/xml/System.Diagnostics/ProcessThread.xml +++ b/xml/System.Diagnostics/ProcessThread.xml @@ -65,7 +65,7 @@ Use to obtain information about a thread that is currently running on the system. Doing so allows you, for example, to monitor the thread's performance characteristics. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). A thread is a path of execution through a program. It is the smallest unit of execution that Win32 schedules. It consists of a stack, the state of the CPU registers, and an entry in the execution list of the system scheduler. @@ -361,7 +361,7 @@ has an effect only when the thread is running in a process that has a set to one of the dynamic priority enumeration values (, , or ). > [!NOTE] -> Boosting the priority too high can drain resources from essential operating system and network functions. This could cause problems with other operating system tasks. +> Boosting the priority too high can drain resources from essential operating system and network functions. This could cause problems with other operating system tasks. ]]> diff --git a/xml/System.Diagnostics/TextWriterTraceListener.xml b/xml/System.Diagnostics/TextWriterTraceListener.xml index 8a2ee48c3a8..ad27720a409 100644 --- a/xml/System.Diagnostics/TextWriterTraceListener.xml +++ b/xml/System.Diagnostics/TextWriterTraceListener.xml @@ -59,14 +59,14 @@ The class provides the property to get or set the text writer that receives the tracing or debugging output. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). This class also provides methods to the so that it no longer receives tracing or debugging output, to the output buffer for the , and to a message to the . You must enable tracing or debugging to use a trace listener. > [!NOTE] -> If an attempt is made to write to a file that is in use or unavailable, the file name is automatically prefixed by a GUID. +> If an attempt is made to write to a file that is in use or unavailable, the file name is automatically prefixed by a GUID. ## Examples The following example implements an instance of the class that uses a called `myOutputWriter` to write to a file named `TestFile.txt`. First the example creates a file for output. Then it creates the for the first text writer, assigns it the output file, and adds it to the . Then, the code outputs one line of text to the file. Finally, the example flushes the output buffer. diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml index 8c7ec32a848..78b68848bef 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml @@ -64,7 +64,7 @@ For more information, see [Isolated Storage](/dotnet/standard/io/isolated-storage). - This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ## Examples The following code example illustrates how to create files and directories in an isolated store. First, a store that is isolated by user, domain, and assembly is retrieved and placed in the `isoStore` variable. The method is then called to create directories, and two instances of the class create files in these directories. @@ -767,7 +767,7 @@ Call `Dispose` when you are finished using the . The `Dispose` method leaves the in an unusable state. After calling `Dispose`, you must release all references to the so the garbage collector can reclaim the memory that was occupying. > [!NOTE] -> Always call Dispose before you release your last reference to the . Otherwise, the resources the is using will not be freed until garbage collection calls the object's method. +> Always call Dispose before you release your last reference to the . Otherwise, the resources the is using will not be freed until garbage collection calls the object's method. @@ -1497,7 +1497,7 @@ :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.vb" id="Snippet19"::: > [!NOTE] -> Different assemblies running within the same application domain always have distinct isolated stores. +> Different assemblies running within the same application domain always have distinct isolated stores. ]]> @@ -1559,7 +1559,7 @@ Different assemblies running within the same application domain always have distinct isolated stores. > [!NOTE] -> will return an object without a quota if the application domain into which the assembly is installed does not have . Later attempts to create an object using the object that does not have a quota will fail with an . +> will return an object without a quota if the application domain into which the assembly is installed does not have . Later attempts to create an object using the object that does not have a quota will fail with an . @@ -1656,7 +1656,7 @@ ## Remarks > [!NOTE] -> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . +> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . ]]> @@ -1740,7 +1740,7 @@ ## Remarks > [!NOTE] -> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . +> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . ]]> @@ -1827,7 +1827,7 @@ This form of `GetStore` is most useful for administrative code that needs to open a store as if it were another assembly. The store is opened for the evidence provided and not for the currently executing assembly. > [!NOTE] -> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . +> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . ]]> @@ -1920,7 +1920,7 @@ This overload of opens an isolated store for the evidence types that are passed in. > [!NOTE] -> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . +> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . @@ -2076,7 +2076,7 @@ :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.vb" id="Snippet22"::: > [!NOTE] -> Different assemblies running within the same application domain always have distinct isolated stores. +> Different assemblies running within the same application domain always have distinct isolated stores. ]]> @@ -2143,7 +2143,7 @@ Different assemblies running within the same application domain always have distinct isolated stores. > [!NOTE] -> will return an object without a quota if the application domain in which the assembly is installed does not have . Later attempts to create an object using the object that does not have a quota will fail with an . +> will return an object without a quota if the application domain in which the assembly is installed does not have . Later attempts to create an object using the object that does not have a quota will fail with an . @@ -2860,7 +2860,7 @@ ## Remarks > [!CAUTION] -> This method irrevocably removes the entire scope and all contained directories and files. +> This method irrevocably removes the entire scope and all contained directories and files. If any of the directories or files in the store are in use, the removal attempt for the store fails and the store is marked for removal. Any subsequent attempts to modify the store throw an . @@ -2927,7 +2927,7 @@ ## Remarks > [!CAUTION] -> This method irrevocably removes the entire scope and all contained directories and files. +> This method irrevocably removes the entire scope and all contained directories and files. If any of the directories or files in the store are in use, the removal attempt for the store fails and the store is marked for removal. Any subsequent attempts to modify the store throw an . diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml index 42b4ecdbbf7..463302e3261 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml @@ -60,7 +60,7 @@ Since this class extends , you can use an instance of in most situations where a might otherwise be used, such as to construct a or . - This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ## Examples The following console application demonstrates how you can use and to write data to an Isolated Storage file. The user is requested to log in. If the user is a new user, a News URL and a Sports URL are recorded as personal preferences in Isolated Storage. If the user is a returning user, the user's current preferences are displayed. The code examples used throughout this namespace are presented in the context of this sample application. You can use the [Storeadm.exe (Isolated Storage Tool)](/dotnet/framework/tools/storeadm-exe-isolated-storage-tool) utility to list and remove the Isolated Storage files that are created with this console application. diff --git a/xml/System.IO/BinaryReader.xml b/xml/System.IO/BinaryReader.xml index 60a9bcfd9bb..1928d62aff7 100644 --- a/xml/System.IO/BinaryReader.xml +++ b/xml/System.IO/BinaryReader.xml @@ -90,9 +90,7 @@ When you create a new instance of the class, you provide the stream to read from, and optionally specify the type of encoding and whether to leave the stream open after disposing the object. If you do not specify an encoding type, UTF-8 is used. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - - +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ## Examples The following code example demonstrates how to store and retrieve application settings in a file. @@ -372,7 +370,7 @@ ## Remarks > [!CAUTION] -> Using the underlying stream while reading or while using the `BinaryReader` can cause data loss and corruption. For example, the same bytes might be read more than once, bytes might be skipped, or character reading might become unpredictable. +> Using the underlying stream while reading or while using the `BinaryReader` can cause data loss and corruption. For example, the same bytes might be read more than once, bytes might be skipped, or character reading might become unpredictable. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -521,7 +519,7 @@ For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call `Dispose` before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. +> Always call `Dispose` before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. ]]> diff --git a/xml/System.IO/BinaryWriter.xml b/xml/System.IO/BinaryWriter.xml index a633ffe1d03..c144c1db1bb 100644 --- a/xml/System.IO/BinaryWriter.xml +++ b/xml/System.IO/BinaryWriter.xml @@ -98,12 +98,10 @@ When you create a new instance of the class, you provide the stream to write to, and optionally specify the type of encoding and whether to leave the stream open after disposing the object. If you do not specify an encoding type, UTF-8 is used. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). A derived class can override the methods of this class to give unique character encodings. - - ## Examples The following code example demonstrates how to store and retrieve application settings in a file. diff --git a/xml/System.IO/BufferedStream.xml b/xml/System.IO/BufferedStream.xml index dee7e516824..b7b00fc99ee 100644 --- a/xml/System.IO/BufferedStream.xml +++ b/xml/System.IO/BufferedStream.xml @@ -82,12 +82,10 @@ A buffer is a block of bytes in memory used to cache data, thereby reducing the number of calls to the operating system. Buffers improve read and write performance. A buffer can be used for either reading or writing, but never both simultaneously. The and methods of `BufferedStream` automatically maintain the buffer. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). `BufferedStream` can be composed around certain types of streams. It provides implementations for reading and writing bytes to an underlying data source or repository. Use and for reading and writing other data types. `BufferedStream` is designed to prevent the buffer from slowing down input and output when the buffer is not needed. If you always read and write for sizes greater than the internal buffer size, then `BufferedStream` might not even allocate the internal buffer. `BufferedStream` also buffers reads and writes in a shared buffer. It is assumed that you will almost always be doing a series of reads or writes, but rarely alternate between the two of them. - - ## Examples The following code examples show how to use the `BufferedStream` class over the `NetworkStream` class to increase the performance of certain I/O operations. Start the server on a remote computer before starting the client. Specify the remote computer name as a command-line argument when starting the client. Vary the `dataArraySize` and `streamBufferSize` constants to view their effect on performance. diff --git a/xml/System.IO/FileStream.xml b/xml/System.IO/FileStream.xml index afd57c22031..4be01949c21 100644 --- a/xml/System.IO/FileStream.xml +++ b/xml/System.IO/FileStream.xml @@ -72,7 +72,7 @@ Use the class to read from, write to, open, and close files on a file system, and to manipulate other file-related operating system handles, including pipes, standard input, and standard output. You can use the , , , and methods to perform synchronous operations, or the , , , and methods to perform asynchronous operations. Use the asynchronous methods to perform resource-intensive file operations without blocking the main thread. This performance consideration is particularly important in a desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. buffers input and output for better performance. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). The property detects whether the file handle was opened asynchronously. You specify this value when you create an instance of the class using a constructor that has an `isAsync`, `useAsync`, or `options` parameter. When the property is `true`, the stream utilizes overlapped I/O to perform file operations asynchronously. However, the property does not have to be `true` to call the , , or method. When the property is `false` and you call the asynchronous read and write operations, the UI thread is still not blocked, but the actual I/O operation is performed synchronously. @@ -186,7 +186,7 @@ A object will not have an exclusive hold on its hand `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. `FileShare.Read` is the default for those constructors without a `FileShare` parameter. @@ -279,7 +279,7 @@ A object will not have an exclusive hold on its hand `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. `FileShare.Read` is the default for those constructors without a `FileShare` parameter. @@ -363,7 +363,7 @@ A object will not have an exclusive hold on its hand The buffer size is set to the default size of 4096 bytes (4 KB). > [!NOTE] -> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. +> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . @@ -372,7 +372,7 @@ A object will not have an exclusive hold on its hand For constructors without a parameter, if the `mode` parameter is set to , is the default access. Otherwise, the access is set to . > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -478,7 +478,7 @@ The disk was full (when was provided and was pointing to a regular file). The caller does not have the required permission. The specified path is invalid, such as being on an unmapped drive. - The requested is not permitted by the operating system for the specified , such as when is or and the file or directory is set for read-only access. + The requested is not permitted by the operating system for the specified , such as when is or and the file or directory is set for read-only access. -or- @@ -542,7 +542,7 @@ The file was too large (when constructors without a `FileShare` parameter. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -729,7 +729,7 @@ The file was too large (when constructors without a `FileShare` parameter. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -921,7 +921,7 @@ The file was too large (when [!NOTE] -> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. +> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1125,7 +1125,7 @@ The file was too large (when [!NOTE] -> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. +> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1310,12 +1310,12 @@ The file was too large (when [!NOTE] -> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. +> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -2568,7 +2568,7 @@ This method flushes the .NET stream buffers to the file, but does not flush inte The operating system handle might have been opened synchronously or asynchronously, depending on which `FileStream` constructor was called. Use the property to discover whether this handle was opened asynchronously. In Win32, this means the handle was opened for overlapped IO, and it requires different parameters to `ReadFile` and `WriteFile`. > [!CAUTION] -> Data corruption might occur if a `FileStream` is created, its handle is passed, some operation moves the handle's file pointer, and then the `FileStream` is used again. Multiple threads cannot safely write to the same file simultaneously, and `FileStream` buffering code assumes that it exclusively controls the handle. `FileStream` might throw an if `FileStream` detects that some other process has moved the file pointer. To avoid this, do not write any data into a portion of the file that `FileStream` might have buffered, and restore the file pointer to the location it had when methods were last called on `FileStream`. +> Data corruption might occur if a `FileStream` is created, its handle is passed, some operation moves the handle's file pointer, and then the `FileStream` is used again. Multiple threads cannot safely write to the same file simultaneously, and `FileStream` buffering code assumes that it exclusively controls the handle. `FileStream` might throw an if `FileStream` detects that some other process has moved the file pointer. To avoid this, do not write any data into a portion of the file that `FileStream` might have buffered, and restore the file pointer to the location it had when methods were last called on `FileStream`. ]]> @@ -3304,7 +3304,7 @@ The following example shows how to read from a file asynchronously. This method overrides . > [!NOTE] -> Use the property to determine whether the current instance supports reading. For additional information, see . +> Use the property to determine whether the current instance supports reading. For additional information, see . @@ -3442,7 +3442,7 @@ The following example shows how to read from a file asynchronously. This method overrides . > [!NOTE] -> Use the property to determine whether the current instance supports seeking. For additional information, see . +> Use the property to determine whether the current instance supports seeking. For additional information, see . You can seek to any location beyond the length of the stream. When you seek beyond the length of the file, the file size grows. Data added to the end of the file is set to zero. @@ -3530,7 +3530,7 @@ The following example shows how to read from a file asynchronously. A stream must support both writing and seeking for `SetLength` to work. > [!NOTE] -> Use the property to determine whether the current instance supports writing, and the property to determine whether seeking is supported. For additional information, see and . +> Use the property to determine whether the current instance supports writing, and the property to determine whether seeking is supported. For additional information, see and . For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). diff --git a/xml/System.IO/Stream.xml b/xml/System.IO/Stream.xml index 57e51440d0a..fd29290ad5e 100644 --- a/xml/System.IO/Stream.xml +++ b/xml/System.IO/Stream.xml @@ -105,7 +105,7 @@ The and methods read and write data in a variety of formats. For streams that support seeking, use the and methods and the and properties to query and modify the current position and length of a stream. - This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). Disposing a object flushes any buffered data, and essentially calls the method for you. also releases operating system resources such as file handles, network connections, or memory used for any internal buffering. The class provides the capability of wrapping a buffered stream around another stream in order to improve read and write performance. diff --git a/xml/System.IO/StreamReader.xml b/xml/System.IO/StreamReader.xml index 12c7754fd51..280f0c07acd 100644 --- a/xml/System.IO/StreamReader.xml +++ b/xml/System.IO/StreamReader.xml @@ -84,7 +84,7 @@ is designed for character input in a particular encoding, whereas the class is designed for byte input and output. Use for reading lines of information from a standard text file. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). defaults to UTF-8 encoding unless specified otherwise, instead of defaulting to the ANSI code page for the current system. UTF-8 handles Unicode characters correctly and provides consistent results on localized versions of the operating system. If you get the current character encoding using the property, the value is not reliable until after the first method, since encoding auto detection is not done until the first call to a method. @@ -93,7 +93,7 @@ The and method overloads read and write the number of characters specified by the `count` parameter. These are to be distinguished from and , which read and write the number of bytes specified by the `count` parameter. Use the methods only for reading and writing an integral number of byte array elements. > [!NOTE] -> When reading from a , it is more efficient to use a buffer that is the same size as the internal buffer of the stream. +> When reading from a , it is more efficient to use a buffer that is the same size as the internal buffer of the stream. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -189,7 +189,7 @@ The object calls on the provided object when is called. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -266,7 +266,7 @@ The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -442,7 +442,7 @@ The object calls on the provided object when is called. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -669,7 +669,7 @@ The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -768,7 +768,7 @@ The object calls on the provided object when is called. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -862,7 +862,7 @@ The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -963,10 +963,10 @@ The object calls on the provided object when is called. > [!NOTE] -> When reading from a , it is more efficient to use a buffer that is the same size as the internal buffer of the stream. +> When reading from a , it is more efficient to use a buffer that is the same size as the internal buffer of the stream. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1065,7 +1065,7 @@ The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1234,10 +1234,10 @@ This constructor enables you to change the encoding the first time you read from the object. If the `detectEncodingFromByteOrderMarks` parameter is `true`, the constructor detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. > [!NOTE] -> When reading from a , it is more efficient to use a buffer that is the same size as the internal buffer of the stream. +> When reading from a , it is more efficient to use a buffer that is the same size as the internal buffer of the stream. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpreted correctly, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpreted correctly, and could cause an exception to be thrown. ]]> diff --git a/xml/System.IO/StreamWriter.xml b/xml/System.IO/StreamWriter.xml index 5e4cc16297f..683f00b4ff4 100644 --- a/xml/System.IO/StreamWriter.xml +++ b/xml/System.IO/StreamWriter.xml @@ -84,7 +84,7 @@ is designed for character output in a particular encoding, whereas classes derived from are designed for byte input and output. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). defaults to using an instance of unless specified otherwise. This instance of `UTF8Encoding` is constructed without a byte order mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as or . @@ -92,8 +92,6 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - ## Examples The following example shows how to use a object to write a file that lists the directories on the C drive, and then uses a object to read and display each directory name. A good practice is to use these objects in a `using` statement so that the unmanaged resources are correctly disposed. The `using` statement automatically calls on the object when the code that is using it has completed. The constructor used in this example is not supported for use in Windows Store Apps. @@ -180,7 +178,7 @@ The object calls on the provided object when is called. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable and could cause an exception to be thrown. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -259,7 +257,7 @@ The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable and could cause an exception to be thrown. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -359,7 +357,7 @@ The object calls on the provided object when is called. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -442,7 +440,7 @@ The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -589,7 +587,7 @@ The object calls on the provided object when is called. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -684,7 +682,7 @@ `path` is not required to be a file stored on disk; it can be any part of a system that supports access via streams. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -844,7 +842,7 @@ This constructor initializes the property by using the `encoding` parameter, and initializes the property by using the `stream` parameter. The position of the stream is not reset. For additional information, see the property. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. @@ -935,7 +933,7 @@ `path` is not required to be a file stored on disk; it can be any part of a system that supports access via streams. > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). diff --git a/xml/System.IO/TextReader.xml b/xml/System.IO/TextReader.xml index c8aac3ac6e3..befffd4b67a 100644 --- a/xml/System.IO/TextReader.xml +++ b/xml/System.IO/TextReader.xml @@ -94,7 +94,7 @@ is the abstract base class of and , which read characters from streams and strings, respectively. Use these derived classes to open a text file for reading a specified range of characters, or to create a reader based on an existing stream. > [!IMPORTANT] -> This type implements the interface. When you have finished using any type that derives from this type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see Dispose and the "Using an Object that Implements IDisposable" section in the interface topic. +This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ## Examples The class is an abstract class. Therefore, you do not instantiate it in your code. The class derives from and provides implementations of the members for reading from a stream. The following example shows how to read all the characters in a file by using the method. It checks whether each character is a letter, digit, or white space before adding the character to an instance of the class. @@ -226,7 +226,7 @@ This implementation of `Close` calls the method and passes it a `true` value. > [!NOTE] -> In derived classes, do not override the method. Instead, override the method to add code for releasing resources. +> In derived classes, do not override the method. Instead, override the method to add code for releasing resources. ]]> @@ -307,7 +307,7 @@ For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's method. +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's method. ]]> diff --git a/xml/System.IO/TextWriter.xml b/xml/System.IO/TextWriter.xml index cae430d376f..3b1bee1248e 100644 --- a/xml/System.IO/TextWriter.xml +++ b/xml/System.IO/TextWriter.xml @@ -106,7 +106,7 @@ By default, a is not thread safe. See for a thread-safe wrapper. > [!IMPORTANT] -> This type implements the interface. When you have finished using any type that derives from this type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see Dispose and the "Using an Object that Implements IDisposable" section in the interface topic. +This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -325,7 +325,7 @@ Flushing the stream will not flush its underlying encoder unless you explicitly call or `Close`. Setting the property to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can be encoded only after the encoder receives the adjacent character or characters. > [!NOTE] -> In derived classes, do not override the method. Instead, override the method to add code for releasing resources. +> In derived classes, do not override the method. Instead, override the method to add code for releasing resources. ]]> @@ -1988,7 +1988,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo ## Remarks -This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the method to avoid creating the intermediate string. +This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the method to avoid creating the intermediate string. ]]> diff --git a/xml/System.Resources/ResourceReader.xml b/xml/System.Resources/ResourceReader.xml index 400080978cc..05516f9fcd0 100644 --- a/xml/System.Resources/ResourceReader.xml +++ b/xml/System.Resources/ResourceReader.xml @@ -97,7 +97,7 @@ The class provides a standard implementation of the interface. A instance represents either a standalone .resources file or a .resources file that is embedded in an assembly. It is used to enumerate the resources in a .resources file and retrieve its name/value pairs. It differs from the class, which is used to retrieve specified named resources from a .resources file that is embedded in an assembly. The class is used to retrieve resources whose names are known in advance, whereas the class is useful for retrieving resources whose number or precise names are not known at compile time. For example, an application may use a resources file to store configuration information that is organized into sections and items in a section, where the number of sections or items in a section is not known in advance. Resources can then be named generically (such as `Section1`, `Section1Item1`, `Section1Item2`, and so on) and retrieved by using a object. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface documentation. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ## Instantiate a ResourceReader object diff --git a/xml/System.Resources/ResourceSet.xml b/xml/System.Resources/ResourceSet.xml index a96bca2c67e..66c5c67114d 100644 --- a/xml/System.Resources/ResourceSet.xml +++ b/xml/System.Resources/ResourceSet.xml @@ -81,7 +81,7 @@ You can instantiate a object that represents the resources of a specific culture by calling the method. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ]]> diff --git a/xml/System.Resources/ResourceWriter.xml b/xml/System.Resources/ResourceWriter.xml index 1b0e1155672..49fbb8d54cc 100644 --- a/xml/System.Resources/ResourceWriter.xml +++ b/xml/System.Resources/ResourceWriter.xml @@ -75,7 +75,7 @@ Resources are specified as name and value pairs using the method. Resource names are case-sensitive when used for lookups, but to more easily support authoring tools and help eliminate bugs, will not allow a .resources file to have names that vary only by case. The class enables you to create string, object, and binary resources. Binary resources can be written to the resource file as a byte array or a stream. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). To create a resources file, create a with a unique file name, call at least once, call to write the resources file to disk, and then call to close the file. Calling will implicitly call if you do not explicitly call . @@ -83,8 +83,6 @@ To retrieve resources from a binary .resources file created by the class, you can use the class, which lets you retrieve named resources, or the class, which lets you enumerate all the resources in the file. - - ## Examples The following example writes several strings into the myResources.resources file. diff --git a/xml/System.Runtime/MemoryFailPoint.xml b/xml/System.Runtime/MemoryFailPoint.xml index 092664e7392..52552e15e74 100644 --- a/xml/System.Runtime/MemoryFailPoint.xml +++ b/xml/System.Runtime/MemoryFailPoint.xml @@ -54,12 +54,12 @@ ## Remarks > [!NOTE] -> This class is intended for use in advanced development. +> This class is intended for use in advanced development. Creating an instance of the class creates a memory gate. A memory gate checks for sufficient resources before initiating an activity that requires a large amount of memory. Failing the check results in an exception being thrown. This exception prevents an operation from being started and reduces the possibility of failure due to lack of resources. This enables you decrease performance to avoid an exception and any state corruption that may result from improper handling of the exception in arbitrary locations in your code. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). By throwing an exception, an application can distinguish between an estimate that an operation will not be able to complete and a partially completed operation that may have corrupted the application state. This allows an application to reduce the frequency of a pessimistic escalation policy, which may require unloading the current or recycling the process. @@ -71,8 +71,6 @@ operates at a granularity of 16 MB. Any values smaller than 16 MB are treated as 16 MB, and other values are treated as the next largest multiple of 16 MB. - - ## Examples enables an application to slow itself to avoid running out of memory in a corrupting manner. It should be used within a lexical scope. The following example launches threads to process items in a work queue. Before each thread is launched, the available memory resources are checked using . If an exception is thrown, the main method waits until memory is available before launching the next thread. @@ -187,7 +185,7 @@ Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. ]]> diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml b/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml index 508df69b49b..4f58648156e 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml @@ -87,7 +87,7 @@ For most scenarios, you should use the class instead. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ## Examples The following example loads an X.509 certificate from a file, calls the method, and displays the results to the console. @@ -318,7 +318,7 @@ This constructor creates a new object using a handle for the Microsoft Cryptographic API certificate context, `PCCERT_CONTEXT`. > [!IMPORTANT] -> This constructor creates a copy of the certificate context. Do not assume that the context structure you passed to the constructor is valid; it may have been released. You can get a copy of the current `PCCERT_CONTEXT` structure from the property, but it is valid only during the lifetime of the object. +> This constructor creates a copy of the certificate context. Do not assume that the context structure you passed to the constructor is valid; it may have been released. You can get a copy of the current `PCCERT_CONTEXT` structure from the property, but it is valid only during the lifetime of the object. ]]> @@ -551,7 +551,7 @@ ASN.1 DER is the only certificate format supported by this class. > [!IMPORTANT] -> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening the assembly in a text editor such as Notepad.exe. +> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening the assembly in a text editor such as Notepad.exe. If you create an certificate by specifying a PKCS7 signed file store for `rawData`, the is created for the certificate that signed the store rather than for any of the certificates within the store. @@ -641,7 +641,7 @@ ASN.1 DER is the only certificate format supported by this class. > [!IMPORTANT] -> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening the assembly in a text editor such as Notepad.exe. +> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening the assembly in a text editor such as Notepad.exe. If you create an certificate by specifying a PKCS7 signed file store for `rawData`, the is created for the certificate that signed the store rather than for any of the certificates within the store. @@ -796,7 +796,7 @@ ASN.1 DER is the only certificate format supported by this class. Calling this constructor with the correct password decrypts the private key and saves it to a key container. > [!IMPORTANT] -> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening the assembly in a text editor such as Notepad.exe. +> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening the assembly in a text editor such as Notepad.exe. If you create an certificate by specifying a PKCS7 signed file store for `fileName`, the is created for the certificate that signed the store rather than for any of the certificates within the store. @@ -971,7 +971,7 @@ ASN.1 DER is the only certificate format supported by this class. > [!IMPORTANT] -> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening the assembly in a text editor such as Notepad.exe. +> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening the assembly in a text editor such as Notepad.exe. If you create an certificate by specifying a PKCS7 signed file store for `rawData`, the is created for the certificate that signed the store rather than for any of the certificates within the store. @@ -1067,7 +1067,7 @@ ASN.1 DER is the only certificate format supported by this class. > [!IMPORTANT] -> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening the assembly in a text editor such as Notepad.exe. +> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening the assembly in a text editor such as Notepad.exe. If you create an certificate by specifying a PKCS7 signed file store for `rawData`, the is created for the certificate that signed the store rather than for any of the certificates within the store. @@ -1318,7 +1318,7 @@ ASN.1 DER is the only certificate format supported by this class. > [!NOTE] -> The certificate file is not restricted to .cer files. Any PKCS7 signed file can be used, including an Authenticode signed .pfx file. +> The certificate file is not restricted to .cer files. Any PKCS7 signed file can be used, including an Authenticode signed .pfx file. @@ -1818,7 +1818,7 @@ The `contentType` parameter accepts only the following values of the enumeration: , , and . Passing any other value causes a to be thrown. > [!IMPORTANT] -> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening the assembly in a text editor such as Notepad.exe. +> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening the assembly in a text editor such as Notepad.exe. ]]> @@ -1893,7 +1893,7 @@ The `contentType` parameter accepts only the following values of the enumeration: , , and . Passing any other value causes a to be thrown. > [!IMPORTANT] -> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening the assembly in a text editor such as Notepad.exe. +> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening the assembly in a text editor such as Notepad.exe. ]]> @@ -2400,7 +2400,7 @@ The method returns a string that shows the date formatted in Short Date Pattern followed by the time formatted in Long Time Pattern. The date and time are formatted using the current culture and time zone. > [!NOTE] -> This method may return a different string format on Macintosh computers, although the underlying object will represent the same value. +> This method may return a different string format on Macintosh computers, although the underlying object will represent the same value. diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Chain.xml b/xml/System.Security.Cryptography.X509Certificates/X509Chain.xml index e936f19df7d..1cf703f48ad 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Chain.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Chain.xml @@ -72,7 +72,7 @@ The object has a global error status called that should be used for certificate validation. The rules governing certificate validation are complex, and it is easy to oversimplify the validation logic by ignoring the error status of one or more of the elements involved. The global error status takes into consideration the status of each element in the chain. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). When disposing , the certificates in are not disposed. You should dispose of the certificates in this collection when the certificate instances are no longer needed. diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Store.xml b/xml/System.Security.Cryptography.X509Certificates/X509Store.xml index 7a4480a37ea..ee7fdb7b281 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Store.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Store.xml @@ -72,7 +72,7 @@ Use this class to work with an X.509 store. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ## Examples This section contains two examples. The first example demonstrates how you can open standard X.509 stores and list the number of certificates in each. @@ -1314,12 +1314,10 @@ ## Remarks > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). This method removes more than one certificate from an X.509 certificate store; if one certificate removal fails, the operation is reverted and no certificates are removed. - - ## Examples The following code example opens an X.509 certificate store, adds and deletes certificates, and then closes the store. It assumes that you have three certificates to add to and remove from a local store. diff --git a/xml/System.Security.Cryptography/RNGCryptoServiceProvider.xml b/xml/System.Security.Cryptography/RNGCryptoServiceProvider.xml index 12b13b1464e..fda83110ef4 100644 --- a/xml/System.Security.Cryptography/RNGCryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/RNGCryptoServiceProvider.xml @@ -74,9 +74,7 @@ ## Remarks > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - - +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ## Examples The following code example shows how to create a random number with the class. diff --git a/xml/System.Security.Cryptography/SHA1CryptoServiceProvider.xml b/xml/System.Security.Cryptography/SHA1CryptoServiceProvider.xml index 4a4c05acc78..7de3a082bec 100644 --- a/xml/System.Security.Cryptography/SHA1CryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/SHA1CryptoServiceProvider.xml @@ -71,7 +71,7 @@ The hash size for the class is 160 bits. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better. diff --git a/xml/System.Security.Principal/WindowsIdentity.xml b/xml/System.Security.Principal/WindowsIdentity.xml index 209f5b226af..e4f7205b065 100644 --- a/xml/System.Security.Principal/WindowsIdentity.xml +++ b/xml/System.Security.Principal/WindowsIdentity.xml @@ -58,9 +58,7 @@ Call the method to create a object that represents the current user. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - - +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ## Examples The following example shows the use of members of class. For an example showing how to obtain a Windows account token through a call to the unmanaged Win32 `LogonUser` function, and use that token to impersonate another user, see the class. @@ -128,7 +126,7 @@ ||`false`| > [!NOTE] -> You can retrieve the token represented by `userToken` by calling unmanaged code such as the Windows API `LogonUser` function. Always release `userToken` by calling the Windows API `CloseHandle` function. For more information on calling unmanaged code, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). +> You can retrieve the token represented by `userToken` by calling unmanaged code such as the Windows API `LogonUser` function. Always release `userToken` by calling the Windows API `CloseHandle` function. For more information on calling unmanaged code, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). ]]> @@ -217,7 +215,7 @@ A UPN has the format *username*@*domainname*.com, in other words, an email address. The UPN identified in `sUserPrincipalName` is used to retrieve a token for that user through the Windows API `LsaLogonUser` function. In turn that token is used to identify the user. An exception might be returned due to the inability to log on using the supplied UPN. > [!NOTE] -> This constructor is intended for use only on computers joined to Windows Server 2003 or later domains. An exception is thrown for earlier domain types. This restriction is due to the fact that this constructor uses the [KERB_S4U_LOGON structure](https://learn.microsoft.com/windows/win32/api/ntsecapi/ns-ntsecapi-kerb_s4u_logon), which was first introduced in Windows Server 2003. Also, this constructor requires read access to the [token-groups-global-and-universal (TGGAU) attribute](https://support.microsoft.com/en-us/help/331951/some-applications-and-apis-require-access-to-authorization-information) on the target user account. +> This constructor is intended for use only on computers joined to Windows Server 2003 or later domains. An exception is thrown for earlier domain types. This restriction is due to the fact that this constructor uses the [KERB_S4U_LOGON structure](https://learn.microsoft.com/windows/win32/api/ntsecapi/ns-ntsecapi-kerb_s4u_logon), which was first introduced in Windows Server 2003. Also, this constructor requires read access to the [token-groups-global-and-universal (TGGAU) attribute](https://support.microsoft.com/en-us/help/331951/some-applications-and-apis-require-access-to-authorization-information) on the target user account. ]]> @@ -287,7 +285,7 @@ The value of the `type` parameter is used to set the parameter. If `type` is `null`, the security system sets to `Negotiate` on Windows Vista and later versions of the Windows operating system, and to `Kerberos` on earlier versions of the Windows operating system. The security system does not use this value; it is for informational use only. > [!NOTE] -> You can retrieve the token represented by `userToken` by calling unmanaged code such as the Windows API `LogonUser` function. Always release `userToken` by calling the Windows API `CloseHandle` function. For more information on calling unmanaged code, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). +> You can retrieve the token represented by `userToken` by calling unmanaged code such as the Windows API `LogonUser` function. Always release `userToken` by calling the Windows API `CloseHandle` function. For more information on calling unmanaged code, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). @@ -423,7 +421,7 @@ The value of the `type` parameter is used to set the parameter. If `type` is `null`, the security system sets to `Negotiate` on Windows Vista and later versions of the Windows operating system, and to `Kerberos` on earlier versions of the Windows operating system. The security system does not use this value; it is for informational use only. > [!NOTE] -> You can retrieve the token represented by `userToken` by calling unmanaged code such as the Windows API `LogonUser` function. Always release `userToken` by calling the Windows API `CloseHandle` function. For more information on calling unmanaged code, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). +> You can retrieve the token represented by `userToken` by calling unmanaged code such as the Windows API `LogonUser` function. Always release `userToken` by calling the Windows API `CloseHandle` function. For more information on calling unmanaged code, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). @@ -808,7 +806,7 @@ Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. ]]> @@ -1526,7 +1524,7 @@ ## Remarks > [!NOTE] -> This method may be used reliably with the async/await pattern, unlike `Impersonate`. In an async method, the generic overload of this method may be used with an async delegate argument so that the resulting task may be awaited. +> This method may be used reliably with the async/await pattern, unlike `Impersonate`. In an async method, the generic overload of this method may be used with an async delegate argument so that the resulting task may be awaited. @@ -1534,7 +1532,7 @@ The following example demonstrates the use of the class to impersonate a user. > [!WARNING] -> This sample asks the user to enter a password on the console screen. The password will be visible on the screen, because the console window does not support masked input natively. +> This sample asks the user to enter a password on the console screen. The password will be visible on the screen, because the console window does not support masked input natively. ```csharp // The following example demonstrates the use of the WindowsIdentity class to impersonate a user. @@ -1665,7 +1663,7 @@ public class ImpersonationDemo ## Remarks > [!NOTE] -> This method may be used reliably with the async/await pattern, unlike `Impersonate`. In an async method, this method may be used with an async delegate argument so that the resulting task may be awaited. +> This method may be used reliably with the async/await pattern, unlike `Impersonate`. In an async method, this method may be used with an async delegate argument so that the resulting task may be awaited. @@ -1673,7 +1671,7 @@ public class ImpersonationDemo The following example demonstrates the use of the class to impersonate a user. > [!WARNING] -> This sample asks the user to enter a password on the console screen. The password will be visible on the screen, because the console window does not support masked input natively. +> This sample asks the user to enter a password on the console screen. The password will be visible on the screen, because the console window does not support masked input natively. ```csharp // The following example demonstrates the use of the WindowsIdentity class to impersonate a user. @@ -2018,7 +2016,7 @@ public class ImpersonationDemo The SID uniquely identifies a user or group on all Windows NT implementations. > [!NOTE] -> The object returned by the method is not the same as the Windows anonymous user. This property gets `null` for an anonymous user represented by the object returned by the method; it does not get the SID representing an anonymous Windows user. +> The object returned by the method is not the same as the Windows anonymous user. This property gets `null` for an anonymous user represented by the object returned by the method; it does not get the SID representing an anonymous Windows user. ]]> diff --git a/xml/System.Security/SecureString.xml b/xml/System.Security/SecureString.xml index 593672fe2e9..af81e747b4b 100644 --- a/xml/System.Security/SecureString.xml +++ b/xml/System.Security/SecureString.xml @@ -75,7 +75,7 @@ The maximum length of a instance is 65,536 characters. > [!IMPORTANT] -> This type implements the interface. When you have finished using an instance of the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). The class and its members are not visible to COM. For more information, see . diff --git a/xml/System.Threading/AutoResetEvent.xml b/xml/System.Threading/AutoResetEvent.xml index bea0c956430..0f432b6a653 100644 --- a/xml/System.Threading/AutoResetEvent.xml +++ b/xml/System.Threading/AutoResetEvent.xml @@ -71,7 +71,7 @@ You can control the initial state of an `AutoResetEvent` by passing a Boolean va > Unlike the class, the class provides access to named system synchronization events. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section on the interface page. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ## Examples diff --git a/xml/System.Threading/CancellationTokenSource.xml b/xml/System.Threading/CancellationTokenSource.xml index dd9ffe37b3a..f4f98d2a567 100644 --- a/xml/System.Threading/CancellationTokenSource.xml +++ b/xml/System.Threading/CancellationTokenSource.xml @@ -86,7 +86,7 @@ The general pattern for implementing the cooperative cancellation model is: For more information, see [Cancellation in Managed Threads](/dotnet/standard/threading/cancellation-in-managed-threads). > [!IMPORTANT] -> This type implements the interface. When you have finished using an instance of the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`finally` block. To dispose of it indirectly, use a language construct such as `using` in C#. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). ## Examples The following example uses a random number generator to emulate a data collection application that reads 10 integral values from eleven different instruments. A value of zero indicates that the measurement has failed for one instrument, in which case the operation should be cancelled and no overall mean should be computed. @@ -920,7 +920,7 @@ If `throwOnFirstException` is `false`, this overload aggregates any exceptions t For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call `Dispose` before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. +> Always call `Dispose` before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. ]]> diff --git a/xml/System.Threading/Mutex.xml b/xml/System.Threading/Mutex.xml index 8a090e463e1..aef12fefbfc 100644 --- a/xml/System.Threading/Mutex.xml +++ b/xml/System.Threading/Mutex.xml @@ -60,12 +60,11 @@ When two or more threads need to access a shared resource at the same time, the system needs a synchronization mechanism to ensure that only one thread at a time uses the resource. is a synchronization primitive that grants exclusive access to the shared resource to only one thread. If a thread acquires a mutex, the second thread that wants to acquire that mutex is suspended until the first thread releases the mutex. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). You can use the method to request ownership of a mutex. The calling thread blocks until one of the following occurs: - The mutex is signaled to indicate that it is not owned. When this happens, the method returns `true`, and the calling thread assumes ownership of the mutex and accesses the resource protected by the mutex. When it has finished accessing the resource, the thread must call the method to release ownership of the mutex. The first example in the Examples section illustrates this pattern. - - The time-out interval specified in the call to a method that has a `millisecondsTimeout` or `timeout` parameter has elapsed. When this happens, the method returns `false`, and the calling thread makes no further attempt to acquire ownership of the mutex. In this case, you should structure your code so that access to the resource that is protected by the mutex is denied to the calling thread. Because the thread never acquired ownership of the mutex, it must not call the method. The second example in the Examples section illustrates this pattern. The class enforces thread identity, so a mutex can be released only by the thread that acquired it. By contrast, the class does not enforce thread identity. @@ -77,7 +76,7 @@ If a thread terminates while owning a mutex, the mutex is said to be abandoned. The state of the mutex is set to signaled, and the next waiting thread gets ownership. An is thrown in the next thread that acquires the abandoned mutex. > [!CAUTION] -> An abandoned mutex often indicates a serious error in the code. When a thread exits without releasing the mutex, the data structures protected by the mutex might not be in a consistent state. The next thread to request ownership of the mutex can handle this exception and proceed, if the integrity of the data structures can be verified. +> An abandoned mutex often indicates a serious error in the code. When a thread exits without releasing the mutex, the data structures protected by the mutex might not be in a consistent state. The next thread to request ownership of the mutex can handle this exception and proceed, if the integrity of the data structures can be verified. In the case of a system-wide mutex, an abandoned mutex might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). @@ -851,7 +850,7 @@ There was some other error. The `HResult` property might provide more informatio If a thread terminates while owning a mutex, the mutex is said to be abandoned. The state of the mutex is set to signaled and the next waiting thread gets ownership. If no one owns the mutex, the state of the mutex is signaled. An is thrown in the next thread that acquires the mutex. > [!CAUTION] -> An abandoned mutex often indicates a serious error in the code. When a thread exits without releasing the mutex, the data structures protected by the mutex might not be in a consistent state. The next thread to request ownership of the mutex can handle this exception and proceed, if the integrity of the data structures can be verified. +> An abandoned mutex often indicates a serious error in the code. When a thread exits without releasing the mutex, the data structures protected by the mutex might not be in a consistent state. The next thread to request ownership of the mutex can handle this exception and proceed, if the integrity of the data structures can be verified. In the case of a system-wide mutex, an abandoned mutex might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). diff --git a/xml/System.Threading/ReaderWriterLockSlim.xml b/xml/System.Threading/ReaderWriterLockSlim.xml index e3299883ff9..b098d5d2b70 100644 --- a/xml/System.Threading/ReaderWriterLockSlim.xml +++ b/xml/System.Threading/ReaderWriterLockSlim.xml @@ -67,7 +67,7 @@ A thread can enter the lock in three modes: read mode, write mode, and upgradeab Regardless of recursion policy, only one thread can be in write mode at any time. When a thread is in write mode, no other thread can enter the lock in any mode. Only one thread can be in upgradeable mode at any time. Any number of threads can be in read mode, and there can be one thread in upgradeable mode while other threads are in read mode. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). has managed thread affinity; that is, each object must make its own method calls to enter and exit lock modes. No thread can change the mode of another thread. @@ -110,11 +110,8 @@ You can create a that supports recu For a that allows recursion, the following can be said about the modes a thread can enter: - A thread in read mode can enter read mode recursively, but cannot enter write mode or upgradeable mode. If it tries to do this, a is thrown. Entering read mode and then entering write mode or upgradeable mode is a pattern with a strong probability of deadlocks, so it is not allowed. As discussed earlier, upgradeable mode is provided for cases where it is necessary to upgrade a lock. - - A thread in upgradeable mode can enter write mode and/or read mode, and can enter any of the three modes recursively. However, an attempt to enter write mode blocks if there are other threads in read mode. - - A thread in write mode can enter read mode and/or upgradeable mode, and can enter any of the three modes recursively. - - A thread that has not entered the lock can enter any mode. This attempt can block for the same reasons as an attempt to enter a non-recursive lock. A thread can exit the modes it has entered in any order, as long as it exits each mode exactly as many times as it entered that mode. If a thread tries to exit a mode too many times, or to exit a mode it has not entered, a is thrown. @@ -124,14 +121,12 @@ A thread can exit the modes it has entered in any order, as long as it exits eac You may find it useful to think of the lock in terms of its states. A can be in one of four states: not entered, read, upgrade, and write. - Not entered: In this state, no threads have entered the lock (or all threads have exited the lock). - - Read: In this state, one or more threads have entered the lock for read access to the protected resource. > [!NOTE] > A thread can enter the lock in read mode by using the or methods, or by downgrading from upgradeable mode. - Upgrade: In this state, one thread has entered the lock for read access with the option to upgrade to write access (that is, in upgradeable mode), and zero or more threads have entered the lock for read access. No more than one thread at a time can enter the lock with the option to upgrade; additional threads that try to enter upgradeable mode are blocked. - - Write: In this state, one thread has entered the lock for write access to the protected resource. That thread has exclusive possession of the lock. Any other thread that tries to enter the lock for any reason is blocked. The following table describes the transitions between lock states, for locks that do not allow recursion, when a thread `t` takes the action described in the leftmost column. At the time it takes the action, `t` has no mode. (The special case where `t` is in upgradeable mode is described in the table footnotes.) The top row describes the starting state of the lock. The cells describe what happens to the thread, and show changes to the lock state in parentheses. @@ -314,7 +309,7 @@ The following code then uses the `SynchronizedCache` object to store a dictionar Recursion policy determines the restrictions on threads that enter the lock more than once. For example, if a lock was created with and a thread has entered the lock in read mode, is thrown if the thread tries to reenter the lock in read mode. Similarly, if a thread has entered the lock in write mode, is thrown if the thread tries to reenter the lock in any mode. > [!NOTE] -> A thread in upgradeable mode can upgrade to write mode or downgrade to read mode regardless of the lock recursion policy setting. +> A thread in upgradeable mode can upgrade to write mode or downgrade to read mode regardless of the lock recursion policy setting. Regardless of recursion policy, a thread that initially entered read mode is not allowed to upgrade to upgradeable mode or write mode, because that pattern creates a strong probability of deadlocks. @@ -459,7 +454,7 @@ The following code then uses the `SynchronizedCache` object to store a dictionar Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the object. +> Always call before you release your last reference to the object. ]]> @@ -525,7 +520,7 @@ The following code then uses the `SynchronizedCache` object to store a dictionar If one or more threads are waiting to enter write mode, a thread that calls the method blocks until those threads have either timed out or entered write mode and then exited from it. > [!NOTE] -> If a lock allows recursion, a thread that has entered the lock in read mode can enter read mode recursively, even if other threads are waiting to enter write mode. +> If a lock allows recursion, a thread that has entered the lock in read mode can enter read mode recursively, even if other threads are waiting to enter write mode. At most one thread can be in upgradeable mode while other threads are in read mode. If additional threads are waiting to enter upgradeable mode, and there are no threads waiting to enter write mode, threads that call the method enter read mode immediately and do not block. @@ -607,7 +602,7 @@ The following code then uses the `SynchronizedCache` object to store a dictionar If one or more threads are waiting to enter write mode, a thread that calls the method blocks until those threads have either timed out or entered write mode and then exited from it. > [!NOTE] -> If a lock allows recursion, a thread that has entered the lock in upgradeable mode can enter upgradeable mode recursively, even if other threads are waiting to enter write mode. +> If a lock allows recursion, a thread that has entered the lock in upgradeable mode can enter upgradeable mode recursively, even if other threads are waiting to enter write mode. @@ -689,7 +684,7 @@ The following code then uses the `SynchronizedCache` object to store a dictionar If other threads have entered the lock in read mode, a thread that calls the method blocks until those threads have exited read mode. When there are threads waiting to enter write mode, additional threads that try to enter read mode or upgradeable mode block until all the threads waiting to enter write mode have either timed out or entered write mode and then exited from it. > [!NOTE] -> If a lock allows recursion, a thread that has entered the lock in write mode can enter write mode recursively, even if other threads are waiting to enter write mode. +> If a lock allows recursion, a thread that has entered the lock in write mode can enter write mode recursively, even if other threads are waiting to enter write mode. @@ -1141,7 +1136,7 @@ The following code then uses the `SynchronizedCache` object to store a dictionar Recursion policy determines the restrictions on threads that enter the lock more than once. For example, if a lock was created with and a thread has entered the lock in read mode, is thrown if the thread tries to reenter the lock in read mode. > [!NOTE] -> A thread in upgradeable mode can upgrade to write mode or downgrade to read mode regardless of the lock recursion policy setting. +> A thread in upgradeable mode can upgrade to write mode or downgrade to read mode regardless of the lock recursion policy setting. Regardless of recursion policy, a thread that initially entered read mode is not allowed to upgrade to upgradeable mode or write mode, because that pattern creates a strong probability of deadlocks. @@ -1365,7 +1360,7 @@ The following code then uses the `SynchronizedCache` object to store a dictionar If one or more threads are waiting to enter write mode, a thread that calls the method blocks until those threads have either timed out or entered write mode and then exited from it, or until the calling thread's own time-out interval expires. > [!NOTE] -> If a lock allows recursion, a thread that has entered the lock in read mode can enter read mode recursively, even if other threads are waiting to enter write mode. +> If a lock allows recursion, a thread that has entered the lock in read mode can enter read mode recursively, even if other threads are waiting to enter write mode. One thread can be in upgradeable mode while other threads are in read mode. If additional threads are waiting to enter upgradeable mode, and there are no threads waiting to enter write mode, threads that call the method enter read mode immediately and do not block. @@ -1435,7 +1430,7 @@ The following code then uses the `SynchronizedCache` object to store a dictionar If one or more threads are queued to enter write mode, a thread that calls the method blocks until those threads have either timed out or entered write mode and then exited from it, or until the calling thread's own time-out interval expires. > [!NOTE] -> If a lock allows recursion, a thread that has entered the lock in read mode can enter read mode recursively, even if other threads are waiting to enter write mode. +> If a lock allows recursion, a thread that has entered the lock in read mode can enter read mode recursively, even if other threads are waiting to enter write mode. One thread can be in upgradeable mode while other threads are in read mode. If additional threads are waiting to enter upgradeable mode, and there are no threads waiting to enter write mode, threads that call the method enter read mode immediately and do not block. @@ -1522,7 +1517,7 @@ The following code then uses the `SynchronizedCache` object to store a dictionar If one or more threads are waiting to enter write mode, a thread that calls the method blocks until those threads have either timed out or entered write mode and then exited from it, or until the calling thread's own time-out interval expires. > [!NOTE] -> If a lock allows recursion, a thread that has entered the lock in upgradeable mode can enter upgradeable mode recursively, even if other threads are waiting to enter write mode. +> If a lock allows recursion, a thread that has entered the lock in upgradeable mode can enter upgradeable mode recursively, even if other threads are waiting to enter write mode. ]]> @@ -1596,7 +1591,7 @@ The following code then uses the `SynchronizedCache` object to store a dictionar If one or more threads are waiting to enter write mode, a thread that calls the method blocks until those threads have either timed out or entered write mode and then exited from it, or until the calling thread's own time-out interval expires. > [!NOTE] -> If a lock allows recursion, a thread that has entered the lock in upgradeable mode can enter upgradeable mode recursively, even if other threads are waiting to enter write mode. +> If a lock allows recursion, a thread that has entered the lock in upgradeable mode can enter upgradeable mode recursively, even if other threads are waiting to enter write mode. ]]> @@ -1681,7 +1676,7 @@ The following code then uses the `SynchronizedCache` object to store a dictionar If other threads have entered the lock in read mode, a thread that calls the method blocks until those threads have exited read mode or until the time-out interval has elapsed. While threads are blocked waiting to enter write mode, additional threads that try to enter read mode or upgradeable mode block until all the threads waiting to enter write mode have either timed out or entered write mode and then exited from it. > [!NOTE] -> If a lock allows recursion, a thread that has entered the lock in write mode can enter write mode recursively, even if other threads are waiting to enter write mode. +> If a lock allows recursion, a thread that has entered the lock in write mode can enter write mode recursively, even if other threads are waiting to enter write mode. @@ -1765,7 +1760,7 @@ The following code then uses the `SynchronizedCache` object to store a dictionar If other threads have entered the lock in read mode, a thread that calls the method blocks until those threads have exited read mode or until the time-out interval has elapsed. While threads are blocked waiting to enter write mode, additional threads that try to enter read mode or upgradeable mode block until all the threads waiting to enter write mode have either timed out or entered write mode and then exited from it. > [!NOTE] -> If a lock allows recursion, a thread that has entered the lock in write mode can enter write mode recursively, even if other threads are waiting to enter write mode. +> If a lock allows recursion, a thread that has entered the lock in write mode can enter write mode recursively, even if other threads are waiting to enter write mode. ]]> diff --git a/xml/System.Threading/WaitHandle.xml b/xml/System.Threading/WaitHandle.xml index b0ac5db5583..a40b4b52029 100644 --- a/xml/System.Threading/WaitHandle.xml +++ b/xml/System.Threading/WaitHandle.xml @@ -90,7 +90,7 @@ The overloads of these methods provide timeout intervals for abandoning the wait, and the opportunity to exit a synchronization context before entering the wait, allowing other threads to use the synchronization context. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type or a type derived from it, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` in C#. +> This type implements the interface. When you've finished using the type or a type derived from it, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`finally` block. To dispose of it indirectly, use a language construct such as `using` in C#. > > When you derive from , use the property to store your native operating system handle. You do not need to override the protected method unless you use additional unmanaged resources. @@ -197,7 +197,7 @@ Once this method is called, references to the current instance cause undefined behavior. > [!NOTE] -> Always call or before you release your last reference to the . Otherwise, the resources it is using will not be freed. +> Always call or before you release your last reference to the . Otherwise, the resources it is using will not be freed. ]]> @@ -268,7 +268,7 @@ This method is equivalent to the method. > [!NOTE] -> Always call or before you release your last reference to the . Otherwise, the resources it is using will not be freed. +> Always call or before you release your last reference to the . Otherwise, the resources it is using will not be freed. ]]> @@ -824,7 +824,7 @@ If `millisecondsTimeout` is zero, the method does not block. It tests the state The method returns when all the handles are signaled. If more than 64 handles are passed, a is thrown. If the array contains duplicates, the call fails with a . > [!NOTE] -> The method is not supported on threads in state. +> The method is not supported on threads in state. Calling this method overload is equivalent to calling the method overload and specifying -1 (or ) for `millisecondsTimeout` and `true` for `exitContext`. @@ -910,7 +910,7 @@ If `millisecondsTimeout` is zero, the method does not block. It tests the state The method returns when the wait terminates, which means either when all the handles are signaled or when time-out occurs. If more than 64 handles are passed, a is thrown. If there are duplicates in the array, the call fails with a . > [!NOTE] -> The method is not supported on threads in state. +> The method is not supported on threads in state. Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. @@ -992,7 +992,7 @@ If `millisecondsTimeout` is zero, the method does not block. It tests the state The method returns when the wait terminates, which means either all the handles are signaled or a time-out occurs. If more than 64 handles are passed, a is thrown. If the array contains duplicates, the call will fail. > [!NOTE] -> The method is not supported on threads in state. +> The method is not supported on threads in state. The maximum value for `timeout` is . diff --git a/xml/System.Timers/Timer.xml b/xml/System.Timers/Timer.xml index 6933c19a7bf..62cf769a0e1 100644 --- a/xml/System.Timers/Timer.xml +++ b/xml/System.Timers/Timer.xml @@ -70,20 +70,19 @@ The component is a server-based timer that raises an event in your application after the number of milliseconds in the property has elapsed. You can configure the object to raise the event just once or repeatedly using the property. Typically, a object is declared at the class level so that it stays in scope as long as it is needed. You can then handle its event to provide regular processing. For example, suppose you have a critical server that must be kept running 24 hours a day, 7 days a week. You could create a service that uses a object to periodically check the server and ensure that the system is up and running. If the system is not responding, the service could attempt to restart the server or notify an administrator. > [!IMPORTANT] -> The class is not available for all .NET implementations and versions, such as .NET Standard 1.6 and lower versions. -> In these cases, you can use the class instead. +> The class is not available for all .NET implementations and versions, such as .NET Standard 1.6 and lower versions. In these cases, you can use the class instead. - This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +This type implements the interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). The server-based class is designed for use with worker threads in a multithreaded environment. Server timers can move among threads to handle the raised event, resulting in more accuracy than Windows timers in raising the event on time. The component raises the event, based on the value (in milliseconds) of the property. You can handle this event to perform the processing you need. For example, suppose that you have an online sales application that continuously posts sales orders to a database. The service that compiles the instructions for shipping operates on a batch of orders rather than processing each order individually. You could use a to start the batch processing every 30 minutes. > [!IMPORTANT] -> The System.Timers.Timer class has the same resolution as the system clock. This means that the event will fire at an interval defined by the resolution of the system clock if the property is less than the resolution of the system clock. For more information, see the property. +> The System.Timers.Timer class has the same resolution as the system clock. This means that the event will fire at an interval defined by the resolution of the system clock if the property is less than the resolution of the system clock. For more information, see the property. > [!NOTE] -> The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). +> The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). When is set to `false`, a object raises the event only once, after the first has elapsed. To keep raising the event regularly at the interval defined by the , set to `true`, which is the default value. @@ -96,7 +95,7 @@ If the property is `null`, the event is raised on a thread. If processing of the event lasts longer than , the event might be raised again on another thread. In this situation, the event handler should be reentrant. > [!NOTE] -> The event-handling method might run on one thread at the same time that another thread calls the method or sets the property to `false`. This might result in the event being raised after the timer is stopped. The example code for the method shows one way to avoid this race condition. +> The event-handling method might run on one thread at the same time that another thread calls the method or sets the property to `false`. This might result in the event being raised after the timer is stopped. The example code for the method shows one way to avoid this race condition. Even if is not `null`, events can occur after the or method has been called or after the property has been set to `false`, because the signal to raise the event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the event to ignore subsequent events. @@ -105,7 +104,7 @@ For a list of default property values for an instance of , see the constructor. > [!TIP] -> .NET includes four classes named `Timer`, each of which offers different functionality: +> .NET includes a few classes named `Timer`, each of which offers different functionality: > > - (this topic): fires an event at regular intervals. The class is intended for use as a server-based or service component in a multithreaded environment; it has no user interface and is not visible at runtime. > - : executes a single callback method on a thread pool thread at regular intervals. The callback method is defined when the timer is instantiated and cannot be changed. Like the class, this class is intended for use as a server-based or service component in a multithreaded environment; it has no user interface and is not visible at runtime. @@ -179,14 +178,12 @@ ## Remarks The following table shows initial property values for an instance of . -|Property|Initial value| -|--------------|-------------------| -||`true`| -||`false`| -||100 milliseconds| -||A null reference (`Nothing` in Visual Basic).| - - +| Property | Initial value | +|-------------------------------------------------|-----------------------------------------------| +| | `true` | +| | `false` | +| | 100 milliseconds | +| | A null reference (`Nothing` in Visual Basic). | ## Examples The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. @@ -247,8 +244,6 @@ ## Remarks This constructor sets the property of the new timer instance, but does not enable the timer. - - ## Examples The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. @@ -344,8 +339,6 @@ Resetting the interval affects when the event is raised. For example, if you set the interval to 5 seconds and then set the property to `true`, the count starts at the time is set. If you reset the interval to 10 seconds when the count is 3 seconds, the event is raised for the first time 13 seconds after the property was set to `true`. - - ## Examples The following example creates a whose event fires after 1.5 seconds. Its event handler then displays "Hello World!" on the console. @@ -566,7 +559,7 @@ If the property is `null`,the event is raised on a thread. If the processing of the event lasts longer than , the event might be raised again on another thread. In this situation, the event handler should be reentrant. > [!NOTE] -> The event-handling method might run on one thread at the same time that another thread calls the method or sets the property to `false`. This might result in the event being raised after the timer is stopped. The example code for the method shows one way to avoid this race condition. +> The event-handling method might run on one thread at the same time that another thread calls the method or sets the property to `false`. This might result in the event being raised after the timer is stopped. The example code for the method shows one way to avoid this race condition. Even if is not `null`, events can occur after the or method has been called or after the property has been set to `false`, because the signal to raise the event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the event to ignore subsequent events. @@ -642,14 +635,14 @@ Setting to `true` is the same as calling , while setting to `false` is the same as calling . > [!NOTE] -> The signal to raise the event is always queued for execution on a thread. This might result in the event being raised after the property is set to `false`. The code example for the method shows one way to work around this race condition. +> The signal to raise the event is always queued for execution on a thread. This might result in the event being raised after the property is set to `false`. The code example for the method shows one way to work around this race condition. If is set to `true` and is set to `false`, the raises the event only once, the first time the interval elapses. If the interval is set after the has started, the count is reset. For example, if you set the interval to 5 seconds and then set the property to `true`, the count starts at the time is set. If you reset the interval to 10 seconds when count is 3 seconds, the event is raised for the first time 13 seconds after was set to `true`. > [!NOTE] -> Some visual designers, such as those in Microsoft Visual Studio, set the property to `true` when inserting a new . +> Some visual designers, such as those in Microsoft Visual Studio, set the property to `true` when inserting a new . ## Examples The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. @@ -715,7 +708,7 @@ method starts the initialization. Using the and methods prevents the control from being used before it is fully initialized. + The Visual Studio 2005 design environment uses this method to end the initialization of a component that's used on a form or by another component. The method starts the initialization. Using the and methods prevents the control from being used before it's fully initialized. ]]> @@ -776,7 +769,7 @@ You use the property to determine the frequency at which the event is fired. Because the class depends on the system clock, it has the same resolution as the system clock. This means that the event will fire at an interval defined by the resolution of the system clock if the property is less than the resolution of the system clock. The following example sets the property to 5 milliseconds. When run on a Windows system whose system clock has a resolution of approximately 15 milliseconds, the event fires approximately every 15 milliseconds rather than every 5 milliseconds. > [!NOTE] -> The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). +> The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). :::code language="csharp" source="~/snippets/csharp/System.Timers/Timer/Interval/interval2.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Timers/Timer/Interval/interval2.fs" id="Snippet1"::: @@ -789,9 +782,7 @@ If is set to `true` and is set to `false`, the raises the event only once, the first time the interval elapses. is then set to `false`. > [!NOTE] -> If and are both set to `false`, and the timer has previously been enabled, setting the property causes the event to be raised once, as if the property had been set to `true`. To set the interval without raising the event, you can temporarily set the property to `true`, set the property to the desired time interval, and then immediately set the property back to `false`. - - +> If and are both set to `false`, and the timer has previously been enabled, setting the property causes the event to be raised once, as if the property had been set to `true`. To set the interval without raising the event, you can temporarily set the property to `true`, set the property to the desired time interval, and then immediately set the property back to `false`. ## Examples The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. @@ -910,7 +901,7 @@ You can also start timing by setting to `true`. > [!NOTE] -> If is `false`, the method must be called in order to start the count again. +> If is `false`, the method must be called in order to start the count again. A call to the method when the timer is enabled has no effect. @@ -1053,7 +1044,7 @@ When the event is handled by a visual Windows Forms component, such as a button, accessing the component through the system-thread pool might result in an exception or just might not work. Avoid this effect by setting to a Windows Forms component, which causes the method that handles the event to be called on the same thread that the component was created on. > [!NOTE] -> Even if the property is not `null`, events can occur after the or method has been called or after the property has been set to `false`, because the signal to raise the event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the event to ignore subsequent events. +> Even if the property is not `null`, events can occur after the or method has been called or after the property has been set to `false`, because the signal to raise the event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the event to ignore subsequent events. If the is used inside Visual Studio in a Windows Forms designer, is automatically set to the control that contains the . For example, if you place a on a designer for `Form1` (which inherits from ), the property of is set to the instance of `Form1`. @@ -1066,10 +1057,8 @@ The example requires that you add the following controls to the form: - A control named `TextBox1` (its default name). - - A control named `Button1` (its default name). - -- A control named `SaveSaveFileDialog1` (its default name) . +- A control named `SaveSaveFileDialog1` (its default name). ]]> diff --git a/xml/System/IDisposable.xml b/xml/System/IDisposable.xml index 7a9df94b03e..29bfcf90493 100644 --- a/xml/System/IDisposable.xml +++ b/xml/System/IDisposable.xml @@ -59,21 +59,18 @@ Use the method of this interface to explicitl Because the implementation is called by the consumer of a type when the resources owned by an instance are no longer needed, you should either wrap the managed object in a (the recommended alternative), or you should override to free unmanaged resources in the event that the consumer forgets to call . -For a detailed discussion about how this interface and the method are used, see the [Garbage Collection](/dotnet/standard/garbage-collection/index) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose) topics. +For a detailed discussion about how this interface and the method are used, see [Garbage collection](/dotnet/standard/garbage-collection/index) and [Implementing a dispose method](/dotnet/standard/garbage-collection/implementing-dispose). ## Use an object that implements IDisposable -If your app simply uses an object that implements the interface, you should call the object's implementation when you are finished using it. Depending on your programming language, you can do this in one of two ways: +If your app uses an object that implements the interface, you should dispose of it when it's no longer needed. Depending on your programming language, you can do this in one of two ways: -- By using a language construct such as the `using` statement in C# and Visual Basic, and the `use` statement or `using` function in F#. -- By wrapping the call to the implementation in a `try`/`finally` block. +- By using a language construct such as `using` in C#, `Using` in Visual Basic, or the `use` statement or `using` function in F#. +- By wrapping a call to the method in a `try`/`finally` block. -> [!NOTE] -> Documentation for types that implement note that fact and include a reminder to call its implementation. +### The C#, F#, and Visual Basic using/Using/use statement -### The C#, F#, and Visual Basic Using statement - -If your language supports a construct such as the [using](/dotnet/csharp/language-reference/keywords/using) statement in C#, the [Using](/dotnet/visual-basic/language-reference/statements/using-statement) statement in Visual Basic, or the [use](/dotnet/fsharp/language-reference/resource-management-the-use-keyword) statement in F#, you can use it instead of explicitly calling yourself. The following example uses this approach in defining a `WordCount` class that preserves information about a file and the number of words in it. +You can use a language construct such as the [using](/dotnet/csharp/language-reference/keywords/using) statement in C#, the [Using](/dotnet/visual-basic/language-reference/statements/using-statement) statement in Visual Basic, or the [use](/dotnet/fsharp/language-reference/resource-management-the-use-keyword) statement in F# instead of explicitly calling yourself. The following example uses this approach in defining a `WordCount` class that preserves information about a file and the number of words in it. :::code language="csharp" source="~/snippets/csharp/System/IDisposable/Overview/calling1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/IDisposable/Overview/calling1.fs" id="Snippet1"::: @@ -81,24 +78,24 @@ If your language supports a construct such as the [using](/dotnet/csharp/languag The `using` statement (`use` expression in F#) is actually a syntactic convenience. At compile time, the language compiler implements the intermediate language (IL) for a `try`/`finally` block. -For more information about the `using` statement, see the [Using Statement](/dotnet/visual-basic/language-reference/statements/using-statement) or [using Statement](/dotnet/csharp/language-reference/keywords/using-statement) topics. +For more information about the `using` statement, see [using statement (C# reference)](/dotnet/csharp/language-reference/keywords/using-statement) or [Using statement (Visual Basic)](/dotnet/visual-basic/language-reference/statements/using-statement). -### The Try/Finally block +### The try/finally block -If your programming language does not support a construct like the `using` statement in C# or Visual Basic, or the `use` statement in F#, or if you prefer not to use it, you can call the implementation from the `finally` block of a `try`/`finally` statement. The following example replaces the `using` block in the previous example with a `try`/`finally` block. +If you prefer not to use a `using` statement or declaration, you can call from the `finally` block of a `try`/`finally` statement. The following example replaces the `using` block in the previous example with a `try`/`finally` block. :::code language="csharp" source="~/snippets/csharp/System/IDisposable/Overview/calling2.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/IDisposable/Overview/calling2.fs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System/IDisposable/Overview/calling2.vb" id="Snippet2"::: -For more information about the `try`/`finally` pattern, see [Try...Catch...Finally Statement](/dotnet/visual-basic/language-reference/statements/try-catch-finally-statement), [try-finally](/dotnet/csharp/language-reference/keywords/try-finally), [try...finally Expression](/dotnet/fsharp/language-reference/exception-handling/the-try-finally-expression), or [try-finally Statement](/cpp/c-language/try-finally-statement-c). +For more information about the `try`/`finally` pattern, see [try-finally (C#)](/dotnet/csharp/language-reference/keywords/try-finally), [Try...Catch...Finally statement (Visual Basic)](/dotnet/visual-basic/language-reference/statements/try-catch-finally-statement), or [try...finally expression (F#)](/dotnet/fsharp/language-reference/exception-handling/the-try-finally-expression). ## Implement IDisposable You should implement if your type uses unmanaged resources directly or if you wish to use disposable resources yourself. The consumers of your type can call your implementation to free resources when the instance is no longer needed. To handle cases in which they fail to call , you should either use a class derived from to wrap the unmanaged resources, or you should override the method for a reference type. In either case, you use the method to perform whatever cleanup is necessary after using the unmanaged resources, such as freeing, releasing, or resetting the unmanaged resources. For more information about implementing , see [the Dispose(bool) method overload](/dotnet/standard/garbage-collection/implementing-dispose.md#the-disposebool-method-overload). > [!IMPORTANT] -> If you are defining a base class that uses unmanaged resources and that either has, or is likely to have, subclasses that should be disposed, you should implement the method and provide a second overload of `Dispose`, as discussed in the next section. +> If you're defining a base class that uses unmanaged resources and that either has, or is likely to have, subclasses that should be disposed, you should implement the method and provide a second overload of `Dispose`, as discussed in the next section. ## IDisposable and the inheritance hierarchy @@ -192,38 +189,34 @@ The following code fragment reflects the dispose pattern for derived classes. It [!WARNING] -> If you are using a class that implements the interface, you should call its implementation when you are finished using the class. For more information, see the "Using an object that implements IDisposable" section in the topic. - When implementing this method, ensure that all held resources are freed by propagating the call through the containment hierarchy. For example, if an object A allocates an object B, and object B allocates an object C, then A's implementation must call on B, which must in turn call on C. +Use this method to close or release unmanaged resources such as files, streams, and handles held by an instance of the class that implements this interface. By convention, this method is used for all tasks associated with freeing resources held by an object, or preparing an object for reuse. -> [!IMPORTANT] -> The C++ compiler supports deterministic disposal of resources and doesn't allow direct implementation of the method. +> [!WARNING] +> If you're using a class that implements the interface, you should call its implementation when you're finished using the class. For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable). - An object must also call the method of its base class if the base class implements . For more information about implementing on a base class and its subclasses, see the "IDisposable and the inheritance hierarchy" section in the topic. +When implementing this method, ensure that all held resources are freed by propagating the call through the containment hierarchy. For example, if an object A allocates an object B, and object B allocates an object C, then A's implementation must call on B, which must in turn call on C. - If an object's method is called more than once, the object must ignore all calls after the first one. The object must not throw an exception if its method is called multiple times. Instance methods other than can throw an when resources are already disposed. +An object must also call the method of its base class if the base class implements . For more information about implementing on a base class and its subclasses, see [IDisposable and the inheritance hierarchy](xref:System.IDisposable#idisposable-and-the-inheritance-hierarchy). - Users might expect a resource type to use a particular convention to denote an allocated state versus a freed state. An example of this is stream classes, which are traditionally thought of as open or closed. The implementer of a class that has such a convention might choose to implement a public method with a customized name, such as `Close`, that calls the method. +If an object's method is called more than once, the object must ignore all calls after the first one. The object must not throw an exception if its method is called multiple times. Instance methods other than can throw an when resources are already disposed. - Because the method must be called explicitly, there is always a danger that the unmanaged resources will not be released, because the consumer of an object fails to call its method. There are two ways to avoid this: +Users might expect a resource type to use a particular convention to denote an allocated state versus a freed state. An example of this is stream classes, which are traditionally thought of as open or closed. The implementer of a class that has such a convention might choose to implement a public method with a customized name, such as `Close`, that calls the method. -- Wrap the managed resource in an object derived from . Your implementation then calls the method of the instances. For more information, see "The SafeHandle alternative" section in the topic. +Because the method must be called explicitly, there is always a danger that the unmanaged resources will not be released, because the consumer of an object fails to call its method. There are two ways to avoid this: +- Wrap the managed resource in an object derived from . Your implementation then calls the method of the instances. For more information, see [The SafeHandle alternative](xref:System.Object.Finalize#the-safehandle-alternative). - Implement a finalizer to free resources when is not called. By default, the garbage collector automatically calls an object's finalizer before reclaiming its memory. However, if the method has been called, it is typically unnecessary for the garbage collector to call the disposed object's finalizer. To prevent automatic finalization, implementations can call the method. - When you use an object that accesses unmanaged resources, such as a , a good practice is to create the instance with a `using` statement. The `using` statement automatically closes the stream and calls on the object when the code that is using it has completed. For an example, see the class. - - +When you use an object that accesses unmanaged resources, such as a , a good practice is to create the instance with a `using` statement. The `using` statement automatically closes the stream and calls on the object when the code that is using it has completed. For an example, see the class. ## Examples - The following example shows how you can implement the method. - :::code language="csharp" source="~/snippets/csharp/System/IDisposable/Overview/idisposabledispose.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/IDisposable/Overview/idisposabledispose.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/IDisposable/Overview/idisposabledispose.vb" id="Snippet1"::: +The following example shows how you can implement the method. + +:::code language="csharp" source="~/snippets/csharp/System/IDisposable/Overview/idisposabledispose.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/IDisposable/Overview/idisposabledispose.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/System/IDisposable/Overview/idisposabledispose.vb" id="Snippet1"::: ]]>