From fd8448fa1798b7291952a3f7276a32df153496c2 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 18 Jun 2026 09:23:48 -0700 Subject: [PATCH 1/3] Improve IDisposable note (#12752) --- .../BlockingCollection`1.xml | 22 +++--- .../AggregateCatalog.xml | 2 +- .../AggregateExportProvider.xml | 2 +- .../ApplicationCatalog.xml | 2 +- .../AssemblyCatalog.xml | 2 +- .../AtomicComposition.xml | 2 +- .../CatalogExportProvider.xml | 2 +- .../ComposablePartExportProvider.xml | 2 +- .../CompositionContainer.xml | 2 +- .../CompositionScopeDefinition.xml | 2 +- .../CompositionService.xml | 2 +- .../DirectoryCatalog.xml | 7 +- .../FilteredCatalog.xml | 2 +- .../ImportEngine.xml | 2 +- .../TypeCatalog.xml | 2 +- .../ComposablePartCatalog.xml | 2 +- .../ExportLifetimeContext`1.xml | 2 +- .../DelimitedListTraceListener.xml | 16 ++-- xml/System.Diagnostics/EventLogEntry.xml | 4 +- xml/System.Diagnostics/Process.xml | 78 +++++++++---------- xml/System.Diagnostics/ProcessModule.xml | 6 +- xml/System.Diagnostics/ProcessThread.xml | 4 +- .../TextWriterTraceListener.xml | 4 +- .../IsolatedStorageFile.xml | 24 +++--- .../IsolatedStorageFileStream.xml | 2 +- xml/System.IO/BinaryReader.xml | 8 +- xml/System.IO/BinaryWriter.xml | 4 +- xml/System.IO/BufferedStream.xml | 4 +- xml/System.IO/FileStream.xml | 48 ++++++------ xml/System.IO/Stream.xml | 2 +- xml/System.IO/StreamReader.xml | 26 +++---- xml/System.IO/StreamWriter.xml | 20 +++-- xml/System.IO/TextReader.xml | 6 +- xml/System.IO/TextWriter.xml | 6 +- xml/System.Resources/ResourceReader.xml | 2 +- xml/System.Resources/ResourceSet.xml | 2 +- xml/System.Resources/ResourceWriter.xml | 4 +- xml/System.Runtime/MemoryFailPoint.xml | 8 +- .../X509Certificate.xml | 22 +++--- .../X509Chain.xml | 2 +- .../X509Store.xml | 6 +- .../RNGCryptoServiceProvider.xml | 4 +- .../SHA1CryptoServiceProvider.xml | 2 +- .../WindowsIdentity.xml | 24 +++--- xml/System.Security/SecureString.xml | 2 +- xml/System.Threading/AutoResetEvent.xml | 2 +- .../CancellationTokenSource.xml | 4 +- xml/System.Threading/Mutex.xml | 7 +- xml/System.Threading/ReaderWriterLockSlim.xml | 31 ++++---- xml/System.Threading/WaitHandle.xml | 12 +-- xml/System.Timers/Timer.xml | 53 +++++-------- xml/System/IDisposable.xml | 59 +++++++------- 52 files changed, 259 insertions(+), 308 deletions(-) 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"::: ]]> From 7faab99c0291381f2e3ea48646286dc614e705f1 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Thu, 18 Jun 2026 09:24:57 -0700 Subject: [PATCH 2/3] Fix DeflateStream.Flush() summary: method is not a no-op when compressing (#12756) --- xml/System.IO.Compression/DeflateStream.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/xml/System.IO.Compression/DeflateStream.xml b/xml/System.IO.Compression/DeflateStream.xml index ed1fc0d3daa..8753696a584 100644 --- a/xml/System.IO.Compression/DeflateStream.xml +++ b/xml/System.IO.Compression/DeflateStream.xml @@ -1102,11 +1102,11 @@ The end write call is invalid. - The current implementation of this method has no functionality. + Flushes the internal buffer to the underlying stream. . +If the compression mode is set to , this method flushes the internal buffer to the underlying stream. If the compression mode is set to , this method has no effect. ]]> From cc11708ff73fc1d37ee271bce80476553221679a Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 19 Jun 2026 09:12:04 -0700 Subject: [PATCH 3/3] Fix up list indentation (#12758) --- xml/System.CodeDom/CodeTypeReference.xml | 16 +- .../BlockingCollection`1.xml | 2 +- .../DisplayColumnAttribute.xml | 6 +- .../DisplayFormatAttribute.xml | 6 +- .../RangeAttribute.xml | 6 +- .../RequiredAttribute.xml | 4 +- xml/System.ComponentModel/BindingList`1.xml | 33 +-- .../ConfigurationCollectionAttribute.xml | 14 +- .../ConfigurationPropertyAttribute.xml | 18 +- .../ConfigurationSection.xml | 18 +- xml/System.Diagnostics.Contracts/Contract.xml | 25 +- xml/System.Diagnostics/Activity.xml | 12 +- .../ActivityTagsCollection.xml | 11 +- .../ConditionalAttribute.xml | 18 +- .../DirectorySearcher.xml | 4 +- xml/System.Globalization/CultureInfo.xml | 4 +- xml/System.IO.Packaging/Package.xml | 8 +- xml/System.Linq.Expressions/Expression.xml | 224 +++++++++--------- xml/System.Printing/PrintCapabilities.xml | 28 +-- .../ModuleResolveEventHandler.xml | 13 +- xml/System.Resources/ResourceReader.xml | 39 +-- xml/System.Resources/ResourceWriter.xml | 12 +- xml/System.Runtime.Caching/ChangeMonitor.xml | 28 +-- .../InternalsVisibleToAttribute.xml | 26 +- .../SEHException.xml | 8 +- .../RecognizedAudio.xml | 18 +- .../SemanticResultValue.xml | 16 +- .../SemanticValue.xml | 4 +- .../EventParameterType.xml | 15 +- .../FragmentState.xml | 13 +- .../SpeechEventInfo.xml | 47 ++-- .../TextFragment.xml | 66 +++--- .../TtsEngineAction.xml | 12 +- .../TtsEngineSsml.xml | 22 +- .../TtsEventId.xml | 13 +- xml/System.Text/Encoding.xml | 4 +- xml/System.Threading.Tasks/Task.xml | 12 +- xml/System.Threading/Thread.xml | 16 +- xml/System.Threading/ThreadPool.xml | 32 +-- xml/System.Xml.Schema/Extensions.xml | 88 +++---- xml/System.Xml.Xsl/XslCompiledTransform.xml | 2 +- xml/System.Xml/XmlWriter.xml | 22 +- xml/System/ArgumentNullException.xml | 2 +- xml/System/ArraySegment`1.xml | 6 +- xml/System/BitConverter.xml | 6 +- xml/System/Console.xml | 26 +- xml/System/DateTime.xml | 20 +- xml/System/DateTimeOffset.xml | 16 +- xml/System/EntryPointNotFoundException.xml | 54 ++--- xml/System/GC.xml | 4 +- xml/System/IEquatable`1.xml | 10 +- xml/System/IndexOutOfRangeException.xml | 96 ++++---- xml/System/IntPtr.xml | 6 +- xml/System/InvalidOperationException.xml | 8 +- xml/System/NullReferenceException.xml | 90 +++---- xml/System/Object.xml | 16 +- xml/System/ObjectDisposedException.xml | 6 +- xml/System/OutOfMemoryException.xml | 8 +- xml/System/OverflowException.xml | 12 +- xml/System/String.xml | 28 +-- xml/System/TimeSpan.xml | 2 +- xml/System/Tuple`2.xml | 12 +- xml/System/Tuple`3.xml | 6 +- xml/System/Tuple`4.xml | 6 +- xml/System/Tuple`5.xml | 6 +- xml/System/Tuple`6.xml | 6 +- xml/System/Tuple`7.xml | 6 +- xml/System/Type.xml | 26 +- xml/System/TypeInitializationException.xml | 4 +- 69 files changed, 694 insertions(+), 779 deletions(-) diff --git a/xml/System.CodeDom/CodeTypeReference.xml b/xml/System.CodeDom/CodeTypeReference.xml index c95abe2af2a..a51d414c504 100644 --- a/xml/System.CodeDom/CodeTypeReference.xml +++ b/xml/System.CodeDom/CodeTypeReference.xml @@ -555,27 +555,27 @@ System.Collections.Generic.Dictionary`2[[System.String], [System.Collections.Gen - The property for the parent returns the following: - ``` + ``` System.Collections.Generic.Dictionary`2 - ``` + ``` - The property for the first object in the collection returns the following: - ``` + ``` System.String - ``` + ``` - The property for the second object in the collection returns the following: - ``` + ``` System.Collections.Generic.List`1 - ``` + ``` - The property in the object for ``System.Collections.Generic.List`1`` returns the following: - ``` + ``` System.Int32 - ``` + ``` The type argument count should be used when parsing the associated values. The common practice is to remove the type argument count from the generated code, but the practice is compiler specific. It is important to note that the type argument count can be found within a nested type name, in which case it is followed by a plus sign ("+"). diff --git a/xml/System.Collections.Concurrent/BlockingCollection`1.xml b/xml/System.Collections.Concurrent/BlockingCollection`1.xml index 687e1deaeeb..1d410824ef0 100644 --- a/xml/System.Collections.Concurrent/BlockingCollection`1.xml +++ b/xml/System.Collections.Concurrent/BlockingCollection`1.xml @@ -862,7 +862,7 @@ Do not modify the underlying collection directly. Use [!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.ComponentModel.DataAnnotations/DisplayColumnAttribute.xml b/xml/System.ComponentModel.DataAnnotations/DisplayColumnAttribute.xml index 91f486f2e4b..ea4993b535c 100644 --- a/xml/System.ComponentModel.DataAnnotations/DisplayColumnAttribute.xml +++ b/xml/System.ComponentModel.DataAnnotations/DisplayColumnAttribute.xml @@ -68,11 +68,11 @@ - Applies the attribute to the `Address` metadata partial class to specify the following: - - The City column from the Address table (the parent table) is displayed as the foreign-key column in the CustomerAddress child table. + - The City column from the Address table (the parent table) is displayed as the foreign-key column in the CustomerAddress child table. - - The PostalCode column from the Address table (the parent table) is used for sorting the Address selection box in the CustomerAddress child table. + - The PostalCode column from the Address table (the parent table) is used for sorting the Address selection box in the CustomerAddress child table. - - The sort order is set to ascending. + - The sort order is set to ascending. The example applies the attribute to the `Customer` metadata partial class to specify that the LastName column in displayed as the foreign-key column for the CustomerAddress table. diff --git a/xml/System.ComponentModel.DataAnnotations/DisplayFormatAttribute.xml b/xml/System.ComponentModel.DataAnnotations/DisplayFormatAttribute.xml index 4b59d8642e0..3066257af81 100644 --- a/xml/System.ComponentModel.DataAnnotations/DisplayFormatAttribute.xml +++ b/xml/System.ComponentModel.DataAnnotations/DisplayFormatAttribute.xml @@ -60,9 +60,9 @@ The following example shows how to use the attribute to specify the following results: - - Display the text "[Null]" when a data field is empty. - - Display currency data in locale specific currency format. - - Display date information in short format (mm/dd/yy). This format also applies in edit mode. + - Display the text "[Null]" when a data field is empty. + - Display currency data in locale specific currency format. + - Display date information in short format (mm/dd/yy). This format also applies in edit mode. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.ComponentModel.DataAnnotations.DisplayFormatAttribute/CS/product.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.ComponentModel.DataAnnotations.DisplayFormatAttribute/VB/product.vb" id="Snippet1"::: diff --git a/xml/System.ComponentModel.DataAnnotations/RangeAttribute.xml b/xml/System.ComponentModel.DataAnnotations/RangeAttribute.xml index a389edbcc9d..e6306d20b55 100644 --- a/xml/System.ComponentModel.DataAnnotations/RangeAttribute.xml +++ b/xml/System.ComponentModel.DataAnnotations/RangeAttribute.xml @@ -59,11 +59,11 @@ - In the associated metadata class, it applies the attribute to obtain the following results: - - Apply the attribute to a data field of type integer. + - Apply the attribute to a data field of type integer. - - Apply the attribute to an integer data field and define a custom validation error message. + - Apply the attribute to an integer data field and define a custom validation error message. - - Apply the attribute to a `DateTime` data field and define a custom validation error message. + - Apply the attribute to a `DateTime` data field and define a custom validation error message. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.ComponentModel.DataAnnotations.RangeAttribute/CS/Product.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.ComponentModel.DataAnnotations.RangeAttribute/VB/Product.vb" id="Snippet1"::: diff --git a/xml/System.ComponentModel.DataAnnotations/RequiredAttribute.xml b/xml/System.ComponentModel.DataAnnotations/RequiredAttribute.xml index 665d7a9b3c3..3f5154f49d5 100644 --- a/xml/System.ComponentModel.DataAnnotations/RequiredAttribute.xml +++ b/xml/System.ComponentModel.DataAnnotations/RequiredAttribute.xml @@ -58,9 +58,9 @@ - In the associated metadata class, it applies the attribute, which specifies the following requirements: - - The Title data field cannot be empty. If validation fails, the code in the example throws a validation exception and displays an error message. The error message is specified at the time that the attribute is applied to the data field. + - The Title data field cannot be empty. If validation fails, the code in the example throws a validation exception and displays an error message. The error message is specified at the time that the attribute is applied to the data field. - - The MiddleName data field cannot be empty. If validation fails, the code in the example throws a validation exception and displays an error message. + - The MiddleName data field cannot be empty. If validation fails, the code in the example throws a validation exception and displays an error message. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.ComponentModel.DataAnnotations.RequiredAttribute/CS/Customer.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.ComponentModel.DataAnnotations.RequiredAttribute/VB/Customer.vb" id="Snippet1"::: diff --git a/xml/System.ComponentModel/BindingList`1.xml b/xml/System.ComponentModel/BindingList`1.xml index 6a2dbeece8a..024ff60a2c0 100644 --- a/xml/System.ComponentModel/BindingList`1.xml +++ b/xml/System.ComponentModel/BindingList`1.xml @@ -99,8 +99,6 @@ supports factory-created instances through the extensible method. (This same type of extensibility is also found in other classes, such as ) In addition, since this class implements the interface, it enables transactional commits or rollbacks of the new item through the and methods. - - ## Examples The following code example demonstrates binding to a component containing a business object. This is a complete example that contains a `Main` method. @@ -173,14 +171,12 @@ ## Remarks The following table shows initial property values for an instance of class. -|Property|Initial Value| -|--------------|-------------------| -||`true`| -||`true` if the list type has a parameterless constructor; otherwise, `false`.| -||`true`| -||`true`| - - +| Property | Initial Value | +|--------------------------------------------------------------------|---------------| +| | `true` | +| | `true` if the list type has a parameterless constructor; otherwise, `false`. | +| | `true` | +| | `true` | ## Examples The following code example demonstrates how to construct a new . For the complete example, see the class overview topic. @@ -302,8 +298,6 @@ For more information about supplying custom new item functionality, see the method. For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - ## Examples The following code example demonstrates how to handle the event. For the complete example, see the class overview topic. @@ -362,24 +356,21 @@ ## Remarks The method adds a new item to the collection represented by the property. To add a new item, the following logic is used: -1. The event is automatically raised. +1. The event is automatically raised. - This event can be programmatically handled to construct a new custom item. This is accomplished in the event handler by setting the property of the parameter to the new item. + This event can be programmatically handled to construct a new custom item. This is accomplished in the event handler by setting the property of the parameter to the new item. - Otherwise, the new item is automatically created through its public parameterless constructor. + Otherwise, the new item is automatically created through its public parameterless constructor. -2. The position of the new item is tracked, but it is not added to the list until one of the following conditions are met: +2. The position of the new item is tracked, but it is not added to the list until one of the following conditions are met: - - The item is explicitly committed by a call to . - - - The item is implicitly committed by some other operation that changed the contents of the list, such as an insertion or removal of an item. + - The item is explicitly committed by a call to . + - The item is implicitly committed by some other operation that changed the contents of the list, such as an insertion or removal of an item. In contrast, calling the method before the item is committed will cause the new item to be discarded. This method raises the event when the new item is committed. - - ## Examples The following code example demonstrates how to use the method. . For the complete example, see the class overview topic. diff --git a/xml/System.Configuration/ConfigurationCollectionAttribute.xml b/xml/System.Configuration/ConfigurationCollectionAttribute.xml index 2a8b3e2cd10..3262c2ea72e 100644 --- a/xml/System.Configuration/ConfigurationCollectionAttribute.xml +++ b/xml/System.Configuration/ConfigurationCollectionAttribute.xml @@ -51,21 +51,21 @@ - The attributes that instruct .NET how to create instances of the custom configuration element properties. These types include: - - + - - - + - - The attributes that instruct .NET how to validate the custom configuration element properties. These types include: - - + - - - + - - - + - - - + - - - + - ## Examples The following example shows how to use the . diff --git a/xml/System.Configuration/ConfigurationPropertyAttribute.xml b/xml/System.Configuration/ConfigurationPropertyAttribute.xml index 1ae43cd7715..f6351f8822a 100644 --- a/xml/System.Configuration/ConfigurationPropertyAttribute.xml +++ b/xml/System.Configuration/ConfigurationPropertyAttribute.xml @@ -49,23 +49,23 @@ The .NET configuration system provides attribute types that you can use during the creation of custom configuration elements. There are two kinds of attribute types: -1. The types instructing .NET how to instantiate the custom configuration-element properties. These types include: +1. The types instructing .NET how to instantiate the custom configuration-element properties. These types include: - - + - - - + - -2. The types instructing .NET how to validate the custom configuration-element properties. These types include: +2. The types instructing .NET how to validate the custom configuration-element properties. These types include: - - + - - - + - - - + - - - + - - - + - diff --git a/xml/System.Configuration/ConfigurationSection.xml b/xml/System.Configuration/ConfigurationSection.xml index 7e413864c15..a1aa5ead9ec 100644 --- a/xml/System.Configuration/ConfigurationSection.xml +++ b/xml/System.Configuration/ConfigurationSection.xml @@ -75,21 +75,19 @@ - Reading. You use or to read configuration information. Note that the user or process that reads must have the following permissions: - - Read permission on the configuration file at the current configuration hierarchy level. + - Read permission on the configuration file at the current configuration hierarchy level. + - Read permissions on all the parent configuration files. - - Read permissions on all the parent configuration files. + If your application needs read-only access to its own configuration, it is recommended you use the overloaded methods in the case of Web applications, or the method in the case of client applications. - If your application needs read-only access to its own configuration, it is recommended you use the overloaded methods in the case of Web applications, or the method in the case of client applications. - - These methods provide access to the cached configuration values for the current application, which has better performance than the class. + These methods provide access to the cached configuration values for the current application, which has better performance than the class. Note: If you use a static method that takes a parameter, the parameter must refer to the application in which the code is running; otherwise, the parameter is ignored and configuration information for the currently-running application is returned. - Writing. You use one of the methods to write configuration information. Note that the user or process that writes must have the following permissions: - - Write permission on the configuration file and directory at the current configuration hierarchy level. - - - Read permissions on all the configuration files. + - Write permission on the configuration file and directory at the current configuration hierarchy level. + - Read permissions on all the configuration files. @@ -129,8 +127,6 @@ Note: If you use a static method that takes a constructor, you need to define a custom section type first. For an example see the class overview. - - ## Examples The following example shows how to use the constructor. This example assumes that you have created a custom section class named `CustomSection`. For an example of such a class, see the class overview. @@ -235,8 +231,6 @@ Note: If you use a static method that takes a simply returns the object that represents the from which it is called. - - ## Examples The following example shows how to use the method. diff --git a/xml/System.Diagnostics.Contracts/Contract.xml b/xml/System.Diagnostics.Contracts/Contract.xml index f9167cef0c9..3f241803ac6 100644 --- a/xml/System.Diagnostics.Contracts/Contract.xml +++ b/xml/System.Diagnostics.Contracts/Contract.xml @@ -58,7 +58,7 @@ For tools and detailed instructions for using code contracts, see [Code Contracts](https://marketplace.visualstudio.com/items?itemName=RiSEResearchinSoftwareEngineering.CodeContractsforNET) on the Visual Studio Marketplace. > [!IMPORTANT] -> You must use a binary rewriter to insert run-time enforcement of contracts. Otherwise, contracts such as the method can only be tested statically and will not throw exceptions during run time if a contract is violated. You can download the binary rewriter CCRewrite from [Code Contracts](https://marketplace.visualstudio.com/items?itemName=RiSEResearchinSoftwareEngineering.CodeContractsforNET) on the Visual Studio Marketplace. CCRewrite comes with a Visual Studio add-in that enables you to activate run-time contract enforcement from the project **Properties** page. The binary rewriter and the Visual Studio add-in do not ship with Visual Studio 2010 or the Windows SDK. +> You must use a binary rewriter to insert run-time enforcement of contracts. Otherwise, contracts such as the method can only be tested statically and will not throw exceptions during run time if a contract is violated. You can download the binary rewriter CCRewrite from [Code Contracts](https://marketplace.visualstudio.com/items?itemName=RiSEResearchinSoftwareEngineering.CodeContractsforNET) on the Visual Studio Marketplace. CCRewrite comes with a Visual Studio add-in that enables you to activate run-time contract enforcement from the project **Properties** page. The binary rewriter and the Visual Studio add-in do not ship with Visual Studio 2010 or the Windows SDK. ]]> @@ -282,7 +282,7 @@ method. + At runtime, using this method is equivalent to using the method. ]]> @@ -354,7 +354,7 @@ ## Remarks If `userMessage` is not a constant string literal, the contract may not be understood by tools. - At run time, using this method is equivalent to using the method. + At runtime, using this method is equivalent to using the method. ]]> @@ -536,8 +536,6 @@ - You must use the binary rewriter (available at [Code Contracts](https://marketplace.visualstudio.com/items?itemName=RiSEResearchinSoftwareEngineering.CodeContractsforNET) on the Visual Studio Marketplace) for run-time enforcement of this postcondition. - - ## Examples The following example shows how to use the method to ensure that an expected value is returned. This code example is part of a larger example provided for the class. @@ -604,11 +602,8 @@ The `condition` parameter specifies a postcondition that is expected to be `true` when the enclosing method or property returns normally. - This method call must be at the beginning of a method or property, before any other code. - - This contract is exposed to clients; therefore, it must only reference members that are at least as visible as the enclosing method. - - You must use the binary rewriter (available at [Code Contracts](https://marketplace.visualstudio.com/items?itemName=RiSEResearchinSoftwareEngineering.CodeContractsforNET) on the Visual Studio Marketplace) for run-time enforcement of this postcondition. - - If `userMessage` is not a constant string literal, the contract may not be understood by tools. ]]> @@ -952,8 +947,6 @@ ## Remarks The `toExclusive` parameter is one more than the last integer to facilitate using the length of a range of integers starting at 0. For example, it would be set to 5 for integers 0 through 4. - - ## Examples The following example demonstrates how to use the method to determine whether an array has a null element. @@ -1241,8 +1234,6 @@ ## Remarks This method can be used only in the conditional expression for the contract. - - ## Examples The following example shows the use of the method to ensure that a count has been updated. This code example is part of a larger example provided for the class. @@ -1442,7 +1433,7 @@ ## Remarks > [!IMPORTANT] -> You must turn on run-time checking to use the method. If run-time checking is turned off, the process will be terminated. To obtain the tools for runtime checking, see [Code Contracts](https://marketplace.visualstudio.com/items?itemName=RiSEResearchinSoftwareEngineering.CodeContractsforNET) on the Visual Studio Marketplace. +> You must turn on run-time checking to use the method. If run-time checking is turned off, the process will be terminated. To obtain the tools for runtime checking, see [Code Contracts](https://marketplace.visualstudio.com/items?itemName=RiSEResearchinSoftwareEngineering.CodeContractsforNET) on the Visual Studio Marketplace. - This method call must be at the beginning of a method or property, before any other code. @@ -1517,10 +1508,10 @@ ## Remarks -- > [!IMPORTANT] - > You must turn on run-time checking to use the method. If run-time checking is turned off, the process will be terminated. To obtain the tools for runtime checking, see [Code Contracts](https://marketplace.visualstudio.com/items?itemName=RiSEResearchinSoftwareEngineering.CodeContractsforNET) on the Visual Studio Marketplace. +> [!IMPORTANT] +> You must turn on run-time checking to use the method. If run-time checking is turned off, the process will be terminated. To obtain the tools for run-time checking, see [Code Contracts](https://marketplace.visualstudio.com/items?itemName=RiSEResearchinSoftwareEngineering.CodeContractsforNET) on the Visual Studio Marketplace. - This method call must be at the beginning of a method or property, before any other code. +This method call must be at the beginning of a method or property, before any other code. - This contract is exposed to clients; therefore, it must only reference members that are at least as visible as the enclosing method. @@ -1585,8 +1576,6 @@ ## Remarks This method can be used only in the conditional expression for the contract. - - ## Examples The following example shows how to use the method to specify an expected return value. This code example is part of a larger example provided for the class. diff --git a/xml/System.Diagnostics/Activity.xml b/xml/System.Diagnostics/Activity.xml index ab0bb0a76be..e86fd24a6d5 100644 --- a/xml/System.Diagnostics/Activity.xml +++ b/xml/System.Diagnostics/Activity.xml @@ -1853,13 +1853,15 @@ When passing code value different than ActivityStatusCode.Error, the Activity.St ## Remarks - - If the input value is `null`: - - If the collection has any tag with the same key, then this tag will get removed from the collection. - - Otherwise, nothing will happen and the collection will not change. + + - If the collection has any tag with the same key, then this tag will get removed from the collection. + - Otherwise, nothing will happen and the collection will not change. + - If the input value is not `null`: - - If the collection has any tag with the same key, then the value mapped to this key will get updated with the new input value. - - Otherwise, the key and value will get added as a new tag to the collection. + + - If the collection has any tag with the same key, then the value mapped to this key will get updated with the new input value. + - Otherwise, the key and value will get added as a new tag to the collection. ]]> diff --git a/xml/System.Diagnostics/ActivityTagsCollection.xml b/xml/System.Diagnostics/ActivityTagsCollection.xml index c8f3a912510..d2ea348e8fc 100644 --- a/xml/System.Diagnostics/ActivityTagsCollection.xml +++ b/xml/System.Diagnostics/ActivityTagsCollection.xml @@ -55,12 +55,15 @@ This collection will be used with classes like and . This collection behaves as follows: + - The collection items will be ordered according to how they are added. - Don't allow duplication of items with the same key. - When using the indexer to store an item in the collection: - - If the item has a key that previously existed in the collection and the value is , the collection item matching the key will be removed from the collection. - - If the item has a key that previously existed in the collection and the value is not , the new item value will replace the old value stored in the collection. - - Otherwise, the item will be added to the collection. + + - If the item has a key that previously existed in the collection and the value is , the collection item matching the key will be removed from the collection. + - If the item has a key that previously existed in the collection and the value is not , the new item value will replace the old value stored in the collection. + - Otherwise, the item will be added to the collection. + - Add method will add a new item to the collection if an item doesn't already exist with the same key. Otherwise, it will throw an exception. To be added. @@ -481,7 +484,7 @@ This collection behaves as follows: The key of the value to get or set. Gets or sets a specified collection item. - + When setting a value to this indexer property, the following behavior is observed: - If the key previously existed in the collection and the value is , the collection item matching the key will get removed from the collection. - If the key previously existed in the collection and the value is not , the value will replace the old value stored in the collection. diff --git a/xml/System.Diagnostics/ConditionalAttribute.xml b/xml/System.Diagnostics/ConditionalAttribute.xml index a2548e676ff..a557f8aef41 100644 --- a/xml/System.Diagnostics/ConditionalAttribute.xml +++ b/xml/System.Diagnostics/ConditionalAttribute.xml @@ -75,23 +75,23 @@ - Use pragmas in the source code; for example, define the compilation variable as follows: - ```csharp + ```csharp #define DEBUG - ``` + ``` - ```vb + ```vb #Const DEBUG=True - ``` + ``` - To undefine the variable, use the following: + To undefine the variable, use the following: - ```csharp + ```csharp #undef DEBUG - ``` + ``` - ```vb + ```vb #Const DEBUG=False - ``` + ``` Compilers that comply with the Common Language Specification (CLS) are permitted to ignore . The C#, F#, Visual Basic, and C++ compilers support ; the JScript compiler does not support the attribute. diff --git a/xml/System.DirectoryServices/DirectorySearcher.xml b/xml/System.DirectoryServices/DirectorySearcher.xml index 5735df56fd7..390bee82ad6 100644 --- a/xml/System.DirectoryServices/DirectorySearcher.xml +++ b/xml/System.DirectoryServices/DirectorySearcher.xml @@ -1159,13 +1159,13 @@ SearchResultCollection res = src.FindAll(); - The following C# code shows how to enumerate the global catalog and pick the first child. - ```csharp + ```csharp DirectoryEntry entry = new DirectoryEntry("GC://forestname"); IEnumerator ie = entry.Children.GetEnumerator(); ie.MoveNext(); entry = (DirectoryEntry)ie.Current; DirectorySearcher search = new DirectorySearcher(entry); - ``` + ``` ]]> diff --git a/xml/System.Globalization/CultureInfo.xml b/xml/System.Globalization/CultureInfo.xml index 80035b007e6..eb76fa10f4b 100644 --- a/xml/System.Globalization/CultureInfo.xml +++ b/xml/System.Globalization/CultureInfo.xml @@ -2372,8 +2372,8 @@ Setting `predefinedOnly` to `true` will ensure a culture is created only if the - , which returns all custom cultures, such as those registered by the class. In versions of Windows before Windows 10, the value applies to all user-defined custom cultures. Starting with Windows 10, it applies to system cultures that lack complete cultural data and that do not have a unique local identifier, as indicated by the property value. As a result, code such as the following will return different results when run on Windows 10 and on an earlier version of Windows. - :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/DisplayName/getcultures3.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Globalization/CultureInfo/DisplayName/getcultures3.vb" id="Snippet2"::: + :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/DisplayName/getcultures3.cs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/System.Globalization/CultureInfo/DisplayName/getcultures3.vb" id="Snippet2"::: ## Examples The following code example displays several properties of the neutral cultures. diff --git a/xml/System.IO.Packaging/Package.xml b/xml/System.IO.Packaging/Package.xml index ad4a2a709d0..e52027aa309 100644 --- a/xml/System.IO.Packaging/Package.xml +++ b/xml/System.IO.Packaging/Package.xml @@ -70,13 +70,13 @@ - A package-level relationship (created by the method) relates a to either: - - A target part in the package. - - A target resource outside the package. + - A target part in the package. + - A target resource outside the package. - A part-level relationship (created by the method) relates a source to either: - - Another target part in the package. - - A target resource outside the package. + - Another target part in the package. + - A target resource outside the package. The relationship's source or source is considered the "owner" of the relationship. When the source object is deleted, all the relationships owned by the source object are also deleted. The process of creating or deleting a relationship does not physically change either the source or target objects in any way. diff --git a/xml/System.Linq.Expressions/Expression.xml b/xml/System.Linq.Expressions/Expression.xml index afb05ada36c..1f672037282 100644 --- a/xml/System.Linq.Expressions/Expression.xml +++ b/xml/System.Linq.Expressions/Expression.xml @@ -875,9 +875,9 @@ If the implementing method is `null`: - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -971,9 +971,9 @@ If the implementing method is `null`: - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -1070,9 +1070,9 @@ If the implementing method is `null`: - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -1174,9 +1174,9 @@ If the implementing method is `null`: - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -1276,13 +1276,13 @@ If the implementing method is `null`: - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable, and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable, and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: -- `left`.Type and `right`.Type are the same Boolean type. +- `left`.Type and `right`.Type are the same Boolean type. - If `left`.Type and `right`.Type are non-nullable, the node is not lifted. The type of the node is the result type of the predefined conditional `AND` operator. @@ -1389,13 +1389,13 @@ If the implementing method is `null`: - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable, and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable, and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: -- `left`.Type and `right`.Type are the same Boolean type. +- `left`.Type and `right`.Type are the same Boolean type. - If `left`.Type and `right`.Type are non-nullable, the node is not lifted. The type of the node is the result type of the predefined conditional `AND` operator. @@ -5234,9 +5234,9 @@ If the implementing method is `null`: - Otherwise: - - If both `expression`.Type and `type` represent numeric or Boolean types, or nullable or non-nullable enumeration types, the implementing method is `null`. + - If both `expression`.Type and `type` represent numeric or Boolean types, or nullable or non-nullable enumeration types, the implementing method is `null`. - - If either `expression`.Type or `type` is a reference type and an explicit boxing, unboxing, or reference conversion exists from `expression`.Type to `type`, the implementing method is `null`. + - If either `expression`.Type or `type` is a reference type and an explicit boxing, unboxing, or reference conversion exists from `expression`.Type to `type`, the implementing method is `null`. #### Lifted versus Non-Lifted If the implementing method is not `null`: @@ -5336,9 +5336,9 @@ If the implementing method is `null`: - Otherwise: - - If both `expression`.Type and `type` represent numeric or Boolean types, or nullable or non-nullable enumeration types, the implementing method is `null`. + - If both `expression`.Type and `type` represent numeric or Boolean types, or nullable or non-nullable enumeration types, the implementing method is `null`. - - If either `expression`.Type or `type` is a reference type and an explicit boxing, unboxing, or reference conversion exists from `expression`.Type to `type`, the implementing method is `null`. + - If either `expression`.Type or `type` is a reference type and an explicit boxing, unboxing, or reference conversion exists from `expression`.Type to `type`, the implementing method is `null`. #### Lifted versus Non-Lifted If the implementing method is not `null`: @@ -5445,9 +5445,9 @@ If the implementing method is `null`: - Otherwise: - - If both `expression`.Type and `type` represent numeric or Boolean types, or nullable or non-nullable enumeration types, the implementing method is `null`. + - If both `expression`.Type and `type` represent numeric or Boolean types, or nullable or non-nullable enumeration types, the implementing method is `null`. - - If either `expression`.Type or `type` is a reference type and an explicit boxing, unboxing, or reference conversion exists from `expression`.Type to `type`, the implementing method is `null`. + - If either `expression`.Type or `type` is a reference type and an explicit boxing, unboxing, or reference conversion exists from `expression`.Type to `type`, the implementing method is `null`. #### Lifted versus Non-Lifted If the implementing method is not `null`: @@ -5539,9 +5539,9 @@ If the implementing method is `null`: - Otherwise: - - If both `expression`.Type and `type` represent numeric or Boolean types, or nullable or non-nullable enumeration types, the implementing method is `null`. + - If both `expression`.Type and `type` represent numeric or Boolean types, or nullable or non-nullable enumeration types, the implementing method is `null`. - - If either `expression`.Type or `type` is a reference type and an explicit boxing, unboxing, or reference conversion exists from `expression`.Type to `type`, the implementing method is `null`. + - If either `expression`.Type or `type` is a reference type and an explicit boxing, unboxing, or reference conversion exists from `expression`.Type to `type`, the implementing method is `null`. #### Lifted versus Non-Lifted If the implementing method is not `null`: @@ -5899,9 +5899,9 @@ If the implementing method is `null`: - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -6003,9 +6003,9 @@ If the implementing method is `null`: - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -6915,9 +6915,9 @@ If the implementing method is `null`: - If the following two conditions are satisfied, the node is lifted and the type of the node is : - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is . + - The return type of the implementing method is . If the implementing method is `null`: @@ -7020,9 +7020,9 @@ If the implementing method is `null`: - If the following two conditions are satisfied, the node is lifted; also, the type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is . + - The return type of the implementing method is . If the implementing method is `null`: @@ -7119,9 +7119,9 @@ If the implementing method is `null`: - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -7223,9 +7223,9 @@ If the implementing method is `null`: - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -8172,9 +8172,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is : - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is . + - The return type of the implementing method is . If the implementing method is `null`: @@ -8279,9 +8279,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted; also, the type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is . + - The return type of the implementing method is . If the implementing method is `null`: @@ -8378,9 +8378,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is : - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is . + - The return type of the implementing method is . If the implementing method is `null`: @@ -8485,9 +8485,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted; also, the type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is . + - The return type of the implementing method is . If the implementing method is `null`: @@ -10945,9 +10945,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -11041,9 +11041,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -11322,9 +11322,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is : - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is . + - The return type of the implementing method is . If the implementing method is `null`: @@ -11429,9 +11429,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted; also, the type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is . + - The return type of the implementing method is . If the implementing method is `null`: @@ -11528,9 +11528,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is : - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is . + - The return type of the implementing method is . If the implementing method is `null`: @@ -11635,9 +11635,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted; also, the type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is . + - The return type of the implementing method is . If the implementing method is `null`: @@ -14271,9 +14271,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -14367,9 +14367,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -14648,9 +14648,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -14752,9 +14752,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -15215,9 +15215,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -15311,9 +15311,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -15406,9 +15406,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. + - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. @@ -15502,9 +15502,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. + - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. @@ -15597,9 +15597,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. + - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. @@ -15685,9 +15685,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. + - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. @@ -16698,9 +16698,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `expression`.Type is a nullable value type and the corresponding non-nullable type is equal to the argument type of the implementing method. + - `expression`.Type is a nullable value type and the corresponding non-nullable type is equal to the argument type of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. @@ -16794,9 +16794,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. + - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. @@ -16893,9 +16893,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is : - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is . + - The return type of the implementing method is . If the implementing method is `null`: @@ -16992,9 +16992,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted; also, the type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is . + - The return type of the implementing method is . If the implementing method is `null`: @@ -17203,9 +17203,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -17307,9 +17307,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -17591,13 +17591,13 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable, and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable, and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: -- `left`.Type and `right`.Type are the same Boolean type. +- `left`.Type and `right`.Type are the same Boolean type. - If `left`.Type and `right`.Type are non-nullable, the node is not lifted. The type of the node is the result type of the predefined conditional `OR` operator. @@ -17704,13 +17704,13 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable, and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable, and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: -- `left`.Type and `right`.Type are the same Boolean type. +- `left`.Type and `right`.Type are the same Boolean type. - If `left`.Type and `right`.Type are non-nullable, the node is not lifted. The type of the node is the result type of the predefined conditional `OR` operator. @@ -18157,9 +18157,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. ]]> @@ -18250,9 +18250,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. ]]> @@ -19939,9 +19939,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -20035,9 +20035,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -20425,9 +20425,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -20529,9 +20529,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -20992,9 +20992,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -21088,9 +21088,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`: @@ -22787,9 +22787,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. + - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. @@ -22875,9 +22875,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. + - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. - - The return type of the implementing method is a non-nullable value type. + - The return type of the implementing method is a non-nullable value type. If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. diff --git a/xml/System.Printing/PrintCapabilities.xml b/xml/System.Printing/PrintCapabilities.xml index 29ae0cc927c..58d7b95832f 100644 --- a/xml/System.Printing/PrintCapabilities.xml +++ b/xml/System.Printing/PrintCapabilities.xml @@ -36,12 +36,10 @@ **Note** When the object is created with the constructor that takes a PrintCapabilities document (as a ) parameter, that entire document is stored in a non-public field in the object, including the XML elements within it that express less common features that are not represented by any of the public properties of the class. In fact, if the driver that produced the PrintCapabilities document is using a private extension of the [Print Schema](https://learn.microsoft.com/windows/win32/printdocs/printschema), that privately defined markup is also stored as part of the non-public PrintCapabilities document. > [!CAUTION] -> Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. +> Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. If you want to print from a Windows Forms application, see the namespace. - - ## Examples The following example shows how to determine the capabilities of a specific printer and how to configure a print job to take advantage of them. @@ -131,8 +129,6 @@ This property corresponds to the [Print Schema](https://learn.microsoft.com/windows/win32/printdocs/printschema)'s `DocumentCollate` keyword, not the `JobCollateAllDocuments` keyword. - - ## Examples The following example shows how to use this property to determine the capabilities of a specific printer and how to configure a print job to take advantage of them. @@ -214,8 +210,6 @@ This property corresponds to the [Print Schema](https://learn.microsoft.com/windows/win32/printdocs/printschema)'s `JobDuplexAllDocumentsContiguously` keyword, not the `DocumentDuplex` keyword. - - ## Examples The following example shows how to use this property to determine the capabilities of a specific printer and how to configure a print job to take advantage of them. @@ -558,8 +552,6 @@ This property corresponds to the [Print Schema](https://learn.microsoft.com/windows/win32/printdocs/printschema)'s `PageMediaSize` keyword. - - ## Examples The following code example shows how to search for a particular value in the . @@ -726,8 +718,6 @@ foreach (PageMediaSize mediaSize in pc.PageMediaSizeCapability) This property corresponds to the [Print Schema](https://learn.microsoft.com/windows/win32/printdocs/printschema)'s `PageResolution` keyword. - - ## Examples The following code example shows how to search for a particular value in the . @@ -781,21 +771,21 @@ foreach (PageResolution pageRes in pc.PageResolutionCapability) - In all other cases, the property's behavior is as follows. - The property of the property's object is the smallest of the following values. + The property of the property's object is the smallest of the following values. - - The **MinValue** property of the `PageScalingScaleWidth` datatype that provides the value of the **Custom** option's **ScaleWidth** `ScoredProperty`. + - The **MinValue** property of the `PageScalingScaleWidth` datatype that provides the value of the **Custom** option's **ScaleWidth** `ScoredProperty`. - - The **MinValue** property of the `PageScalingScaleHeight` datatype that provides the value of the **Custom** option's **ScaleHeight** `ScoredProperty`. + - The **MinValue** property of the `PageScalingScaleHeight` datatype that provides the value of the **Custom** option's **ScaleHeight** `ScoredProperty`. - - The **MinValue** property of the `PageScalingScale` datatype that provides the value of the **CustomSquare** option's **Scale** `ScoredProperty`. + - The **MinValue** property of the `PageScalingScale` datatype that provides the value of the **CustomSquare** option's **Scale** `ScoredProperty`. - The property of the property's object is the largest of the following values. + The property of the property's object is the largest of the following values. - - The **MaxValue** property of the `PageScalingScaleWidth` datatype that provides the value of the **Custom** option's **ScaleWidth** `ScoredProperty`. + - The **MaxValue** property of the `PageScalingScaleWidth` datatype that provides the value of the **Custom** option's **ScaleWidth** `ScoredProperty`. - - The **MaxValue** property of the `PageScalingScaleHeight` datatype that provides the value of the **Custom** option's **ScaleHeight** `ScoredProperty`. + - The **MaxValue** property of the `PageScalingScaleHeight` datatype that provides the value of the **Custom** option's **ScaleHeight** `ScoredProperty`. - - The **MaxValue** property of the `PageScalingScale` datatype that provides the value of the **CustomSquare** option's **Scale** `ScoredProperty`. + - The **MaxValue** property of the `PageScalingScale` datatype that provides the value of the **CustomSquare** option's **Scale** `ScoredProperty`. ]]> diff --git a/xml/System.Reflection/ModuleResolveEventHandler.xml b/xml/System.Reflection/ModuleResolveEventHandler.xml index 6bff7a3d96a..037663788bc 100644 --- a/xml/System.Reflection/ModuleResolveEventHandler.xml +++ b/xml/System.Reflection/ModuleResolveEventHandler.xml @@ -66,20 +66,21 @@ To compile and run the example: 1. Compile Server1 using the following command: - ```console - csc /out:subfolder\Server1.netmodule /t:module Server1.cs - ``` + ```console + csc /out:subfolder\Server1.netmodule /t:module Server1.cs + ``` 1. Compile MySample using the following command: - ```console - csc /out:MySample.exe /t:exe /addmodule:subfolder\Server1.netmodule MySample.cs - ``` + ```console + csc /out:MySample.exe /t:exe /addmodule:subfolder\Server1.netmodule MySample.cs + ``` 1. Run MySample.exe. > [!NOTE] > The module file Server1.netmodule must be in a subdirectory named "subfolder" for this example to work properly. + ]]> diff --git a/xml/System.Resources/ResourceReader.xml b/xml/System.Resources/ResourceReader.xml index 05516f9fcd0..185f5787952 100644 --- a/xml/System.Resources/ResourceReader.xml +++ b/xml/System.Resources/ResourceReader.xml @@ -182,9 +182,9 @@ The following example illustrates how to use this approach to retrieve resources The source code file is named CreateResources.cs. You can compile it in C# by using the following command: - ``` - csc CreateResources.cs /r:library.dll - ``` + ``` + csc CreateResources.cs /r:library.dll + ``` 2. Compile and run the following code to enumerate the resources in the ContactResources.resources file. @@ -590,17 +590,17 @@ Label11="Mobile Phone:" The implementation of the property by the class can throw the following exceptions: -- +- - The assembly that contains the type to which the data belongs cannot be found. + The assembly that contains the type to which the data belongs cannot be found. -- +- - The data is not in the expected format. + The data is not in the expected format. -- +- - The type to which the data belongs cannot be found. + The type to which the data belongs cannot be found. You can handle the exception by calling the method to retrieve information about the data type and the byte array assigned to the named resource. For more information, see the "Retrieving Resources by Name with GetResourceData" section in the class topic. @@ -696,23 +696,24 @@ Label11="Mobile Phone:" method retrieves the value of a named resource as a byte array. It is typically used when the property throws an exception when it tries to retrieve the value of a resource. - `resourceType` is a string that represents the data type of the resource. It can be any of the following values: +The method retrieves the value of a named resource as a byte array. It is typically used when the property throws an exception when it tries to retrieve the value of a resource. - - The string representation of a `ResourceTypeCode` enumeration member that indicates the data type of the resource. `ResourceTypeCode` is a private enumeration that is used by Resgen.exe to indicate that a special binary format is used to store one of 19 common data types. These include the .NET primitive data types (, , , , , , , , , , , , ), as well as , , and . In addition, the `ResourceTypeCode` enumeration includes the values shown in the following table. +`resourceType` is a string that represents the data type of the resource. It can be any of the following values: - |ResourceTypeCode value|Description| - |----------------------------|-----------------| - |`ResourceTypeCode.ByteArray`|The data is a byte array. This data type commonly results from the call to the method.| - |`ResourceTypeCode.Null`|The data is a null reference. This data type commonly results from the call to the method with an object whose value is `null`.| - |`ResourceTypeCode.Stream`|The data is stored in a stream. This data type commonly results from the call to the or method.| +- The string representation of a `ResourceTypeCode` enumeration member that indicates the data type of the resource. `ResourceTypeCode` is a private enumeration that is used by Resgen.exe to indicate that a special binary format is used to store one of 19 common data types. These include the .NET primitive data types (, , , , , , , , , , , , ), as well as , , and . In addition, the `ResourceTypeCode` enumeration includes the values shown in the following table. - Assuming that `resourceData` has not been corrupted, it can usually be converted from a byte array back to its original value by calling a or method. + |ResourceTypeCode value|Description| + |----------------------------|-----------------| + |`ResourceTypeCode.ByteArray`|The data is a byte array. This data type commonly results from the call to the method.| + |`ResourceTypeCode.Null`|The data is a null reference. This data type commonly results from the call to the method with an object whose value is `null`.| + |`ResourceTypeCode.Stream`|The data is stored in a stream. This data type commonly results from the call to the or method.| + + Assuming that `resourceData` has not been corrupted, it can usually be converted from a byte array back to its original value by calling a or method. - A string that contains the fully qualified name of the type whose serialized data is assigned to the `resourceData` argument (for example, `System.String`). In addition, for types that are not part of the .NET class library, the string includes the name, version, culture, and public key of the assembly that contains the type. For example, the following string indicates that the serialized data represents an instance of the `Person` type in the `Extensions` namespace, which is found in version 1.0 of an assembly named Utility that has no public key and no designated culture. - `Extensions.Person, Utility, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null` + `Extensions.Person, Utility, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null` - The string used to describe the data type in the method call. diff --git a/xml/System.Resources/ResourceWriter.xml b/xml/System.Resources/ResourceWriter.xml index 49fbb8d54cc..006d129b3b8 100644 --- a/xml/System.Resources/ResourceWriter.xml +++ b/xml/System.Resources/ResourceWriter.xml @@ -696,15 +696,15 @@ - The string representation of a `ResourceTypeCode` enumeration member that indicates the data type of the resource. `ResourceTypeCode` is a private enumeration that is used by [Resgen.exe](/dotnet/framework/tools/resgen-exe-resource-file-generator) to indicate that a special binary format is used to store one of 19 common data types. These include the .NET primitive data types (, , , , , , , , , , , , ), as well as , , and . In addition, the `ResourceTypeCode` enumeration includes the values shown in the following table. - |`ResourceTypeCode` value|Description| - |------------------------------|-----------------| - |`ResourceTypeCode.ByteArray`|The data is a byte array.| - |`ResourceTypeCode.Null`|The data is a null reference.| - |`ResourceTypeCode.Stream`|The data is stored in a stream.| + |`ResourceTypeCode` value|Description| + |------------------------------|-----------------| + |`ResourceTypeCode.ByteArray`|The data is a byte array.| + |`ResourceTypeCode.Null`|The data is a null reference.| + |`ResourceTypeCode.Stream`|The data is stored in a stream.| - A string that contains the fully qualified name of the type whose binary data is assigned to the `serializedData` argument (for example, `System.String`). In addition, for types that are not part of the .NET class library, the string includes the name, version, culture, and public key of the assembly that contains the type. For example, the following string indicates that the serialized data represents an instance of the `Person` type in the `Extensions` namespace, which is found in version 1.0 of an assembly named Utility that has no public key and no designated culture. - `Extensions.Person, Utility, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null` + `Extensions.Person, Utility, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null` A parallel method for reading resource data written with the method is . diff --git a/xml/System.Runtime.Caching/ChangeMonitor.xml b/xml/System.Runtime.Caching/ChangeMonitor.xml index 634237cd932..199d56f80bd 100644 --- a/xml/System.Runtime.Caching/ChangeMonitor.xml +++ b/xml/System.Runtime.Caching/ChangeMonitor.xml @@ -40,10 +40,10 @@ .NET includes the following classes that derive from class: -- -- -- -- +- +- +- +- Each of these classes works with different types of dependencies. For example, the derived class monitors changes to a cache for file system data (files and folders) that the cache item depends on. @@ -71,21 +71,21 @@ - The method overload must be called to dispose of the instance. The rules for calling Dispose are as follows: - - Before an item is inserted into the cache, it is the responsibility of caller to dispose of a instance. + - Before an item is inserted into the cache, it is the responsibility of caller to dispose of a instance. - - Once cache item and the instances that are associated with it are passed to a cache, the cache implementer must make sure that the method is called, even if the insert fails. + - Once cache item and the instances that are associated with it are passed to a cache, the cache implementer must make sure that the method is called, even if the insert fails. - - After an item and its associated instances are passed to a cache, the caller must not dispose the dependency because when the method is called, the call is treated as if the dependency has changed. As a result, the method is automatically invoked. + - After an item and its associated instances are passed to a cache, the caller must not dispose the dependency because when the method is called, the call is treated as if the dependency has changed. As a result, the method is automatically invoked. - Taking these rules into consideration, the method must be called in one of the following ways: - - Users must call the method overload if they decide not to insert the derived change-monitor instance into a cache. + - Users must call the method overload if they decide not to insert the derived change-monitor instance into a cache. - - If the implementation tries to insert the change-monitor instance into an object cache but the insertion fails, the cache implementation is responsible for calling the overload. When the insertion attempt causes an exception, the cache implementation must dispose of any associated dependencies. + - If the implementation tries to insert the change-monitor instance into an object cache but the insertion fails, the cache implementation is responsible for calling the overload. When the insertion attempt causes an exception, the cache implementation must dispose of any associated dependencies. - - If the cache entry is removed, the cache implementation must also dispose of the dependency. + - If the cache entry is removed, the cache implementation must also dispose of the dependency. - - The internal implementation of the method automatically calls the method after it calls a callback that is registered through . + - The internal implementation of the method automatically calls the method after it calls a callback that is registered through . Note: This automatic call to the dispose method during the event firing only occurs if the initialization of the instance was previously completed. @@ -180,11 +180,11 @@ Note: This automatic call to the dispose method during the event firing only occ - Taking these rules into consideration, the method must be called in one of the following ways: - - Users must call the method overload if they decide not to insert the derived change-monitor instance into a cache. + - Users must call the method overload if they decide not to insert the derived change-monitor instance into a cache. - - The cache implementation is responsible for calling the overload if the implementation tries to insert the change-monitor instance into an object cache but the insertion fails. When the insertion attempt causes an exception, the cache implementation must dispose any associated dependencies. + - The cache implementation is responsible for calling the overload if the implementation tries to insert the change-monitor instance into an object cache but the insertion fails. When the insertion attempt causes an exception, the cache implementation must dispose any associated dependencies. - - If the cache entry is removed, the cache implementation must also dispose the dependency. + - If the cache entry is removed, the cache implementation must also dispose the dependency. The internal implementation of the method automatically calls the method after it calls a callback that is registered through the method. diff --git a/xml/System.Runtime.CompilerServices/InternalsVisibleToAttribute.xml b/xml/System.Runtime.CompilerServices/InternalsVisibleToAttribute.xml index ba5c1216f44..fc965833449 100644 --- a/xml/System.Runtime.CompilerServices/InternalsVisibleToAttribute.xml +++ b/xml/System.Runtime.CompilerServices/InternalsVisibleToAttribute.xml @@ -96,11 +96,11 @@ You can use the [Strong Name Tool (Sn.exe)](/dotnet/framework/tools/sn-exe-stron 1. Extract the public key from the strong-named key file to a separate file: - `Sn -p ` + `Sn -p ` 2. Display the full public key to the console: - `Sn -tp ` + `Sn -tp ` 3. Copy and paste the full public key value into your source code. @@ -196,21 +196,17 @@ The following example provides the source code for the `Friend2` assembly. Note You can use [Sn.exe (Strong Name Tool)](/dotnet/framework/tools/sn-exe-strong-name-tool) to retrieve the full public key from a strong-named key (.snk) file. To do this, you perform the following steps: -1. Extract the public key from the strong-named key file to a separate file: - - **Sn -p** *snk_file* *outfile* - -2. Display the full public key to the console: +1. Extract the public key from the strong-named key file to a separate file: - **Sn -tp** *outfile* + **Sn -p** *snk_file* *outfile* -3. Copy and paste the full public key value into your source code. +2. Display the full public key to the console: - For more information about how to use the attribute, see the following articles: + **Sn -tp** *outfile* -- [Friend Assemblies (C++)](/cpp/dotnet/friend-assemblies-cpp) +3. Copy and paste the full public key value into your source code. -- [Friend assemblies](/dotnet/standard/assembly/friend) + For more information about how to use the attribute, see [Friend assemblies](/dotnet/standard/assembly/friend). ## Examples **Signed assemblies** @@ -225,7 +221,7 @@ The following example provides the source code for the `Friend2` assembly. Note :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/friend1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/friend1.vb" id="Snippet2"::: - The following example uses the attribute to make an `internal` member of an unsigned assembly visible to another unsigned assembly. The attribute ensures that the `internal` `StringLib.IsFirstLetterUpperCase` method in an assembly named `UtilityLib` is visible to the code in an assembly named `Friend2`. The following is the source code for UtilityLib.dll: + The following example uses the attribute to make an `internal` member of an unsigned assembly visible to another unsigned assembly. The attribute ensures that the `internal` `StringLib.IsFirstLetterUpperCase` method in an assembly named `UtilityLib` is visible to the code in an assembly named `Friend2`. The following is the source code for UtilityLib.dll: :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/UtilityLib/utilitylib.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/UtilityLib/utilitylib.vb" id="Snippet5"::: @@ -327,9 +323,9 @@ The following example provides the source code for the `Friend2` assembly. Note ## Remarks For more information about how to use the attribute, see the following topics: -- [Friend Assemblies (C++)](/cpp/dotnet/friend-assemblies-cpp) +- [Friend Assemblies (C++)](/cpp/dotnet/friend-assemblies-cpp) -- [Friend assemblies](/dotnet/standard/assembly/friend) +- [Friend assemblies](/dotnet/standard/assembly/friend) ]]> diff --git a/xml/System.Runtime.InteropServices/SEHException.xml b/xml/System.Runtime.InteropServices/SEHException.xml index 3a8e298e19a..b772da14190 100644 --- a/xml/System.Runtime.InteropServices/SEHException.xml +++ b/xml/System.Runtime.InteropServices/SEHException.xml @@ -74,10 +74,10 @@ The class handles SEH errors - `STATUS_NO_MEMORY` exceptions are automatically mapped to the class. - `STATUS_ACCESS_VIOLATION` exceptions are automatically mapped as follows: - - If `legacyNullReferencePolicy` is applied, all access violations are mapped to the class. - - If the address at which the read/write was attempted is not in JIT-compiled code, the exception is mapped to the class. - - If the address at which the read/write was attempted is in JIT-compiled code, but it is not in the OS Null partition area, the exception is mapped to the class. - - If there is no `legacyNullReferencePolicy`, and the address at which the read/write was attempted is in JIT-compiled code and in the OS Null partition area, the exception is mapped to the class. + - If `legacyNullReferencePolicy` is applied, all access violations are mapped to the class. + - If the address at which the read/write was attempted is not in JIT-compiled code, the exception is mapped to the class. + - If the address at which the read/write was attempted is in JIT-compiled code, but it is not in the OS Null partition area, the exception is mapped to the class. + - If there is no `legacyNullReferencePolicy`, and the address at which the read/write was attempted is in JIT-compiled code and in the OS Null partition area, the exception is mapped to the class. Any SEH exception that is not automatically mapped to a specific exception is mapped to the class by default. diff --git a/xml/System.Speech.Recognition/RecognizedAudio.xml b/xml/System.Speech.Recognition/RecognizedAudio.xml index 046f58ce58c..20d16603c2c 100644 --- a/xml/System.Speech.Recognition/RecognizedAudio.xml +++ b/xml/System.Speech.Recognition/RecognizedAudio.xml @@ -40,25 +40,25 @@ - Events: - - and + - and - - and + - and - - and + - and - - and + - and - - + - - Methods: - - and + - and - - and + - and - - + - - - + - > [!IMPORTANT] > A recognition result produced by emulated speech recognition does not contain recognized audio. For such a recognition result, its property returns `null` and its method throws an exception. For more information about emulated speech recognition, see the `EmulateRecognize` and `EmulateRecognizeAsync` methods of the and classes. diff --git a/xml/System.Speech.Recognition/SemanticResultValue.xml b/xml/System.Speech.Recognition/SemanticResultValue.xml index 3cb73af67d5..f3372e837ba 100644 --- a/xml/System.Speech.Recognition/SemanticResultValue.xml +++ b/xml/System.Speech.Recognition/SemanticResultValue.xml @@ -45,24 +45,24 @@ - If only the value (specified by an instance of ) is used to construct a object, the is associated with the grammar component that preceded it, in addition to a object. - For instance, in the code fragment below, if a constructed using this instance recognizes the word "background", a value of `true` is set in the recognized phrase semantics. + For instance, in the code fragment below, if a constructed using this instance recognizes the word "background", a value of `true` is set in the recognized phrase semantics. - ```csharp + ```csharp GrammarBuilder backgroundGB=new GrammarBuilder("background"); backgroundGB.Append(new SemanticResultValue(true)); - ``` + ``` - For more information, see the description of . + For more information, see the description of . - If a string value phrase or specific instance is used, together with a that specifies a value, that value is automatically associated with the string value phrase or the instance. If the phrase or object is used in the process of recognition, the value will be assigned to the semantics of the recognized phrase. - The following example illustrates this, and is functionally equivalent to the preceding example, which used explicit calls to and . If the recognition logic uses the word "background", the value `true` will be added to the recognized semantics. + The following example illustrates this, and is functionally equivalent to the preceding example, which used explicit calls to and . If the recognition logic uses the word "background", the value `true` will be added to the recognized semantics. - ```csharp + ```csharp fgOrbgChoice.Add((GrammarBuilder)new SemanticResultValue("background", true)); - ``` + ``` - For more information, see the description of and . + For more information, see the description of and . To be used by a in recognition, all instances must be associated with one of the objects used by that . This is done by associating a semantic key with the . diff --git a/xml/System.Speech.Recognition/SemanticValue.xml b/xml/System.Speech.Recognition/SemanticValue.xml index b1926bcd4c2..48fe3d34ee0 100644 --- a/xml/System.Speech.Recognition/SemanticValue.xml +++ b/xml/System.Speech.Recognition/SemanticValue.xml @@ -70,12 +70,12 @@ - A collection of name/value pairs () of child objects, which are also instances. Child nodes are accessible through the implementation of using a string lookup key and a instance, as in the following example. - ```csharp + ```csharp foreach (KeyValuePair child in semantics) { Utils.CreateSemanticsTreeNodes(semanticsNode.Nodes, child.Value, child.Key); } - ``` + ``` Recognition engines based on System.Speech provide valid instances of for all output from recognition, even for phrases with no explicit semantic structure. diff --git a/xml/System.Speech.Synthesis.TtsEngine/EventParameterType.xml b/xml/System.Speech.Synthesis.TtsEngine/EventParameterType.xml index 397628c8c5b..67bf89e27c4 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/EventParameterType.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/EventParameterType.xml @@ -40,19 +40,18 @@ For detailed information on how use `EventParameterType`, see the documentation ## Examples The following example is part of a custom speech synthesis implementation inheriting from , and using the use of , , , and . - The implementation of + The implementation of : -1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. +1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. -2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation +2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - - Translates Americanism to Britishisms in the text to be spoken. + - Translates Americanism to Britishisms in the text to be spoken. + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + The parameters on , including the member value returned by , are used to log the event generated through the `LogSpeechEvent` method. - The parameters on , including the member value returned by , are used to log the event generated through the `LogSpeechEvent` method. - -3. A speech rendering engine is then called with the modified array. +3. A speech rendering engine is then called with the modified array. ```csharp private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; diff --git a/xml/System.Speech.Synthesis.TtsEngine/FragmentState.xml b/xml/System.Speech.Synthesis.TtsEngine/FragmentState.xml index 9431377c6d4..1f0fe2d5b2a 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/FragmentState.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/FragmentState.xml @@ -194,17 +194,16 @@ ## Remarks The interpretation of the value returned by depends on the value returned by the property on the current . -1. If the value of is +1. If the value of is - - If is positive, the value returned should be interpreted as the length of the silence in milliseconds. + - If is positive, the value returned should be interpreted as the length of the silence in milliseconds. + - If is negative, the value returned should be interpreted as a member of the . - - If is negative, the value returned should be interpreted as a member of the . + Emphasis information returned by when the property is corresponds to the attributes of the `` element of SSML input to a speech synthesizer engine. - Emphasis information returned by when the property is corresponds to the attributes of the `` element of SSML input to a speech synthesizer engine. +2. For all other values of , the values should be interpreted as being of . -2. For all other values of , the values should be interpreted as being of . - - Emphasis information returned by for spoken words corresponds to the attributes of the `` element of SSML input to a speech synthesizer engine. + Emphasis information returned by for spoken words corresponds to the attributes of the `` element of SSML input to a speech synthesizer engine. ]]> diff --git a/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml b/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml index aaf92fef58e..cbc2e69bcbf 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml @@ -43,15 +43,14 @@ ## Examples The example below is part of a custom speech synthesis implementation inheriting from , and using the use of , , , and - The implementation of +The implementation of : 1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. 2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - - Translates Americanism to Britishisms in the text to be spoken. - - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + - Translates Americanism to Britishisms in the text to be spoken. + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. 3. A speech rendering engine is then called with the modified array. @@ -148,20 +147,18 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si The type of the events which can be handled by the Speech platform infrastructure can be obtained through the property on the synthesizer engine site implementation of . - - ## Examples The example below is part of a custom speech synthesis implementation inheriting from , and using the use of , , , and - The implementation of +The implementation of : 1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. 2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - - Translates Americanism to Britishisms in the text to be spoken. + - Translates Americanism to Britishisms in the text to be spoken. - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. 3. A speech rendering engine is then called with the modified array. @@ -317,17 +314,17 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si ## Examples The example below is part of a custom speech synthesis implementation inheriting from , and using the use of , , , and - The implementation of +The implementation of : 1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. 2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - - Translates Americanism to Britishisms in the text to be spoken. + - Translates Americanism to Britishisms in the text to be spoken. - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. - The parameters on , including are used to log the event generated through the `LogSpeechEvent` method. + The parameters on , including are used to log the event generated through the `LogSpeechEvent` method. 3. A speech rendering engine is then called with the modified array. @@ -506,17 +503,17 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si ## Examples The example below is part of a custom speech synthesis implementation inheriting from , and using the use of , , , and - The implementation of +The implementation of : 1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. 2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - - Translates Americanism to Britishisms in the text to be spoken. + - Translates Americanism to Britishisms in the text to be spoken. - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. - The parameters on , including are used to log the event generated through the `LogSpeechEvent` method. + The parameters on , including are used to log the event generated through the `LogSpeechEvent` method. 3. A speech rendering engine is then called with the modified array. @@ -610,17 +607,17 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si ## Examples The example below is part of a custom speech synthesis implementation inheriting from , and using the use of , , , and - The implementation of +The implementation of : 1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. 2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - - Translates Americanism to Britishisms in the text to be spoken. + - Translates Americanism to Britishisms in the text to be spoken. - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. - The parameters on , including are used to log the event generated through the `LogSpeechEvent` method. + The parameters on , including are used to log the event generated through the `LogSpeechEvent` method. 3. A speech rendering engine is then called with the modified array. @@ -714,17 +711,17 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si ## Examples The example below is part of a custom speech synthesis implementation inheriting from , and using the use of , , , and - The implementation of +The implementation of : 1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. 2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - - Translates Americanism to Britishisms in the text to be spoken. + - Translates Americanism to Britishisms in the text to be spoken. - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. - The parameters on , including are used to log the event generated through the `LogSpeechEvent` method. + The parameters on , including are used to log the event generated through the `LogSpeechEvent` method. 3. A speech rendering engine is then called with the modified array. diff --git a/xml/System.Speech.Synthesis.TtsEngine/TextFragment.xml b/xml/System.Speech.Synthesis.TtsEngine/TextFragment.xml index 36e24d7ac82..d9162be14d1 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/TextFragment.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/TextFragment.xml @@ -40,26 +40,23 @@ Speech attribute information, such as emphasis, pitch, and rate, are obtained from the object returned by the property. - - ## Examples The example below is part of a custom speech synthesis implementation inheriting from , and using the use of , , , and . The implementation of -1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. +1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. - Particular care is used to respect the , on the original when creating the on the new instances. + Particular care is used to respect the , on the original when creating the on the new instances. -2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation +2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - - Translates Americanism to Britishisms in the text to be spoken. + - Translates Americanism to Britishisms in the text to be spoken. + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. +3. A speech rendering engine is then called with the modified array. -3. A speech rendering engine is then called with the modified array. - -``` +```csharp private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; private readonly char[] spaces = new char[] { ' ', '\t', '\r', '\n' }; internal struct UsVsUk @@ -201,19 +198,18 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si The implementation of -1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. +1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. - Particular care is used to respect the , on the original when creating the on the new instances. + Particular care is used to respect the , on the original when creating the on the new instances. -2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation +2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - - Translates Americanism to Britishisms in the text to be spoken. + - Translates Americanism to Britishisms in the text to be spoken. + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. +3. A speech rendering engine is then called with the modified array. -3. A speech rendering engine is then called with the modified array. - -``` +```csharp private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; private readonly char[] spaces = new char[] { ' ', '\t', '\r', '\n' }; internal struct UsVsUk @@ -292,26 +288,23 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si ## Remarks The default value of this property is 0. - - ## Examples The example below is part of a custom speech synthesis implementation inheriting from , and using the use of , , , and . The implementation of -1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. - - Particular care is used to respect the , on the original when creating the on the new instances. +1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. -2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation + Particular care is used to respect the , on the original when creating the on the new instances. - - Translates Americanism to Britishisms in the text to be spoken. +2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + - Translates Americanism to Britishisms in the text to be spoken. + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. -3. A speech rendering engine is then called with the modified array. +3. A speech rendering engine is then called with the modified array. -``` +```csharp private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; private readonly char[] spaces = new char[] { ' ', '\t', '\r', '\n' }; internal struct UsVsUk @@ -394,26 +387,23 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si Resetting the value of will not change the value of and . - - ## Examples The example below is part of a custom speech synthesis implementation inheriting from , and using the use of , , , and . The implementation of -1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. - - Particular care is used to respect the , on the original when creating the on the new instances. +1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. -2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation + Particular care is used to respect the , on the original when creating the on the new instances. - - Translates Americanism to Britishisms in the text to be spoken. +2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + - Translates Americanism to Britishisms in the text to be spoken. + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. -3. A speech rendering engine is then called with the modified array. +3. A speech rendering engine is then called with the modified array. -``` +```csharp private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; private readonly char[] spaces = new char[] { ' ', '\t', '\r', '\n' }; internal struct UsVsUk diff --git a/xml/System.Speech.Synthesis.TtsEngine/TtsEngineAction.xml b/xml/System.Speech.Synthesis.TtsEngine/TtsEngineAction.xml index 334413887cb..1191a674d6a 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/TtsEngineAction.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/TtsEngineAction.xml @@ -34,22 +34,20 @@ Processing of the value returned by the property is handled by a speech synthesizes implementation of the method on a class derived from . - - ## Examples The following example is part of a custom speech synthesis implementation inheriting from , and using the use of , , and The implementation of -1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. +1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. -2. If the enumeration value by found from the property on the returned by the property of each instance is Speak, the implementation +2. If the enumeration value by found from the property on the returned by the property of each instance is Speak, the implementation - - Translates Americanism to Britishisms in the text to be spoken. + - Translates Americanism to Britishisms in the text to be spoken. - - If the property on the interface provided to the implementation support the event type, an event to drive a synthesizer progress meter is created. + - If the property on the interface provided to the implementation support the event type, an event to drive a synthesizer progress meter is created. -3. A speech rendering engine is then called with the modified array. +3. A speech rendering engine is then called with the modified array. ```csharp private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; diff --git a/xml/System.Speech.Synthesis.TtsEngine/TtsEngineSsml.xml b/xml/System.Speech.Synthesis.TtsEngine/TtsEngineSsml.xml index ddb797b2cd1..1b74aec9d4c 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/TtsEngineSsml.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/TtsEngineSsml.xml @@ -44,9 +44,9 @@ The method is called by the infrastructures text parser receiving: -1. A reference to the interface, which provides access to system services such as even queuing and writing audio output. +1. A reference to the interface, which provides access to system services such as event queuing and writing audio output. -2. An array of instance produced from Speech Synthesis Markup Language (SSML) input. In addition to text to be rendered as speech, the parsing of the SSML stores information about the requested attributes of the speech in a instance associated with each incoming object. +2. An array of instance produced from Speech Synthesis Markup Language (SSML) input. In addition to text to be rendered as speech, the parsing of the SSML stores information about the requested attributes of the speech in a instance associated with each incoming object. A speech synthesizer application can optionally make requests for a specified output format by implementing to be called by the platform when it tries to provide the correct audio output. @@ -362,17 +362,17 @@ internal struct WaveFormat ## Examples The example below is part of a custom speech synthesis implementation inheriting from , and using the use of , , , and - The implementation of +The implementation of : -1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. +1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. -2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation +2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - - Translates Americanism to Britishisms in the text to be spoken. + - Translates Americanism to Britishisms in the text to be spoken. - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. -3. A speech rendering engine is then called with the modified array. +3. A speech rendering engine is then called with the modified array. ``` private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; @@ -430,11 +430,11 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si A implementation: -1. Traps or modify aspects of the incoming objects +1. Traps or modify aspects of the incoming objects -2. Generates any necessary events using the site reference to a instance +2. Generates any necessary events using the site reference to a instance -3. Generates the actual synthesized speech. +3. Generates the actual synthesized speech. Generation of speech is most typically done by calling Speak on one of the speech rendering engines provided by the operating system. diff --git a/xml/System.Speech.Synthesis.TtsEngine/TtsEventId.xml b/xml/System.Speech.Synthesis.TtsEngine/TtsEventId.xml index f6f6e80956e..2d477689fdd 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/TtsEventId.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/TtsEventId.xml @@ -35,23 +35,20 @@ The value of is a bitmask, where the members of define the location of the bit corresponding to the event type. For example, WordBoundary has a value of five (5), meaning the fifth bit in the value returned by indicates if the site supports the event type. - - ## Examples The following example is part of a custom speech synthesis implementation inheriting from , and using the , , , and classes. The implementation of includes the following steps: -1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. +1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. -2. If the property of each instance is equal to +2. If the property of each instance is equal to , the code does the following: - - Translates American English to British English in the text to be spoken. - - - If the property provided to the implementation supports the `WordBoundary` event type, a instance is used to create an event to drive a synthesizer progress meter is created. + - Translates American English to British English in the text to be spoken. + - If the property provided to the implementation supports the `WordBoundary` event type, a instance is used to create an event to drive a synthesizer progress meter is created. -3. A speech rendering engine is then called with the modified array. +3. A speech rendering engine is then called with the modified array. ```csharp private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; diff --git a/xml/System.Text/Encoding.xml b/xml/System.Text/Encoding.xml index f0a619f4534..f84914868b1 100644 --- a/xml/System.Text/Encoding.xml +++ b/xml/System.Text/Encoding.xml @@ -5785,8 +5785,8 @@ If multiple providers are registered, object that uses replacement fallback to replace each string that it can't encode and each byte that it can't decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a object whose fallback is either an or a , as the following example illustrates. - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/UTF8/encoding.utf8.1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoding/UTF8/encoding.utf8.1.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/UTF8/encoding.utf8.1.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoding/UTF8/encoding.utf8.1.vb" id="Snippet1"::: ## Examples The following example defines an array that consists of the following characters: diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index a7cc342dc93..690b0ba60b1 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -2694,15 +2694,15 @@ End Sub - At the beginning of the task, as the following example shows. - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay5.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay5.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Task/Delay/delay5.vb" id="Snippet5"::: + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay5.cs" id="Snippet5"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay5.fs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Task/Delay/delay5.vb" id="Snippet5"::: - Sometime while the task is executing. In this case, the call to the method executes as a child task within a task, as the following example shows. Note that since the task that calls the method executes asynchronously, the parent task must wait for it to complete by using the `await` keyword. - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay5.cs" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay5.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Task/Delay/delay5.vb" id="Snippet7"::: + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay5.cs" id="Snippet7"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay5.fs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Task/Delay/delay5.vb" id="Snippet7"::: After the specified time delay, the task is completed in the state. diff --git a/xml/System.Threading/Thread.xml b/xml/System.Threading/Thread.xml index f5560aa66f0..feade230857 100644 --- a/xml/System.Threading/Thread.xml +++ b/xml/System.Threading/Thread.xml @@ -78,13 +78,13 @@ The constructors can take either of two delegate - If the method has no arguments, you pass a delegate to the constructor. It has the signature: - ```csharp + ```csharp public delegate void ThreadStart() - ``` + ``` - ```vb + ```vb Public Delegate Sub ThreadStart() - ``` + ``` The following example creates and starts a thread that executes the `ExecuteInForeground` method. The method displays information about some thread properties, then executes a loop in which it pauses for half a second and displays the elapsed number of seconds. When the thread has executed for at least five seconds, the loop ends and the thread terminates execution. @@ -94,13 +94,13 @@ The constructors can take either of two delegate - If the method has an argument, you pass a delegate to the constructor. It has the signature: - ```csharp + ```csharp public delegate void ParameterizedThreadStart(object obj) - ``` + ``` - ```vb + ```vb Public Delegate Sub ParameterizedThreadStart(obj As Object) - ``` + ``` The method executed by the delegate can then cast (in C#) or convert (in Visual Basic) the parameter to the appropriate type. diff --git a/xml/System.Threading/ThreadPool.xml b/xml/System.Threading/ThreadPool.xml index cb5545882dd..9ac41e9c48d 100644 --- a/xml/System.Threading/ThreadPool.xml +++ b/xml/System.Threading/ThreadPool.xml @@ -64,23 +64,13 @@ - When you use registered wait handles, a system thread monitors the status of the wait handles. When a wait operation completes, a worker thread from the thread pool executes the corresponding callback function. -- When you call the method to queue a method for execution on a thread pool thread. You do this by passing the method a delegate. The delegate has the signature - - ```csharp - void WaitCallback(Object state) - ``` - - ```vb - Sub WaitCallback(state As Object) - ``` - - where `state` is an object that contains data to be used by the delegate. The actual data can be passed to the delegate by calling the method. +- When you call the method to queue a method for execution on a thread pool thread. You do this by passing the method a delegate. The delegate has the signature `void WaitCallback(object state)`, where `state` is an object that contains data to be used by the delegate. The actual data can be passed to the delegate by calling the method. > [!NOTE] -> The threads in the managed thread pool are background threads. That is, their properties are `true`. This means that a thread will not keep an application running after all foreground threads have exited. +> The threads in the managed thread pool are background threads. That is, their properties are `true`. This means that a thread will not keep an application running after all foreground threads have exited. > [!IMPORTANT] -> When the thread pool reuses a thread, it does not clear the data in thread local storage or in fields that are marked with the attribute. Therefore, when a method examines thread local storage or fields that are marked with the attribute, the values it finds might be left over from an earlier use of the thread pool thread. +> When the thread pool reuses a thread, it does not clear the data in thread local storage or in fields that are marked with the attribute. Therefore, when a method examines thread local storage or fields that are marked with the attribute, the values it finds might be left over from an earlier use of the thread pool thread. You can also queue work items that are not related to a wait operation to the thread pool. To request that a work item be handled by a thread in the thread pool, call the method. This method takes as a parameter a reference to the method or delegate that will be called by the thread selected from the thread pool. There is no way to cancel a work item after it has been queued. @@ -94,12 +84,12 @@ The thread pool provides new worker threads or I/O completion threads on demand until it reaches the maximum for each category. When a maximum is reached, the thread pool can create additional threads in that category or wait until some tasks complete. The thread pool creates and destroys worker threads in order to optimize throughput, which is defined as the number of tasks that complete per unit of time. Too few threads might not make optimal use of available resources, whereas too many threads could increase resource contention. > [!NOTE] -> When demand is low, the actual number of thread pool threads can fall below the minimum values. +> When demand is low, the actual number of thread pool threads can fall below the minimum values. You can use the method to obtain these minimum values. > [!CAUTION] -> You can use the method to increase the minimum number of threads. However, unnecessarily increasing these values can cause performance problems. If too many tasks start at the same time, all of them might appear to be slow. In most cases the thread pool will perform better with its own algorithm for allocating threads. +> You can use the method to increase the minimum number of threads. However, unnecessarily increasing these values can cause performance problems. If too many tasks start at the same time, all of them might appear to be slow. In most cases the thread pool will perform better with its own algorithm for allocating threads. ## Examples In the following example, the main application thread queues a method named `ThreadProc` to execute on a thread pool thread, sleeps for one second, and then exits. The `ThreadProc` method simply displays a message. @@ -492,7 +482,7 @@ If a thread pool implementation may have different types of work items, the coun The thread pool provides new worker threads or I/O completion threads on demand until it reaches the minimum for each category. By default, the minimum number of threads is set to the number of processors on a system. When the minimum is reached, the thread pool can create additional threads in that category or wait until some tasks complete. The thread pool creates and destroys threads in order to optimize throughput, which is defined as the number of tasks that complete per unit of time. Too few threads might not make optimal use of available resources, whereas too many threads could increase resource contention. > [!NOTE] -> When demand is low, the actual number of thread pool threads can fall below the minimum values. +> When demand is low, the actual number of thread pool threads can fall below the minimum values. ## Examples The following example sets the minimum number of worker threads to four, and preserves the original value for the minimum number of asynchronous I/O completion threads. @@ -850,7 +840,7 @@ The following example uses the method checks the current state of the specified object's . If the object's state is unsignaled, the method registers a wait operation. The wait operation is performed by a thread from the thread pool. The delegate is executed by a worker thread when the object's state becomes signaled or the time-out interval elapses. If the `timeOutInterval` parameter is not 0 (zero) and the `executeOnlyOnce` parameter is `false`, the timer is reset every time the event is signaled or the time-out interval elapses. > [!IMPORTANT] -> Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. +> Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. To cancel the wait operation, call the method. @@ -945,7 +935,7 @@ The following example uses the method checks the current state of the specified object's . If the object's state is unsignaled, the method registers a wait operation. The wait operation is performed by a thread from the thread pool. The delegate is executed by a worker thread when the object's state becomes signaled or the time-out interval elapses. If the `timeOutInterval` parameter is not 0 (zero) and the `executeOnlyOnce` parameter is `false`, the timer is reset every time the event is signaled or the time-out interval elapses. > [!IMPORTANT] -> Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. +> Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. To cancel the wait operation, call the method. @@ -1040,7 +1030,7 @@ The following example uses the method checks the current state of the specified object's . If the object's state is unsignaled, the method registers a wait operation. The wait operation is performed by a thread from the thread pool. The delegate is executed by a worker thread when the object's state becomes signaled or the time-out interval elapses. If the `timeOutInterval` parameter is not 0 (zero) and the `executeOnlyOnce` parameter is `false`, the timer is reset every time the event is signaled or the time-out interval elapses. > [!IMPORTANT] -> Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. +> Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. To cancel the wait operation, call the method. @@ -1140,7 +1130,7 @@ The following example uses the method checks the current state of the specified object's . If the object's state is unsignaled, the method registers a wait operation. The wait operation is performed by a thread from the thread pool. The delegate is executed by a worker thread when the object's state becomes signaled or the time-out interval elapses. If the `timeOutInterval` parameter is not 0 (zero) and the `executeOnlyOnce` parameter is `false`, the timer is reset every time the event is signaled or the time-out interval elapses. > [!IMPORTANT] -> Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. +> Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. To cancel the wait operation, call the method. @@ -1226,7 +1216,7 @@ The following example uses the [!NOTE] -> The thread pool may have upper limits for the maximum thread counts (such as `short.MaxValue`, depending on the implementation). The argument values are capped to the upper limit, so even when the method returns `true`, the actual maximum thread counts may be lower than requested. +> The thread pool may have upper limits for the maximum thread counts (such as `short.MaxValue`, depending on the implementation). The argument values are capped to the upper limit, so even when the method returns `true`, the actual maximum thread counts may be lower than requested. ]]> diff --git a/xml/System.Xml.Schema/Extensions.xml b/xml/System.Xml.Schema/Extensions.xml index dbd3b5637d8..cb226a3a2ef 100644 --- a/xml/System.Xml.Schema/Extensions.xml +++ b/xml/System.Xml.Schema/Extensions.xml @@ -729,25 +729,22 @@ doc2 did not validate To validate an attribute, you use an instance of . You can obtain this instance in various ways. An easy way is as follows: -1. Validate that a document conforms to a schema. +1. Validate that a document conforms to a schema. -2. Add the post-schema-validation infoset (PSVI) by calling the extension method. +2. Add the post-schema-validation infoset (PSVI) by calling the extension method. -3. Call the extension method to retrieve an object that implements . From the retrieved object, you can get an . +3. Call the extension method to retrieve an object that implements . From the retrieved object, you can get an . - - If you get an for an , the type will be . + - If you get an for an , the type will be . - - If you get an for an , the type will be . + - If you get an for an , the type will be . After you have an instance of an , you can use this method to validate an attribute. - - ## Examples ```csharp - - string xsdMarkup = +string xsdMarkup = @" @@ -797,7 +794,7 @@ lang.Validate(lang.GetSchemaInfo().SchemaAttribute, schemas, (sender, e) => }); Console.WriteLine("lang {0}", errors ? "did not validate" : "validated"); -// the following makes the Lang attribute invalid according to the schema +// The following makes the Lang attribute invalid according to the schema lang.Value = "VC"; Console.WriteLine(); @@ -813,8 +810,7 @@ Console.WriteLine("lang {0}", errors ? "did not validate" : "validated"); ``` ```vb - - Dim errors As Boolean = False +Dim errors As Boolean = False Private Sub XSDErrors(ByVal o As Object, ByVal e As ValidationEventArgs) Console.WriteLine("{0}", e.Message) @@ -874,7 +870,7 @@ Sub Main() End Sub ``` - This example produces the following output: +This example produces the following output: ``` Validating doc1 ... @@ -958,9 +954,9 @@ lang did not validate There are two steps to populating the XML tree with the PSVI. -1. First, an annotation is added to all nodes in the tree to enable you to call or on an element or attribute in the tree. +1. First, an annotation is added to all nodes in the tree to enable you to call or on an element or attribute in the tree. -2. Second, default elements and attributes defined in the XSD are added to the XML tree. By calling one of the methods, you can determine if a specific element or attribute was added from the XSD as a default element or attribute. +2. Second, default elements and attributes defined in the XSD are added to the XML tree. By calling one of the methods, you can determine if a specific element or attribute was added from the XSD as a default element or attribute. @@ -1364,25 +1360,22 @@ Invalid Element /Root/Child1/GrandChild3 To validate a sub-tree, you use an instance of . You can obtain this instance in various ways. An easy way is as follows: -1. Validate that a document conforms to a schema. +1. Validate that a document conforms to a schema. -2. Add the post-schema-validation infoset (PSVI) by calling the extension method. +2. Add the post-schema-validation infoset (PSVI) by calling the extension method. -3. Call the extension method to retrieve an object that implements . From the retrieved object, you can get an . +3. Call the extension method to retrieve an object that implements . From the retrieved object, you can get an . - - If you get an for an , the type will be . + - If you get an for an , the type will be . - - If you get an for an , the type will be . + - If you get an for an , the type will be . After you have an instance of an , you can use this method to validate an sub-tree. - - ## Examples ```csharp - - string xsdMarkup = +string xsdMarkup = @" @@ -1446,8 +1439,7 @@ Console.WriteLine("child1 {0}", errors ? "did not validate" : "validated"); ``` ```vb - - Dim errors As Boolean = False +Dim errors As Boolean = False Private Sub XSDErrors(ByVal o As Object, ByVal e As ValidationEventArgs) Console.WriteLine("{0}", e.Message) @@ -1509,7 +1501,7 @@ Sub Main() End Sub ``` - This example produces the following output: +This example produces the following output: ``` Validating doc1 ... @@ -1597,25 +1589,22 @@ child1 did not validate To validate an attribute, you use an instance of . You can obtain this instance in various ways. An easy way is as follows: -1. Validate that a document conforms to a schema. +1. Validate that a document conforms to a schema. -2. Add the post-schema-validation infoset (PSVI) by calling the extension method. +2. Add the post-schema-validation infoset (PSVI) by calling the extension method. -3. Call the extension method to retrieve an object that implements . From the retrieved object, you can get an . +3. Call the extension method to retrieve an object that implements . From the retrieved object, you can get an . - - If you get an for an , the type will be . + - If you get an for an , the type will be . - - If you get an for an , the type will be . + - If you get an for an , the type will be . After you have an instance of an , you can use this method to validate an attribute. - - ## Examples ```csharp - - static void DumpInvalidNodes(XElement el) +static void DumpInvalidNodes(XElement el) { if (el.GetSchemaInfo().Validity != XmlSchemaValidity.Valid) Console.WriteLine("Invalid Element {0}", @@ -1708,8 +1697,7 @@ static void Main(string[] args) ``` ```vb - - Private Sub DumpInvalidNodes(ByVal el As XElement) +Private Sub DumpInvalidNodes(ByVal el As XElement) If el.GetSchemaInfo.Validity <> XmlSchemaValidity.Valid Then Console.WriteLine("Invalid Element {0}", _ el _ @@ -1799,7 +1787,7 @@ Sub Main() End Sub ``` - This example produces the following output: +This example produces the following output: ``` Validating doc1 ... @@ -1894,25 +1882,22 @@ Invalid Attribute /Root/@Lang To validate a sub-tree, you use an instance of . You can obtain this instance in various ways. An easy way is as follows: -1. Validate that a document conforms to a schema. - -2. Add the post-schema-validation infoset (PSVI) by calling the extension method. +1. Validate that a document conforms to a schema. -3. Call the extension method to retrieve an object that implements . From the retrieved object, you can get an . +2. Add the post-schema-validation infoset (PSVI) by calling the extension method. - - If you get an for an , the type will be . +3. Call the extension method to retrieve an object that implements . From the retrieved object, you can get an . - - If you get an for an , the type will be . - - After you have an instance of an , you can use this method to validate a sub-tree.. + - If you get an for an , the type will be . + - If you get an for an , the type will be . +After you have an instance of an , you can use this method to validate a sub-tree. ## Examples ```csharp - - string xsdMarkup = +string xsdMarkup = @" @@ -1977,8 +1962,7 @@ Console.WriteLine(doc2); ``` ```vb - - Dim errors As Boolean = False +Dim errors As Boolean = False Private Sub XSDErrors(ByVal o As Object, ByVal e As ValidationEventArgs) Console.WriteLine("{0}", e.Message) @@ -2044,7 +2028,7 @@ Sub Main() End Sub ``` - This example produces the following output: +This example produces the following output: ``` Validating doc1 diff --git a/xml/System.Xml.Xsl/XslCompiledTransform.xml b/xml/System.Xml.Xsl/XslCompiledTransform.xml index e62fb9b51f4..21bb34fe089 100644 --- a/xml/System.Xml.Xsl/XslCompiledTransform.xml +++ b/xml/System.Xml.Xsl/XslCompiledTransform.xml @@ -206,7 +206,7 @@ The sample uses the following two input files: - The style sheet is passed to the method either as a URI, or an implementation of the class that implements the interface. The interface is implemented on all text-parsing objects. - In other words, if the style sheet is loaded using an object, such as an or , or an implementation that does not implement the interface, you cannot debug the style sheet. + In other words, if the style sheet is loaded using an object, such as an or , or an implementation that does not implement the interface, you cannot debug the style sheet. - The used to load the style sheet is a file-based , such as the (this is the default used by the class). diff --git a/xml/System.Xml/XmlWriter.xml b/xml/System.Xml/XmlWriter.xml index 7a0c7d1f6af..1e3915d9105 100644 --- a/xml/System.Xml/XmlWriter.xml +++ b/xml/System.Xml/XmlWriter.xml @@ -116,18 +116,18 @@ An XML writer uses two properties from the c - The property configures the XML writer to check that the stream being written complies with the rules for a well-formed XML 1.0 document or document fragment, as defined by the W3C. The three conformance levels are described in the following table. The default is . For details, see the property and the enumeration. - |Level|Description| - |-----------|-----------------| - ||The XML output conforms to the rules for a well-formed XML 1.0 document and can be processed by any conforming processor.| - ||The XML output conforms to the rules for a well-formed XML 1.0 document fragment.| - ||The XML writer determines which level of conformation checking to apply (document or fragment) based on the incoming data.| + |Level|Description| + |-----------|-----------------| + ||The XML output conforms to the rules for a well-formed XML 1.0 document and can be processed by any conforming processor.| + ||The XML output conforms to the rules for a well-formed XML 1.0 document fragment.| + ||The XML writer determines which level of conformation checking to apply (document or fragment) based on the incoming data.| ## Write elements You can use the following methods to write element nodes. For examples, see the methods listed. -|Use|To| -|---------|--------| +| Use | To | +|-----|----| ||Write an entire element node, including a string value.| ||To write an element value by using multiple method calls. For example, you can call to write a typed value, to write a character entity, to write an attribute, or you can write a child element. This is a more sophisticated version of the method.

To close the element, you call the or method.| ||To copy an element node found at the current position of an or object. When called, it copies everything from the source object to the instance.| @@ -136,8 +136,8 @@ You can use the following methods to write element n You can use the following methods to write attributes on element nodes. These methods can also be used to create namespace declarations on an element, as discussed in the next section. -|Use|To| -|---------|--------| +| Use | To | +|-----|----| ||To write an entire attribute node, including a string value.| ||To write the attribute value using multiple method calls. For example, you can call to write a typed value. This is a more sophisticated version of the method.

To close the element, you call the method.| ||To copy all the attributes found at the current position of an object. The attributes that are written depend on the type of node the reader is currently positioned on:

- For an attribute node, it writes the current attribute, and then the rest of the attributes until the element closing tag.
- For an element node, it writes all attributes contained by the element.
- For an XML declaration node, it writes all the attributes in the declaration.
- For all other node types, the method throws an exception.| @@ -157,11 +157,11 @@ The maintains a namespace stack that corresponds to The code generates the following XML string: - ```xml + ```xml - ``` + ``` - Specify a namespace prefix when writing attributes or elements. Many of the methods used to write element and attributes enable you to do this. For example, the method writes a start tag and associates it with a specified namespace and prefix. diff --git a/xml/System/ArgumentNullException.xml b/xml/System/ArgumentNullException.xml index d9adc2b9475..f2244295d41 100644 --- a/xml/System/ArgumentNullException.xml +++ b/xml/System/ArgumentNullException.xml @@ -199,7 +199,7 @@ | Property | Value | |-----------------------------------------|-----------------------------------------------| | | A null reference (`Nothing` in Visual Basic). | - || | A localized error message string that identifies the null argument. For example, if the `paramName` argument is "arg1", the English language message string is `Value cannot be null. (Parameter name: 'arg1')`. | +| | A localized error message string that identifies the null argument. For example, if the `paramName` argument is "arg1", the English language message string is `Value cannot be null. (Parameter name: 'arg1')`. | | | The parameter name string. | ]]> diff --git a/xml/System/ArraySegment`1.xml b/xml/System/ArraySegment`1.xml index fbd91d57ff6..9c251b183d1 100644 --- a/xml/System/ArraySegment`1.xml +++ b/xml/System/ArraySegment`1.xml @@ -103,9 +103,9 @@ - For task-based asynchronous operations, you can use an object to ensure that each task operates on a distinct segment of the array. The following example divides an array into individual segments with up to ten elements. Each element in the segment is multiplied by its segment number. The result shows that using the class to manipulate elements in this way changes the values of its underlying array. - :::code language="csharp" source="~/snippets/csharp/System/ArraySegmentT/Overview/segmentexample.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.ArraySegment/FS/segmentexample.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System/ArraySegmentT/Overview/segmentexample.vb" id="Snippet2"::: + :::code language="csharp" source="~/snippets/csharp/System/ArraySegmentT/Overview/segmentexample.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.ArraySegment/FS/segmentexample.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/System/ArraySegmentT/Overview/segmentexample.vb" id="Snippet2"::: Note, however, that although the structure can be used to divide an array into distinct segments, the segments are not completely independent of one another. The property returns the entire original array, not a copy of the array; therefore, changes made to the array returned by the property are made to the original array. If this is undesirable, you should perform operations on a copy of the array, rather than an object that represents a portion of the array. diff --git a/xml/System/BitConverter.xml b/xml/System/BitConverter.xml index 2a6df3ffdda..eba1bb392a5 100644 --- a/xml/System/BitConverter.xml +++ b/xml/System/BitConverter.xml @@ -103,9 +103,9 @@ - If systems sending and receiving data can have different endianness, always transmit data in a particular order. This means that the order of bytes in the array may have to be reversed either before sending them or after receiving them. A common convention is to transmit data in network byte order (big-endian order). The following example provides an implementation for sending an integer value in network byte order. - :::code language="csharp" source="~/snippets/csharp/System/BitConverter/Overview/networkorder1.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.BitConverter.Class/FS/networkorder1.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System/BitConverter/Overview/networkorder1.vb" id="Snippet4"::: + :::code language="csharp" source="~/snippets/csharp/System/BitConverter/Overview/networkorder1.cs" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.BitConverter.Class/FS/networkorder1.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/System/BitConverter/Overview/networkorder1.vb" id="Snippet4"::: - If systems sending and receiving data can have different endianness and the data to be transmitted consists of signed integers, call the method to convert the data to network byte order and the method to convert it to the order required by the recipient. diff --git a/xml/System/Console.xml b/xml/System/Console.xml index 419432bd77e..3c0be1b3872 100644 --- a/xml/System/Console.xml +++ b/xml/System/Console.xml @@ -3159,34 +3159,34 @@ A property get operation might return a cached value instead of the console's cu - If the standard input device is the keyboard, the method blocks until the user presses the **Enter** key. - One of the most common uses of the method is to pause program execution before clearing the console and displaying new information to it, or to prompt the user to press the Enter key before terminating the application. The following example illustrates this. + One of the most common uses of the method is to pause program execution before clearing the console and displaying new information to it, or to prompt the user to press the Enter key before terminating the application. The following example illustrates this. - :::code language="csharp" source="~/snippets/csharp/System/Console/ReadLine/ReadLineSimple.cs" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.Console.ReadLine/fs/ReadLineSimple.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System/Console/ReadLine/ReadLineSimple.vb" id="Snippet6"::: + :::code language="csharp" source="~/snippets/csharp/System/Console/ReadLine/ReadLineSimple.cs" id="Snippet6"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.Console.ReadLine/fs/ReadLineSimple.fs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/System/Console/ReadLine/ReadLineSimple.vb" id="Snippet6"::: - If standard input is redirected to a file, the method reads a line of text from a file. For example, the following is a text file named ReadLine1.txt: - ``` + ``` This is the first line. This is the second line. This is the third line. This is the fourth line. - ``` + ``` - The following example uses the method to read input that is redirected from a file. The read operation terminates when the method returns `null`, which indicates that no lines remain to be read. + The following example uses the method to read input that is redirected from a file. The read operation terminates when the method returns `null`, which indicates that no lines remain to be read. - :::code language="csharp" source="~/snippets/csharp/System/Console/ReadLine/ReadLine3.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.Console.ReadLine/fs/ReadLine3.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System/Console/ReadLine/ReadLine3.vb" id="Snippet3"::: + :::code language="csharp" source="~/snippets/csharp/System/Console/ReadLine/ReadLine3.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.Console.ReadLine/fs/ReadLine3.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/System/Console/ReadLine/ReadLine3.vb" id="Snippet3"::: - After compiling the example to an executable named ReadLine1.exe, you can run it from the command line to read the contents of the file and display them to the console. The syntax is: + After compiling the example to an executable named ReadLine1.exe, you can run it from the command line to read the contents of the file and display them to the console. The syntax is: - ``` + ``` ReadLine1 < ReadLine1.txt - ``` + ``` A line is defined as a sequence of characters followed by a carriage return (hexadecimal 0x000d), a line feed (hexadecimal 0x000a), or the value of the property. The returned string does not contain the terminating character(s). By default, the method reads input from a 256-character input buffer. Because this includes the character(s), the method can read lines that contain up to 254 characters. To read longer lines, call the method. diff --git a/xml/System/DateTime.xml b/xml/System/DateTime.xml index 4168e33a3d6..61eba18e353 100644 --- a/xml/System/DateTime.xml +++ b/xml/System/DateTime.xml @@ -3672,11 +3672,11 @@ The return value is a whose p - If the value that is serialized represents an invalid time in the local time zone. In this case, the method adjusts the restored value so that it represents a valid time in the local time zone. - For example, the transition from standard time to daylight saving time occurs in the U.S. Pacific Time zone on March 14, 2010, at 2:00 A.M., when the time advances by one hour, to 3:00 A.M. This hour interval is an invalid time, that is, a time interval that does not exist in this time zone. The following example shows that when a time that falls within this range is converted to a long integer value by the method and is then restored by the method, the original value is adjusted to become a valid time. You can determine whether a particular date and time value may be subject to modification by passing it to the method, as the example illustrates. + For example, the transition from standard time to daylight saving time occurs in the U.S. Pacific Time zone on March 14, 2010, at 2:00 A.M., when the time advances by one hour, to 3:00 A.M. This hour interval is an invalid time, that is, a time interval that does not exist in this time zone. The following example shows that when a time that falls within this range is converted to a long integer value by the method and is then restored by the method, the original value is adjusted to become a valid time. You can determine whether a particular date and time value may be subject to modification by passing it to the method, as the example illustrates. - :::code language="csharp" source="~/snippets/csharp/System/DateTime/FromFileTime/fromfiletime1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.datetime.fromfiletime/fs/fromfiletime1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/DateTime/FromFileTime/fromfiletime1.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/DateTime/FromFileTime/fromfiletime1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.datetime.fromfiletime/fs/fromfiletime1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/System/DateTime/FromFileTime/fromfiletime1.vb" id="Snippet1"::: @@ -5791,11 +5791,11 @@ The return value is a whose p - A string that includes the GMT designator and conforms to the RFC 1123 time format; for example: - "Sat, 01 Nov 2008 19:35:00 GMT" + "Sat, 01 Nov 2008 19:35:00 GMT" - A string that includes the date and time along with time zone offset information; for example: - "03/01/2009 05:42:00 -5:00" + "03/01/2009 05:42:00 -5:00" The following example parses strings in each of these formats by using the formatting conventions of the current culture, which in this case is the en-US culture: @@ -8333,11 +8333,11 @@ The return value is a whose p - If the value that is serialized represents an invalid time in the local time zone. In this case, the method adjusts the restored value so that it represents a valid time in the local time zone. - For example, the transition from standard time to daylight saving time occurs in the U.S. Pacific Time zone on March 14, 2010, at 2:00 A.M., when the time advances by one hour, to 3:00 A.M. This hour interval is an invalid time, that is, a time interval that does not exist in this time zone. The following example shows that when a time that falls within this range is converted to a long integer value by the method and is then restored by the method, the original value is adjusted to become a valid time. You can determine whether a particular date and time value may be subject to modification by passing it to the method, as the example illustrates. + For example, the transition from standard time to daylight saving time occurs in the U.S. Pacific Time zone on March 14, 2010, at 2:00 A.M., when the time advances by one hour, to 3:00 A.M. This hour interval is an invalid time, that is, a time interval that does not exist in this time zone. The following example shows that when a time that falls within this range is converted to a long integer value by the method and is then restored by the method, the original value is adjusted to become a valid time. You can determine whether a particular date and time value may be subject to modification by passing it to the method, as the example illustrates. - :::code language="csharp" source="~/snippets/csharp/System/DateTime/FromFileTime/fromfiletime1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.datetime.fromfiletime/fs/fromfiletime1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/DateTime/FromFileTime/fromfiletime1.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/DateTime/FromFileTime/fromfiletime1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.datetime.fromfiletime/fs/fromfiletime1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/System/DateTime/FromFileTime/fromfiletime1.vb" id="Snippet1"::: diff --git a/xml/System/DateTimeOffset.xml b/xml/System/DateTimeOffset.xml index e36d0c1b3e5..b0c8fe3bdcf 100644 --- a/xml/System/DateTimeOffset.xml +++ b/xml/System/DateTimeOffset.xml @@ -130,19 +130,19 @@ - Date and time arithmetic. - You can add or subtract either dates or time intervals from a particular value. Arithmetic operations with values, unlike those with values, adjust for differences in time offsets when returning a result. For example, the following code uses variables to subtract the current local time from the current UTC time. The code then uses variables to perform the same operation. The subtraction with values returns the local time zone's difference from UTC, while the subtraction with values returns . + You can add or subtract either dates or time intervals from a particular value. Arithmetic operations with values, unlike those with values, adjust for differences in time offsets when returning a result. For example, the following code uses variables to subtract the current local time from the current UTC time. The code then uses variables to perform the same operation. The subtraction with values returns the local time zone's difference from UTC, while the subtraction with values returns . - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Overview/Type.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Type/fs/Type.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/DateTimeOffset/Overview/Type.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Overview/Type.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Type/fs/Type.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/System/DateTimeOffset/Overview/Type.vb" id="Snippet1"::: - Type conversion operations. - You can convert values to values and vice versa. + You can convert values to values and vice versa. - Time manipulation and extraction operations. - You can extract either the date or the time of a value. You can also retrieve the value of a particular component, such as its year or its month. + You can extract either the date or the time of a value. You can also retrieve the value of a particular component, such as its year or its month. > [!NOTE] > If you are working with a ticks value that you want to convert to some other time interval, such as minutes or seconds, you should use the , , , , or constant to perform the conversion. For example, to add the number of seconds represented by a specified number of ticks to the component of a value, you can use the expression `dateValue.Second + nTicks/Timespan.TicksPerSecond`. @@ -150,11 +150,11 @@ - Date and time conversion. - You can convert any value to another value that represents the same point in time in another time zone. However, a time zone's adjustment rules are applied only in the case of the method, which converts a value to the date and time in the local system zone. + You can convert any value to another value that represents the same point in time in another time zone. However, a time zone's adjustment rules are applied only in the case of the method, which converts a value to the date and time in the local system zone. - Date and time comparison. - You can determine whether any particular value is earlier than, the same as, or later than another value. Before the comparison is performed, all values are converted to UTC. + You can determine whether any particular value is earlier than, the same as, or later than another value. Before the comparison is performed, all values are converted to UTC. ]]> diff --git a/xml/System/EntryPointNotFoundException.xml b/xml/System/EntryPointNotFoundException.xml index c4095c90012..c966ba8bc06 100644 --- a/xml/System/EntryPointNotFoundException.xml +++ b/xml/System/EntryPointNotFoundException.xml @@ -61,51 +61,51 @@ - The call to a function in a Windows DLL cannot be resolved because the function cannot be found. In the following example, an exception is thrown because User32.dll does not include a function named `GetMyNumber`. - :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/nofunction1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/nofunction1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/EntryPointNotFoundException/Overview/nofunction1.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/nofunction1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/nofunction1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/System/EntryPointNotFoundException/Overview/nofunction1.vb" id="Snippet1"::: - The call to a function in a Windows DLL cannot be resolved because the name used in the method call does not match a name found in the assembly. Frequently, this occurs because the field is either implicitly or explicitly set to `true`, the called method includes one or more string parameters and has both an ANSI and a Unicode version, and the name used in the method call does not correspond to the name of this ANSI or Unicode version. The following example provides an illustration by attempting to call the Windows `MessageBox` function in User32.dll. Because the first method definition specifies for string marshaling, the common language looks for the wide-character version of the function, `MessageBoxW`, instead of the name used in the method call, `MessageBox`. The second method definition corrects this problem by calling the `MessageBoxW` instead of the `MessageBox` function. - :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/badcall1.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/badcall1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System/EntryPointNotFoundException/Overview/badcall1.vb" id="Snippet2"::: + :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/badcall1.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/badcall1.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/System/EntryPointNotFoundException/Overview/badcall1.vb" id="Snippet2"::: - You're trying to call a function in a dynamic link library by its simple name rather than its decorated name. Typically, the C++ compiler generates a decorated name for DLL functions. For example, the following C++ code defines a function named `Double` in a library named TestDll.dll. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.entrypointnotfoundexception.class/cpp/testdll.cpp" id="Snippet6"::: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.entrypointnotfoundexception.class/cpp/testdll.cpp" id="Snippet6"::: - When the code in the following example tries to call the function, an exception is thrown because the `Double` function cannot be found. + When the code in the following example tries to call the function, an exception is thrown because the `Double` function cannot be found. - :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/mangle1.cs" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/mangle1.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System/EntryPointNotFoundException/Overview/mangle1.vb" id="Snippet7"::: + :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/mangle1.cs" id="Snippet7"::: + :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/mangle1.fs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/System/EntryPointNotFoundException/Overview/mangle1.vb" id="Snippet7"::: - However, if the function is called by using its decorated name (in this case, `?Double@@YAHH@Z`), the function call succeeds, as the following example shows. + However, if the function is called by using its decorated name (in this case, `?Double@@YAHH@Z`), the function call succeeds, as the following example shows. - :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/mangle2.cs" id="Snippet8"::: - :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/mangle2.fs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/System/EntryPointNotFoundException/Overview/mangle2.vb" id="Snippet8"::: + :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/mangle2.cs" id="Snippet8"::: + :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/mangle2.fs" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/System/EntryPointNotFoundException/Overview/mangle2.vb" id="Snippet8"::: - You can find the decorated names of functions exported by a DLL by using a utility such as Dumpbin.exe. + You can find the decorated names of functions exported by a DLL by using a utility such as Dumpbin.exe. - You are attempting to call a method in a managed assembly as if it were an unmanaged dynamic link library. To see this in action, compile the following example to an assembly named StringUtilities.dll. - :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/stringutilities.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/stringutilities.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System/EntryPointNotFoundException/Overview/stringutilities.vb" id="Snippet3"::: + :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/stringutilities.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/stringutilities.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/System/EntryPointNotFoundException/Overview/stringutilities.vb" id="Snippet3"::: - Then compile and execute the following example, which attempts to call the `StringUtilities.SayGoodMorning` method in the StringUtilities.dll dynamic link library as if it were unmanaged code. The result is an exception. + Then compile and execute the following example, which attempts to call the `StringUtilities.SayGoodMorning` method in the StringUtilities.dll dynamic link library as if it were unmanaged code. The result is an exception. - :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/importassembly1.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/importassembly1.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System/EntryPointNotFoundException/Overview/importassembly1.vb" id="Snippet4"::: + :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/importassembly1.cs" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/importassembly1.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/System/EntryPointNotFoundException/Overview/importassembly1.vb" id="Snippet4"::: - To eliminate the exception, add a reference to the managed assembly and access the `StringUtilities.SayGoodMorning` method just as you would access any other method in managed code, as the following example does. + To eliminate the exception, add a reference to the managed assembly and access the `StringUtilities.SayGoodMorning` method just as you would access any other method in managed code, as the following example does. - :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/fiximportassembly1.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/fiximportassembly1.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System/EntryPointNotFoundException/Overview/fiximportassembly1.vb" id="Snippet5"::: + :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/fiximportassembly1.cs" id="Snippet5"::: + :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/fiximportassembly1.fs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/System/EntryPointNotFoundException/Overview/fiximportassembly1.vb" id="Snippet5"::: - You are trying to call a method in a COM DLL as if it were a Windows DLL. To access a COM DLL, select the **Add Reference** option in Visual Studio to add a reference to the project, and then select the type library from the **COM** tab. diff --git a/xml/System/GC.xml b/xml/System/GC.xml index 4262436d341..46eb2b22fad 100644 --- a/xml/System/GC.xml +++ b/xml/System/GC.xml @@ -1510,9 +1510,9 @@ The following example demonstrates the use of the interface - When the search methods of a number of generic collection objects are called. Some of these types and their methods include the following: - - Some of the generic overloads of the method. + - Some of the generic overloads of the method. - - The search methods of the class, including , , , and . + - The search methods of the class, including , , , and . - - The search methods of the class, including and . + - The search methods of the class, including and . - - The search methods of the generic class, including and . + - The search methods of the generic class, including and . In other words, to handle the possibility that objects of a class will be stored in an array or a generic collection object, it is a good idea to implement so that the object can be easily identified and manipulated. When implementing the method, define equality appropriately for the type specified by the generic type argument. For example, if the type argument is , define equality appropriately for the comparison of two 32-bit signed integers. - - ## Examples The following example shows the partial implementation of a `Person` class that implements and has two properties, `LastName` and `NationalId`. `NationalId` is considered to be a unique identifier, therefore the method returns `True` if the `NationalId` property of two `Person` objects is identical; otherwise, it returns `False`. (Note that the F# example does not handle `null` values for `Person` instances.) diff --git a/xml/System/IndexOutOfRangeException.xml b/xml/System/IndexOutOfRangeException.xml index c0717ab50b3..bdc0d8aeded 100644 --- a/xml/System/IndexOutOfRangeException.xml +++ b/xml/System/IndexOutOfRangeException.xml @@ -71,84 +71,82 @@ - Forgetting that the upper bound of a collection or a zero-based array is one less than its number of members or elements, as the following example illustrates. - :::code language="csharp" source="~/snippets/csharp/System/IndexOutOfRangeException/Overview/length1.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System/IndexOutOfRangeException/Overview/length1.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System/IndexOutOfRangeException/Overview/length1.vb" id="Snippet3"::: + :::code language="csharp" source="~/snippets/csharp/System/IndexOutOfRangeException/Overview/length1.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System/IndexOutOfRangeException/Overview/length1.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/System/IndexOutOfRangeException/Overview/length1.vb" id="Snippet3"::: - To correct the error, you can use code like the following. + To correct the error, you can use code like the following. - :::code language="csharp" source="~/snippets/csharp/System/IndexOutOfRangeException/Overview/length2.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System/IndexOutOfRangeException/Overview/length2.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System/IndexOutOfRangeException/Overview/length2.vb" id="Snippet4"::: + :::code language="csharp" source="~/snippets/csharp/System/IndexOutOfRangeException/Overview/length2.cs" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/System/IndexOutOfRangeException/Overview/length2.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/System/IndexOutOfRangeException/Overview/length2.vb" id="Snippet4"::: - Alternately, instead of iterating all the elements in the array by their index, you can use the `foreach` statement (in C#), the `for...in` statement (in F#), or the `For Each` statement (in Visual Basic). + Alternately, instead of iterating all the elements in the array by their index, you can use the `foreach` statement (in C#), the `for...in` statement (in F#), or the `For Each` statement (in Visual Basic). - Attempting to assign an array element to another array that has not been adequately dimensioned and that has fewer elements than the original array. The following example attempts to assign the last element in the `value1` array to the same element in the `value2` array. However, the `value2` array has been incorrectly dimensioned to have six instead of seven elements. As a result, the assignment throws an exception. - :::code language="csharp" source="~/snippets/csharp/System/IndexOutOfRangeException/Overview/Uninit1.cs" id="Snippet10"::: - :::code language="fsharp" source="~/snippets/fsharp/System/IndexOutOfRangeException/Overview/Uninit1.fs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/System/IndexOutOfRangeException/Overview/Uninit1.vb" id="Snippet10"::: + :::code language="csharp" source="~/snippets/csharp/System/IndexOutOfRangeException/Overview/Uninit1.cs" id="Snippet10"::: + :::code language="fsharp" source="~/snippets/fsharp/System/IndexOutOfRangeException/Overview/Uninit1.fs" id="Snippet10"::: + :::code language="vb" source="~/snippets/visualbasic/System/IndexOutOfRangeException/Overview/Uninit1.vb" id="Snippet10"::: - Using a value returned by a search method to iterate a portion of an array or collection starting at a particular index position. If you forget to check whether the search operation found a match, the runtime throws an exception, as shown in this example. - :::code language="csharp" source="~/snippets/csharp/System/IndexOutOfRangeException/Overview/negative1.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System/IndexOutOfRangeException/Overview/negative1.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System/IndexOutOfRangeException/Overview/negative1.vb" id="Snippet5"::: + :::code language="csharp" source="~/snippets/csharp/System/IndexOutOfRangeException/Overview/negative1.cs" id="Snippet5"::: + :::code language="fsharp" source="~/snippets/fsharp/System/IndexOutOfRangeException/Overview/negative1.fs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/System/IndexOutOfRangeException/Overview/negative1.vb" id="Snippet5"::: - In this case, the method returns -1, which is an invalid index value, when it fails to find a match. To correct this error, check the search method's return value before iterating the array, as shown in this example. + In this case, the method returns -1, which is an invalid index value, when it fails to find a match. To correct this error, check the search method's return value before iterating the array, as shown in this example. - :::code language="csharp" source="~/snippets/csharp/System/IndexOutOfRangeException/Overview/negative2.cs" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/System/IndexOutOfRangeException/Overview/negative2.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System/IndexOutOfRangeException/Overview/negative2.vb" id="Snippet6"::: + :::code language="csharp" source="~/snippets/csharp/System/IndexOutOfRangeException/Overview/negative2.cs" id="Snippet6"::: + :::code language="fsharp" source="~/snippets/fsharp/System/IndexOutOfRangeException/Overview/negative2.fs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/System/IndexOutOfRangeException/Overview/negative2.vb" id="Snippet6"::: - Trying to use or enumerate a result set, collection, or array returned by a query without testing whether the returned object has any valid data. - Using a computed value to define the starting index, the ending index, or the number of items to be iterated. If the result of the computation is unexpected, it might result in an exception. You should check your program's logic in calculating the index value and validate the value before iterating the array or collection. The following conditions must all be true; otherwise, an exception is thrown: - - The starting index must be greater than or equal to for the dimension of the array that you want to iterate, or greater than or equal to 0 for a collection. + - The starting index must be greater than or equal to for the dimension of the array that you want to iterate, or greater than or equal to 0 for a collection. + - The ending index cannot exceed for the dimension of the array that you want to iterate, or cannot be greater than or equal to the `Count` property of a collection. + - The following equation must be true for the dimension of the array that you want to iterate: - - The ending index cannot exceed for the dimension of the array that you want to iterate, or cannot be greater than or equal to the `Count` property of a collection. + ``` + start_index >= lower_bound And start_index + items_to_iterate - 1 <= upper_bound + ``` - - The following equation must be true for the dimension of the array that you want to iterate: + For a collection, the following equation must be true: - ``` - start_index >= lower_bound And start_index + items_to_iterate - 1 <= upper_bound - ``` + ``` + start_index >= 0 And start_index + items_to_iterate <= Count + ``` - For a collection, the following equation must be true: + > [!TIP] + > The starting index of an array or collection can never be a negative number. - ``` - start_index >= 0 And start_index + items_to_iterate <= Count - ``` +- Assuming that an array must be zero-based. Arrays that are not zero-based can be created by the method and can be returned by COM interop, although they aren't CLS-compliant. The following example illustrates the that is thrown when you try to iterate a non-zero-based array created by the method. - > [!TIP] - > The starting index of an array or collection can never be a negative number. + :::code language="csharp" source="~/snippets/csharp/System/IndexOutOfRangeException/Overview/nonzero1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/IndexOutOfRangeException/Overview/nonzero1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/System/IndexOutOfRangeException/Overview/nonzero1.vb" id="Snippet1"::: -- Assuming that an array must be zero-based. Arrays that are not zero-based can be created by the method and can be returned by COM interop, although they aren't CLS-compliant. The following example illustrates the that is thrown when you try to iterate a non-zero-based array created by the method. + To correct the error, as the following example does, you can call the method instead of making assumptions about the starting index of an array. - :::code language="csharp" source="~/snippets/csharp/System/IndexOutOfRangeException/Overview/nonzero1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/IndexOutOfRangeException/Overview/nonzero1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/IndexOutOfRangeException/Overview/nonzero1.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/IndexOutOfRangeException/Overview/nonzero2.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System/IndexOutOfRangeException/Overview/nonzero2.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/System/IndexOutOfRangeException/Overview/nonzero2.vb" id="Snippet2"::: - To correct the error, as the following example does, you can call the method instead of making assumptions about the starting index of an array. - - :::code language="csharp" source="~/snippets/csharp/System/IndexOutOfRangeException/Overview/nonzero2.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/IndexOutOfRangeException/Overview/nonzero2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System/IndexOutOfRangeException/Overview/nonzero2.vb" id="Snippet2"::: - - Note that when you call the method to get the starting index of an array, you should also call the method to get its ending index. + Note that when you call the method to get the starting index of an array, you should also call the method to get its ending index. - Confusing an index and the value at that index in a numeric array or collection. This issue usually occurs when using the `foreach` statement (in C#), the `for...in` statement (in F#), or the `For Each` statement (in Visual Basic). The following example illustrates the problem. - :::code language="csharp" source="~/snippets/csharp/System/IndexOutOfRangeException/Overview/foreach1.cs" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/System/IndexOutOfRangeException/Overview/foreach1.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System/IndexOutOfRangeException/Overview/foreach1.vb" id="Snippet7"::: + :::code language="csharp" source="~/snippets/csharp/System/IndexOutOfRangeException/Overview/foreach1.cs" id="Snippet7"::: + :::code language="fsharp" source="~/snippets/fsharp/System/IndexOutOfRangeException/Overview/foreach1.fs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/System/IndexOutOfRangeException/Overview/foreach1.vb" id="Snippet7"::: - The iteration construct returns each value in an array or collection, not its index. To eliminate the exception, use this code. + The iteration construct returns each value in an array or collection, not its index. To eliminate the exception, use this code. - :::code language="csharp" source="~/snippets/csharp/System/IndexOutOfRangeException/Overview/foreach2.cs" id="Snippet8"::: - :::code language="fsharp" source="~/snippets/fsharp/System/IndexOutOfRangeException/Overview/foreach2.fs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/System/IndexOutOfRangeException/Overview/foreach2.vb" id="Snippet8"::: + :::code language="csharp" source="~/snippets/csharp/System/IndexOutOfRangeException/Overview/foreach2.cs" id="Snippet8"::: + :::code language="fsharp" source="~/snippets/fsharp/System/IndexOutOfRangeException/Overview/foreach2.fs" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/System/IndexOutOfRangeException/Overview/foreach2.vb" id="Snippet8"::: - Providing an invalid column name to the property. @@ -167,9 +165,7 @@ The following intermediate language (IL) instructions throw : - ldelem.\ - - ldelema - - stelem.\ uses the HRESULT COR_E_INDEXOUTOFRANGE, which has the value 0x80131508. diff --git a/xml/System/IntPtr.xml b/xml/System/IntPtr.xml index 13084a44d0c..87f9f1329d9 100644 --- a/xml/System/IntPtr.xml +++ b/xml/System/IntPtr.xml @@ -278,13 +278,13 @@ 3. The Visual Basic example defines a variable named `offset` that is equal to the length of the ANSI string. It is used to determine the offset into unmanaged memory to which the next character in the ANSI string is copied. Because its starting value is the length of the string, the copy operation will copy a character from the start of the string to the end of the memory block. - The C#, F# and C++ examples call the method to get an unmanaged pointer to the starting address of the string and the unmanaged block of memory, and they add one less than the length of the string to the starting address of the ANSI string. Because the unmanaged string pointer now points to the end of the string, the copy operation will copy a character from the end of the string to the start of the memory block. + The C#, F# and C++ examples call the method to get an unmanaged pointer to the starting address of the string and the unmanaged block of memory, and they add one less than the length of the string to the starting address of the ANSI string. Because the unmanaged string pointer now points to the end of the string, the copy operation will copy a character from the end of the string to the start of the memory block. 4. Uses a loop to copy each character from the string to the unmanaged block of memory. - The Visual Basic example calls the method to read the byte (or one-byte character) at a specified offset from the managed pointer to the ANSI string. The offset is incremented with each iteration of the loop. It then calls the method to write the byte to the memory address defined by the starting address of the unmanaged block of memory plus `offset`. It then decrements `offset`. + The Visual Basic example calls the method to read the byte (or one-byte character) at a specified offset from the managed pointer to the ANSI string. The offset is incremented with each iteration of the loop. It then calls the method to write the byte to the memory address defined by the starting address of the unmanaged block of memory plus `offset`. It then decrements `offset`. - The C#, F# and C++ examples perform the copy operation, then decrement the pointer to the address of the next location in the unmanaged ANSI string and increment the pointer to the next address in the unmanaged block. + The C#, F# and C++ examples perform the copy operation, then decrement the pointer to the address of the next location in the unmanaged ANSI string and increment the pointer to the next address in the unmanaged block. 5. All examples call the to convert the unmanaged memory block containing the copied ANSI string to a managed Unicode object. diff --git a/xml/System/InvalidOperationException.xml b/xml/System/InvalidOperationException.xml index a3b545c03fb..ae1940301a4 100644 --- a/xml/System/InvalidOperationException.xml +++ b/xml/System/InvalidOperationException.xml @@ -177,13 +177,13 @@ You can eliminate the exception in any of three ways: - If you cannot modify the source code for the type you are trying to sort, you can create a delegate to perform the sorting. The delegate signature is - ```vb + ```vb Function Comparison(Of T)(x As T, y As T) As Integer - ``` + ``` - ```csharp + ```csharp int Comparison(T x, T y) - ``` + ``` The following example uses the approach by defining a `PersonComparison` method that matches the delegate signature. It then passes this delegate to the method. diff --git a/xml/System/NullReferenceException.xml b/xml/System/NullReferenceException.xml index d46bf738bd3..e09656d6d32 100644 --- a/xml/System/NullReferenceException.xml +++ b/xml/System/NullReferenceException.xml @@ -73,85 +73,85 @@ A exception is thrown when you try to acces - You forgot to instantiate a reference type. In the following example, `names` is declared but never instantiated (the affected line is commented out in the C# example since it doesn't compile): - :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/example1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/example1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/example1.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/example1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/example1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/example1.vb" id="Snippet1"::: - Some compilers issue a warning when they compile this code. Others issue an error, and the compilation fails. To address this problem, instantiate the object so that its value is no longer `null`. The following example does this by calling a type's class constructor. + Some compilers issue a warning when they compile this code. Others issue an error, and the compilation fails. To address this problem, instantiate the object so that its value is no longer `null`. The following example does this by calling a type's class constructor. - :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/example1a.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/example1a.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/example1a.vb" id="Snippet2"::: + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/example1a.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/example1a.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/example1a.vb" id="Snippet2"::: - You forgot to dimension an array before initializing it. In the following example, `values` is declared to be an integer array, but the number of elements that it contains is never specified. The attempt to initialize its values therefore throws a exception. - :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/Array3.cs" id="Snippet10"::: - :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/Array3.fs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/Array3.vb" id="Snippet10"::: + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/Array3.cs" id="Snippet10"::: + :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/Array3.fs" id="Snippet10"::: + :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/Array3.vb" id="Snippet10"::: - You can eliminate the exception by declaring the number of elements in the array before initializing it, as the following example does. + You can eliminate the exception by declaring the number of elements in the array before initializing it, as the following example does. - :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/Array4.cs" id="Snippet11"::: - :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/Array4.fs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/Array4.vb" id="Snippet11"::: + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/Array4.cs" id="Snippet11"::: + :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/Array4.fs" id="Snippet11"::: + :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/Array4.vb" id="Snippet11"::: - For more information on declaring and initializing arrays, see [Arrays](/dotnet/csharp/language-reference/builtin-types/arrays) and [Arrays](/dotnet/visual-basic/programming-guide/language-features/arrays/). + For more information on declaring and initializing arrays, see [Arrays](/dotnet/csharp/language-reference/builtin-types/arrays) and [Arrays](/dotnet/visual-basic/programming-guide/language-features/arrays/). - You get a **null** return value from a method, and then call a method on the returned type. This sometimes is the result of a documentation error; the documentation fails to note that a method call can return `null`. In other cases, your code erroneously assumes that the method will always return a non-null value. - The code in the following example assumes that the method always returns `Person` object whose `FirstName` field matches a search string. Because there is no match, the runtime throws a exception. + The code in the following example assumes that the method always returns `Person` object whose `FirstName` field matches a search string. Because there is no match, the runtime throws a exception. - :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/nullreturn2.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/nullreturn2.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/nullreturn2.vb" id="Snippet4"::: + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/nullreturn2.cs" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/nullreturn2.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/nullreturn2.vb" id="Snippet4"::: - To address this problem, test the method's return value to ensure that it's not `null` before calling any of its members, as the following example does. + To address this problem, test the method's return value to ensure that it's not `null` before calling any of its members, as the following example does. - :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/nullreturn2.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/nullreturn2a.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/nullreturn2a.vb" id="Snippet5"::: + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/nullreturn2.cs" id="Snippet5"::: + :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/nullreturn2a.fs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/nullreturn2a.vb" id="Snippet5"::: - You're using an expression (for example, you chained a list of methods or properties together) to retrieve a value and, although you're checking whether the value is `null`, the runtime still throws a exception. This occurs because one of the intermediate values in the expression returns `null`. As a result, your test for `null` is never evaluated. - The following example defines a `Pages` object that caches information about web pages, which are presented by `Page` objects. The `Example.Main` method checks whether the current web page has a non-null title and, if it does, displays the title. Despite this check, however, the method throws a exception. + The following example defines a `Pages` object that caches information about web pages, which are presented by `Page` objects. The `Example.Main` method checks whether the current web page has a non-null title and, if it does, displays the title. Despite this check, however, the method throws a exception. - :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/Chain1.cs" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/Chain1.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/Chain1.vb" id="Snippet6"::: + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/Chain1.cs" id="Snippet6"::: + :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/Chain1.fs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/Chain1.vb" id="Snippet6"::: - The exception is thrown because `pages.CurrentPage` returns `null` if no page information is stored in the cache. This exception can be corrected by testing the value of the `CurrentPage` property before retrieving the current `Page` object's `Title` property, as the following example does: + The exception is thrown because `pages.CurrentPage` returns `null` if no page information is stored in the cache. This exception can be corrected by testing the value of the `CurrentPage` property before retrieving the current `Page` object's `Title` property, as the following example does: - :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/Chain2.cs" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/Chain2.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/Chain2.vb" id="Snippet7"::: + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/Chain2.cs" id="Snippet7"::: + :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/Chain2.fs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/Chain2.vb" id="Snippet7"::: - You're enumerating the elements of an array that contains reference types, and your attempt to process one of the elements throws a exception. - The following example defines a string array. A `for` statement enumerates the elements in the array and calls each string's method before displaying the string. + The following example defines a string array. A `for` statement enumerates the elements in the array and calls each string's method before displaying the string. - :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/Array1.cs" id="Snippet8"::: - :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/Array1.fs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/Array1.vb" id="Snippet8"::: + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/Array1.cs" id="Snippet8"::: + :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/Array1.fs" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/Array1.vb" id="Snippet8"::: - This exception occurs if you assume that each element of the array must contain a non-null value, and the value of the array element is in fact `null`. The exception can be eliminated by testing whether the element is `null` before performing any operation on that element, as the following example shows. + This exception occurs if you assume that each element of the array must contain a non-null value, and the value of the array element is in fact `null`. The exception can be eliminated by testing whether the element is `null` before performing any operation on that element, as the following example shows. - :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/Array2.cs" id="Snippet9"::: - :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/Array2.fs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/Array2.vb" id="Snippet9"::: + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/Array2.cs" id="Snippet9"::: + :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/Array2.fs" id="Snippet9"::: + :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/Array2.vb" id="Snippet9"::: - A method when it accesses a member of one of its arguments, but that argument is `null`. The `PopulateNames` method in the following example throws the exception at the line `names.Add(arrName);`. - :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/example2.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/example2.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/example2.vb" id="Snippet3"::: + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/example2.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/example2.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/System/NullReferenceException/Overview/example2.vb" id="Snippet3"::: - To address this issue, make sure that the argument passed to the method is not `null`, or handle the thrown exception in a `try…catch…finally` block. For more information, see [Exceptions](/dotnet/standard/exceptions/). + To address this issue, make sure that the argument passed to the method is not `null`, or handle the thrown exception in a `try…catch…finally` block. For more information, see [Exceptions](/dotnet/standard/exceptions/). - A list is created without knowing the type, and the list was not initialized. The `GetList` method in the following example throws the exception at the line `emptyList.Add(value)`. - :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/example3.cs" id="Snippet12"::: + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/example3.cs" id="Snippet12"::: - To address this issue, make sure that the list is initialized (one way to do this is to call `Activator.CreateInstance` instead of `FormatterServices.GetUninitializedObject`), or handle the thrown exception in a `try…catch…finally` block. For more information, see [Exceptions](/dotnet/standard/exceptions/). + To address this issue, make sure that the list is initialized (one way to do this is to call `Activator.CreateInstance` instead of `FormatterServices.GetUninitializedObject`), or handle the thrown exception in a `try…catch…finally` block. For more information, see [Exceptions](/dotnet/standard/exceptions/). The following Microsoft intermediate language (MSIL) instructions throw : `callvirt`, `cpblk`, `cpobj`, `initblk`, `ldelem.`, `ldelema`, `ldfld`, `ldflda`, `ldind.`, `ldlen`, `stelem.`, `stfld`, `stind.`, `throw`, and `unbox`. diff --git a/xml/System/Object.xml b/xml/System/Object.xml index 236f43fcc4a..2a3b01fc8a5 100644 --- a/xml/System/Object.xml +++ b/xml/System/Object.xml @@ -896,19 +896,19 @@ To illustrate the difference between a shallow and a deep copy operation, consid - When comparing value types. If `objA` and `objB` are value types, they are boxed before they are passed to the method. This means that if both `objA` and `objB` represent the same instance of a value type, the method nevertheless returns `false`, as the following example shows. - :::code language="csharp" source="~/snippets/csharp/System/Object/ReferenceEquals/referenceequals4.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/ReferenceEquals/referenceequals4.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/Object/ReferenceEquals/referenceequals4.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/Object/ReferenceEquals/referenceequals4.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Object/ReferenceEquals/referenceequals4.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/System/Object/ReferenceEquals/referenceequals4.vb" id="Snippet1"::: - For information on boxing value types, see [Boxing and Unboxing](/dotnet/csharp/programming-guide/types/boxing-and-unboxing). + For information on boxing value types, see [Boxing and Unboxing](/dotnet/csharp/programming-guide/types/boxing-and-unboxing). - When comparing strings. If `objA` and `objB` are strings, the method returns `true` if the string is interned. It does not perform a test for value equality. In the following example, `s1` and `s2` are equal because they are two instances of a single interned string. However, `s3` and `s4` are not equal, because although they have identical string values, that string is not interned. - :::code language="csharp" source="~/snippets/csharp/System/Object/ReferenceEquals/referenceequalsa.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/ReferenceEquals/referenceequalsa.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System/Object/ReferenceEquals/referenceequalsa.vb" id="Snippet2"::: + :::code language="csharp" source="~/snippets/csharp/System/Object/ReferenceEquals/referenceequalsa.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Object/ReferenceEquals/referenceequalsa.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/System/Object/ReferenceEquals/referenceequalsa.vb" id="Snippet2"::: - For more information about string interning, see . + For more information about string interning, see . diff --git a/xml/System/ObjectDisposedException.xml b/xml/System/ObjectDisposedException.xml index 23adfe53df1..6a8d14da8f2 100644 --- a/xml/System/ObjectDisposedException.xml +++ b/xml/System/ObjectDisposedException.xml @@ -63,9 +63,9 @@ - You've called an `IDisposable` object's `Dispose` method (or an `IDisposableAsync` object's `DisposeAsync` method), and you're trying to access an instance member that gets or sets the object's state. The following example illustrates the that is thrown when you try to reset the frequency of timer notifications after you call the method. - :::code language="csharp" source="~/snippets/csharp/System/ObjectDisposedException/Overview/dispose1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/ObjectDisposedException/Overview/dispose1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/ObjectDisposedException/Overview/dispose1.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/ObjectDisposedException/Overview/dispose1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/ObjectDisposedException/Overview/dispose1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/System/ObjectDisposedException/Overview/dispose1.vb" id="Snippet1"::: - You've called an object's `Close` method, and you're trying to access an instance member that gets or sets the object's state. Often, the `Close` method provides a type's public implementation of the method. The same is true for `CloseAsync` and ``. diff --git a/xml/System/OutOfMemoryException.xml b/xml/System/OutOfMemoryException.xml index bdae1b80fc3..bc42bd66a20 100644 --- a/xml/System/OutOfMemoryException.xml +++ b/xml/System/OutOfMemoryException.xml @@ -79,11 +79,11 @@ An exception has two major causes: - The common language runtime cannot allocate enough contiguous memory to successfully perform an operation. This exception can be thrown by any property assignment or method call that requires a memory allocation. For more information on the cause of the exception, see the blog post ["Out of Memory" Does Not Refer to Physical Memory](https://learn.microsoft.com/archive/blogs/ericlippert/out-of-memory-does-not-refer-to-physical-memory). - This type of exception represents a catastrophic failure. If you choose to handle the exception, you should include a `catch` block that calls the method to terminate your app and add an entry to the system event log, as the following example does. + This type of exception represents a catastrophic failure. If you choose to handle the exception, you should include a `catch` block that calls the method to terminate your app and add an entry to the system event log, as the following example does. - :::code language="csharp" source="~/snippets/csharp/System/OutOfMemoryException/Overview/failfast1.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/OutOfMemoryException/Overview/failfast1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System/OutOfMemoryException/Overview/failfast1.vb" id="Snippet2"::: + :::code language="csharp" source="~/snippets/csharp/System/OutOfMemoryException/Overview/failfast1.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System/OutOfMemoryException/Overview/failfast1.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/System/OutOfMemoryException/Overview/failfast1.vb" id="Snippet2"::: Some of the conditions under which the exception is thrown and the actions you can take to eliminate it include the following: diff --git a/xml/System/OverflowException.xml b/xml/System/OverflowException.xml index ebd6defd757..4791c07f76d 100644 --- a/xml/System/OverflowException.xml +++ b/xml/System/OverflowException.xml @@ -63,15 +63,15 @@ - An arithmetic operation produces a result that is outside the range of the data type returned by the operation. The following example illustrates the that is thrown by a multiplication operation that overflows the bounds of the type. - :::code language="csharp" source="~/snippets/csharp/System/OverflowException/Overview/arithmetic1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/OverflowException/Overview/arithmetic1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/OverflowException/Overview/arithmetic1.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/OverflowException/Overview/arithmetic1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/OverflowException/Overview/arithmetic1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/System/OverflowException/Overview/arithmetic1.vb" id="Snippet1"::: - A casting or conversion operation attempts to perform a narrowing conversion, and the value of the source data type is outside the range of the target data type. The following example illustrates the that is thrown by the attempt to convert a large unsigned byte value to a signed byte value. - :::code language="csharp" source="~/snippets/csharp/System/OverflowException/Overview/arithmetic1.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/OverflowException/Overview/arithmetic1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System/OverflowException/Overview/arithmetic1.vb" id="Snippet2"::: + :::code language="csharp" source="~/snippets/csharp/System/OverflowException/Overview/arithmetic1.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System/OverflowException/Overview/arithmetic1.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/System/OverflowException/Overview/arithmetic1.vb" id="Snippet2"::: In each case, the result of the operation is a value that is less than the `MinValue` property or greater than the `MaxValue` property of the data type that results from the operation. diff --git a/xml/System/String.xml b/xml/System/String.xml index ec5c43a4640..051f6bdb669 100644 --- a/xml/System/String.xml +++ b/xml/System/String.xml @@ -284,14 +284,14 @@ Casing operations can be based on the rules of the current culture, a specified - Differences in case mappings between the invariant culture and all other cultures. In these cases, using the casing rules of the invariant culture to change a character to uppercase or lowercase returns the same character. For all other cultures, it returns a different character. Some of the affected characters are listed in the following table. - |Character|If changed to|Returns| - |---------------|-------------------|-------------| - |MICRON SIGN (U+00B5)|Uppercase|GREEK CAPITAL LETTER MU (U+-39C)| - |LATIN CAPITAL LETTER I WITH DOT ABOVE (U+0130)|Lowercase|LATIN SMALL LETTER I (U+0069)| - |LATIN SMALL LETTER DOTLESS I (U+0131)|Uppercase|LATIN CAPITAL LETTER I (U+0049)| - |LATIN SMALL LETTER LONG S (U+017F)|Uppercase|LATIN CAPITAL LETTER S (U+0053)| - |LATIN CAPITAL LETTER D WITH SMALL LETTER Z WITH CARON (U+01C5)|Lowercase|LATIN SMALL LETTER DZ WITH CARON (U+01C6)| - |COMBINING GREEK YPOGEGRAMMENI (U+0345)|Uppercase|GREEK CAPITAL LETTER IOTA (U+0399)| + |Character|If changed to|Returns| + |---------------|-------------------|-------------| + |MICRON SIGN (U+00B5)|Uppercase|GREEK CAPITAL LETTER MU (U+-39C)| + |LATIN CAPITAL LETTER I WITH DOT ABOVE (U+0130)|Lowercase|LATIN SMALL LETTER I (U+0069)| + |LATIN SMALL LETTER DOTLESS I (U+0131)|Uppercase|LATIN CAPITAL LETTER I (U+0049)| + |LATIN SMALL LETTER LONG S (U+017F)|Uppercase|LATIN CAPITAL LETTER S (U+0053)| + |LATIN CAPITAL LETTER D WITH SMALL LETTER Z WITH CARON (U+01C5)|Lowercase|LATIN SMALL LETTER DZ WITH CARON (U+01C6)| + |COMBINING GREEK YPOGEGRAMMENI (U+0345)|Uppercase|GREEK CAPITAL LETTER IOTA (U+0399)| - Differences in case mappings of two-letter mixed-case pairs in the ASCII character range. In most cultures, a two-letter mixed-case pair is equal to the equivalent two-letter uppercase or lowercase pair. This is not true for the following two-letter pairs in the following cultures, because in each case they are compared to a digraph: @@ -14720,15 +14720,15 @@ If the substring should extend from `startIndex` to a specified character sequen - If you've searched for a single character that is to mark the end of the substring, the `length` parameter equals `endIndex` - `startIndex` + 1, where `endIndex` is the return value of the or method. The following example extracts a continuous block of "b" characters from a string. - :::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring2.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System/String/Substring/Substring2.vb" id="Snippet2"::: + :::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring2.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring2.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/System/String/Substring/Substring2.vb" id="Snippet2"::: - If you've searched for multiple characters that are to mark the end of the substring, the `length` parameter equals `endIndex` + `endMatchLength` - `startIndex`, where `endIndex` is the return value of the or method, and `endMatchLength` is the length of the character sequence that marks the end of the substring. The following example extracts a block of text that contains an XML `` element. - :::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring3.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring3.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System/String/Substring/Substring3.vb" id="Snippet3"::: + :::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring3.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring3.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/System/String/Substring/Substring3.vb" id="Snippet3"::: - If the character or character sequence is not included in the end of the substring, the `length` parameter equals `endIndex` - `startIndex`, where `endIndex` is the return value of the or method. diff --git a/xml/System/TimeSpan.xml b/xml/System/TimeSpan.xml index d6f34f5ab73..0e85d0341d9 100644 --- a/xml/System/TimeSpan.xml +++ b/xml/System/TimeSpan.xml @@ -139,7 +139,7 @@ You can instantiate a value in a number of ways: :::code language="fsharp" source="~/snippets/fsharp/System/TimeSpan/Overview/zero1.fs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System/TimeSpan/Overview/zero1.vb" id="Snippet6"::: - values are returned by arithmetic operators and methods of the , , and structures. + values are returned by arithmetic operators and methods of the , , and structures. - By parsing the string representation of a value. You can use the and methods to convert strings that contain time intervals to values. The following example uses the method to convert an array of strings to values. diff --git a/xml/System/Tuple`2.xml b/xml/System/Tuple`2.xml index 384350d2079..c60f9b0a1d3 100644 --- a/xml/System/Tuple`2.xml +++ b/xml/System/Tuple`2.xml @@ -105,15 +105,15 @@ - To provide easy access to, and manipulation of, a data set. The following example defines an array of objects that contain the names of students and their corresponding test scores. It then iterates the array to calculate the mean test score. - :::code language="csharp" source="~/snippets/csharp/System/TupleT1,T2/Overview/example1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/TupleT1,T2/Overview/example1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/TupleT1,T2/Overview/example1.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/TupleT1,T2/Overview/example1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/TupleT1,T2/Overview/example1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/System/TupleT1,T2/Overview/example1.vb" id="Snippet1"::: - To return multiple values from a method without the use of `out` parameters (in C#) or `ByRef` parameters (in Visual Basic). For example, the following example uses a object to return the quotient and the remainder that result from integer division. - :::code language="csharp" source="~/snippets/csharp/System/TupleT1,T2/Overview/item1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/TupleT1,T2/Overview/item1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/TupleT1,T2/Overview/item1.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/TupleT1,T2/Overview/item1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/TupleT1,T2/Overview/item1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/System/TupleT1,T2/Overview/item1.vb" id="Snippet1"::: - To pass multiple values to a method through a single parameter. For example, the method has a single parameter that lets you supply one value to the method that the thread executes at startup. If you supply a object as the method argument, you can supply the thread's startup routine with two items of data. diff --git a/xml/System/Tuple`3.xml b/xml/System/Tuple`3.xml index 6ecdcccdbc6..c6064c1865f 100644 --- a/xml/System/Tuple`3.xml +++ b/xml/System/Tuple`3.xml @@ -114,9 +114,9 @@ - To provide easy access to, and manipulation of, a data set. The following example defines an array of objects that contain the names of students, their average test scores, and the number of tests taken. The array is passed to the `ComputeStatistics` method, which calculates the mean and standard deviation of the test scores. - :::code language="csharp" source="~/snippets/csharp/System/TupleT1,T2,T3/Overview/example1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/TupleT1,T2,T3/Overview/example1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/TupleT1,T2,T3/Overview/example1.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/TupleT1,T2,T3/Overview/example1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/TupleT1,T2,T3/Overview/example1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/System/TupleT1,T2,T3/Overview/example1.vb" id="Snippet1"::: - To return multiple values from a method without the use of `out` parameters (in C#) or `ByRef` parameters (in Visual Basic). For example, the previous example returns its summary test score statistics in a object. diff --git a/xml/System/Tuple`4.xml b/xml/System/Tuple`4.xml index adc73534e86..887165ff8cb 100644 --- a/xml/System/Tuple`4.xml +++ b/xml/System/Tuple`4.xml @@ -123,9 +123,9 @@ - To provide easy access to, and manipulation of, a data set. The following example defines an array of objects that contain the names of baseball pitchers, the number of innings they pitched, and the number of earned runs (runs that scored without fielding errors), and hits that they gave up. The array is passed to the `ComputeStatistics` method, which calculates each pitcher's earned run average (the average number of runs given up in a nine-inning game), and the average number of hits given up per inning. The method also uses these two averages to compute a hypothetical effectiveness average. - :::code language="csharp" source="~/snippets/csharp/System/TupleT1,T2,T3,T4/Overview/example1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/TupleT1,T2,T3,T4/Overview/example1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/TupleT1,T2,T3,T4/Overview/example1.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/TupleT1,T2,T3,T4/Overview/example1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/TupleT1,T2,T3,T4/Overview/example1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/System/TupleT1,T2,T3,T4/Overview/example1.vb" id="Snippet1"::: - To return multiple values from a method without the use of `out` parameters (in C#) or `ByRef` parameters (in Visual Basic). For example, the previous example returns its computed statistics, along with the name of the pitcher, in an array of objects. diff --git a/xml/System/Tuple`5.xml b/xml/System/Tuple`5.xml index 1e24a87df2a..af13290561c 100644 --- a/xml/System/Tuple`5.xml +++ b/xml/System/Tuple`5.xml @@ -132,9 +132,9 @@ - To provide easy access to, and manipulation of, a data set. The following example defines an array of objects that contain the names of running backs in American football, the number of games in which they played, and the number of carries, total yards gained, and touchdowns scored during those games. The array is passed to the `ComputeStatistics` method, which calculates each running back's number of carries per game, average yards per game, average yards per carry, and average number of touchdowns per attempt. - :::code language="csharp" source="~/snippets/csharp/System/TupleT1,T2,T3,T4,T5/Overview/example1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/TupleT1,T2,T3,T4,T5/Overview/example1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/TupleT1,T2,T3,T4,T5/Overview/example1.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/TupleT1,T2,T3,T4,T5/Overview/example1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/TupleT1,T2,T3,T4,T5/Overview/example1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/System/TupleT1,T2,T3,T4,T5/Overview/example1.vb" id="Snippet1"::: - To return multiple values from a method without the use of `out` parameters (in C#) or `ByRef` parameters (in Visual Basic). For example, the previous example returns its computed statistics, along with the name of the player, in an array of objects. diff --git a/xml/System/Tuple`6.xml b/xml/System/Tuple`6.xml index 5593ba51b1d..00b56ec83bd 100644 --- a/xml/System/Tuple`6.xml +++ b/xml/System/Tuple`6.xml @@ -141,9 +141,9 @@ - To provide easy access to, and manipulation of, a data set. The following example defines a object that contains population data for New York City for each census from 1960 through 2000. The sextuple is passed to the `ComputePopulationChange` method, which calculates the annual rate of change between censuses, as well as the annual rate of change for the entire 50 year period. - :::code language="csharp" source="~/snippets/csharp/System/TupleT1,T2,T3,T4,T5,T6/Overview/example1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/TupleT1,T2,T3,T4,T5,T6/Overview/example1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/TupleT1,T2,T3,T4,T5,T6/Overview/example1.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/TupleT1,T2,T3,T4,T5,T6/Overview/example1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/TupleT1,T2,T3,T4,T5,T6/Overview/example1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/System/TupleT1,T2,T3,T4,T5,T6/Overview/example1.vb" id="Snippet1"::: - To return multiple values from a method without the use of `out` parameters (in C#) or `ByRef` parameters (in Visual Basic). For example, the previous example returns its computed statistics, along with the city name, in a object. diff --git a/xml/System/Tuple`7.xml b/xml/System/Tuple`7.xml index 30698adf694..76f11a1fec4 100644 --- a/xml/System/Tuple`7.xml +++ b/xml/System/Tuple`7.xml @@ -150,9 +150,9 @@ - To provide easy access to, and manipulation of, a data set. The following example defines a object that contains population data for New York City for each census from 1950 through 2000. The septuple is passed to the `ComputePopulationChange` method, which calculates the annual rate of change between censuses, as well as the annual rate of change for the entire 60 year period. - :::code language="csharp" source="~/snippets/csharp/System/TupleT1,T2,T3,T4,T5,T6,T7/Overview/example1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/TupleT1,T2,T3,T4,T5,T6,T7/Overview/example1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/TupleT1,T2,T3,T4,T5,T6,T7/Overview/example1.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/TupleT1,T2,T3,T4,T5,T6,T7/Overview/example1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/TupleT1,T2,T3,T4,T5,T6,T7/Overview/example1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/System/TupleT1,T2,T3,T4,T5,T6,T7/Overview/example1.vb" id="Snippet1"::: - To return multiple values from a method without the use of `out` parameters (in C#) or `ByRef` parameters (in Visual Basic). For example, the previous example returns its computed statistics, along with the city name, in a object. diff --git a/xml/System/Type.xml b/xml/System/Type.xml index 67894475b71..32f5683d7f8 100644 --- a/xml/System/Type.xml +++ b/xml/System/Type.xml @@ -1609,29 +1609,29 @@ The `filter` argument can be a custom delegate of type object represents a type parameter of a generic type. - The following example retrieves the type parameter of the type and attempts to display its property. + The following example retrieves the type parameter of the type and attempts to display its property. - :::code language="csharp" source="~/snippets/csharp/System/Type/FullName/Fullname3.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Type/FullName/Fullname3.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System/Type/FullName/Fullname3.vb" id="Snippet3"::: + :::code language="csharp" source="~/snippets/csharp/System/Type/FullName/Fullname3.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Type/FullName/Fullname3.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/System/Type/FullName/Fullname3.vb" id="Snippet3"::: - The current object represents an array type, a pointer type, or a `byref` type that is based on a generic type parameter. - The following example defines a generic type, `Generictype1`, with three methods: `Display(T[])`, which is passed an array of type T; `HandleT(T)`, which is passed a T object; and `ChangeValue(ref T)`, which is passed a T object by reference. Because C# and Visual Basic do not allow us to define T as a pointer in the `HandleT` method, we have to call the method on the object that represents the method's parameter type to create a pointer to a generic type. The output from the example shows that in all three cases, the property is `null`. + The following example defines a generic type, `Generictype1`, with three methods: `Display(T[])`, which is passed an array of type T; `HandleT(T)`, which is passed a T object; and `ChangeValue(ref T)`, which is passed a T object by reference. Because C# and Visual Basic do not allow us to define T as a pointer in the `HandleT` method, we have to call the method on the object that represents the method's parameter type to create a pointer to a generic type. The output from the example shows that in all three cases, the property is `null`. - :::code language="csharp" source="~/snippets/csharp/System/Type/FullName/Fullname4.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Type/FullName/Fullname4.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System/Type/FullName/FullName4.vb" id="Snippet4"::: + :::code language="csharp" source="~/snippets/csharp/System/Type/FullName/Fullname4.cs" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Type/FullName/Fullname4.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/System/Type/FullName/FullName4.vb" id="Snippet4"::: - The current type contains generic type parameters that have not been replaced by specific types (that is, the property returns `true`), but the type is not a generic type definition (that is, the property returns `false` - In the following example, `Derived` inherits from `Base`. The property obtains the object that represents the base type of `Derived`, and its property returns `null`. + In the following example, `Derived` inherits from `Base`. The property obtains the object that represents the base type of `Derived`, and its property returns `null`. - :::code language="csharp" source="~/snippets/csharp/System/Type/FullName/Fullname5.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Type/FullName/Fullname5.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System/Type/FullName/FullName5.vb" id="Snippet5"::: + :::code language="csharp" source="~/snippets/csharp/System/Type/FullName/Fullname5.cs" id="Snippet5"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Type/FullName/Fullname5.fs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/System/Type/FullName/FullName5.vb" id="Snippet5"::: - To get a that is not `null`, you can use the method to get the generic type definition, as the example illustrates. + To get a that is not `null`, you can use the method to get the generic type definition, as the example illustrates. This property is read-only. diff --git a/xml/System/TypeInitializationException.xml b/xml/System/TypeInitializationException.xml index fe0d550654f..c2025ecda5e 100644 --- a/xml/System/TypeInitializationException.xml +++ b/xml/System/TypeInitializationException.xml @@ -90,7 +90,7 @@ Most commonly, a exception is thrown w - The type has `static` (in C# or F#) or `Shared` (in Visual Basic) variables that are declared and initialized in a single statement. In this case, the language compiler generates a static constructor for the type. For instance, when the C# and VB compilers compile the following example, they generate the IL for a static constructor that is similar to this: - ```il + ```il .method private specialname rtspecialname static void .cctor() cil managed { @@ -101,7 +101,7 @@ Most commonly, a exception is thrown w IL_0006: stsfld class TestClass Example::test IL_000b: ret } // end of method Example::.cctor - ``` + ``` The following example shows a exception thrown by a compiler-generated static constructor. The `Example` class includes a `static` (in C#) or `Shared` (in Visual Basic) field of type `TestClass` that is instantiated by passing a value of 3 to its class constructor. That value, however, is illegal; only values of 0 or 1 are permitted. As a result, the `TestClass` class constructor throws an . Since this exception is not handled, it is wrapped in a exception.