From 9350b9fb455ed3e6f7be29512f2ddeb53670371b Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 30 Mar 2026 16:02:27 -0700 Subject: [PATCH 1/4] System.T* --- xml/System.Text.Encodings.Web/TextEncoder.xml | 18 +- .../ReferenceHandler.xml | 4 +- xml/System.Text.Json/JsonDocument.xml | 6 +- .../JsonElement+ArrayEnumerator.xml | 2 +- .../JsonElement+ObjectEnumerator.xml | 2 +- .../JsonSerializerOptions.xml | 2 +- xml/System.Text.Json/Utf8JsonReader.xml | 64 +-- xml/System.Text.Json/Utf8JsonWriter.xml | 2 +- .../Capture.xml | 4 +- .../CaptureCollection.xml | 30 +- .../GroupCollection.xml | 30 +- xml/System.Text.RegularExpressions/Match.xml | 22 +- .../MatchCollection.xml | 44 +- .../MatchEvaluator.xml | 4 +- xml/System.Text.RegularExpressions/Regex.xml | 156 +++--- .../RegexCompilationInfo.xml | 26 +- .../RegexMatchTimeoutException.xml | 14 +- .../RegexOptions.xml | 14 +- .../RegexRunnerFactory.xml | 10 +- xml/System.Text.Unicode/UnicodeRange.xml | 16 +- xml/System.Text/ASCIIEncoding.xml | 90 ++-- xml/System.Text/CodePagesEncodingProvider.xml | 22 +- xml/System.Text/Decoder.xml | 56 +- xml/System.Text/DecoderExceptionFallback.xml | 6 +- .../DecoderExceptionFallbackBuffer.xml | 8 +- xml/System.Text/DecoderFallback.xml | 10 +- xml/System.Text/DecoderFallbackBuffer.xml | 16 +- .../DecoderReplacementFallback.xml | 2 +- .../DecoderReplacementFallbackBuffer.xml | 8 +- xml/System.Text/Encoder.xml | 42 +- xml/System.Text/EncoderExceptionFallback.xml | 6 +- .../EncoderExceptionFallbackBuffer.xml | 10 +- xml/System.Text/EncoderFallback.xml | 10 +- xml/System.Text/EncoderFallbackBuffer.xml | 18 +- .../EncoderReplacementFallback.xml | 2 +- .../EncoderReplacementFallbackBuffer.xml | 10 +- xml/System.Text/Encoding.xml | 504 +++++++++--------- xml/System.Text/EncodingInfo.xml | 18 +- xml/System.Text/EncodingProvider.xml | 20 +- xml/System.Text/Rune.xml | 26 +- xml/System.Text/SpanRuneEnumerator.xml | 2 +- .../StringBuilder+ChunkEnumerator.xml | 4 +- xml/System.Text/StringBuilder.xml | 178 +++---- xml/System.Text/StringRuneEnumerator.xml | 2 +- xml/System.Text/UTF32Encoding.xml | 110 ++-- xml/System.Text/UTF7Encoding.xml | 82 +-- xml/System.Text/UTF8Encoding.xml | 150 +++--- xml/System.Text/UnicodeEncoding.xml | 134 ++--- .../ChannelReader`1.xml | 6 +- .../ActionBlock`1.xml | 18 +- .../BatchBlock`1.xml | 168 +++--- .../BatchedJoinBlock`2.xml | 80 +-- .../BatchedJoinBlock`3.xml | 78 +-- .../BroadcastBlock`1.xml | 140 ++--- .../BufferBlock`1.xml | 136 ++--- .../DataflowBlock.xml | 6 +- .../DataflowBlockOptions.xml | 50 +- .../ExecutionDataflowBlockOptions.xml | 48 +- .../GroupingDataflowBlockOptions.xml | 40 +- .../IDataflowBlock.xml | 40 +- .../ISourceBlock`1.xml | 52 +- .../JoinBlock`2.xml | 86 +-- .../JoinBlock`3.xml | 94 ++-- .../TransformBlock`2.xml | 162 +++--- .../TransformManyBlock`2.xml | 166 +++--- .../WriteOnceBlock`1.xml | 136 ++--- .../ValueTaskSourceOnCompletedFlags.xml | 4 +- .../ConcurrentExclusiveSchedulerPair.xml | 4 +- xml/System.Threading.Tasks/Parallel.xml | 70 +-- .../ParallelLoopResult.xml | 20 +- .../ParallelLoopState.xml | 52 +- .../ParallelOptions.xml | 8 +- xml/System.Threading.Tasks/Task.xml | 206 +++---- .../TaskCanceledException.xml | 12 +- .../TaskCompletionSource`1.xml | 26 +- .../TaskCreationOptions.xml | 10 +- xml/System.Threading.Tasks/TaskExtensions.xml | 34 +- xml/System.Threading.Tasks/TaskFactory.xml | 160 +++--- xml/System.Threading.Tasks/TaskFactory`1.xml | 48 +- xml/System.Threading.Tasks/TaskScheduler.xml | 10 +- .../TaskSchedulerException.xml | 12 +- xml/System.Threading.Tasks/Task`1.xml | 86 +-- .../UnobservedTaskExceptionEventArgs.xml | 2 +- xml/System.Threading.Tasks/ValueTask.xml | 26 +- xml/System.Threading.Tasks/ValueTask`1.xml | 32 +- .../AbandonedMutexException.xml | 60 +-- xml/System.Threading/AsyncFlowControl.xml | 64 +-- .../AsyncLocalValueChangedArgs`1.xml | 4 +- xml/System.Threading/AsyncLocal`1.xml | 6 +- xml/System.Threading/AutoResetEvent.xml | 16 +- xml/System.Threading/Barrier.xml | 152 +++--- .../BarrierPostPhaseException.xml | 12 +- xml/System.Threading/CancellationToken.xml | 16 +- .../CancellationTokenSource.xml | 28 +- xml/System.Threading/CompressedStack.xml | 88 +-- xml/System.Threading/ContextCallback.xml | 14 +- xml/System.Threading/CountdownEvent.xml | 6 +- xml/System.Threading/EventResetMode.xml | 4 +- xml/System.Threading/EventWaitHandle.xml | 46 +- xml/System.Threading/ExecutionContext.xml | 14 +- xml/System.Threading/HostExecutionContext.xml | 2 +- .../HostExecutionContextManager.xml | 8 +- xml/System.Threading/Interlocked.xml | 50 +- xml/System.Threading/LazyThreadSafetyMode.xml | 6 +- xml/System.Threading/Lock+Scope.xml | 6 +- xml/System.Threading/Lock.xml | 8 +- xml/System.Threading/LockCookie.xml | 6 +- .../LockRecursionException.xml | 12 +- xml/System.Threading/ManualResetEvent.xml | 14 +- xml/System.Threading/ManualResetEventSlim.xml | 108 ++-- xml/System.Threading/Monitor.xml | 88 +-- xml/System.Threading/Mutex.xml | 116 ++-- xml/System.Threading/Overlapped.xml | 30 +- .../ParameterizedThreadStart.xml | 12 +- xml/System.Threading/PeriodicTimer.xml | 36 +- .../PreAllocatedOverlapped.xml | 16 +- xml/System.Threading/ReaderWriterLock.xml | 68 +-- xml/System.Threading/ReaderWriterLockSlim.xml | 56 +- xml/System.Threading/RegisteredWaitHandle.xml | 22 +- xml/System.Threading/Semaphore.xml | 108 ++-- .../SemaphoreFullException.xml | 14 +- xml/System.Threading/SemaphoreSlim.xml | 26 +- xml/System.Threading/SpinLock.xml | 18 +- xml/System.Threading/SpinWait.xml | 68 +-- .../SynchronizationContext.xml | 8 +- .../SynchronizationLockException.xml | 16 +- xml/System.Threading/Thread.xml | 184 +++---- xml/System.Threading/ThreadAbortException.xml | 10 +- .../ThreadInterruptedException.xml | 16 +- xml/System.Threading/ThreadLocal`1.xml | 24 +- xml/System.Threading/ThreadPool.xml | 126 ++--- .../ThreadPoolBoundHandle.xml | 72 +-- xml/System.Threading/ThreadStart.xml | 4 +- xml/System.Threading/ThreadState.xml | 24 +- xml/System.Threading/ThreadStateException.xml | 16 +- xml/System.Threading/Timeout.xml | 8 +- xml/System.Threading/Timer.xml | 60 +-- xml/System.Threading/TimerCallback.xml | 6 +- xml/System.Threading/Volatile.xml | 8 +- xml/System.Threading/WaitCallback.xml | 28 +- xml/System.Threading/WaitHandle.xml | 90 ++-- .../WaitHandleCannotBeOpenedException.xml | 10 +- xml/System.Threading/WaitHandleExtensions.xml | 4 +- xml/System.Threading/WaitOrTimerCallback.xml | 16 +- xml/System.Timers/ElapsedEventArgs.xml | 2 +- xml/System.Timers/Timer.xml | 84 +-- .../DefaultSettingsSection.xml | 74 +-- .../CommittableTransaction.xml | 12 +- .../DependentCloneOption.xml | 24 +- .../DependentTransaction.xml | 54 +- xml/System.Transactions/Enlistment.xml | 14 +- xml/System.Transactions/EnlistmentOptions.xml | 22 +- .../HostCurrentTransactionCallback.xml | 10 +- .../IEnlistmentNotification.xml | 32 +- .../IPromotableSinglePhaseNotification.xml | 8 +- .../ISinglePhaseNotification.xml | 44 +- .../ITransactionPromoter.xml | 20 +- .../PreparingEnlistment.xml | 12 +- .../SinglePhaseEnlistment.xml | 50 +- xml/System.Transactions/Transaction.xml | 16 +- .../TransactionAbortedException.xml | 14 +- .../TransactionInterop.xml | 16 +- .../TransactionManager.xml | 10 +- .../TransactionOptions.xml | 24 +- .../TransactionPromotionException.xml | 10 +- xml/System.Transactions/TransactionScope.xml | 14 +- .../TransactionScopeAsyncFlowOption.xml | 10 +- 167 files changed, 3539 insertions(+), 3539 deletions(-) diff --git a/xml/System.Text.Encodings.Web/TextEncoder.xml b/xml/System.Text.Encodings.Web/TextEncoder.xml index e9c03077b07..8cf4984f278 100644 --- a/xml/System.Text.Encodings.Web/TextEncoder.xml +++ b/xml/System.Text.Encodings.Web/TextEncoder.xml @@ -29,12 +29,12 @@ The base class of web encoders. - , , and properties. +## Remarks + TextEncoder subclasses can be used to do HTML encoding, URI encoding, and JavaScript encoding. Instances of such subclasses can be accessed using the , , and properties. - The source code for this type is available in the [System.Text.Encodings.Web project](https://github.com/dotnet/runtime/tree/main/src/libraries/System.Text.Encodings.Web) on GitHub. Unit tests that can also serve as code examples are found in the [System.Text.Encodings.Web/tests](https://github.com/dotnet/runtime/tree/main/src/libraries/System.Text.Encodings.Web/tests) folder on GitHub. + The source code for this type is available in the [System.Text.Encodings.Web project](https://github.com/dotnet/runtime/tree/main/src/libraries/System.Text.Encodings.Web) on GitHub. Unit tests that can also serve as code examples are found in the [System.Text.Encodings.Web/tests](https://github.com/dotnet/runtime/tree/main/src/libraries/System.Text.Encodings.Web/tests) folder on GitHub. ]]> @@ -380,9 +380,9 @@ The `utf8Source` and `utf8Destination` buffers must not overlap. Finds the index of the first character to encode. The index of the first character to encode. - @@ -513,10 +513,10 @@ The `utf8Source` and `utf8Destination` buffers must not overlap. if is too small to fit the encoded text; otherwise, returns . - overloads should be used instead. Implementations of the class must be thread-safe and stateless. +## Remarks + This method is seldom called directly. One of the overloads should be used instead. Implementations of the class must be thread-safe and stateless. ]]> diff --git a/xml/System.Text.Json.Serialization/ReferenceHandler.xml b/xml/System.Text.Json.Serialization/ReferenceHandler.xml index 33ff49b985d..c95994a2463 100644 --- a/xml/System.Text.Json.Serialization/ReferenceHandler.xml +++ b/xml/System.Text.Json.Serialization/ReferenceHandler.xml @@ -152,14 +152,14 @@ * For JSON objects that don't contain any metadata properties, the deserialization behavior is identical to not using `Preserve`. * For value types, the `$id` metadata property is ignored. A is thrown if a `$ref` metadata property is found within the JSON object. * For enumerable value types, the `$values` metadata property is ignored. - + * For the metadata properties within the JSON to be considered well-formed, they must follow these rules: * Unless is set to `true`, the `$id` metadata property must be the first property in the JSON object. * A JSON object that contains a `$ref` metadata property must not contain any other properties. * The value of the `$ref` metadata property must refer to an `$id` that has appeared earlier in the JSON. * The value of the `$id` and `$ref` metadata properties must be a JSON string. - * For enumerable types, such as , the JSON array must be nested within a JSON object containing an `$id` and `$values` metadata property, in that order. (However, the order is not important if is set to `true`.) + * For enumerable types, such as , the JSON array must be nested within a JSON object containing an `$id` and `$values` metadata property, in that order. (However, the order is not important if is set to `true`.) * For enumerable types, the `$values` metadata property must be a JSON array. * The `$values` metadata property is only valid when referring to enumerable types. diff --git a/xml/System.Text.Json/JsonDocument.xml b/xml/System.Text.Json/JsonDocument.xml index db8235911f9..fc324661842 100644 --- a/xml/System.Text.Json/JsonDocument.xml +++ b/xml/System.Text.Json/JsonDocument.xml @@ -115,7 +115,7 @@ For more information, see [How to use the JSON DOM, Utf8JsonReader, and Utf8Json ## Remarks -The may be used for the entire lifetime of the JsonDocument object, and the caller must ensure that the data therein does not change during the object lifetime. +The may be used for the entire lifetime of the JsonDocument object, and the caller must ensure that the data therein does not change during the object lifetime. Because the input is considered to be text, a UTF-8 Byte-Order-Mark (BOM) must not be present. ]]> @@ -204,7 +204,7 @@ Because the input is considered to be text, a UTF-8 Byte-Order-Mark (BOM) must n value will be used for the entire lifetime of the JsonDocument object, and the caller must ensure that the data therein does not change during the object lifetime. +The value will be used for the entire lifetime of the JsonDocument object, and the caller must ensure that the data therein does not change during the object lifetime. Because the input is considered to be text, a UTF-8 Byte-Order-Mark (BOM) must not be present. ]]> @@ -264,7 +264,7 @@ Because the input is considered to be text, a UTF-8 Byte-Order-Mark (BOM) must n ## Remarks -The value may be used for the entire lifetime of the JsonDocument object, and the caller must ensure that the data therein does not change during the object lifetime. +The value may be used for the entire lifetime of the JsonDocument object, and the caller must ensure that the data therein does not change during the object lifetime. ]]> diff --git a/xml/System.Text.Json/JsonElement+ArrayEnumerator.xml b/xml/System.Text.Json/JsonElement+ArrayEnumerator.xml index 0eedd9e801b..9dd7711b1d6 100644 --- a/xml/System.Text.Json/JsonElement+ArrayEnumerator.xml +++ b/xml/System.Text.Json/JsonElement+ArrayEnumerator.xml @@ -250,7 +250,7 @@ ## Remarks -This member is an explicit interface member implementation. It can be used only when the instance is cast to an [IEnumerable\]( instance is cast to an [IEnumerable\]( diff --git a/xml/System.Text.Json/JsonElement+ObjectEnumerator.xml b/xml/System.Text.Json/JsonElement+ObjectEnumerator.xml index 8f3b3d17f0c..14077bbd188 100644 --- a/xml/System.Text.Json/JsonElement+ObjectEnumerator.xml +++ b/xml/System.Text.Json/JsonElement+ObjectEnumerator.xml @@ -256,7 +256,7 @@ The enumerator will enumerate the properties in the order they are declared, and instance is cast to an [IEnumerator\](xref:System.Collections.Generic.IEnumerator%601) interface. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an [IEnumerator\](xref:System.Collections.Generic.IEnumerator`1) interface. ]]> diff --git a/xml/System.Text.Json/JsonSerializerOptions.xml b/xml/System.Text.Json/JsonSerializerOptions.xml index eb44068fb8f..3497339c510 100644 --- a/xml/System.Text.Json/JsonSerializerOptions.xml +++ b/xml/System.Text.Json/JsonSerializerOptions.xml @@ -634,7 +634,7 @@ For more information, see [How to write custom converters for JSON serialization ## Remarks -Returned metadata can be downcast to and used with the relevant overloads. +Returned metadata can be downcast to and used with the relevant overloads. If the instance is locked for modification, the method returns a cached instance for the metadata. diff --git a/xml/System.Text.Json/Utf8JsonReader.xml b/xml/System.Text.Json/Utf8JsonReader.xml index 6294771de3f..754b3109a95 100644 --- a/xml/System.Text.Json/Utf8JsonReader.xml +++ b/xml/System.Text.Json/Utf8JsonReader.xml @@ -93,7 +93,7 @@ For more information, see [Use Utf8JsonReader](/dotnet/standard/serialization/sy Since this type is a ref struct, it is a stack-only type, and all the limitations of ref structs apply to it. This constructor assumes that the entire JSON payload is contained in `jsonData`; it is equivalent to = `true`. - + ]]> @@ -133,7 +133,7 @@ This constructor assumes that the entire JSON payload is contained in `jsonData` Since this type is a ref struct, it is a stack-only type, and all the limitations of ref structs apply to it. This constructor assumes that the entire JSON payload is contained in `jsonData`; it is equivalent to = `true`. - + ]]> @@ -297,7 +297,7 @@ This is the reason why the constructor accepts a , this method does not support . - + This method will throw an if the destination buffer is too small to hold the unescaped value. You can determine an appropriately sized buffer by consulting the length of either or , since the unescaped result is always less than or equal to the length of the encoded strings. ]]> @@ -349,7 +349,7 @@ The JSON string contains invalid UTF-8 bytes or invalid UTF-16 surrogates., this method does not support . - + This method will throw an if the destination buffer is too small to hold the unescaped value. You can determine an appropriately sized buffer by consulting the length of either or , since the unescaped result is always less than or equal to the length of the encoded strings. ]]> @@ -512,7 +512,7 @@ Unlike the , which is a ref struct, the st To be added. The value of the JSON token is not a . The numeric format of the JSON token value is incorrect (for example, it contains a fractional value or is written in scientific notation). - + -or- The JSON token value represents a number less than Byte.MinValue or greater than Byte.MaxValue. @@ -630,9 +630,9 @@ This method only creates a representation of JSON strings The value of the JSON token isn't a . The JSON token value cannot be read as a . - + -or- - + The entire UTF-8 encoded token value cannot be parsed to a value. -or- @@ -681,7 +681,7 @@ This method only creates a representation of JSON s The JSON token value cannot be read as a . -or- - + The entire UTF-8 encoded token value cannot be parsed to a value. -or- @@ -786,7 +786,7 @@ The JSON token value is of an unsupported format. To be added. The value of the JSON token isn't a . The JSON token value is in an unsupported format for a Guid. - + -or- The entire UTF-8 encoded token value cannot be parsed to a value. @@ -823,7 +823,7 @@ The entire UTF-8 encoded token value cannot be parsed to a The value of the JSON token is not a . The numeric format of the JSON token value is incorrect (for example, it contains a fractional value or is written in scientific notation). - + -or- The JSON token value represents a number less than Int16.MinValue or greater than Int16.MaxValue. @@ -860,7 +860,7 @@ The JSON token value represents a number less than The JSON token value isn't a . The JSON token value is of the incorrect numeric format. For example, it contains a decimal or is written in scientific notation. - + -or- The JSON token value represents a number less than Int32.MinValue or greater than Int32.MaxValue. @@ -897,7 +897,7 @@ The JSON token value represents a number less than The JSON token value isn't a . The JSON token value is of the incorrect numeric format. For example, it contains a decimal or is written in scientific notation. - + -or- The JSON token value represents a number less than Int64.MinValue or greater than Int64.MaxValue. @@ -940,7 +940,7 @@ The JSON token value represents a number less than The value of the JSON token is not a . The numeric format of the JSON token value is incorrect (for example, it contains a fractional value or is written in scientific notation). - + -or- The JSON token value represents a number less than SByte.MinValue or greater than SByte.MaxValue. @@ -1015,7 +1015,7 @@ The JSON token value represents a number less than The value of the JSON token is not a . The numeric format of the JSON token value is incorrect (for example, it contains a fractional value or is written in scientific notation). - + -or- The JSON token value represents a number less than UInt16.MinValue or greater than UInt16.MaxValue. @@ -1149,7 +1149,7 @@ The JSON token value represents a number less than The JSON token value isn't a . The JSON token value is of the incorrect numeric format. For example, it contains a decimal or is written in scientific notation. - + -or- The JSON token value represents a number less than UInt64.MinValue or greater than UInt64.MaxValue. @@ -1303,7 +1303,7 @@ For input data within a `ReadOnlySpan`, this always returns `false`. For i if the token was read successfully; otherwise, . To be added. An invalid JSON token according to the JSON RFC is encountered. - + -or- The current depth exceeds the recursive limit set by the maximum depth. @@ -1343,7 +1343,7 @@ The current depth exceeds the recursive limit set by the maximum depth. is , the reader first moves to the property value. When (originally, or after advancing) is or , the reader advances to the matching or . - + For all other token types, the reader does not move. After the next call to , the reader will be at the next value (when in an array), the next property name (when in an object), or the end array/object token. ]]> @@ -1712,7 +1712,7 @@ This method only creates a representation of JSON s ## Remarks -This method only parses values with hyphens and without any surrounding decorations. +This method only parses values with hyphens and without any surrounding decorations. ]]> @@ -2066,17 +2066,17 @@ This method only parses values with hyphens and without any s ## Remarks If the reader did not have enough data to completely skip the children of the current token, it will be reset to the state it was in before the method was called. - + When is , the reader first moves to the property value. When (originally, or after advancing) is or , the reader advances to the matching or . - + For all other token types, the reader does not move. After the next call to , the reader will be at the next value (when in an array), the next property name (when in an object), or the end array/object token. ]]> An invalid JSON token was encountered while skipping, according to the JSON RFC. - + -or - The current depth exceeds the recursive limit set by the maximum depth. @@ -2152,14 +2152,14 @@ The current depth exceeds the recursive limit set by the maximum depth. contains the sliced value since it can be represented as a span. Otherwise, `ValueSequence` contains the token value. -If is `false`, `ValueSequence` is empty. +If is `false`, `ValueSequence` is empty. Therefore, only access `ValueSequence` if is `true`. Otherwise, the token value must be accessed from . There is no guarantee that this property will always contain well-formed data. If the input JSON passed in to the `Utf8JsonReader` contains invalid UTF-8 bytes within JSON string tokens, this property will return back those invalid UTF-8 bytes as is. Therefore, if the input is untrusted or not previously validated, call to get the JSON string token. -Since this property returns the raw bytes, avoid using it for text comparison. Instead call , which unescapes the text if necessary. +Since this property returns the raw bytes, avoid using it for text comparison. Instead call , which unescapes the text if necessary. ]]> @@ -2204,14 +2204,14 @@ Since this property returns the raw bytes, avoid using it for text comparison. I If the JSON is provided within a ReadOnlySequence<byte> and the slice that represents the token value fits in a single segment, then `ValueSpan` contains the sliced value since it can be represented as a span. Otherwise, contains the token value. -If is `true`, `ValueSpan` is empty. +If is `true`, `ValueSpan` is empty. Therefore, only access `ValueSpan` if is `false`. Otherwise, the token value must be accessed from . There is no guarantee that this property will always contain well-formed data. If the input JSON passed in to the `Utf8JsonReader` contains invalid UTF-8 bytes within JSON string tokens, this property will return back those invalid UTF-8 bytes as is. Therefore, if the input is untrusted or not previously validated, call to get the JSON string token. -Since this property returns the raw bytes, avoid using it for text comparison. Instead call which unescapes the text if necessary. +Since this property returns the raw bytes, avoid using it for text comparison. Instead call which unescapes the text if necessary. ]]> @@ -2261,9 +2261,9 @@ Since this property returns the raw bytes, avoid using it for text comparison. I ## Remarks The lookup text must be valid UTF-8 text. Otherwise, this method could return `true` if the source has a string token containing invalid UTF-8 text that matches. - + The comparison of the JSON token value in the source and the lookup text is done by first unescaping the JSON value in source, if required. The lookup text is matched as is, without any modifications to it. - + ]]> The JSON token is not a JSON string (that is, it is not or ). @@ -2313,9 +2313,9 @@ The comparison of the JSON token value in the source and the lookup text is done ## Remarks If the lookup text is invalid or incomplete UTF-16 text (that is, unpaired surrogates), the method returns `false` since you can't have invalid UTF-16 within the JSON payload. - + The comparison of the JSON token value in the source and the lookup text is done by first unescaping the JSON value in source, if required. The lookup text is matched as is, without any modifications to it. - + ]]> The JSON token is not a JSON string (that is, it is not or ). @@ -2366,9 +2366,9 @@ The comparison of the JSON token value in the source and the lookup text is done ## Remarks If the lookup text is invalid or incomplete UTF-16 text (that is, unpaired surrogates), the method returns `false` since you can't have invalid UTF-16 within the JSON payload. - + The comparison of the JSON token value in the source and the lookup text is done by first unescaping the JSON value in source, if required. The lookup text is matched as is, without any modifications to it. - + ]]> The JSON token is not a JSON string (that is, it is not or ). diff --git a/xml/System.Text.Json/Utf8JsonWriter.xml b/xml/System.Text.Json/Utf8JsonWriter.xml index 74246c15cb6..c42cd0d20cd 100644 --- a/xml/System.Text.Json/Utf8JsonWriter.xml +++ b/xml/System.Text.Json/Utf8JsonWriter.xml @@ -151,7 +151,7 @@ For more information, see [How to write custom serializers and deserializers wit ## Remarks -In the case of an , this property indicates how much the IBufferWriter has advanced. +In the case of an , this property indicates how much the IBufferWriter has advanced. In the case of a , this property indicates how much data has been written to the stream. diff --git a/xml/System.Text.RegularExpressions/Capture.xml b/xml/System.Text.RegularExpressions/Capture.xml index 5449f728c30..49452291293 100644 --- a/xml/System.Text.RegularExpressions/Capture.xml +++ b/xml/System.Text.RegularExpressions/Capture.xml @@ -61,7 +61,7 @@ object is immutable and has no public constructor. Instances are returned through the object, which is returned by the `Match.Captures` and properties. However, the `Match.Captures` property provides information about the same match as the object. + A object is immutable and has no public constructor. Instances are returned through the object, which is returned by the `Match.Captures` and properties. However, the `Match.Captures` property provides information about the same match as the object. If you do not apply a quantifier to a capturing group, the property returns a with a single object that provides information about the same capture as the object. If you do apply a quantifier to a capturing group, the `Group.Index`, `Group.Length`, and `Group.Value` properties provide information only about the last captured group, whereas the objects in the provide information about all subexpression captures. The example provides an illustration. @@ -306,7 +306,7 @@ or method fails to find a match, the value of the returned `Match.Value` property is . If the regular expression engine is unable to match a capturing group. the value of the returned `Group.Value` property is . See the second example for an illustration. + If a call to the or method fails to find a match, the value of the returned `Match.Value` property is . If the regular expression engine is unable to match a capturing group. the value of the returned `Group.Value` property is . See the second example for an illustration. diff --git a/xml/System.Text.RegularExpressions/CaptureCollection.xml b/xml/System.Text.RegularExpressions/CaptureCollection.xml index 296b3bb2b27..1a893182f5b 100644 --- a/xml/System.Text.RegularExpressions/CaptureCollection.xml +++ b/xml/System.Text.RegularExpressions/CaptureCollection.xml @@ -113,16 +113,16 @@ - The `Match.Captures` property. In this case, the collection consists of a single object that provides information about the match as a whole. That is, the object provides the same information as the object. - To iterate through the members of the collection, you should use the collection iteration construct provided by your language (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) instead of retrieving the enumerator that is returned by the method. + To iterate through the members of the collection, you should use the collection iteration construct provided by your language (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) instead of retrieving the enumerator that is returned by the method. ## Examples - The following example compares the objects in the object returned by the and `Match.Captures` properties. It also compares objects with the objects in the returned by the property. The example uses the following two regular expressions to find matches in a single input string: + The following example compares the objects in the object returned by the and `Match.Captures` properties. It also compares objects with the objects in the returned by the property. The example uses the following two regular expressions to find matches in a single input string: - `\b\w+\W{1,2}` - This regular expression pattern identifies a word that consists of one or more word characters, followed by either one or two non-word characters such as white space or punctuation. The regular expression does not include any capturing groups. The output from the example shows that both the object and the objects returned by the and `Match.Captures` properties contain information about the same match. + This regular expression pattern identifies a word that consists of one or more word characters, followed by either one or two non-word characters such as white space or punctuation. The regular expression does not include any capturing groups. The output from the example shows that both the object and the objects returned by the and `Match.Captures` properties contain information about the same match. - `(\b\w+\W{1,2})+` @@ -191,7 +191,7 @@ Because the entire collection is copied into the array starting at the given index, the destination array must be at least as large as the collection. > [!WARNING] -> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the method instead. +> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the method instead. ]]> @@ -363,7 +363,7 @@ method to retrieve an enumerator that lets you iterate through the objects in the collection, you should use the group iteration construct (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) that is provided by your programming language. + Instead of calling the method to retrieve an enumerator that lets you iterate through the objects in the collection, you should use the group iteration construct (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) that is provided by your programming language. ]]> @@ -418,7 +418,7 @@ ## Remarks -A collection that is read-only does not allow the addition or removal of elements after the collection is created. Note that read-only in this context does not indicate whether individual elements of the collection can be modified, since the interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. +A collection that is read-only does not allow the addition or removal of elements after the collection is created. Note that read-only in this context does not indicate whether individual elements of the collection can be modified, since the interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. ]]> @@ -821,10 +821,10 @@ A collection that is read-only does not allow the addition or removal of element ## Remarks -The returned provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. - Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . - returns the same object until is called again as sets to the next element. - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. +The returned provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. + Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . + returns the same object until is called again as sets to the next element. + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. An enumerator does not have exclusive access to the collection so an enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection. Default implementations of collections in the namespace aren't synchronized. @@ -878,7 +878,7 @@ The returned provides the abil ## Remarks -If an object occurs multiple times in the list, the method always returns the first instance found. +If an object occurs multiple times in the list, the method always returns the first instance found. ]]> @@ -977,7 +977,7 @@ If an object occurs multiple times in the list, the property. Visual Basic implements as a [default](/dotnet/visual-basic/language-reference/modifiers/default) property, which provides the same indexing functionality. + The C# language uses the [this](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a [default](/dotnet/visual-basic/language-reference/modifiers/default) property, which provides the same indexing functionality. ]]> @@ -1293,7 +1293,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks -This method uses the collection's objects' and methods on `value` to determine whether `value` exists. +This method uses the collection's objects' and methods on `value` to determine whether `value` exists. ]]> @@ -1345,7 +1345,7 @@ This method uses the collection's objects' and and methods on `value` to determine whether `value` exists. +This method uses the collection's objects' and methods on `value` to determine whether `value` exists. ]]> @@ -1504,7 +1504,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]`. - The C# language uses the [this](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. + The C# language uses the [this](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. ]]> diff --git a/xml/System.Text.RegularExpressions/GroupCollection.xml b/xml/System.Text.RegularExpressions/GroupCollection.xml index deb4873af27..e3f55b27bcd 100644 --- a/xml/System.Text.RegularExpressions/GroupCollection.xml +++ b/xml/System.Text.RegularExpressions/GroupCollection.xml @@ -129,7 +129,7 @@ The collection contains one or more objects. If the match is successful, the first element in the collection contains the object that corresponds to the entire match. Each subsequent element represents a captured group, if the regular expression includes capturing groups. Matches from numbered (unnamed) capturing groups appear in numeric order before matches from named capturing groups. If the match is unsuccessful, the collection contains a single object whose property is `false` and whose property equals . For more information, see the "Grouping Constructs and Regular Expression Objects" section in the [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions) article. - To iterate through the members of the collection, you should use the collection iteration construct provided by your language (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) instead of retrieving the enumerator that is returned by the method. In addition, you can access individual numbered captured groups from the property (the indexer in C#), and you can access individual named captured groups from the property. Note that you can retrieve an array that contains the numbers and names of all capturing groups by calling the and methods, respectively. Both are instance methods and require that you instantiate a object that represents the regular expression to be matched. + To iterate through the members of the collection, you should use the collection iteration construct provided by your language (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) instead of retrieving the enumerator that is returned by the method. In addition, you can access individual numbered captured groups from the property (the indexer in C#), and you can access individual named captured groups from the property. Note that you can retrieve an array that contains the numbers and names of all capturing groups by calling the and methods, respectively. Both are instance methods and require that you instantiate a object that represents the regular expression to be matched. @@ -249,12 +249,12 @@ Because the entire collection is copied into the array starting at the given index, the destination array must be at least as large as the collection. > [!WARNING] -> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the method instead. +> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the method instead. ## Examples - The following example extracts each word from a sentence and captures it in a capturing group, The method is then used to copy the elements in each match's object to an array that contains the capturing groups from all matches. The individual captured words are then displayed to the console. + The following example extracts each word from a sentence and captures it in a capturing group, The method is then used to copy the elements in each match's object to an array that contains the capturing groups from all matches. The individual captured words are then displayed to the console. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/GroupCollection/CopyTo/copyto1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/GroupCollection/CopyTo/copyto1.vb" id="Snippet1"::: @@ -442,7 +442,7 @@ method to retrieve an enumerator that lets you iterate through the objects in the collection, you should use the group iteration construct (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) that is provided by your programming language. + Instead of calling the method to retrieve an enumerator that lets you iterate through the objects in the collection, you should use the group iteration construct (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) that is provided by your programming language. ]]> @@ -497,7 +497,7 @@ ## Remarks -A collection that is read-only does not allow the addition or removal of elements after the collection is created. Note that read-only in this context does not indicate whether individual elements of the collection can be modified, since the interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. +A collection that is read-only does not allow the addition or removal of elements after the collection is created. Note that read-only in this context does not indicate whether individual elements of the collection can be modified, since the interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. ]]> @@ -632,9 +632,9 @@ A collection that is read-only does not allow the addition or removal of element property is the index (in C#) or the default property (in Visual Basic) of the class. It allows you to enumerate the members of the collection by using a `foreach` statement in C# or a `For Each` statement in Visual Basic. + The property is the index (in C#) or the default property (in Visual Basic) of the class. It allows you to enumerate the members of the collection by using a `foreach` statement in C# or a `For Each` statement in Visual Basic. - You can also use this property to retrieve individual captured groups by their index number. You can retrieve an array that contains the numbers of all capturing groups in a regular expression by calling the instance method. You can also map named capturing groups to their numbers by calling the instance method. + You can also use this property to retrieve individual captured groups by their index number. You can retrieve an array that contains the numbers of all capturing groups in a regular expression by calling the instance method. You can also map named capturing groups to their numbers by calling the instance method. You can determine the number of items in the collection by retrieving the value of the property. Valid values for the `groupnum` parameter range from 0 to one less than the number of items in the collection. @@ -645,7 +645,7 @@ A collection that is read-only does not allow the addition or removal of element ## Examples - The following example defines a regular expression that consists of two numbered groups. The first group captures one or more consecutive digits. The second group matches a single character. Because the regular expression engine looks for zero or one occurrence of the first group, it does not always find a match even if the regular expression match is successful. The example then illustrates the result when the property is used to retrieve an unmatched group, a matched group, and a group that is not defined in the regular expression. The example defines a regular expression pattern `(\d+)*(\w)\2`, which is interpreted as shown in the following table. + The following example defines a regular expression that consists of two numbered groups. The first group captures one or more consecutive digits. The second group matches a single character. Because the regular expression engine looks for zero or one occurrence of the first group, it does not always find a match even if the regular expression match is successful. The example then illustrates the result when the property is used to retrieve an unmatched group, a matched group, and a group that is not defined in the regular expression. The example defines a regular expression pattern `(\d+)*(\w)\2`, which is interpreted as shown in the following table. |Pattern|Description| |-------------|-----------------| @@ -717,14 +717,14 @@ A collection that is read-only does not allow the addition or removal of element ## Remarks `groupName` can be either the name of a capturing group that is defined by the `(?<`*name*`>)` element in a regular expression, or the string representation of the number of a capturing group that is defined by a grouping construct. For more information about groups in regular expressions, see [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions). - You can retrieve the names of all the captured groups in a object by calling the method. You can also map the numbers of capturing groups in a regular expression to their names by calling the method. Individual names from the array can then be passed to the property to retrieve the captured string. + You can retrieve the names of all the captured groups in a object by calling the method. You can also map the numbers of capturing groups in a regular expression to their names by calling the method. Individual names from the array can then be passed to the property to retrieve the captured string. If `groupname` is not the name of a capturing group in the collection, or if `groupname` is the name of a capturing group that has not been matched in the input string, the method returns a object whose property is `false` and whose `Group.Value` property is . ## Examples - The following example defines a regular expression that consists of two named groups. The first group, `numbers`, captures one or more consecutive digits. The second group, `letter`, matches a single character. Because the regular expression engine looks for zero or one occurrence of the pattern defined by the `numbers` group, the `numbers` group is not always present even if a match is successful. The example then illustrates the result when the property is used to retrieve an unmatched group, a matched group, and a group that is not defined in the regular expression. The example defines a regular expression pattern `(?\d+)*(?\w)\k`, which is interpreted as shown in the following table. + The following example defines a regular expression that consists of two named groups. The first group, `numbers`, captures one or more consecutive digits. The second group, `letter`, matches a single character. Because the regular expression engine looks for zero or one occurrence of the pattern defined by the `numbers` group, the `numbers` group is not always present even if a match is successful. The example then illustrates the result when the property is used to retrieve an unmatched group, a matched group, and a group that is not defined in the regular expression. The example defines a regular expression pattern `(?\d+)*(?\w)\k`, which is interpreted as shown in the following table. |Pattern|Description| |-------------|-----------------| @@ -780,7 +780,7 @@ A collection that is read-only does not allow the addition or removal of element ## Remarks -The order of the keys in the enumerable collection is unspecified, but the implementation must guarantee that the keys are in the same order as the corresponding values in the enumerable collection that is returned by the property. +The order of the keys in the enumerable collection is unspecified, but the implementation must guarantee that the keys are in the same order as the corresponding values in the enumerable collection that is returned by the property. ]]> @@ -979,7 +979,7 @@ The order of the keys in the enumerable collection is unspecified, but the imple ## Remarks -This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. ]]> @@ -1172,7 +1172,7 @@ Instead of calling this method to retrieve an enumerator that lets you iterate t ## Remarks -This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. ]]> @@ -1270,7 +1270,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks -This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. ]]> @@ -1990,7 +1990,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks -This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. ]]> diff --git a/xml/System.Text.RegularExpressions/Match.xml b/xml/System.Text.RegularExpressions/Match.xml index 2148dfe122b..847181fa8ef 100644 --- a/xml/System.Text.RegularExpressions/Match.xml +++ b/xml/System.Text.RegularExpressions/Match.xml @@ -65,11 +65,11 @@ object is immutable and has no public constructor. An instance of the class is returned by the method and represents the first pattern match in a string. Subsequent matches are represented by objects returned by the method. In addition, a object that consists of zero, one, or more objects is returned by the method. + The object is immutable and has no public constructor. An instance of the class is returned by the method and represents the first pattern match in a string. Subsequent matches are represented by objects returned by the method. In addition, a object that consists of zero, one, or more objects is returned by the method. - If the method fails to match a regular expression pattern in an input string, it returns an empty object. You can then use a `foreach` construct in C# or a `For Each` construct in Visual Basic to iterate the collection. + If the method fails to match a regular expression pattern in an input string, it returns an empty object. You can then use a `foreach` construct in C# or a `For Each` construct in Visual Basic to iterate the collection. - If the method fails to match the regular expression pattern, it returns a object that is equal to . You can use the property to determine whether the match was successful. The following example provides an illustration. + If the method fails to match the regular expression pattern, it returns a object that is equal to . You can use the property to determine whether the match was successful. The following example provides an illustration. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Match/Overview/Match1.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Match/Overview/Match1.vb" id="Snippet1"::: @@ -80,9 +80,9 @@ - You can iterate the members of the object by using a `foreach` (C#) or `For Each` (Visual Basic) construct. -- You can use the property to retrieve groups by the number of the capturing group. Note that you can determine which numbered groups are present in a regular expression by calling the instance method. +- You can use the property to retrieve groups by the number of the capturing group. Note that you can determine which numbered groups are present in a regular expression by calling the instance method. -- You can use the property to retrieve groups by the name of the capturing group. Note that you can determine which named groups are present in a regular expression by calling the instance method. +- You can use the property to retrieve groups by the name of the capturing group. Note that you can determine which named groups are present in a regular expression by calling the instance method. ## Examples @@ -95,14 +95,14 @@ The following examples use the regular expression `Console\.Write(Line)?`. The r **Example 1** - The following example calls the method to retrieve all pattern matches in an input string. It then iterates the objects in the returned object to display information about each match. + The following example calls the method to retrieve all pattern matches in an input string. It then iterates the objects in the returned object to display information about each match. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Match/Overview/Match2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Match/Overview/Match2.vb" id="Snippet2"::: **Example 2** - The following example calls the and methods to retrieve one match at a time. + The following example calls the and methods to retrieve one match at a time. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Match/Overview/Match3.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Match/Overview/Match3.vb" id="Snippet3"::: @@ -166,7 +166,7 @@ The following examples use the regular expression `Console\.Write(Line)?`. The r ). + This property should not be used to determine if a match is successful. Instead, use the `Match.Success` property (which is inherited from ). ]]> @@ -286,7 +286,7 @@ The following examples use the regular expression `Console\.Write(Line)?`. The r again and passing (`Index+Length`) as the new starting position. + This method is similar to calling again and passing (`Index+Length`) as the new starting position. > [!NOTE] > This method does not modify the current instance. Instead, it returns a new object that contains information about the next match. @@ -296,7 +296,7 @@ The following examples use the regular expression `Console\.Write(Line)?`. The r ## Examples - The following example uses the method to capture regular expression matches beyond the first match. + The following example uses the method to capture regular expression matches beyond the first match. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Match/Groups/snippet8.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Match/Groups/snippet8.vb" id="Snippet8"::: @@ -365,7 +365,7 @@ The following examples use the regular expression `Console\.Write(Line)?`. The r method replaces all matches in an input string with a specified replacement pattern, the method replaces a single match with a specified replacement pattern. Because it operates on an individual match, it is also possible to perform processing on the matched string before you call the method. + Whereas the method replaces all matches in an input string with a specified replacement pattern, the method replaces a single match with a specified replacement pattern. Because it operates on an individual match, it is also possible to perform processing on the matched string before you call the method. The `replacement` parameter is a standard regular expression replacement pattern. It can consist of literal characters and regular expression substitutions. For more information, see [Substitutions](/dotnet/standard/base-types/substitutions-in-regular-expressions). diff --git a/xml/System.Text.RegularExpressions/MatchCollection.xml b/xml/System.Text.RegularExpressions/MatchCollection.xml index a4a0f059578..8544819176c 100644 --- a/xml/System.Text.RegularExpressions/MatchCollection.xml +++ b/xml/System.Text.RegularExpressions/MatchCollection.xml @@ -105,7 +105,7 @@ method returns a object. + The collection is immutable (read-only) and has no public constructor. The method returns a object. The collection contains zero or more objects. If the match is successful, the collection is populated with one object for each match found in the input string. If the match is unsuccessful, the collection contains no objects, and its property equals zero. @@ -113,13 +113,13 @@ - Direct evaluation. - The object is populated all at once, with all matches resulting from a particular call to the method. This technique is used when the collection's property is accessed. It typically is the more expensive method of populating the collection and entails a greater performance hit. + The object is populated all at once, with all matches resulting from a particular call to the method. This technique is used when the collection's property is accessed. It typically is the more expensive method of populating the collection and entails a greater performance hit. - Lazy evaluation. - The object is populated as needed on a match-by-match basis. It is equivalent to the regular expression engine calling the method repeatedly and adding each match to the collection. This technique is used when the collection is accessed through its method, or when it is accessed using the `foreach` statement (in C#) or the `For Each`...`Next` statement (in Visual Basic). + The object is populated as needed on a match-by-match basis. It is equivalent to the regular expression engine calling the method repeatedly and adding each match to the collection. This technique is used when the collection is accessed through its method, or when it is accessed using the `foreach` statement (in C#) or the `For Each`...`Next` statement (in Visual Basic). - To iterate through the members of the collection, you should use the collection iteration construct provided by your language (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) instead of retrieving the enumerator that is returned by the method. + To iterate through the members of the collection, you should use the collection iteration construct provided by your language (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) instead of retrieving the enumerator that is returned by the method. @@ -187,7 +187,7 @@ Because the collection is copied into the array starting at the given index, the destination array must be at least as large as the entire collection. > [!WARNING] -> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the method instead. +> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the method instead. Because the object is generally populated by using lazy evaluation, trying to copy the collection before it has been fully populated may throw a exception. This exception can be thrown if a time-out value for matching operations is in effect, and the attempt to find a single match exceeds that time-out interval. @@ -301,14 +301,14 @@ object by retrieving the value of the collection's property causes the regular expression engine to populate the collection using direct evaluation. ln contrast, calling the method (or using the `foreach` statement in C# and the `For Each`...`Next` statement in Visual Basic) causes the regular expression engine to populate the collection on an as needed basis using lazy evaluation. Direct evaluation can be a much more expensive method of building the collection than lazy evaluation. + Accessing individual members of the object by retrieving the value of the collection's property causes the regular expression engine to populate the collection using direct evaluation. ln contrast, calling the method (or using the `foreach` statement in C# and the `For Each`...`Next` statement in Visual Basic) causes the regular expression engine to populate the collection on an as needed basis using lazy evaluation. Direct evaluation can be a much more expensive method of building the collection than lazy evaluation. Because the object is generally populated by using lazy evaluation, trying to determine the number of elements in the collection before it has been fully populated may throw a exception. This exception can be thrown if a time-out value for matching operations is in effect, and the attempt to find a single match exceeds that time-out interval. ## Examples - The following example uses the property to determine whether the call to the method found any matches. If not, it indicates that no matches were found. Otherwise, it enumerates the matches and displays their value and the position in the input string at which they were found. + The following example uses the property to determine whether the call to the method found any matches. If not, it indicates that no matches were found. Otherwise, it enumerates the matches and displays their value and the position in the input string at which they were found. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/MatchCollection/Count/countex1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/MatchCollection/Count/countex1.vb" id="Snippet1"::: @@ -371,9 +371,9 @@ method to retrieve an enumerator that lets you iterate through the objects in the collection, you should use the group iteration construct (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) provided by your programming language. + Instead of calling the method to retrieve an enumerator that lets you iterate through the objects in the collection, you should use the group iteration construct (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) provided by your programming language. - Iterating the members of the object using the method (or the `foreach` statement in C# and the `For Each`...`Next` statement in Visual Basic) causes the regular expression engine to populate the collection on an as needed basis using lazy evaluation. This is analogous to repeatedly calling the method, and then adding the resulting match to the object. In contrast, the regular expression engine uses direct evaluation to populate the collection all at once when the property is accessed. This can be a much more expensive method of building the collection than lazy evaluation. + Iterating the members of the object using the method (or the `foreach` statement in C# and the `For Each`...`Next` statement in Visual Basic) causes the regular expression engine to populate the collection on an as needed basis using lazy evaluation. This is analogous to repeatedly calling the method, and then adding the resulting match to the object. In contrast, the regular expression engine uses direct evaluation to populate the collection all at once when the property is accessed. This can be a much more expensive method of building the collection than lazy evaluation. Because the object is generally populated by using lazy evaluation, trying to navigate to the next member of the collection may throw a exception. This exception can be thrown if a time-out value for matching operations is in effect, and the attempt to find the next match exceeds that time-out interval. @@ -431,7 +431,7 @@ ## Remarks -A collection that is read-only does not allow the addition or removal of elements after the collection is created. Note that read-only in this context does not indicate whether individual elements of the collection can be modified, since the interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. +A collection that is read-only does not allow the addition or removal of elements after the collection is created. Note that read-only in this context does not indicate whether individual elements of the collection can be modified, since the interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. ]]> @@ -549,7 +549,7 @@ A collection that is read-only does not allow the addition or removal of element ## Remarks In C#, the property is an indexer; it is not explicitly referenced in code, but instead allows the collection to be accessed as if it were an array. - Typically, individual items in the object are accessed by their index only after the total number of items in the collection has been determined from the property. However, accessing the property causes the regular expression engine to use direct evaluation to build the collection all at once. This is typically more expensive than iterating the collection using the method, the C# `foreach` statement, or the Visual Basic `For Each`...`Next` statement. + Typically, individual items in the object are accessed by their index only after the total number of items in the collection has been determined from the property. However, accessing the property causes the regular expression engine to use direct evaluation to build the collection all at once. This is typically more expensive than iterating the collection using the method, the C# `foreach` statement, or the Visual Basic `For Each`...`Next` statement. Because the object is generally populated by using lazy evaluation, trying to navigate to a specific match may throw a exception. This exception can be thrown if a time-out value for matching operations is in effect, and the attempt to find a specific match exceeds that time-out interval. @@ -718,7 +718,7 @@ huge ## Remarks - must be set to 0, and references to other objects from elements of the collection must be released. + must be set to 0, and references to other objects from elements of the collection must be released. ]]> @@ -859,10 +859,10 @@ huge ## Remarks -The returned provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. - Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . - returns the same object until is called again as sets to the next element. - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. +The returned provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. + Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . + returns the same object until is called again as sets to the next element. + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. An enumerator does not have exclusive access to the collection so an enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection. Default implementations of collections in the namespace aren't synchronized. @@ -917,7 +917,7 @@ The returned provides the abil ## Remarks -If an object occurs multiple times in the list, the method always returns the first instance found. +If an object occurs multiple times in the list, the method always returns the first instance found. ]]> @@ -1016,7 +1016,7 @@ If an object occurs multiple times in the list, the property. Visual Basic implements as a [default property](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. + The C# language uses the [this](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a [default property](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. ]]> @@ -1281,7 +1281,7 @@ This member is an explicit interface member implementation. It can be used only - Implementations of this method can vary in how they handle the and the capacity of a collection. Typically, the count is set to zero, and references to other objects from elements of the collection are also released. The capacity can be set to zero or a default value, or it can remain unchanged. + Implementations of this method can vary in how they handle the and the capacity of a collection. Typically, the count is set to zero, and references to other objects from elements of the collection are also released. The capacity can be set to zero or a default value, or it can remain unchanged. ]]> @@ -1335,7 +1335,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks -This method uses the collection's objects' and methods on `value` to determine whether `value` exists. +This method uses the collection's objects' and methods on `value` to determine whether `value` exists. ]]> @@ -1387,7 +1387,7 @@ This method uses the collection's objects' and and methods on `value` to determine whether `value` exists. +This method uses the collection's objects' and methods on `value` to determine whether `value` exists. ]]> @@ -1546,7 +1546,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]`. - The C# language uses the [this](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. + The C# language uses the [this](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. ]]> diff --git a/xml/System.Text.RegularExpressions/MatchEvaluator.xml b/xml/System.Text.RegularExpressions/MatchEvaluator.xml index 0e95e289567..920b13a8979 100644 --- a/xml/System.Text.RegularExpressions/MatchEvaluator.xml +++ b/xml/System.Text.RegularExpressions/MatchEvaluator.xml @@ -68,13 +68,13 @@ delegate method to perform a custom verification or manipulation operation for each match found by a replacement method such as . For each matched string, the method calls the delegate method with a object that represents the match. The delegate method performs whatever processing you prefer and returns a string that the method substitutes for the matched string. + You can use a delegate method to perform a custom verification or manipulation operation for each match found by a replacement method such as . For each matched string, the method calls the delegate method with a object that represents the match. The delegate method performs whatever processing you prefer and returns a string that the method substitutes for the matched string. ## Examples The following code example uses the delegate to replace every matched group of characters with the number of the match occurrence. - + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/MatchEvaluator/Overview/regexreplace.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/MatchEvaluator/Overview/regexreplace.vb" id="Snippet1"::: diff --git a/xml/System.Text.RegularExpressions/Regex.xml b/xml/System.Text.RegularExpressions/Regex.xml index d240367e846..f5d847c84d8 100644 --- a/xml/System.Text.RegularExpressions/Regex.xml +++ b/xml/System.Text.RegularExpressions/Regex.xml @@ -462,17 +462,17 @@ For more information about this API, see [Supplemental API remarks for Regex](/d The `matchTimeout` parameter specifies how long a pattern-matching method should try to find a match before it times out. If no match is found in that time interval, the pattern-matching method throws a exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the object is created. The instance pattern-matching methods that observe the `matchTimeout` time-out interval include the following: -- +- -- +- -- +- -- +- -- +- -- +- Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to stop responding when they process input that contains near matches. For more information, see [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices) and [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions). To set a reasonable time-out interval, consider the following factors: @@ -563,7 +563,7 @@ For more information about this API, see [Supplemental API remarks for Regex](/d class maintains an internal cache of compiled regular expressions used in static method calls, such as or . If the value specified in a set operation is less than the current cache size, cache entries are discarded until the cache size is equal to the specified value. + The class maintains an internal cache of compiled regular expressions used in static method calls, such as or . If the value specified in a set operation is less than the current cache size, cache entries are discarded until the cache size is equal to the specified value. By default, the cache holds 15 compiled static regular expressions. Your application typically will not have to modify the size of the cache. Use the property only when you want to turn off caching or when you have an unusually large cache. @@ -1093,13 +1093,13 @@ For more information about this API, see [Supplemental API remarks for Regex](/d Ordinarily, the code that instantiates and uses the compiled regular expression is found in an assembly or application that is separate from the code that creates the assembly. - Because the method generates a .NET Framework assembly from a method call instead of using a particular language's class definition keyword (such as `class` in C# or `Class`...`End Class` in Visual Basic), it does not allow .NET Framework attributes to be assigned to the assembly by using the development language's standard attribute syntax. The `attributes` parameter provides an alternative method for defining the attributes that apply to the assembly. For each attribute that you want to apply to the assembly, do the following: + Because the method generates a .NET Framework assembly from a method call instead of using a particular language's class definition keyword (such as `class` in C# or `Class`...`End Class` in Visual Basic), it does not allow .NET Framework attributes to be assigned to the assembly by using the development language's standard attribute syntax. The `attributes` parameter provides an alternative method for defining the attributes that apply to the assembly. For each attribute that you want to apply to the assembly, do the following: 1. Create an array of objects representing the parameter types of the attribute constructor that you want to call. 2. Retrieve a object representing the attribute class that you want to apply to the new assembly. -3. Call the method of the attribute object to retrieve a object representing the attribute constructor that you want to call. Pass the method the array of objects that represents the constructor's parameter types. +3. Call the method of the attribute object to retrieve a object representing the attribute constructor that you want to call. Pass the method the array of objects that represents the constructor's parameter types. 4. Create a array that defines the parameters to pass to the attribute's constructor. @@ -1228,13 +1228,13 @@ For more information about this API, see [Supplemental API remarks for Regex](/d Ordinarily, the code that instantiates and uses the compiled regular expression is found in an assembly or application that is separate from the code that creates the assembly. - Because the method generates a .NET Framework assembly from a method call instead of using a particular language's class definition keyword (such as `class` in C# or `Class`...`End Class` in Visual Basic), it does not allow .NET Framework attributes to be assigned to the assembly by using the development language's standard attribute syntax. The `attributes` parameter provides an alternative method for defining the attributes that apply to the assembly. For each attribute that you want to apply to the assembly, do the following: + Because the method generates a .NET Framework assembly from a method call instead of using a particular language's class definition keyword (such as `class` in C# or `Class`...`End Class` in Visual Basic), it does not allow .NET Framework attributes to be assigned to the assembly by using the development language's standard attribute syntax. The `attributes` parameter provides an alternative method for defining the attributes that apply to the assembly. For each attribute that you want to apply to the assembly, do the following: 1. Create an array of objects representing the parameter types of the attribute constructor that you want to call. 2. Retrieve a object representing the attribute class that you want to apply to the new assembly. -3. Call the method of the attribute object to retrieve a object representing the attribute constructor that you want to call. Pass the method the array of objects that represents the constructor's parameter types +3. Call the method of the attribute object to retrieve a object representing the attribute constructor that you want to call. Pass the method the array of objects that represents the constructor's parameter types 4. Create a array that defines the parameters to pass to the attribute's constructor. @@ -2332,27 +2332,27 @@ Each match won't actually happen until converts a string so that the regular expression engine will interpret any metacharacters that it may contain as character literals. For example, consider a regular expression that is designed to extract comments that are delimited by straight opening and closing brackets ([ and ]) from text. In the following example, the regular expression "[(.*?)]" is interpreted as a character class. Rather than matching comments embedded in the input text, the regular expression matches each opening or closing parenthesis, period, asterisk, or question mark. + converts a string so that the regular expression engine will interpret any metacharacters that it may contain as character literals. For example, consider a regular expression that is designed to extract comments that are delimited by straight opening and closing brackets ([ and ]) from text. In the following example, the regular expression "[(.*?)]" is interpreted as a character class. Rather than matching comments embedded in the input text, the regular expression matches each opening or closing parenthesis, period, asterisk, or question mark. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Escape/Escape1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Escape/Escape1.vb" id="Snippet1"::: - However, if the opening bracket is escaped by passing it to the method, the regular expression succeeds in matching comments that are embedded in the input string. The following example illustrates this. + However, if the opening bracket is escaped by passing it to the method, the regular expression succeeds in matching comments that are embedded in the input string. The following example illustrates this. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Escape/Escape1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Escape/Escape1.vb" id="Snippet2"::: - In a regular expression that is defined by using static text, characters that are to be interpreted literally rather than as metacharacters can be escaped by preceding them with a backslash symbol (\\) as well as by calling the method. In a regular expression that is defined dynamically using characters that are not known at design time, calling the method is particularly important to ensure that the regular expression engine interprets individual characters as literals rather than as metacharacters. + In a regular expression that is defined by using static text, characters that are to be interpreted literally rather than as metacharacters can be escaped by preceding them with a backslash symbol (\\) as well as by calling the method. In a regular expression that is defined dynamically using characters that are not known at design time, calling the method is particularly important to ensure that the regular expression engine interprets individual characters as literals rather than as metacharacters. > [!NOTE] > If a regular expression pattern includes either the number sign (#) or literal white-space characters, they must be escaped if input text is parsed with the option enabled. - While the method escapes the straight opening bracket ([) and opening brace ({) characters, it does not escape their corresponding closing characters (] and }). In most cases, escaping these is not necessary. If a closing bracket or brace is not preceded by its corresponding opening character, the regular expression engine interprets it literally. If an opening bracket or brace is interpreted as a metacharacter, the regular expression engine interprets the first corresponding closing character as a metacharacter. If this is not the desired behavior, the closing bracket or brace should be escaped by explicitly prepending the backslash (\\) character. For an illustration, see the Example section. + While the method escapes the straight opening bracket ([) and opening brace ({) characters, it does not escape their corresponding closing characters (] and }). In most cases, escaping these is not necessary. If a closing bracket or brace is not preceded by its corresponding opening character, the regular expression engine interprets it literally. If an opening bracket or brace is interpreted as a metacharacter, the regular expression engine interprets the first corresponding closing character as a metacharacter. If this is not the desired behavior, the closing bracket or brace should be escaped by explicitly prepending the backslash (\\) character. For an illustration, see the Example section. ## Examples - The following example extracts comments from text. It assumes that the comments are delimited by a begin comment symbol and an end comment symbol that is selected by the user. Because the comment symbols are to be interpreted literally, they are passed to the method to ensure that they cannot be misinterpreted as metacharacters. In addition, the example explicitly checks whether the end comment symbol entered by the user is a closing bracket (]) or brace (}). If it is, a backslash character (\\) is prepended to the bracket or brace so that it is interpreted literally. Note that the example also uses the collection to display the comment only, rather than the comment together with its opening and closing comment symbols. + The following example extracts comments from text. It assumes that the comments are delimited by a begin comment symbol and an end comment symbol that is selected by the user. Because the comment symbols are to be interpreted literally, they are passed to the method to ensure that they cannot be misinterpreted as metacharacters. In addition, the example explicitly checks whether the end comment symbol entered by the user is a closing bracket (]) or brace (}). If it is, a backslash character (\\) is prepended to the bracket or brace so that it is interpreted literally. Note that the example also uses the collection to display the comment only, rather than the comment together with its opening and closing comment symbols. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Escape/Escape3.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Escape/Escape3.vb" id="Snippet3"::: @@ -2579,7 +2579,7 @@ Allows an to attempt to free resources and perfor ## Examples - The following example defines a regular expression, `\b((?\w+)\s*)+(?[.?!])`, that matches a sentence. The regular expression includes three capturing groups: an unnamed group that captures an individual word along with a space character that may follow it; a group named `word` that captures the individual words in the sentence; and a group named `end` that captures the punctuation that ends the sentence. The example calls the method to get the numbers of all capturing groups, and then displays their captured string. In addition, the method is used to indicate whether a particular numbered group corresponds to a named group. + The following example defines a regular expression, `\b((?\w+)\s*)+(?[.?!])`, that matches a sentence. The regular expression includes three capturing groups: an unnamed group that captures an individual word along with a space character that may follow it; a group named `word` that captures the individual words in the sentence; and a group named `end` that captures the punctuation that ends the sentence. The example calls the method to get the numbers of all capturing groups, and then displays their captured string. In addition, the method is used to indicate whether a particular numbered group corresponds to a named group. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/GetGroupNumbers/getgroupnumbers1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/GetGroupNumbers/getgroupnumbers1.vb" id="Snippet1"::: @@ -2652,7 +2652,7 @@ Allows an to attempt to free resources and perfor `*subexpression*) or (?'*name*'*subexpression*), where *name* is the name by which the subexpression will be identified. (For more information, see [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions).) The method identifies both named groups and numbered groups by their ordinal positions in the regular expression. Ordinal position zero always represents the entire regular expression. All numbered groups are then counted before named groups, regardless of their actual position in the regular expression pattern. + A regular expression pattern may contain either named or numbered capturing groups, which delineate subexpressions within a pattern match. Numbered groups are delimited by the syntax (*subexpression*) and are assigned numbers based on their order in the regular expression. Named groups are delimited by the syntax (?`<`*name*`>`*subexpression*) or (?'*name*'*subexpression*), where *name* is the name by which the subexpression will be identified. (For more information, see [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions).) The method identifies both named groups and numbered groups by their ordinal positions in the regular expression. Ordinal position zero always represents the entire regular expression. All numbered groups are then counted before named groups, regardless of their actual position in the regular expression pattern. If `i` is the number of a named group, the method returns the name of the group. If `i` is the number of an unnamed group, the method returns the string representation of the number. For example, if `i` is 1, the method returns "1". If `i` is not the number of a capturing group, the method returns . @@ -2661,7 +2661,7 @@ Allows an to attempt to free resources and perfor ## Examples - The following example defines a regular expression pattern that matches an address line containing a U.S. city name, state name, and zip code. The example uses the method to retrieve the names of capturing groups. It then uses these names to retrieve the corresponding captured groups for matches. + The following example defines a regular expression pattern that matches an address line containing a U.S. city name, state name, and zip code. The example uses the method to retrieve the names of capturing groups. It then uses these names to retrieve the corresponding captured groups for matches. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/GroupNameFromNumber/groupnamefromnumberex.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/GroupNameFromNumber/groupnamefromnumberex.vb" id="Snippet1"::: @@ -2737,7 +2737,7 @@ Allows an to attempt to free resources and perfor `*subexpression*) or (?'*name*'*subexpression*), where *name* is the name by which the subexpression will be identified. (For more information, see [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions).) The method identifies both named groups and numbered groups by their ordinal positions in the regular expression. Ordinal position zero always represents the entire regular expression. All numbered groups are then counted before named groups, regardless of their actual position in the regular expression pattern. + A regular expression pattern may contain either named or numbered capturing groups, which delineate subexpressions within a pattern match. Numbered groups are delimited by the syntax (*subexpression*) and are assigned numbers based on their order in the regular expression. Named groups are delimited by the syntax (?`<`*name*`>`*subexpression*) or (?'*name*'*subexpression*), where *name* is the name by which the subexpression will be identified. (For more information, see [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions).) The method identifies both named groups and numbered groups by their ordinal positions in the regular expression. Ordinal position zero always represents the entire regular expression. All numbered groups are then counted before named groups, regardless of their actual position in the regular expression pattern. If `name` is the string representation of a group number that is present in the regular expression pattern, the method returns that number. If `name` corresponds to a named capturing group that is present in the regular expression pattern, the method returns its corresponding number. The comparison of `name` with the group name is case-sensitive. If `name` does not correspond to the name of a capturing group or to the string representation of the number of a capturing group, the method returns -1. @@ -3029,7 +3029,7 @@ Allows an to attempt to free resources and perfor method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. + The method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. @@ -3215,7 +3215,7 @@ Allows an to attempt to free resources and perfor method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. + The method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. For more details about `startat`, see the Remarks section of . @@ -3317,7 +3317,7 @@ For more details about `startat`, see the Remarks section of method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. + The method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. The static method is equivalent to constructing a object with the regular expression pattern specified by `pattern` and calling the instance method. This regular expression pattern is cached for rapid retrieval by the regular expression engine. @@ -3485,7 +3485,7 @@ For more details about `startat`, see the Remarks section of method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. + The method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. The static method is equivalent to constructing a object with the regular expression pattern specified by `pattern` and the regular expression options specified by `options` and calling the instance method. This regular expression pattern is cached for rapid retrieval by the regular expression engine. @@ -3666,7 +3666,7 @@ For more details about `startat`, see the Remarks section of method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. + The method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. The static method is equivalent to constructing a object with the regular expression pattern specified by `pattern` and the regular expression options specified by `options` and calling the instance method. This regular expression pattern is cached for rapid retrieval by the regular expression engine. @@ -3803,7 +3803,7 @@ For more details about `startat`, see the Remarks section of object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . - This method returns the first substring in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. + This method returns the first substring in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. @@ -3959,14 +3959,14 @@ For more details about `startat`, see the Remarks section of object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . - This method returns the first substring in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. + This method returns the first substring in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. ## Examples - The following example calls the method to find the first word that contains at least one `z` character, and then calls the method to find any additional matches. + The following example calls the method to find the first word that contains at least one `z` character, and then calls the method to find any additional matches. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Match/match1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Match/match1.vb" id="Snippet1"::: @@ -4057,7 +4057,7 @@ For more details about `startat`, see the Remarks section of option so that the search proceeds from right to left, the regular expression engine searches from the character at index `beginning + length - 1` to the character at index `beginning`. - This method returns the first match that it finds within this range. You can retrieve subsequent matches by repeatedly calling the returned object's method. + This method returns the first match that it finds within this range. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . @@ -4152,7 +4152,7 @@ For more details about `startat`, see the Remarks section of object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . - This method returns the first substring found in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. + This method returns the first substring found in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. @@ -4258,7 +4258,7 @@ For more details about `startat`, see the Remarks section of object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . - This method returns the first substring found in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. + This method returns the first substring found in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. The `matchTimeout` parameter specifies how long a pattern matching method should try to find a match before it times out. Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to stop responding when they process input that contains near matches. For more information, see [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices) and [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions). If no match is found in that time interval, the method throws a exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the method executes. @@ -4368,7 +4368,7 @@ For more details about `startat`, see the Remarks section of method searches is defined by the call to one of the class constructors. For more information about the elements that can form a regular expression pattern, see [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. + The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. Because of its lazy evaluation, calling the method does not throw a exception. However, the exception is thrown when an operation is performed on the object returned by this method, if the property is not and a matching operation exceeds the time-out interval. @@ -4456,7 +4456,7 @@ For more details about `startat`, see the Remarks section of . - The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. + The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. Because of its lazy evaluation, calling the method does not throw a exception. However, the exception is thrown when an operation is performed on the object returned by this method, if the property is not and a matching operation exceeds the time-out interval. @@ -4555,7 +4555,7 @@ For more details about `startat`, see the Remarks section of method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. + The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. Because of its lazy evaluation, calling the method does not throw a exception. However, the exception is thrown when an operation is performed on the object returned by this method, if a time-out interval is defined by the "REGEX_DEFAULT_MATCH_TIMEOUT" property of the current application domain and a matching operation exceeds this time-out interval. @@ -4658,7 +4658,7 @@ For more details about `startat`, see the Remarks section of method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. + The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. Because of its lazy evaluation, calling the method does not throw a exception. However, the exception is thrown when an operation is performed on the object returned by this method, if a time-out interval is defined by the "REGEX_DEFAULT_MATCH_TIMEOUT" property of the current application domain and a matching operation exceeds this time-out interval. @@ -4763,9 +4763,9 @@ For more details about `startat`, see the Remarks section of method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. + The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. - Because of its lazy evaluation, calling the method does not throw a exception. However, an exception is thrown when an operation is performed on the object returned by this method, if a matching operation exceeds this time-out interval specified by the`matchTimeout` parameter. + Because of its lazy evaluation, calling the method does not throw a exception. However, an exception is thrown when an operation is performed on the object returned by this method, if a matching operation exceeds this time-out interval specified by the`matchTimeout` parameter. @@ -4854,7 +4854,7 @@ For more details about `startat`, see the Remarks section of property defines the approximate maximum time interval for a instance to execute a single matching operation before the operation times out. The regular expression engine throws a exception during its next timing check after the time-out interval has elapsed. This prevents the regular expression engine from processing input strings that require excessive backtracking. For more information, see [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions) and [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices). - This property is read-only. You can set its value explicitly for an individual object by calling the constructor; and you can set its value for all matching operations in an application domain by calling the method and providing a value for the "REGEX_DEFAULT_MATCH_TIMEOUT" property, as the following example illustrates. + This property is read-only. You can set its value explicitly for an individual object by calling the constructor; and you can set its value for all matching operations in an application domain by calling the method and providing a value for the "REGEX_DEFAULT_MATCH_TIMEOUT" property, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/MatchTimeout/regexmatchtimeout1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/MatchTimeout/regexmatchtimeout1.vb" id="Snippet1"::: @@ -5063,7 +5063,7 @@ For more details about `startat`, see the Remarks section of exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. @@ -5174,7 +5174,7 @@ For more details about `startat`, see the Remarks section of exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. @@ -5258,7 +5258,7 @@ For more details about `startat`, see the Remarks section of exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. @@ -5350,7 +5350,7 @@ For more details about `startat`, see the Remarks section of exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. @@ -5360,7 +5360,7 @@ For more details about `startat`, see the Remarks section of method to replace the local machine and drive names in a UNC path with a local file path. The regular expression uses the property to include the name of the local computer, and the method to include the names of the logical drives. To run the example successfully, you should replace the literal string "MyMachine" with your local machine name. + The following example uses the method to replace the local machine and drive names in a UNC path with a local file path. The regular expression uses the property to include the name of the local computer, and the method to include the names of the logical drives. To run the example successfully, you should replace the literal string "MyMachine" with your local machine name. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replace3.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Replace/replace3.vb" id="Snippet3"::: @@ -5478,12 +5478,12 @@ For more details about `startat`, see the Remarks section of exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. ## Examples - The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. + The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replace5.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Replace/replace5.vb" id="Snippet2"::: @@ -5578,7 +5578,7 @@ For more details about `startat`, see the Remarks section of exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. @@ -5676,7 +5676,7 @@ For more details about `startat`, see the Remarks section of exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. @@ -5782,12 +5782,12 @@ For more details about `startat`, see the Remarks section of exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. ## Examples - The following example uses the method to replace the local machine and drive names in a UNC path with a local file path. The regular expression uses the property to include the name of the local computer, and the method to include the names of the logical drives. All regular expression string comparisons are case-insensitive. To run the example successfully, you should replace the literal string "MyMachine" with your local machine name. + The following example uses the method to replace the local machine and drive names in a UNC path with a local file path. The regular expression uses the property to include the name of the local computer, and the method to include the names of the logical drives. All regular expression string comparisons are case-insensitive. To run the example successfully, you should replace the literal string "MyMachine" with your local machine name. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replace4.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Replace/replace4.vb" id="Snippet4"::: @@ -5912,12 +5912,12 @@ For more details about `startat`, see the Remarks section of exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. ## Examples - The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. The call to the method includes the option so that the comment in the regular expression pattern `\w+ # Matches all the characters in a word.` is ignored by the regular expression engine. + The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. The call to the method includes the option so that the comment in the regular expression pattern `\w+ # Matches all the characters in a word.` is ignored by the regular expression engine. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replace6.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Replace/replace6.vb" id="Snippet10"::: @@ -6014,7 +6014,7 @@ For more details about `startat`, see the Remarks section of exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. ]]> @@ -6103,12 +6103,12 @@ For more details about `startat`, see the Remarks section of exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the method executes. - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. ## Examples - The following example uses the method to replace the local machine and drive names in a UNC path with a local file path. The regular expression uses the property to include the name of the local computer and the method to include the names of the logical drives. All regular expression string comparisons are case-insensitive, and any single replacement operation times out if a match cannot be found in 0.5 second. To run the example successfully, you should replace the literal string "MyMachine" with your local machine name. + The following example uses the method to replace the local machine and drive names in a UNC path with a local file path. The regular expression uses the property to include the name of the local computer and the method to include the names of the logical drives. All regular expression string comparisons are case-insensitive, and any single replacement operation times out if a match cannot be found in 0.5 second. To run the example successfully, you should replace the literal string "MyMachine" with your local machine name. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replace12.cs" id="Snippet12"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Replace/replace12.vb" id="Snippet12"::: @@ -6245,12 +6245,12 @@ For more details about `startat`, see the Remarks section of exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the method executes. - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. ## Examples - The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. The call to the method includes the option so that the comment in the regular expression pattern `\w+ # Matches all the characters in a word.` is ignored by the regular expression engine. + The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. The call to the method includes the option so that the comment in the regular expression pattern `\w+ # Matches all the characters in a word.` is ignored by the regular expression engine. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replace13.cs" id="Snippet13"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Replace/replace13.vb" id="Snippet13"::: @@ -6337,7 +6337,7 @@ For more details about `startat`, see the Remarks section of is `true` if the instance was created with the option. + is `true` if the instance was created with the option. ]]> @@ -6451,7 +6451,7 @@ For more details about `startat`, see the Remarks section of methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original input string. + The methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original input string. If multiple matches are adjacent to one another, an empty string is inserted into the array. For example, splitting a string on a single hyphen causes the returned array to include an empty string in the position where two adjacent hyphens are found, as the following code shows. @@ -6463,7 +6463,7 @@ For more details about `startat`, see the Remarks section of expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. + If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Split/split2.vb" id="Snippet2"::: @@ -6540,7 +6540,7 @@ If the regular expression pattern includes multiple sets of capturing parenthese methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The `count` parameter specifies the maximum number of substrings into which the `input` string can be split; the last string contains the unsplit remainder of the string. A `count` value of zero provides the default behavior of splitting as many times as possible. + The methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The `count` parameter specifies the maximum number of substrings into which the `input` string can be split; the last string contains the unsplit remainder of the string. A `count` value of zero provides the default behavior of splitting as many times as possible. If multiple matches are adjacent to one another or if a match is found at the beginning or end of `input`, and the number of matches found is at least two less than `count`, an empty string is inserted into the array. That is, empty strings that result from adjacent matches or from matches at the beginning or end of the input string are counted in determining whether the number of matched substrings equals `count`. In the following example, the regular expression `/d+` is used to split an input string that includes one or more decimal digits into a maximum of three substrings. Because the beginning of the input string matches the regular expression pattern, the first array element contains , the second contains the first set of alphabetic characters in the input string, and the third contains the remainder of the string that follows the third match. @@ -6631,12 +6631,12 @@ If the regular expression pattern includes multiple sets of capturing parenthese methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The `input` string is split as many times as possible. If `pattern` is not found in the `input` string, the return value contains one element whose value is the original `input` string. + The methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The `input` string is split as many times as possible. If `pattern` is not found in the `input` string, the return value contains one element whose value is the original `input` string. The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). > [!IMPORTANT] -> Compiled regular expressions used in calls to static methods are automatically cached. To manage the lifetime of compiled regular expressions yourself, use the instance methods. +> Compiled regular expressions used in calls to static methods are automatically cached. To manage the lifetime of compiled regular expressions yourself, use the instance methods. If multiple matches are adjacent to one another, an empty string is inserted into the array. For example, splitting a string on a single hyphen causes the returned array to include an empty string in the position where two adjacent hyphens are found, as the following code shows. @@ -6648,14 +6648,14 @@ If the regular expression pattern includes multiple sets of capturing parenthese :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split22.cs" id="Snippet22"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Split/split22.vb" id="Snippet22"::: - If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. + If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split9.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Split/split9.vb" id="Snippet9"::: If the regular expression pattern includes multiple sets of capturing parentheses, and a match isn't found within the first set of capturing parentheses, captured text from additional capturing parentheses is included in the returned array. - If the regular expression can match the empty string, will split the string into an array of single-character strings because the empty string delimiter can be found at every location. For example: + If the regular expression can match the empty string, will split the string into an array of single-character strings because the empty string delimiter can be found at every location. For example: :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split13.cs" id="Snippet13"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Split/split13.vb" id="Snippet13"::: @@ -6731,7 +6731,7 @@ If the regular expression pattern includes multiple sets of capturing parenthese methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The `count` parameter specifies the maximum number of substrings into which the `input` string is split; the last string contains the unsplit remainder of the string. A `count` value of zero provides the default behavior of splitting as many times as possible. The `startat` parameter defines the point at which the search for the first delimiter begins (this can be used for skipping leading white space). + The methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The `count` parameter specifies the maximum number of substrings into which the `input` string is split; the last string contains the unsplit remainder of the string. A `count` value of zero provides the default behavior of splitting as many times as possible. The `startat` parameter defines the point at which the search for the first delimiter begins (this can be used for skipping leading white space). For more details about `startat`, see the Remarks section of . @@ -6749,7 +6749,7 @@ For more details about `startat`, see the Remarks section of splits the string into an array of single-character strings because the empty string delimiter can be found at every location. The following example splits the string "characters" into as many elements as the input string contains, starting with the character "a". Because the null string matches the end of the input string, a null string is inserted at the end of the returned array. + If the regular expression can match the empty string, splits the string into an array of single-character strings because the empty string delimiter can be found at every location. The following example splits the string "characters" into as many elements as the input string contains, starting with the character "a". Because the null string matches the end of the input string, a null string is inserted at the end of the returned array. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split14.cs" id="Snippet14"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Split/split14.vb" id="Snippet14"::: @@ -6828,12 +6828,12 @@ For more details about `startat`, see the Remarks section of methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original `input` string. + The methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original `input` string. The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). > [!IMPORTANT] -> Compiled regular expressions used in calls to static methods are automatically cached. To manage the lifetime of compiled regular expressions yourself, use the instance methods. +> Compiled regular expressions used in calls to static methods are automatically cached. To manage the lifetime of compiled regular expressions yourself, use the instance methods. If multiple matches are adjacent to one another, an empty string is inserted into the array. For example, splitting a string on a single hyphen causes the returned array to include an empty string in the position where two adjacent hyphens are found. @@ -6842,14 +6842,14 @@ For more details about `startat`, see the Remarks section of expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. + If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split9.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Split/split9.vb" id="Snippet9"::: However, when the regular expression pattern includes multiple sets of capturing parentheses, and a match is not found within the first set of capturing parentheses, captured text from additional capturing parentheses is included in the returned array. - If the regular expression can match the empty string, will split the string into an array of single-character strings because the empty string delimiter can be found at every location. + If the regular expression can match the empty string, will split the string into an array of single-character strings because the empty string delimiter can be found at every location. The exception is thrown if the execution time of the split operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. @@ -6929,12 +6929,12 @@ For more details about `startat`, see the Remarks section of methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original `input` string. + The methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original `input` string. The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). > [!IMPORTANT] -> Compiled regular expressions used in calls to static methods are automatically cached. To manage the lifetime of compiled regular expressions yourself, use the instance methods. +> Compiled regular expressions used in calls to static methods are automatically cached. To manage the lifetime of compiled regular expressions yourself, use the instance methods. If multiple matches are adjacent to one another, an empty string is inserted into the array. For example, splitting a string on a single hyphen causes the returned array to include an empty string in the position where two adjacent hyphens are found. @@ -6943,14 +6943,14 @@ For more details about `startat`, see the Remarks section of expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. + If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split9.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Split/split9.vb" id="Snippet9"::: However, when the regular expression pattern includes multiple sets of capturing parentheses, and a match is not found within the first set of capturing parentheses, captured text from additional capturing parentheses is included in the returned array. - If the regular expression can match the empty string, will split the string into an array of single-character strings because the empty string delimiter can be found at every location. + If the regular expression can match the empty string, will split the string into an array of single-character strings because the empty string delimiter can be found at every location. The `matchTimeout` parameter specifies how long a pattern matching method should try to find a match before it times out. Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to stop responding when they process input that contains near matches. For more information, see [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices) and [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions). If no match is found in that time interval, the method throws a exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the method executes. @@ -7148,16 +7148,16 @@ Any objects that are included in the method performs one of the following two transformations: + The method performs one of the following two transformations: -- It reverses the transformation performed by the method by removing the escape character ("\\") from each character escaped by the method. These include the \\, *, +, ?, |, {, [, (,), ^, $, ., #, and white space characters. In addition, the method unescapes the closing bracket (]) and closing brace (}) characters. +- It reverses the transformation performed by the method by removing the escape character ("\\") from each character escaped by the method. These include the \\, *, +, ?, |, {, [, (,), ^, $, ., #, and white space characters. In addition, the method unescapes the closing bracket (]) and closing brace (}) characters. > [!NOTE] -> cannot reverse an escaped string perfectly because it cannot deduce precisely which characters were escaped, +> cannot reverse an escaped string perfectly because it cannot deduce precisely which characters were escaped, - It replaces the hexadecimal values in verbatim string literals with the actual printable characters. For example, it replaces @"\x07" with "\a", or @"\x0A" with "\n". It converts to supported escape characters such as \a, \b, \e, \n, \r, \f, \t, \v, and alphanumeric characters. - If the method encounters other escape sequences that it cannot convert, such as \w or \s, it throws an . + If the method encounters other escape sequences that it cannot convert, such as \w or \s, it throws an . ]]> diff --git a/xml/System.Text.RegularExpressions/RegexCompilationInfo.xml b/xml/System.Text.RegularExpressions/RegexCompilationInfo.xml index 7ce4791b411..3d40a30a5a0 100644 --- a/xml/System.Text.RegularExpressions/RegexCompilationInfo.xml +++ b/xml/System.Text.RegularExpressions/RegexCompilationInfo.xml @@ -49,7 +49,7 @@ objects is passed to the method to provide information about each regular expression to be included in the assembly. Each compiled regular expression that is included in the assembly is represented as a class derived from . The properties of the type define the regular expression's class name, its fully qualified name (that is, its namespace and its type name), its regular expression pattern, any additional options (such as whether the regular expression is case-insensitive), and a time-out interval that specifies how long the regular expression engine should search for a match. + An array of objects is passed to the method to provide information about each regular expression to be included in the assembly. Each compiled regular expression that is included in the assembly is represented as a class derived from . The properties of the type define the regular expression's class name, its fully qualified name (that is, its namespace and its type name), its regular expression pattern, any additional options (such as whether the regular expression is case-insensitive), and a time-out interval that specifies how long the regular expression engine should search for a match. You can instantiate a object by calling its overloaded class constructor. @@ -116,9 +116,9 @@ constructor directly corresponds to a property of the class. Because all properties are read/write, their values can also be assigned directly. + Each parameter of the constructor directly corresponds to a property of the class. Because all properties are read/write, their values can also be assigned directly. - The method generates an assembly that contains compiled regular expressions. Therefore, you should not specify as one of the values of `options`. + The method generates an assembly that contains compiled regular expressions. Therefore, you should not specify as one of the values of `options`. If `ispublic` is `true`, the compiled regular expression class is given public accessibility. That is, it can be instantiated from code that executes in any assembly. If `ispublic` is `false`, the compiled regular expression class is given `internal` (in C#) or `Friend` (in Visual Basic) accessibility. That is, it can be instantiated only from code that executes in the same assembly as the regular expression class. @@ -127,7 +127,7 @@ ## Examples The following example creates and uses a compiled regular expression in two steps. - In the first step, compile and execute the following code example. The constructor in the code example defines a compiled regular expression. The result of executing the code is an assembly named FishRegex.dll that contains a compiled regular expression type named `FishRegex`. + In the first step, compile and execute the following code example. The constructor in the code example defines a compiled regular expression. The result of executing the code is an assembly named FishRegex.dll that contains a compiled regular expression type named `FishRegex`. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/RegexCompilationInfo/.ctor/genFishRegex.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/RegexCompilationInfo/.ctor/genFishRegex.vb" id="Snippet1"::: @@ -202,9 +202,9 @@ constructor directly corresponds to a property of the class. Because all properties are read/write, their values can also be assigned directly. + Each parameter of the constructor directly corresponds to a property of the class. Because all properties are read/write, their values can also be assigned directly. - The method generates an assembly that contains compiled regular expressions. Therefore, you should not specify as one of the values of `options`. + The method generates an assembly that contains compiled regular expressions. Therefore, you should not specify as one of the values of `options`. If `ispublic` is `true`, the compiled regular expression class is given public accessibility. That is, it can be instantiated from code that executes in any assembly. If `ispublic` is `false`, the compiled regular expression class is given `internal` (in C#) or `Friend` (in Visual Basic) accessibility. That is, it can be instantiated only from code that executes in the same assembly as the regular expression class. @@ -300,7 +300,7 @@ property is `false`, the regular expression class defined by the current instance can be instantiated only by code that is executing in the assembly that contains the class. However, because the method generates an assembly that contains only compiled regular expressions and does not allow additional code to be added, there is generally no reason to assign this property a value of `false`. + If the property is `false`, the regular expression class defined by the current instance can be instantiated only by code that is executing in the assembly that contains the class. However, because the method generates an assembly that contains only compiled regular expressions and does not allow additional code to be added, there is generally no reason to assign this property a value of `false`. ]]> @@ -348,9 +348,9 @@ You can assign a default time-out value to a object in any of the following ways: -- By calling the method and providing the string representation of a value for the "REGEX_DEFAULT_MATCH_TIMEOUT" property. +- By calling the method and providing the string representation of a value for the "REGEX_DEFAULT_MATCH_TIMEOUT" property. -- By calling the constructor and providing a value for the `matchTimeout` parameter. +- By calling the constructor and providing a value for the `matchTimeout` parameter. - By setting the value of this property. @@ -428,7 +428,7 @@ class is used to define a compiled regular expression, which is represented as a class derived from . The property defines the class name of the regular expression type, and the and properties together define its fully qualified name. + The class is used to define a compiled regular expression, which is represented as a class derived from . The property defines the class name of the regular expression type, and the and properties together define its fully qualified name. ]]> @@ -479,7 +479,7 @@ class is used to define a compiled regular expression, which is represented as a class derived from . The property defines the namespace that contains the compiled regular expression type, and the and properties together define its fully qualified name. + The class is used to define a compiled regular expression, which is represented as a class derived from . The property defines the namespace that contains the compiled regular expression type, and the and properties together define its fully qualified name. ]]> @@ -533,7 +533,7 @@ method generates an assembly that contains compiled regular expressions. Therefore, you do not have to specify as one of the values of this property. If it is present, the option is ignored. + The method generates an assembly that contains compiled regular expressions. Therefore, you do not have to specify as one of the values of this property. If it is present, the option is ignored. ]]> @@ -582,7 +582,7 @@ property can contain any valid regular expression. If the value of the property is not a syntactically correct regular expression pattern, the call to the method throws an . + The property can contain any valid regular expression. If the value of the property is not a syntactically correct regular expression pattern, the call to the method throws an . ]]> diff --git a/xml/System.Text.RegularExpressions/RegexMatchTimeoutException.xml b/xml/System.Text.RegularExpressions/RegexMatchTimeoutException.xml index 33103ee4ca7..d53f59c10a0 100644 --- a/xml/System.Text.RegularExpressions/RegexMatchTimeoutException.xml +++ b/xml/System.Text.RegularExpressions/RegexMatchTimeoutException.xml @@ -86,7 +86,7 @@ ## Examples - The following example illustrates two possible approaches to handling the exception. A constant whose value is two seconds defines the maximum time-out interval. The method is initially called with a time-out interval of one second. Each exception causes the time-out interval to be increased by one second and results in another call to the method if the current time-out interval is less than the maximum time-out interval. However, if the current time-out interval exceeds the maximum time-out interval, the exception handler writes information to the event log and abandons the processing of the regular expression. + The following example illustrates two possible approaches to handling the exception. A constant whose value is two seconds defines the maximum time-out interval. The method is initially called with a time-out interval of one second. Each exception causes the time-out interval to be increased by one second and results in another call to the method if the current time-out interval is less than the maximum time-out interval. However, if the current time-out interval exceeds the maximum time-out interval, the exception handler writes information to the event log and abandons the processing of the regular expression. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/RegexMatchTimeoutException/Overview/class1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/RegexMatchTimeoutException/Overview/class1.vb" id="Snippet1"::: @@ -261,7 +261,7 @@ object. Instead, it is called by the method when deserializing the object from a stream. + This constructor is not called directly by your code to instantiate the object. Instead, it is called by the method when deserializing the object from a stream. ]]> @@ -371,7 +371,7 @@ , , and properties of the new object. + The `regexInput`, `regexPattern`, and `matchTimeout` values are assigned to the , , and properties of the new object. ]]> @@ -422,9 +422,9 @@ constructor. If this parameter is not explicitly initialized in a constructor call, its value is . + This property reflects the value of the `regexInput` parameter of the constructor. If this parameter is not explicitly initialized in a constructor call, its value is . - When the exception is thrown by the regular expression engine, the value of the property reflects the entire input string passed to the regular expression engine. It does not reflect a partial string, such as the substring that the engine searches in the call to a method such as . + When the exception is thrown by the regular expression engine, the value of the property reflects the entire input string passed to the regular expression engine. It does not reflect a partial string, such as the substring that the engine searches in the call to a method such as . ]]> @@ -475,7 +475,7 @@ constructor. If the parameter is not properly initialized in a constructor call, its value is `Timespan.FromTicks(-1)`. + This property reflects the value of the `matchTimeout` parameter of the constructor. If the parameter is not properly initialized in a constructor call, its value is `Timespan.FromTicks(-1)`. The value of this property reflects the time-out interval set in the call to the constructor or static method. It does not reflect the exact interval that has elapsed from the beginning of the method call to the time the exception is thrown. @@ -528,7 +528,7 @@ constructor. If the parameter is not properly initialized in a constructor call, its value is . + This property reflects the value of the `regexPattern` parameter of the constructor. If the parameter is not properly initialized in a constructor call, its value is . ]]> diff --git a/xml/System.Text.RegularExpressions/RegexOptions.xml b/xml/System.Text.RegularExpressions/RegexOptions.xml index f1abe4d2254..6d3584c6e26 100644 --- a/xml/System.Text.RegularExpressions/RegexOptions.xml +++ b/xml/System.Text.RegularExpressions/RegexOptions.xml @@ -61,19 +61,19 @@ ## Remarks A `RegexOptions` value can be provided as a parameter to the following members of the class: -- The class constructor. +- The class constructor. -- The method. +- The method. -- The method. +- The method. -- The method. +- The method. -- The method. +- The method. -- The and methods. +- The and methods. - A `RegexOptions` value can also be supplied as a parameter to the constructor, or it can be assigned directly to the property. The resulting object is then used in the call to the method. + A `RegexOptions` value can also be supplied as a parameter to the constructor, or it can be assigned directly to the property. The resulting object is then used in the call to the method. Several options provided by members of the `RegexOptions` enumeration (in particular, by its `ExplicitCapture`, `IgnoreCase`, `Multiline`, and `Singleline` members) can instead be provided by using an inline option character in the regular expression pattern. For details, see [Regular Expression Options](/dotnet/standard/base-types/regular-expression-options). diff --git a/xml/System.Text.RegularExpressions/RegexRunnerFactory.xml b/xml/System.Text.RegularExpressions/RegexRunnerFactory.xml index d4a355f2667..4b7ab2f4161 100644 --- a/xml/System.Text.RegularExpressions/RegexRunnerFactory.xml +++ b/xml/System.Text.RegularExpressions/RegexRunnerFactory.xml @@ -54,11 +54,11 @@ Creates a class for a compiled regular expression. - object executes a compiled regular expression. A regular expression that is compiled to an assembly becomes a type in that assembly, and an object of that type is typically created using reflection. However, creating an object by reflection is an expensive operation. The class improves the performance of the .NET Framework by providing the method, which creates a object for a specific compiled regular expression. - + object executes a compiled regular expression. A regular expression that is compiled to an assembly becomes a type in that assembly, and an object of that type is typically created using reflection. However, creating an object by reflection is an expensive operation. The class improves the performance of the .NET Framework by providing the method, which creates a object for a specific compiled regular expression. + ]]> diff --git a/xml/System.Text.Unicode/UnicodeRange.xml b/xml/System.Text.Unicode/UnicodeRange.xml index 1f5e55ef64d..a1657ee8f8d 100644 --- a/xml/System.Text.Unicode/UnicodeRange.xml +++ b/xml/System.Text.Unicode/UnicodeRange.xml @@ -29,12 +29,12 @@ Represents a contiguous range of Unicode code points. - method or the constructor to create a an arbitrary range of Unicode code points. You use the static properties of the class to retrieve a instance that contains the code points in a Unicode named range. +You use the static method or the constructor to create a an arbitrary range of Unicode code points. You use the static properties of the class to retrieve a instance that contains the code points in a Unicode named range. -Currently, the class supports only the Basic Multilingual Plane (BMP), which extends from U+0000 to U+FFFF. +Currently, the class supports only the Basic Multilingual Plane (BMP), which extends from U+0000 to U+FFFF. ]]> @@ -71,17 +71,17 @@ Currently, the class supports only the B The number of code points in the range. Creates a new that includes a specified number of characters starting at a specified Unicode code point. - instance created by calling this constructor. ]]> - is less than zero or greater than 0xFFFF. + is less than zero or greater than 0xFFFF. --or- +-or- is less than zero. diff --git a/xml/System.Text/ASCIIEncoding.xml b/xml/System.Text/ASCIIEncoding.xml index 9bebda5fc96..651758ccfb0 100644 --- a/xml/System.Text/ASCIIEncoding.xml +++ b/xml/System.Text/ASCIIEncoding.xml @@ -63,7 +63,7 @@ ## Remarks Encoding is the process of transforming a set of Unicode characters into a sequence of bytes. Decoding is the process of transforming a sequence of encoded bytes into a set of Unicode characters. - corresponds to the Windows code page 20127. Because ASCII is a 7-bit encoding, ASCII characters are limited to the lowest 128 Unicode characters, from U+0000 to U+007F. If you use the default encoder returned by the property or the constructor, characters outside that range are replaced with a question mark (?) before the encoding operation is performed. Because the class supports only a limited character set, the , , and classes are better suited for globalized applications. The following considerations can help you to decide whether to use : + corresponds to the Windows code page 20127. Because ASCII is a 7-bit encoding, ASCII characters are limited to the lowest 128 Unicode characters, from U+0000 to U+007F. If you use the default encoder returned by the property or the constructor, characters outside that range are replaced with a question mark (?) before the encoding operation is performed. Because the class supports only a limited character set, the , , and classes are better suited for globalized applications. The following considerations can help you to decide whether to use : - Some protocols require ASCII or a subset of ASCII. In these cases ASCII encoding is appropriate. @@ -72,11 +72,11 @@ > [!CAUTION] > does not provide error detection. For security reasons, you should use , , or and enable error detection. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. - Likewise, the method determines how many characters result in decoding a sequence of bytes, and the and methods perform the actual decoding. + Likewise, the method determines how many characters result in decoding a sequence of bytes, and the and methods perform the actual decoding. - Note that the default constructor by itself might not have the appropriate behavior for your application. You might want to consider setting the or property to or to prevent sequences with the 8th bit set. Custom behavior might also be appropriate for these cases. + Note that the default constructor by itself might not have the appropriate behavior for your application. You might want to consider setting the or property to or to prevent sequences with the 8th bit set. Custom behavior might also be appropriate for these cases. @@ -137,7 +137,7 @@ > [!CAUTION] > The class does not provide error detection. For security reasons, you should use the , , or class and enable error detection. - If you choose to use ASCII encoding, this constructor may not provide the appropriate fallback behavior for your application. It uses the and classes to replace every character outside the range of U+0000 through U+007F with a question mark (?). Instead, you can call the or method and pass it and objects to use exception fallback. + If you choose to use ASCII encoding, this constructor may not provide the appropriate fallback behavior for your application. It uses the and classes to replace every character outside the range of U+0000 through U+007F with a question mark (?). Instead, you can call the or method and pass it and objects to use exception fallback. > [!NOTE] > supports only the Unicode character values between U+0000 and U+007F. Therefore, , , and are better suited for globalized applications. @@ -204,7 +204,7 @@ to store the resulting bytes, use . To calculate the maximum size, use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact size required by to store the resulting bytes, use . To calculate the maximum size, use . The method generally allows allocation of less memory, while the method generally executes faster. ]]> @@ -264,12 +264,12 @@ to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. ## Examples - The following example demonstrates how to use the method to return the number of bytes required to encode a string using . + The following example demonstrates how to use the method to return the number of bytes required to encode a string using . :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetByteCount/getbytecount-string.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/ASCIIEncoding/GetByteCount/getbytecount-string.vb" id="Snippet1"::: @@ -352,7 +352,7 @@ to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. ]]> @@ -433,12 +433,12 @@ to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. ## Examples - The following example demonstrates how to use the method to return the number of bytes required to encode an array of Unicode characters using . + The following example demonstrates how to use the method to return the number of bytes required to encode an array of Unicode characters using . :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetByteCount/getbytecount-char[]-int32-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/ASCIIEncoding/GetByteCount/getbytecount-char[]-int32-int32.vb" id="Snippet1"::: @@ -519,9 +519,9 @@ to store the resulting bytes, use . To calculate the maximum size, use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact size required by to store the resulting bytes, use . To calculate the maximum size, use . The method generally allows allocation of less memory, while the method generally executes faster. - Data to be converted, such as data read from a stream, can be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, can be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the provided by the method or the method, respectively. does not provide error detection. Any Unicode character greater than `U+007F` is encoded as the ASCII question mark ("?"). @@ -598,9 +598,9 @@ to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. - Data to be converted, such as data read from a stream, can be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, can be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. does not provide error detection. Any Unicode character greater than U+007F is translated to an ASCII question mark ("?"). @@ -692,9 +692,9 @@ to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. - Data to be converted, such as data read from a stream, can be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, can be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. does not provide error detection. Any Unicode character greater than U+007F is encoded as the ASCII question mark ("?"). @@ -704,7 +704,7 @@ ## Examples - The following example demonstrates how to use the method to encode a range of characters from a string and store the encoded characters in a range of elements in a byte array. + The following example demonstrates how to use the method to encode a range of characters from a string and store the encoded characters in a range of elements in a byte array. :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetBytes/getbytes-string-int32-int32-byte[]-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/ASCIIEncoding/GetBytes/getbytes-string-int32-int32-byte[]-int32.vb" id="Snippet1"::: @@ -801,9 +801,9 @@ to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. - Data to be converted, such as data read from a stream, can be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, can be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. does not provide error detection. Any Unicode character greater than U+007F is encoded as the ASCII question mark ("?"). @@ -811,7 +811,7 @@ > For security reasons, it's recommended to use , , or and enable error detection. ## Examples - The following example demonstrates how to use the method to encode a range of elements from a Unicode character array and store the encoded bytes in a range of elements in a byte array. + The following example demonstrates how to use the method to encode a range of elements from a Unicode character array and store the encoded bytes in a range of elements in a byte array. :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetBytes/getbytes-char[]-int32-int32-byte[]-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/ASCIIEncoding/GetBytes/getbytes-char[]-int32-int32-byte[]-int32.vb" id="Snippet1"::: @@ -892,7 +892,7 @@ to store the resulting characters, use . To calculate the maximum size, use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact size required by to store the resulting characters, use . To calculate the maximum size, use . The method generally allows allocation of less memory, while the method generally executes faster. ]]> @@ -960,7 +960,7 @@ to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. ]]> @@ -1041,12 +1041,12 @@ to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. ## Examples - The following example demonstrates how to use the method to return the number of characters produced by decoding a range of elements in a byte array. + The following example demonstrates how to use the method to return the number of characters produced by decoding a range of elements in a byte array. :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetCharCount/getcharcount-byte[]-int32-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/ASCIIEncoding/GetCharCount/getcharcount-byte[]-int32-int32.vb" id="Snippet1"::: @@ -1127,9 +1127,9 @@ to store the resulting characters, use . To calculate the maximum size, use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact size required by to store the resulting characters, use . To calculate the maximum size, use . The method generally allows allocation of less memory, while the method generally executes faster. - Data to be converted, such as data read from a stream, can be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, can be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively. does not provide error detection. Any byte greater than hexadecimal `0x7F` is decoded as the Unicode question mark ("?"). @@ -1206,9 +1206,9 @@ to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. - Data to be converted, such as data read from a stream, can be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, can be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. does not provide error detection. Any byte greater than hexadecimal 0x7F is decoded as the Unicode question mark ("?"). @@ -1301,9 +1301,9 @@ to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. - Data to be converted, such as data read from a stream, can be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, can be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. does not provide error detection. Any byte greater than hexadecimal 0x7F is decoded as the Unicode question mark ("?"). @@ -1399,7 +1399,7 @@ method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. ]]> @@ -1461,7 +1461,7 @@ method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method of this class. However, an maintains state information between calls so it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method of this class. However, an maintains state information between calls so it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. ]]> @@ -1520,13 +1520,13 @@ method calculates the exact array size required by the method to store the resulting bytes, whereas the method calculates the maximum array size. The method generally allocates less memory, but the method generally executes faster. + The method calculates the exact array size required by the method to store the resulting bytes, whereas the method calculates the maximum array size. The method generally allocates less memory, but the method generally executes faster. - is a worst-case number, including the worst case for the currently selected . If you choose a replacement fallback with a potentially large string, can return large values. + is a worst-case number, including the worst case for the currently selected . If you choose a replacement fallback with a potentially large string, can return large values. - The method considers potential leftover surrogates from a previous encoding operation. As a result, if the object uses the default replacement fallback, or if a custom replacement fallback has been defined with a single possible fallback character, the method returns `charCount` + 1. If the object uses a replacement fallback with more than one possible fallback character, the method returns *n* * (`charCount` + 1), where *n* is the maximum number of fallback characters. + The method considers potential leftover surrogates from a previous encoding operation. As a result, if the object uses the default replacement fallback, or if a custom replacement fallback has been defined with a single possible fallback character, the method returns `charCount` + 1. If the object uses a replacement fallback with more than one possible fallback character, the method returns *n* * (`charCount` + 1), where *n* is the maximum number of fallback characters. - has no relation to . If your application needs a similar function to use with , it should use . + has no relation to . If your application needs a similar function to use with , it should use . > [!NOTE] > `GetMaxByteCount(N)` is not necessarily the same value as `N* GetMaxByteCount(1)`. @@ -1534,7 +1534,7 @@ ## Examples - The following example demonstrates how to use the method to calculate the bytes required to encode a specified number of characters. + The following example demonstrates how to use the method to calculate the bytes required to encode a specified number of characters. :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetMaxByteCount/getmaxbytecount-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/ASCIIEncoding/GetMaxByteCount/getmaxbytecount-int32.vb" id="Snippet1"::: @@ -1600,11 +1600,11 @@ method calculates the exact array size required by the method to store the resulting characters, whereas the method calculates the maximum array size. The method generally allocates less memory, while the method generally executes faster. + The method calculates the exact array size required by the method to store the resulting characters, whereas the method calculates the maximum array size. The method generally allocates less memory, while the method generally executes faster. - retrieves a worst-case number, including the worst case for the currently selected . If a decoder fallback is present that has a maximum fallback length of *n*, the method returns *n* * `byteCount`. + retrieves a worst-case number, including the worst case for the currently selected . If a decoder fallback is present that has a maximum fallback length of *n*, the method returns *n* * `byteCount`. - has no relation to . If your application needs a similar function to use with , it should use . + has no relation to . If your application needs a similar function to use with , it should use . > [!NOTE] > `GetMaxCharCount(N)` is not necessarily the same value as `N* GetMaxCharCount(1)`. @@ -1612,7 +1612,7 @@ ## Examples - The following example demonstrates how to use the method to calculate the maximum number of characters needed to decode a specified number of bytes. + The following example demonstrates how to use the method to calculate the maximum number of characters needed to decode a specified number of bytes. :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetMaxCharCount/getmaxcharcount-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/ASCIIEncoding/GetMaxCharCount/getmaxcharcount-int32.vb" id="Snippet1"::: @@ -1720,7 +1720,7 @@ or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, can be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. does not provide error detection. Any byte greater than hexadecimal 0x7F is decoded as the Unicode question mark ("?"). @@ -1728,7 +1728,7 @@ > For security reasons, you should use the , , or classes and enable error detection instead of using the class. ## Examples - The following example demonstrates how to use the method to convert a byte array into a . + The following example demonstrates how to use the method to convert a byte array into a . :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetString/getstring-byte[].cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/ASCIIEncoding/GetString/getstring-byte[].vb" id="Snippet1"::: @@ -1803,7 +1803,7 @@ property to determine the size of a byte array for encoding operations and the size of a character array for decoding operations (for example, so that the size of the byte array is * the number of characters to be encoded), you should call the or method for encoding operations and the or method for decoding operations. These methods takes the object's replacement fallback strategy into account when calculating the required array size. + Instead of using the property to determine the size of a byte array for encoding operations and the size of a character array for decoding operations (for example, so that the size of the byte array is * the number of characters to be encoded), you should call the or method for encoding operations and the or method for decoding operations. These methods takes the object's replacement fallback strategy into account when calculating the required array size. ]]> diff --git a/xml/System.Text/CodePagesEncodingProvider.xml b/xml/System.Text/CodePagesEncodingProvider.xml index 1a18c74a507..81295e105b9 100644 --- a/xml/System.Text/CodePagesEncodingProvider.xml +++ b/xml/System.Text/CodePagesEncodingProvider.xml @@ -62,7 +62,7 @@ - UTF-16 and UTF-16LE (code page 1200), which is returned by the property. -- UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. +- UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. - UTF-32 and UTF-32LE (code page 12000), which is returned by the property. @@ -74,9 +74,9 @@ - Retrieve a object from the static property. -- Pass the object to the method. +- Pass the object to the method. - After an object is registered, the encodings that it supports are available by calling the overloads of ; you should not call the overloads. + After an object is registered, the encodings that it supports are available by calling the overloads of ; you should not call the overloads. ### Impact on default encoding behavior @@ -104,7 +104,7 @@ When no encoding provider is registered, `GetEncoding(0)` returns UTF-8 on all p ## Remarks -The .NET Framework supports a large number of character encodings and code pages. You can get a complete list of encodings by calling the method, which is available in the .NET Framework. On the other hand, .NET Core only supports the following encodings by default: +The .NET Framework supports a large number of character encodings and code pages. You can get a complete list of encodings by calling the method, which is available in the .NET Framework. On the other hand, .NET Core only supports the following encodings by default: - ASCII (code page 20127), which is returned by the property. @@ -116,7 +116,7 @@ The .NET Framework supports a large number of character encodings and code pages - UTF-16 and UTF-16LE (code page 1200), which is returned by the property. -- UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. +- UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. - UTF-32 and UTF-32LE (code page 12000), which is returned by the property. @@ -128,9 +128,9 @@ The .NET Framework supports a large number of character encodings and code pages - Get the object from the static property. -- Pass the object to the method to make the encodings supplied by the object available to the common language runtime. +- Pass the object to the method to make the encodings supplied by the object available to the common language runtime. -- Call an overload to retrieve the encoding. The method will call the corresponding method to determine whether it can supply the requested encoding. +- Call an overload to retrieve the encoding. The method will call the corresponding method to determine whether it can supply the requested encoding. ]]> @@ -287,7 +287,7 @@ For all other supported code page identifiers, this method returns the correspon ## Remarks - The .NET Framework supports a large number of character encodings and code pages. You can get a complete list of encodings by calling the method, which is available in the .NET Framework. On the other hand, .NET Core only supports the following encodings by default: + The .NET Framework supports a large number of character encodings and code pages. You can get a complete list of encodings by calling the method, which is available in the .NET Framework. On the other hand, .NET Core only supports the following encodings by default: - ASCII (code page 20127), which is returned by the property. @@ -299,7 +299,7 @@ For all other supported code page identifiers, this method returns the correspon - UTF-16 and UTF-16LE (code page 1200), which is returned by the property. -- UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. +- UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. - UTF-32 and UTF-32LE (code page 12000), which is returned by the property. @@ -309,9 +309,9 @@ For all other supported code page identifiers, this method returns the correspon - Get the object from the static property. -- Pass the object to the method to make the encodings supplied by the object available to the common language runtime. +- Pass the object to the method to make the encodings supplied by the object available to the common language runtime. -- Call an overload to retrieve the encoding. The method will call the corresponding method to determine whether it can supply the requested encoding. +- Call an overload to retrieve the encoding. The method will call the corresponding method to determine whether it can supply the requested encoding. ]]> diff --git a/xml/System.Text/Decoder.xml b/xml/System.Text/Decoder.xml index b4eb6d0f860..802f45c76a1 100644 --- a/xml/System.Text/Decoder.xml +++ b/xml/System.Text/Decoder.xml @@ -74,12 +74,12 @@ Converts a sequence of encoded bytes into a set of characters. class, call the method of an implementation. +To obtain an instance of an implementation of the class, call the method of an implementation. -The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. There are several versions of both of these methods available in the class. For more information, see . A object maintains state information between successive calls to `GetChars` or methods so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations because those operations often deal with blocks of data instead of a complete data stream. +The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. There are several versions of both of these methods available in the class. For more information, see . A object maintains state information between successive calls to `GetChars` or methods so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations because those operations often deal with blocks of data instead of a complete data stream. > [!NOTE] -> When the application is done with a stream of data, it should make sure that the state information is flushed by setting the `flush` parameter to `true` in the appropriate method call. If an exception occurs or if the application switches streams, it should call to clear the internal state of the `Decoder` object. +> When the application is done with a stream of data, it should make sure that the state information is flushed by setting the `flush` parameter to `true` in the appropriate method call. If an exception occurs or if the application switches streams, it should call to clear the internal state of the `Decoder` object. ]]> @@ -143,7 +143,7 @@ The following example demonstrates the use of a to co method of a implementation. + To obtain an instance of an implementation of this class, the application should use the method of a implementation. @@ -185,14 +185,14 @@ The following example demonstrates the use of a to co ## Remarks -Remember that the object saves state between calls to . +Remember that the object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the decoder ignores invalid bytes at the end of the data block and clears the internal buffer. Any remaining processed data that is part of a logical unit, such as the high surrogate of a surrogate pair, is converted according to the current fallback settings. The `Convert` method is designed to be used in a loop to decode an arbitrary amount of input, such as data read from a file or stream. It stores the output of the decoding operation in a fixed-size buffer. - will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written, provided the output array allows for at least two characters. -Also see for more comments. + will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written, provided the output array allows for at least two characters. +Also see for more comments. ]]> @@ -439,7 +439,7 @@ The `completed` parameter can also be set to `false`, even though the `bytesUsed ## Examples -The following example uses the method to convert a file of UTF-16 characters to UTF-8. It then uses the method to convert the UTF-8 characters back to UTF-16 characters. +The following example uses the method to convert a file of UTF-16 characters to UTF-8. It then uses the method to convert the UTF-8 characters back to UTF-16 characters. :::code language="csharp" source="~/snippets/csharp/System.Text/Decoder/Convert/edCvt.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Decoder/Convert/edCvt.vb" id="Snippet1"::: @@ -656,7 +656,7 @@ The following example uses the method to c ## Remarks This method does not affect the state of the decoder. - To calculate the exact buffer size that requires to store the resulting characters, the application should use . + To calculate the exact buffer size that requires to store the resulting characters, the application should use . If `GetChars` is called with `flush` set to `false`, the decoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next decoding operation. The application should call `GetCharCount` on a block of data immediately before calling `GetChars` on the same block, so that any trailing bytes from the previous block are included in the calculation. @@ -733,7 +733,7 @@ The following example uses the method to c ## Remarks This method does not affect the state of the decoder. - To calculate the exact array size that requires to store the resulting characters, the application should use . + To calculate the exact array size that requires to store the resulting characters, the application should use . If `GetChars` is called with `flush` set to `false`, the decoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next decoding operation. The application should call `GetCharCount` on a block of data immediately before calling `GetChars` on the same block, so that any trailing bytes from the previous block are included in the calculation. @@ -810,14 +810,14 @@ The following example uses the method to c ## Remarks This method does not affect the state of the decoder. - To calculate the exact array size that requires to store the resulting characters, the application should use . + To calculate the exact array size that requires to store the resulting characters, the application should use . If `GetChars` is called with `flush` set to `false`, the decoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next decoding operation. The application should call `GetCharCount` on a block of data immediately before calling `GetChars` on the same block, so that any trailing bytes from the previous block are included in the calculation. ## Examples - The following code example demonstrates how to use the method to calculate the number of characters required to decode the specified range of bytes in the array. + The following code example demonstrates how to use the method to calculate the number of characters required to decode the specified range of bytes in the array. :::code language="csharp" source="~/snippets/csharp/System.Text/Decoder/GetCharCount/getcharcount-byte[]-int32-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Decoder/GetCharCount/getcharcount-byte[]-int32-int32.vb" id="Snippet1"::: @@ -907,7 +907,7 @@ The following example uses the method to c ## Remarks This method does not affect the state of the decoder. - To calculate the exact array size that requires to store the resulting characters, the application should use . + To calculate the exact array size that requires to store the resulting characters, the application should use . If `GetChars` is called with `flush` set to `false`, the decoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next decoding operation. The application should call `GetCharCount` on a block of data immediately before calling `GetChars` on the same block, so that any trailing bytes from the previous block are included in the calculation. @@ -989,13 +989,13 @@ The following example uses the method to c object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the decoder ignores invalid bytes at the end of the data block and clears the internal buffer. + Remember that the object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the decoder ignores invalid bytes at the end of the data block and clears the internal buffer. - To calculate the exact span size that `GetChars` requires to store the resulting characters, the application should use . + To calculate the exact span size that `GetChars` requires to store the resulting characters, the application should use . If `GetChars` is called with `flush` set to `false`, the decoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next decoding operation. The application should call `GetCharCount` on a block of data immediately before calling `GetChars` on the same block, so that any trailing bytes from the previous block are included in the calculation. - If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output span isn't large enough, but will fill as much space as possible and return the bytes read and chars written, provided the output array allows for at least two characters. Also see the topic for more comments. + If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output span isn't large enough, but will fill as much space as possible and return the bytes read and chars written, provided the output array allows for at least two characters. Also see the topic for more comments. ]]> @@ -1072,13 +1072,13 @@ The following example uses the method to c object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the decoder ignores invalid bytes at the end of the data block and clears the internal buffer. + Remember that the object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the decoder ignores invalid bytes at the end of the data block and clears the internal buffer. - To calculate the exact buffer size that `GetChars` requires to store the resulting characters, the application should use . + To calculate the exact buffer size that `GetChars` requires to store the resulting characters, the application should use . If `GetChars` is called with `flush` set to `false`, the decoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next decoding operation. The application should call `GetCharCount` on a block of data immediately before calling `GetChars` on the same block, so that any trailing bytes from the previous block are included in the calculation. - If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written, provided the output array allows for at least two characters. Also see the topic for more comments. + If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written, provided the output array allows for at least two characters. Also see the topic for more comments. ]]> @@ -1161,18 +1161,18 @@ The following example uses the method to c object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the decoder ignores invalid bytes at the end of the data block and clears the internal buffer. + Remember that the object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the decoder ignores invalid bytes at the end of the data block and clears the internal buffer. - To calculate the exact array size that `GetChars` requires to store the resulting characters, the application should use . + To calculate the exact array size that `GetChars` requires to store the resulting characters, the application should use . If `GetChars` is called with `flush` set to `false`, the decoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next decoding operation. The application should call `GetCharCount` on a block of data immediately before calling `GetChars` on the same block, so that any trailing bytes from the previous block are included in the calculation. - If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written, provided the output array allows for at least two characters. Also see the topic for more comments. + If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written, provided the output array allows for at least two characters. Also see the topic for more comments. ## Examples - The following example demonstrates how to decode a range of elements from a byte array and store them in a Unicode character array. The method is used to calculate the number of characters needed to store the decoded elements in the array `bytes`. The method decodes the specified elements in the byte array and stores them in the new character array. + The following example demonstrates how to decode a range of elements from a byte array and store them in a Unicode character array. The method is used to calculate the number of characters needed to store the decoded elements in the array `bytes`. The method decodes the specified elements in the byte array and stores them in the new character array. :::code language="csharp" source="~/snippets/csharp/System.Text/Decoder/GetChars/getchars-byte[]-int32-int32-char[]-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Decoder/GetChars/getchars-byte[]-int32-int32-char[]-int32.vb" id="Snippet1"::: @@ -1268,13 +1268,13 @@ The following example uses the method to c object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the decoder ignores invalid bytes at the end of the data block and clears the internal buffer. + Remember that the object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the decoder ignores invalid bytes at the end of the data block and clears the internal buffer. - To calculate the exact array size that `GetChars` requires to store the resulting characters, the application should use . + To calculate the exact array size that `GetChars` requires to store the resulting characters, the application should use . If `GetChars` is called with `flush` set to `false`, the decoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next decoding operation. The application should call `GetCharCount` on a block of data immediately before calling `GetChars` on the same block, so that any trailing bytes from the previous block are included in the calculation. - If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written, provided the output array allows for at least two characters. Also see the topic for more comments. + If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written, provided the output array allows for at least two characters. Also see the topic for more comments. ]]> @@ -1358,9 +1358,9 @@ The following example uses the method to c object. The method clears any state information preserved from a previous call to or , including trailing bytes at the end of the previous data block. + This method clears the internal state of the object. The method clears any state information preserved from a previous call to or , including trailing bytes at the end of the previous data block. - Your application should call the method if it wants to reuse the same decoder even after an exception is thrown by , , or , or if the decoder switches streams and begins to decode another stream. + Your application should call the method if it wants to reuse the same decoder even after an exception is thrown by , , or , or if the decoder switches streams and begins to decode another stream. ]]> diff --git a/xml/System.Text/DecoderExceptionFallback.xml b/xml/System.Text/DecoderExceptionFallback.xml index b138812b001..ac4f9aa91f1 100644 --- a/xml/System.Text/DecoderExceptionFallback.xml +++ b/xml/System.Text/DecoderExceptionFallback.xml @@ -81,7 +81,7 @@ ## Examples The following code example demonstrates the and classes. - + :::code language="csharp" source="~/snippets/csharp/System.Text/DecoderExceptionFallback/Overview/fallDecExc.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/DecoderExceptionFallback/Overview/fallDecExc.vb" id="Snippet1"::: @@ -178,7 +178,7 @@ class, which is a subclass of the class. A object throws an exception whenever a sequence of bytes is passed to its method. + A decoder fallback buffer is responsible for receiving and handling byte sequences that a decoder cannot convert to characters. This method returns an instance of the class, which is a subclass of the class. A object throws an exception whenever a sequence of bytes is passed to its method. ]]> @@ -289,7 +289,7 @@ method always returns the same value, the application should not use this value to distinguish one object from another. + Because the method always returns the same value, the application should not use this value to distinguish one object from another. ]]> diff --git a/xml/System.Text/DecoderExceptionFallbackBuffer.xml b/xml/System.Text/DecoderExceptionFallbackBuffer.xml index 1276a6f886b..b58450fc4ad 100644 --- a/xml/System.Text/DecoderExceptionFallbackBuffer.xml +++ b/xml/System.Text/DecoderExceptionFallbackBuffer.xml @@ -48,7 +48,7 @@ method, which throws . + A common reason for an encoding or decoding operation to fail is if the underlying encoding class does not provide a mapping between a character and an equivalent byte sequence. If the input byte sequence cannot be converted to an output character, the decoding operation calls the method, which throws . The class, which represents a data buffer used in a decoding operation, is the base class for the class. However, instead of a data buffer, the class represents a standard behavior in which an exception is thrown if a decoding operation fails. No actual data buffer exists, and the members designed to manipulate such a buffer do no significant work. @@ -143,7 +143,7 @@ and methods call if they encounter an unknown byte in their input. In response, the method always throws and displays the input data. The method nominally indicates whether an exception is thrown if an input byte sequence cannot be decoded. + The and methods call if they encounter an unknown byte in their input. In response, the method always throws and displays the input data. The method nominally indicates whether an exception is thrown if an input byte sequence cannot be decoded. ]]> @@ -195,7 +195,7 @@ has no actual exception data buffer, the method always returns the Unicode NULL character. + Because has no actual exception data buffer, the method always returns the Unicode NULL character. ]]> @@ -246,7 +246,7 @@ has no actual exception data buffer, the method always returns `false`. + Because has no actual exception data buffer, the method always returns `false`. ]]> diff --git a/xml/System.Text/DecoderFallback.xml b/xml/System.Text/DecoderFallback.xml index 9460cd7af04..fbf265cbf29 100644 --- a/xml/System.Text/DecoderFallback.xml +++ b/xml/System.Text/DecoderFallback.xml @@ -73,7 +73,7 @@ class. Specifically, a character is encoded to a byte sequence by calling the encoding type's method, and the byte sequence is decoded to a character array or a string by calling the or method. + An encoding maps a Unicode character to an encoded sequence of bytes. A particular encoding is represented by a type that is derived from the class. Specifically, a character is encoded to a byte sequence by calling the encoding type's method, and the byte sequence is decoded to a character array or a string by calling the or method. A decoding operation can fail if the input byte sequence cannot be mapped by the encoding. For example, an object cannot decode a byte sequence if that sequence represents a character that has a code point value that is outside the range U+0000 to U+007F. @@ -83,13 +83,13 @@ - Best-fit fallback, which maps valid Unicode characters that cannot be decoded to an approximate equivalent. For example, a best-fit fallback handler for the class might map Æ (U+00C6) to AE (U+0041 + U+0045). A best-fit fallback handler might also be implemented to transliterate one alphabet (such as Cyrillic) to another (such as Latin or Roman). The .NET Framework does not provide any public best-fit fallback implementations. -- Replacement fallback, which replaces each character that cannot be decoded with a predefined string. The .NET Framework provides a predefined replacement fallback handler. The class replaces each byte sequence that cannot be decoded with a question mark character ("?", or U+003F) or a REPLACEMENT CHARACTER (U+FFFD). You can customize the replacement string by specifying a substitute in the call to the constructor. After the substitute string is emitted, the decoding operation continues converting the remainder of the input. +- Replacement fallback, which replaces each character that cannot be decoded with a predefined string. The .NET Framework provides a predefined replacement fallback handler. The class replaces each byte sequence that cannot be decoded with a question mark character ("?", or U+003F) or a REPLACEMENT CHARACTER (U+FFFD). You can customize the replacement string by specifying a substitute in the call to the constructor. After the substitute string is emitted, the decoding operation continues converting the remainder of the input. - Exception fallback, which throws an exception when a byte sequence cannot be decoded. The .NET Framework provides a predefined exception fallback handler. The class throws a when an invalid byte sequence is encountered, and the decoding operation terminates. If you choose to implement a custom solution, you must override the following abstract members of the class: -- The method, which returns a class instance derived from . Depending on the type of fallback handler that you are developing, the implementation is responsible for performing the mapping or replacement, or for throwing the exception. +- The method, which returns a class instance derived from . Depending on the type of fallback handler that you are developing, the implementation is responsible for performing the mapping or replacement, or for throwing the exception. - The property, which returns the maximum number of characters that the fallback implementation can return. For an exception fallback handler, its value should be zero. @@ -191,9 +191,9 @@ that is responsible for performing the fallback operation. For example, of the predefined implementations in the .NET Framework, the method returns a object, and the method returns a object. + This method returns an object derived from that is responsible for performing the fallback operation. For example, of the predefined implementations in the .NET Framework, the method returns a object, and the method returns a object. - The method is called by a decoder when it encounters the first byte that it is unable to decode. The object returned by this method provides the fallback implementation and is responsible for returning the string that replaces the byte or bytes that could not be decoded. + The method is called by a decoder when it encounters the first byte that it is unable to decode. The object returned by this method provides the fallback implementation and is responsible for returning the string that replaces the byte or bytes that could not be decoded. ]]> diff --git a/xml/System.Text/DecoderFallbackBuffer.xml b/xml/System.Text/DecoderFallbackBuffer.xml index a7f8047e6d3..a1454049b97 100644 --- a/xml/System.Text/DecoderFallbackBuffer.xml +++ b/xml/System.Text/DecoderFallbackBuffer.xml @@ -80,11 +80,11 @@ The buffer in a implementation represents the entire string to be returned to the decoder in response to a decoder fallback. Generally, implementations also include state information, such as the index of the next character to return to the decoder and the number of remaining characters to be returned. Because is an abstract class, it requires derived classes to implement the following members at a minimum: -- The method, which is called by the decoder when it cannot decode a byte sequence. The decoder passes two pieces of information to the fallback buffer implementation: an array containing the bytes that could not be decoded and the index of the first byte in the input byte array. In a decoder fallback exception handler, the exception is thrown in this method. Otherwise, the method returns `true` if it provides a fallback, or `false` if it does not. +- The method, which is called by the decoder when it cannot decode a byte sequence. The decoder passes two pieces of information to the fallback buffer implementation: an array containing the bytes that could not be decoded and the index of the first byte in the input byte array. In a decoder fallback exception handler, the exception is thrown in this method. Otherwise, the method returns `true` if it provides a fallback, or `false` if it does not. -- The method, which is called repeatedly by the decoder if the method returns `true`. In successive calls, the handler should return each character in its buffer. When it has returned all characters, it should return U+0000. An exception fallback handler always returns U+0000. +- The method, which is called repeatedly by the decoder if the method returns `true`. In successive calls, the handler should return each character in its buffer. When it has returned all characters, it should return U+0000. An exception fallback handler always returns U+0000. -- The method, which tries to move the pointer to the previous position in the buffer and indicates whether the move was successful. An exception handler always returns `false`. +- The method, which tries to move the pointer to the previous position in the buffer and indicates whether the move was successful. An exception handler always returns `false`. - The property, which indicates the number of remaining characters to be returned to the decoder. An exception fallback handler always returns zero. @@ -189,7 +189,7 @@ ## Remarks -The , , and methods call if they encounter an unknown input byte sequence that cannot be decoded. A return value of `true` indicates that the fallback buffer can process the input byte sequence, which causes the calling method to call the method to obtain each character of the fallback buffer. If called in an exception fallback handler, the method throws an exception because it does not process individual bytes. +The , , and methods call if they encounter an unknown input byte sequence that cannot be decoded. A return value of `true` indicates that the fallback buffer can process the input byte sequence, which causes the calling method to call the method to obtain each character of the fallback buffer. If called in an exception fallback handler, the method throws an exception because it does not process individual bytes. ]]> @@ -245,9 +245,9 @@ The , method if the operation encounters an unknown byte sequence in the input. If the method returns `true`, a substitute string exists that can be inserted in the output instead of decoding the unknown input. The decoding operation calls the method repeatedly and obtains the substitute string one character at a time. When all characters in the fallback buffer have been returned to the decoder, the method should return U+0000. + A decoding operation calls the method if the operation encounters an unknown byte sequence in the input. If the method returns `true`, a substitute string exists that can be inserted in the output instead of decoding the unknown input. The decoding operation calls the method repeatedly and obtains the substitute string one character at a time. When all characters in the fallback buffer have been returned to the decoder, the method should return U+0000. - For an exception fallback handler, the method should return U+0000. + For an exception fallback handler, the method should return U+0000. ]]> @@ -353,9 +353,9 @@ The , method returns `true` if is a nonzero value. + The method returns `true` if is a nonzero value. - For an exception fallback handler, the method should return zero. + For an exception fallback handler, the method should return zero. ]]> diff --git a/xml/System.Text/DecoderReplacementFallback.xml b/xml/System.Text/DecoderReplacementFallback.xml index 765c47a6875..3612ef45357 100644 --- a/xml/System.Text/DecoderReplacementFallback.xml +++ b/xml/System.Text/DecoderReplacementFallback.xml @@ -79,7 +79,7 @@ - Replacement with the default character. If you call the constructor, the replacement character is "?" (U+003F). -- Replacement with a string of your choice. If you call the constructor, you provide the replacement string. +- Replacement with a string of your choice. If you call the constructor, you provide the replacement string. This class is one of two .NET Framework classes that implement different fallback strategies for handling decoding conversion failures. The other class is the class, which throws a when an invalid byte sequence is encountered. diff --git a/xml/System.Text/DecoderReplacementFallbackBuffer.xml b/xml/System.Text/DecoderReplacementFallbackBuffer.xml index b7d10139533..30db0106bea 100644 --- a/xml/System.Text/DecoderReplacementFallbackBuffer.xml +++ b/xml/System.Text/DecoderReplacementFallbackBuffer.xml @@ -152,7 +152,7 @@ and methods call if they encounter an unknown input byte sequence that cannot be decoded. If the return value of is `true`, the calling method can invoke the method to obtain each character of the fallback buffer. + The and methods call if they encounter an unknown input byte sequence that cannot be decoded. If the return value of is `true`, the calling method can invoke the method to obtain each character of the fallback buffer. ]]> @@ -202,7 +202,7 @@ and methods call if they encounter an unknown surrogate pair or character in their input. If the return value of is `true`, the calling method can invoke to obtain each character of the replacement fallback buffer. + The and methods call if they encounter an unknown surrogate pair or character in their input. If the return value of is `true`, the calling method can invoke to obtain each character of the replacement fallback buffer. ]]> @@ -293,7 +293,7 @@ method returns `true` if the property is nonzero. + The method returns `true` if the property is nonzero. ]]> @@ -347,7 +347,7 @@ method discards any persisted state information and data that govern the emitting of a replacement string. Unpredictable results occur if the decoding operation continues after the method is invoked. + The method discards any persisted state information and data that govern the emitting of a replacement string. Unpredictable results occur if the decoding operation continues after the method is invoked. ]]> diff --git a/xml/System.Text/Encoder.xml b/xml/System.Text/Encoder.xml index e39564962e1..7db9ab43f9f 100644 --- a/xml/System.Text/Encoder.xml +++ b/xml/System.Text/Encoder.xml @@ -74,14 +74,14 @@ Converts a set of characters into a sequence of bytes. class, the application should use the method of an implementation. +To obtain an instance of an implementation of the class, the application should use the method of an implementation. -The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. There are several versions of both of these methods available in the class. For more information, see . +The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. There are several versions of both of these methods available in the class. For more information, see . -A object maintains state information between successive calls to `GetBytes` or methods so that it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. +A object maintains state information between successive calls to `GetBytes` or methods so that it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. > [!NOTE] -> When the application is done with a stream of data it should make sure that the state information is flushed by setting the `flush` parameter to `true` in the appropriate method call. If an exception occurs or if the application switches streams, it should call to clear the internal state of the `Encoder` object. +> When the application is done with a stream of data it should make sure that the state information is flushed by setting the `flush` parameter to `true` in the appropriate method call. If an exception occurs or if the application switches streams, it should call to clear the internal state of the `Encoder` object. ]]> @@ -144,7 +144,7 @@ The following example demonstrates how to convert an array of Unicode characters method of an implementation. + To obtain an instance of an implementation of this class, the application should use the method of an implementation. @@ -222,9 +222,9 @@ The following example demonstrates how to convert an array of Unicode characters object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the encoder ignores invalid bytes at the end of the data block and clears the internal buffer. Any remaining processed data that is part of a logical unit, such as the high surrogate of a surrogate pair, is converted according to the current fallback settings. + Remember that the object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the encoder ignores invalid bytes at the end of the data block and clears the internal buffer. Any remaining processed data that is part of a logical unit, such as the high surrogate of a surrogate pair, is converted according to the current fallback settings. - The `Convert` method is designed to be used in a loop to encode an arbitrary amount of input, such as data read from a file or stream. It stores the output of the encoding operation in a fixed-size buffer. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the chars read and bytes written. Also see the topic for more comments. + The `Convert` method is designed to be used in a loop to encode an arbitrary amount of input, such as data read from a file or stream. It stores the output of the encoding operation in a fixed-size buffer. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the chars read and bytes written. Also see the topic for more comments. The `completed` output parameter indicates whether all the data in the input buffer was converted and stored in the output buffer. This parameter is set to `false` if the number of characters specified by the `charCount` parameter cannot be converted without exceeding the number of bytes specified by the `byteCount` parameter. In that situation, the application should use the contents of the output buffer or provide a new output buffer, increment the `chars` parameter by the number of characters specified by the `charsUsed` parameter, then call the `Convert` method again to process the remaining input. @@ -310,9 +310,9 @@ The following example demonstrates how to convert an array of Unicode characters object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the encoder ignores invalid bytes at the end of the data block and clears the internal buffer. Any remaining processed data that is part of a logical unit, such as the high surrogate of a surrogate pair, is converted according to the current fallback settings. + Remember that the object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the encoder ignores invalid bytes at the end of the data block and clears the internal buffer. Any remaining processed data that is part of a logical unit, such as the high surrogate of a surrogate pair, is converted according to the current fallback settings. - The `Convert` method is designed to be used in a loop to encode an arbitrary amount of input, such as data read from a file or stream. It stores the output of the encoding operation in a fixed-size buffer. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the chars read and bytes written. Also see the topic for more comments. + The `Convert` method is designed to be used in a loop to encode an arbitrary amount of input, such as data read from a file or stream. It stores the output of the encoding operation in a fixed-size buffer. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the chars read and bytes written. Also see the topic for more comments. The `completed` output parameter indicates whether all the data in the input buffer was converted and stored in the output buffer. This parameter is set to `false` if the number of characters specified by the `charCount` parameter cannot be converted without exceeding the number of bytes specified by the `byteCount` parameter. In that situation, the application should use the contents of the output buffer or provide a new output buffer, increment the `chars` parameter by the number of characters specified by the `charsUsed` parameter, then call the `Convert` method again to process the remaining input. @@ -408,9 +408,9 @@ The following example demonstrates how to convert an array of Unicode characters object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the encoder ignores invalid bytes at the end of the data block and clears the internal buffer. Any remaining processed data that is part of a logical unit, such as the high surrogate of a surrogate pair, is converted according to the current fallback settings. + Remember that the object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the encoder ignores invalid bytes at the end of the data block and clears the internal buffer. Any remaining processed data that is part of a logical unit, such as the high surrogate of a surrogate pair, is converted according to the current fallback settings. - The `Convert` method is designed to be used in a loop to encode an arbitrary amount of input, such as data read from a file or stream. It stores the output of the encoding operation in a fixed-size buffer. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the chars read and bytes written. Also see the article for more comments. + The `Convert` method is designed to be used in a loop to encode an arbitrary amount of input, such as data read from a file or stream. It stores the output of the encoding operation in a fixed-size buffer. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the chars read and bytes written. Also see the article for more comments. The `completed` output parameter indicates whether all the data in the input buffer was converted and stored in the output buffer. This parameter is set to `false` if the number of characters specified by the `charCount` parameter cannot be converted without exceeding the number of bytes specified by the `byteCount` parameter. In that situation, the application should use the contents of the output buffer or provide a new output buffer, increment the `chars` parameter by the number of characters specified by the `charsUsed` parameter, then call the `Convert` method again to process the remaining input. @@ -419,7 +419,7 @@ The following example demonstrates how to convert an array of Unicode characters ## Examples - The following example uses the method to convert a file of UTF-16 characters to UTF-8, then uses the method to convert the UTF-8 characters back to UTF-16 characters. + The following example uses the method to convert a file of UTF-16 characters to UTF-8, then uses the method to convert the UTF-8 characters back to UTF-16 characters. :::code language="csharp" source="~/snippets/csharp/System.Text/Decoder/Convert/edCvt.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Decoder/Convert/edCvt.vb" id="Snippet1"::: @@ -574,7 +574,7 @@ The following example demonstrates how to convert an array of Unicode characters object represents data used by the object. The object represents an error handler that is invoked when a character cannot be converted into an encoded byte sequence. + The object represents data used by the object. The object represents an error handler that is invoked when a character cannot be converted into an encoded byte sequence. ]]> @@ -596,7 +596,7 @@ The following example demonstrates how to convert an array of Unicode characters ## Remarks This method does not affect the state of the encoder. - To calculate the exact array size that requires to store the resulting bytes, the application should use . + To calculate the exact array size that requires to store the resulting bytes, the application should use . If `GetBytes` is called with `flush` set to `false`, the encoder stores trailing characters at the end of the data block in an internal buffer and uses them in the next encoding operation. The application should call `GetByteCount` on a block of data immediately before calling `GetBytes` on the same block, so that any trailing characters from the previous block are included in the calculation. @@ -787,7 +787,7 @@ The following example demonstrates how to convert an array of Unicode characters ## Examples -The following code example demonstrates how to use the method to return the number of bytes required to encode an array of characters using a Unicode . +The following code example demonstrates how to use the method to return the number of bytes required to encode an array of characters using a Unicode . :::code language="csharp" source="~/snippets/csharp/System.Text/Encoder/GetByteCount/getbytecount-char[]-int32-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoder/GetByteCount/getbytecount-char[]-int32-int32.vb" id="Snippet1"::: @@ -824,13 +824,13 @@ The following code example demonstrates how to use the object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` in the last call to `GetBytes` to make sure that the state information is flushed and that the encoded bytes are properly terminated. With this setting, the encoder ignores invalid bytes at the end of the data block, such as unmatched surrogates or incomplete combining sequences, and clears the internal buffer. +Remember that the object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` in the last call to `GetBytes` to make sure that the state information is flushed and that the encoded bytes are properly terminated. With this setting, the encoder ignores invalid bytes at the end of the data block, such as unmatched surrogates or incomplete combining sequences, and clears the internal buffer. -To calculate the exact buffer size that `GetBytes` requires to store the resulting characters, the application should use . +To calculate the exact buffer size that `GetBytes` requires to store the resulting characters, the application should use . If `GetBytes` is called with `flush` set to `false`, the encoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next encoding operation. The application should call `GetByteCount` on a block of data immediately before calling `GetBytes` on the same block, so that any trailing characters from the previous block are included in the calculation. -If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the chars read and bytes written. Also see the topic for more comments. +If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the chars read and bytes written. Also see the topic for more comments. ]]> @@ -1034,7 +1034,7 @@ If your application is to convert many segments of an input stream, consider usi method is used to determine the size of the array required by . + The following example demonstrates how to encode a range of elements from a character array and store the encoded bytes in a range of elements in a byte array. The method is used to determine the size of the array required by . :::code language="csharp" source="~/snippets/csharp/System.Text/Encoder/GetBytes/getbytes-char[]-int32-int32-byte[]-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoder/GetBytes/getbytes-char[]-int32-int32-byte[]-int32.vb" id="Snippet1"::: @@ -1118,9 +1118,9 @@ If your application is to convert many segments of an input stream, consider usi object. The method clears any state information preserved from a previous call to or , including trailing characters at the end of the previous data block, such as an unmatched high surrogate. + This method clears the internal state of the object. The method clears any state information preserved from a previous call to or , including trailing characters at the end of the previous data block, such as an unmatched high surrogate. - Your application should call the `Reset` method if it wants to reuse the same encoder even after an exception is thrown by or , or if the application switches streams. + Your application should call the `Reset` method if it wants to reuse the same encoder even after an exception is thrown by or , or if the application switches streams. ]]> diff --git a/xml/System.Text/EncoderExceptionFallback.xml b/xml/System.Text/EncoderExceptionFallback.xml index 34facfa552b..0c96628935c 100644 --- a/xml/System.Text/EncoderExceptionFallback.xml +++ b/xml/System.Text/EncoderExceptionFallback.xml @@ -81,7 +81,7 @@ ## Examples The following code example demonstrates the and classes. - + :::code language="csharp" source="~/snippets/csharp/System.Text/EncoderExceptionFallback/Overview/fallEncExc.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/EncoderExceptionFallback/Overview/fallEncExc.vb" id="Snippet1"::: @@ -178,7 +178,7 @@ class, which is a subclass of the class. An object throws an exception whenever characters are passed to its method. + An encoder fallback buffer is responsible for receiving and handling characters that an encoder cannot convert to a byte sequence. This method returns an instance of the class, which is a subclass of the class. An object throws an exception whenever characters are passed to its method. ]]> @@ -289,7 +289,7 @@ method always returns the same value, the application should not use this value to distinguish one instance of the class from another. + Because the method always returns the same value, the application should not use this value to distinguish one instance of the class from another. ]]> diff --git a/xml/System.Text/EncoderExceptionFallbackBuffer.xml b/xml/System.Text/EncoderExceptionFallbackBuffer.xml index f5cee29364f..693155c05c5 100644 --- a/xml/System.Text/EncoderExceptionFallbackBuffer.xml +++ b/xml/System.Text/EncoderExceptionFallbackBuffer.xml @@ -48,7 +48,7 @@ method, which throws . + A common reason for an encoding or decoding operation to fail is if the underlying encoding class does not provide a mapping between a character and an equivalent byte sequence. If the input character cannot be converted to an output byte sequence, the encoding operation calls the method, which throws . The class, which represents a data buffer used in an encoding operation, is the base class for the class. However, instead of a data buffer, the class represents a standard behavior wherein an exception is thrown if an encoding operation fails. No actual data buffer exists, and the members designed to manipulate such a buffer do no significant work. @@ -151,7 +151,7 @@ and methods call if they encounter an unknown character in their input. In response, always throws . + The and methods call if they encounter an unknown character in their input. In response, always throws . ]]> @@ -209,7 +209,7 @@ and methods call if they encounter a surrogate pair in their input. In response, always throws an exception. + The and methods call if they encounter a surrogate pair in their input. In response, always throws an exception. ]]> @@ -262,7 +262,7 @@ has no actual exception data buffer, the method always returns the Unicode NULL character. + Because has no actual exception data buffer, the method always returns the Unicode NULL character. ]]> @@ -313,7 +313,7 @@ has no actual exception data buffer, the method always returns `false`. + Because has no actual exception data buffer, the method always returns `false`. ]]> diff --git a/xml/System.Text/EncoderFallback.xml b/xml/System.Text/EncoderFallback.xml index d782ef968ce..5e886a6af78 100644 --- a/xml/System.Text/EncoderFallback.xml +++ b/xml/System.Text/EncoderFallback.xml @@ -73,7 +73,7 @@ class. Specifically, a character is encoded to a byte sequence by calling the encoding type's method, and the byte sequence is decoded to a character array or a string by calling the or method. + An encoding maps a Unicode character to an encoded sequence of bytes. A particular encoding is represented by a type that is derived from the class. Specifically, a character is encoded to a byte sequence by calling the encoding type's method, and the byte sequence is decoded to a character array or a string by calling the or method. An encoding operation can fail if the input character cannot be represented by the encoding. For example, an object cannot encode a character whose Unicode code point value is outside the range U+0000 to U+007F. @@ -83,13 +83,13 @@ - Best-fit fallback, which maps valid Unicode characters that cannot be encoded to an approximate equivalent. For example, a best-fit fallback handler for the class might map Æ (U+00C6) to AE (U+0041 + U+0045). A best-fit fallback handler might also be implemented to transliterate one alphabet (such as Cyrillic) to another (such as Latin or Roman). The .NET Framework does not provide any public best-fit fallback implementations. -- Replacement fallback, which replaces each character that cannot be encoded with a predefined string. The .NET Framework provides a predefined replacement fallback handler. The class replaces each byte sequence that cannot be decoded with a question mark character ("?", or U+003F) or a REPLACEMENT CHARACTER (U+FFFD). You can customize the replacement string by specifying a substitute in the call to the constructor. After the substitute string is emitted, the encoding operation continues converting the remainder of the input. +- Replacement fallback, which replaces each character that cannot be encoded with a predefined string. The .NET Framework provides a predefined replacement fallback handler. The class replaces each byte sequence that cannot be decoded with a question mark character ("?", or U+003F) or a REPLACEMENT CHARACTER (U+FFFD). You can customize the replacement string by specifying a substitute in the call to the constructor. After the substitute string is emitted, the encoding operation continues converting the remainder of the input. - Exception fallback, which throws an exception when a character cannot be encoded. The .NET Framework provides a predefined exception fallback handler. The class throws an when an invalid character is encountered, and the encoding operation terminates. If you choose to implement a custom solution, you must override the following abstract members of the class: -- The method, which returns a class instance derived from . Depending on the type of fallback handler that you are developing, the implementation is responsible for performing the mapping or replacement, or for throwing the exception. +- The method, which returns a class instance derived from . Depending on the type of fallback handler that you are developing, the implementation is responsible for performing the mapping or replacement, or for throwing the exception. - The property, which returns the maximum number of characters that the fallback implementation can return. For an exception fallback handler, its value should be zero. @@ -191,9 +191,9 @@ that is responsible for performing the fallback operation. For example, of the predefined implementations in the .NET Framework, the method returns an object, and the method returns an object. + This method returns an object derived from that is responsible for performing the fallback operation. For example, of the predefined implementations in the .NET Framework, the method returns an object, and the method returns an object. - The method is called by an encoder when it encounters the first character that it is unable to encode. The object returned by this method provides the fallback implementation and is responsible for returning the byte array that replaces the character or characters that could not be encoded. + The method is called by an encoder when it encounters the first character that it is unable to encode. The object returned by this method provides the fallback implementation and is responsible for returning the byte array that replaces the character or characters that could not be encoded. ]]> diff --git a/xml/System.Text/EncoderFallbackBuffer.xml b/xml/System.Text/EncoderFallbackBuffer.xml index 894949e512f..dd5ae770077 100644 --- a/xml/System.Text/EncoderFallbackBuffer.xml +++ b/xml/System.Text/EncoderFallbackBuffer.xml @@ -80,11 +80,11 @@ The buffer in an implementation represents the entire string to be returned to the encoder in response to an encoder fallback. Generally, implementations also include state information, such as the index of the next character to return to the encoder and the number of remaining characters to be returned. Because is an abstract class, it requires derived classes to implement the following members at a minimum: -- The overloaded method, which is called by the encoder when it cannot encode a character. The encoder passes two pieces of information to the fallback buffer implementation: the character or surrogate pair that could not be encoded and the index of the character in the input. In an encoder fallback exception handler, the exception is thrown in this method. Otherwise, the method returns `true` if it provides a fallback, or `false` if it does not. +- The overloaded method, which is called by the encoder when it cannot encode a character. The encoder passes two pieces of information to the fallback buffer implementation: the character or surrogate pair that could not be encoded and the index of the character in the input. In an encoder fallback exception handler, the exception is thrown in this method. Otherwise, the method returns `true` if it provides a fallback, or `false` if it does not. -- The method, which is called repeatedly by the encoder if the method returns `true`. In successive calls, the handler should return each character in its buffer. When it has returned all characters, it should return U+0000. An exception handler always returns U+0000. +- The method, which is called repeatedly by the encoder if the method returns `true`. In successive calls, the handler should return each character in its buffer. When it has returned all characters, it should return U+0000. An exception handler always returns U+0000. -- The method, which tries to move the pointer to the previous position in the buffer and indicates whether the move was successful. An exception handler always returns `false`. +- The method, which tries to move the pointer to the previous position in the buffer and indicates whether the move was successful. An exception handler always returns `false`. - The property, which indicates the number of remaining characters to be returned to the encoder. An exception fallback handler always returns zero. @@ -197,7 +197,7 @@ and methods call if they encounter an unknown input character that cannot be encoded. A return value of `true` indicates that the fallback buffer can process the input character, which causes the calling method to call the method to obtain each character of the fallback buffer. Because it does not process individual characters, the method in an exception fallback handler throws an exception. + The and methods call if they encounter an unknown input character that cannot be encoded. A return value of `true` indicates that the fallback buffer can process the input character, which causes the calling method to call the method to obtain each character of the fallback buffer. Because it does not process individual characters, the method in an exception fallback handler throws an exception. ]]> @@ -258,7 +258,7 @@ and methods call if they encounter a surrogate pair in their input. A return value of `true` indicates that the fallback buffer can process the surrogate pair, which causes the calling method to call the method to obtain each character of the fallback buffer. Because it does not process individual characters, the method in an exception fallback handler throws an exception. + The and methods call if they encounter a surrogate pair in their input. A return value of `true` indicates that the fallback buffer can process the surrogate pair, which causes the calling method to call the method to obtain each character of the fallback buffer. Because it does not process individual characters, the method in an exception fallback handler throws an exception. ]]> @@ -311,9 +311,9 @@ method if the operation encounters an unknown character or surrogate pair in the input. For example, in the case of a replacement fallback, if the method returns `true`, a substitute string exists that can be encoded instead of the unknown input. The encoding operation calls the method repeatedly and obtains the substitute string one character at a time. When all characters in the fallback buffer have been returned to the encoder, the method should return U+0000. + An encoding operation calls the method if the operation encounters an unknown character or surrogate pair in the input. For example, in the case of a replacement fallback, if the method returns `true`, a substitute string exists that can be encoded instead of the unknown input. The encoding operation calls the method repeatedly and obtains the substitute string one character at a time. When all characters in the fallback buffer have been returned to the encoder, the method should return U+0000. - For an exception fallback handler, the method should return U+0000. + For an exception fallback handler, the method should return U+0000. ]]> @@ -419,9 +419,9 @@ method returns `true` if is a nonzero value. + The method returns `true` if is a nonzero value. - For an exception fallback handler, the method should return zero. + For an exception fallback handler, the method should return zero. ]]> diff --git a/xml/System.Text/EncoderReplacementFallback.xml b/xml/System.Text/EncoderReplacementFallback.xml index c48d673cb5c..8fbe77ec861 100644 --- a/xml/System.Text/EncoderReplacementFallback.xml +++ b/xml/System.Text/EncoderReplacementFallback.xml @@ -79,7 +79,7 @@ - Replacement with the default character. If you call the constructor, the replacement character is "?" (U+003F). -- Replacement with a string of your choice. If you call the constructor, you provide the replacement string. +- Replacement with a string of your choice. If you call the constructor, you provide the replacement string. If you choose a fallback string to use with this class, make sure that the string is composed entirely of characters that can be encoded in the target encoding. Otherwise, a recursive fallback results, causing an . diff --git a/xml/System.Text/EncoderReplacementFallbackBuffer.xml b/xml/System.Text/EncoderReplacementFallbackBuffer.xml index 6197f574d79..1662ead3e48 100644 --- a/xml/System.Text/EncoderReplacementFallbackBuffer.xml +++ b/xml/System.Text/EncoderReplacementFallbackBuffer.xml @@ -157,7 +157,7 @@ and methods call if they encounter an unknown character in their input. If the return value of is `true`, the calling method can invoke the method to obtain each character in the replacement fallback buffer. + The and methods call if they encounter an unknown character in their input. If the return value of is `true`, the calling method can invoke the method to obtain each character in the replacement fallback buffer. ]]> @@ -215,7 +215,7 @@ and methods call if they encounter an unknown character in their input. If the return value of is `true`, the calling method can invoke the method to obtain each character in the replacement fallback buffer. + The and methods call if they encounter an unknown character in their input. If the return value of is `true`, the calling method can invoke the method to obtain each character in the replacement fallback buffer. ]]> @@ -270,7 +270,7 @@ and methods call if they encounter an unknown surrogate pair or character in their input. If the return value of is `true`, the calling method can invoke to obtain each character in the replacement fallback buffer. + The and methods call if they encounter an unknown surrogate pair or character in their input. If the return value of is `true`, the calling method can invoke to obtain each character in the replacement fallback buffer. ]]> @@ -361,7 +361,7 @@ method returns `true` if the property is nonzero. + The method returns `true` if the property is nonzero. ]]> @@ -415,7 +415,7 @@ method discards any persisted state information and data that govern emitting a replacement string. Unpredictable results occur if the encoding operation continues after the method is invoked. + The method discards any persisted state information and data that govern emitting a replacement string. Unpredictable results occur if the encoding operation continues after the method is invoked. ]]> diff --git a/xml/System.Text/Encoding.xml b/xml/System.Text/Encoding.xml index 8206ed1bd84..04ef4276487 100644 --- a/xml/System.Text/Encoding.xml +++ b/xml/System.Text/Encoding.xml @@ -92,7 +92,7 @@ The following example converts a string from one encoding to another. > [!NOTE] -> The `byte[]` array is the only type in this example that contains the encoded data. The .NET `Char` and `String` types are themselves Unicode, so the call decodes the data back to Unicode. +> The `byte[]` array is the only type in this example that contains the encoded data. The .NET `Char` and `String` types are themselves Unicode, so the call decodes the data back to Unicode. :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoding/Overview/convert.vb" id="Snippet1"::: @@ -222,7 +222,7 @@ The following example converts a string from one encoding to another. ## Remarks Derived classes override this constructor. - Calls to this constructor from a derived class create an object that uses best-fit fallback for both encoding and decoding operations. Both the and properties are read-only and cannot be modified. To control the fallback strategy for a class derived from , call the constructor. + Calls to this constructor from a derived class create an object that uses best-fit fallback for both encoding and decoding operations. Both the and properties are read-only and cannot be modified. To control the fallback strategy for a class derived from , call the constructor. ]]> @@ -357,7 +357,7 @@ The following example converts a string from one encoding to another. - Prior to .NET Framework version 2.0, .NET Framework allowed spoofing by ignoring the 8th bit. Beginning with .NET Framework 2.0, non-ASCII code points fall back during decoding. - The object that is returned by this property might not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the method to instantiate an object whose fallback is either an or a , as the following example illustrates. + The object that is returned by this property might not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the method to instantiate an object whose fallback is either an or a , as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/ASCII/encoding.ascii2.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoding/ASCII/encoding.ascii2.vb" id="Snippet1"::: @@ -426,12 +426,12 @@ The following example demonstrates the effect of the ASCII encoding on character object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a big endian object whose fallback is either an or a , as the following example illustrates. + The object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a big endian object whose fallback is either an or a , as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/bigendianunicode1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoding/BigEndianUnicode/bigendianunicode1.vb" id="Snippet2"::: - The returned object has , , and properties, which yield the name "unicodeFFFE". Although the UTF-16 big endian byte order mark is hexadecimal FEFF, the name "unicodeFFFE" was chosen because the byte order mark appears as hexadecimal FFFE on little endian Windows computers. + The returned object has , , and properties, which yield the name "unicodeFFFE". Although the UTF-16 big endian byte order mark is hexadecimal FEFF, the name "unicodeFFFE" was chosen because the byte order mark appears as hexadecimal FFFE on little endian Windows computers. ## Examples The following example reads a text file with a UTF-16 encoding using the big endian byte order. @@ -502,12 +502,12 @@ The following example demonstrates the effect of the ASCII encoding on character with the property. Often the method retrieves a different encoding from the test encoding furnished in the call. Generally only email applications need to retrieve such an encoding; most other applications that need to describe an encoding should use its . + If you need an encoding for a body name, you should call with the property. Often the method retrieves a different encoding from the test encoding furnished in the call. Generally only email applications need to retrieve such an encoding; most other applications that need to describe an encoding should use its . In some cases, the value of the property corresponds to the international standard that defines that encoding. This doesn't mean that the implementation complies in full with that standard. ## Examples - The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. + The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoding/BodyName/names.vb" id="Snippet1"::: @@ -635,7 +635,7 @@ The following example demonstrates the effect of the ASCII encoding on character . It displays but does not compare against it. + The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoding/BodyName/names.vb" id="Snippet1"::: @@ -1140,10 +1140,10 @@ For more information about this API, see property is intended for display. To find a name that can be passed to the method, use the property. + The property is intended for display. To find a name that can be passed to the method, use the property. ## Examples - The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. + The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoding/BodyName/names.vb" id="Snippet1"::: @@ -1217,7 +1217,7 @@ For more information about this API, see are considered equal if they correspond to the same code page and their `EncoderFallback` and `DecoderFallback` objects are equal. In particular, derived code pages all have a code page of 0 and their fallbacks are normally `null` (`Nothing` in Visual Basic .NET). Thus they are all considered equal to one another. One consequence is that when is used to populate a hash table, all derived encodings compare equal and fall into the same hash table slot. + Two instances of are considered equal if they correspond to the same code page and their `EncoderFallback` and `DecoderFallback` objects are equal. In particular, derived code pages all have a code page of 0 and their fallbacks are normally `null` (`Nothing` in Visual Basic .NET). Thus they are all considered equal to one another. One consequence is that when is used to populate a hash table, all derived encodings compare equal and fall into the same hash table slot. ## Examples The following example gets two instances of the same encoding (one by codepage and another by name), and checks their equality. @@ -1293,21 +1293,21 @@ For more information about this API, see to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: - Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. -- If your app handles string inputs, you should use the string versions of the method. +- If your app handles string inputs, you should use the string versions of the method. -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, you should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. +- If your app must convert a large amount of data, you should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. ## Examples The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. @@ -1373,17 +1373,17 @@ For more information about this API, see to store the resulting bytes, call the method. To calculate the maximum span size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact span size required by to store the resulting bytes, call the method. To calculate the maximum span size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: - Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. -- If your app handles span of characters inputs, the span version of is recommended. +- If your app handles span of characters inputs, the span version of is recommended. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output span buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output span buffer is too small. For continuous encoding of a stream, this method is often the best choice. ]]> @@ -1441,21 +1441,21 @@ For more information about this API, see to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: - Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. -- If your app handles string inputs, the string version of is recommended. +- If your app handles string inputs, the string version of is recommended. -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. ## Examples The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. @@ -1542,21 +1542,21 @@ For more information about this API, see requires to store the resulting bytes, you should call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size that requires to store the resulting bytes, you should call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - Several versions of and are supported. The following are some considerations for using these methods: + Several versions of and are supported. The following are some considerations for using these methods: - Your app may need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. -- If your app handles string inputs, you should use the string version of the method. +- If your app handles string inputs, you should use the string version of the method. -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. ]]> @@ -1630,21 +1630,21 @@ For more information about this API, see to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: - Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. -- If your app handles string inputs, the string version of is recommended. +- If your app handles string inputs, the string version of is recommended. -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. ## Examples The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. @@ -1721,21 +1721,21 @@ For more information about this API, see to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: - Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. -- If your app handles string inputs, the string version of is recommended. +- If your app handles string inputs, the string version of is recommended. -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. ## Examples The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. @@ -1809,21 +1809,21 @@ For more information about this API, see or the provided by the method or the method, respectively, of a derived class. + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: - Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) -- If your app handles string inputs, you should call the string version of the method. +- If your app handles string inputs, you should call the string version of the method. -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. ## Examples The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. @@ -1897,21 +1897,21 @@ For more information about this API, see or the provided by the method or the method, respectively, of a derived class. + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: - Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) -- If your app handles string inputs, you should use the string version of . +- If your app handles string inputs, you should use the string version of . -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. ## Examples The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. @@ -1979,19 +1979,19 @@ For more information about this API, see or the provided by the method or the method, respectively, of a derived class. + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: - Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) -- If your app handles string inputs, you should use the string version of . +- If your app handles string inputs, you should use the string version of . -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. ]]> @@ -2059,21 +2059,21 @@ For more information about this API, see or the provided by the method or the method, respectively, of a derived class. + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: - Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) -- If your app handles string inputs, you should use the string version of . +- If your app handles string inputs, you should use the string version of . -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. ## Examples The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. @@ -2150,21 +2150,21 @@ For more information about this API, see or the provided by the method or the method, respectively, of a derived class. + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: - Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) -- If your app handles string inputs, you should use the string version of . +- If your app handles string inputs, you should use the string version of . -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. ## Examples The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. @@ -2245,23 +2245,23 @@ For more information about this API, see requires to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size that requires to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the object provided by the or the method, respectively, of a derived class. + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the object provided by the or the method, respectively, of a derived class. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: - Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) -- If your app handles string inputs, you should use the string version of . +- If your app handles string inputs, you should use the string version of . -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. ]]> @@ -2345,23 +2345,23 @@ For more information about this API, see to store the resulting bytes, you should call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, you should call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: - Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) -- If your app handles string inputs, you should use the string version of . +- If your app handles string inputs, you should use the string version of . -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. ## Examples The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. @@ -2459,23 +2459,23 @@ For more information about this API, see to store the resulting bytes, you should call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, you should call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: - Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) -- If your app handles string inputs, you should use the string version of . +- If your app handles string inputs, you should use the string version of . -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. ## Examples The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. @@ -2575,21 +2575,21 @@ For more information about this API, see to store the resulting characters, you should use the method. To calculate the maximum array size, you should use the method. The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, you should use the method. To calculate the maximum array size, you should use the method. The method generally allows allocation of less memory, while the method generally executes faster. - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: - Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. -- If your app handles string outputs, you should use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. +- If your app handles string outputs, you should use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. ## Examples The following example encodes a string into an array of bytes, and then decodes the bytes into an array of characters. @@ -2655,19 +2655,19 @@ For more information about this API, see requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size that requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: - Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. -- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. +- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. ]]> @@ -2738,21 +2738,21 @@ For more information about this API, see requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size that requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: - Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. -- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. +- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. ]]> @@ -2826,21 +2826,21 @@ For more information about this API, see to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: - Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. -- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. +- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. ## Examples The following example converts a string from one encoding to another. @@ -2935,26 +2935,26 @@ For more information about this API, see gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. + gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. > [!NOTE] - > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . + > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) -- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. +- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. ## Examples The following example encodes a string into an array of bytes, and then decodes the bytes into an array of characters. @@ -3023,23 +3023,23 @@ For more information about this API, see gets characters from an input byte span. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. + gets characters from an input byte span. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) -- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. +- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. ]]> @@ -3101,26 +3101,26 @@ For more information about this API, see gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. + gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. > [!NOTE] - > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . + > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) -- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. +- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. ## Examples The following example encodes a string into an array of bytes, and then decodes a range of the bytes into an array of characters. @@ -3218,28 +3218,28 @@ For more information about this API, see requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size that requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. + gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the object provided by the or the method, respectively, of a derived class. + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the object provided by the or the method, respectively, of a derived class. > [!NOTE] - > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . + > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) -- If your app handles string outputs, the method is recommended. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. +- If your app handles string outputs, the method is recommended. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. ]]> @@ -3324,28 +3324,28 @@ For more information about this API, see to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. + gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. > [!NOTE] - > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . + > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - Several versions of and are supported. The following are some programming considerations for use of these methods: + Several versions of and are supported. The following are some programming considerations for use of these methods: -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) -- If your app handles string outputs, the method is recommended. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. +- If your app handles string outputs, the method is recommended. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. ## Examples The following example converts a string from one encoding to another. @@ -3438,7 +3438,7 @@ For more information about this API, see method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it correctly decodes byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it correctly decodes byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. ]]> @@ -3502,7 +3502,7 @@ For more information about this API, see method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method of this class. However, a maintains state information between calls so it correctly encodes character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method of this class. However, a maintains state information between calls so it correctly encodes character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. ]]> @@ -3586,11 +3586,11 @@ For more information about this API, see overload. + The fallback handler depends on the encoding type of `codepage`. If `codepage` is a code page or double-byte character set (DBCS) encoding, a best-fit fallback handler is used. Otherwise, a replacement fallback handler is used. These fallback handlers may not be appropriate for your app. To specify the fallback handler used by the encoding specified by `codepage`, you can call the overload. - In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. + In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. - In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. + In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. You can also supply a value of 0 for the `codepage` argument. The behavior varies between .NET Framework and .NET Core and later versions: @@ -3613,7 +3613,7 @@ You can also supply a value of 0 for the `codepage` argument. The behavior varie > [!NOTE] > The ANSI code pages can be different on different computers and can change on a single computer, leading to data corruption. For this reason, if the active code page is an ANSI code page, encoding and decoding data using the default code page returned by `Encoding.GetEncoding(0)` is not recommended. For the most consistent results, you should use a Unicode encoding, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. - returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. + returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. ## Examples The following example gets two instances of the same encoding (one by code page and another by name), and checks their equality. @@ -3694,18 +3694,18 @@ You can also supply a value of 0 for the `codepage` argument. The behavior varie overload. + The fallback handler depends on the encoding type of `name`. If `name` is a code page or double-byte character set (DBCS) encoding, a best-fit fallback handler is used. Otherwise, a replacement fallback handler is used. These fallback handlers may not be appropriate for your app. To specify the fallback handler used by the encoding specified by `name`, you can call the overload. -In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. +In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. - In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. + In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. In .NET 5 and later versions, the code page name `utf-7` is not supported. > [!NOTE] > The ANSI code pages can be different on different computers, or they can be changed for a single computer, leading to data corruption. For the most consistent results, use Unicode, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. - returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. + returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. ## Examples The following example gets two instances of the same encoding (one by code page and another by name), and checks their equality. @@ -3796,9 +3796,9 @@ In .NET 5 and later versions, the code page name `utf-7` is not supported. > - Some unsupported code pages cause the exception to be thrown, whereas others cause . Therefore, your code must catch all exceptions indicated in the Exceptions section. > - In .NET 5 and later versions, the code page identifier `65000`, which represents UTF-7, is not supported. -In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. +In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. - In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. + In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. You can also supply a value of 0 for the `codepage` argument. The behavior varies between .NET Framework and .NET Core and later versions: @@ -3819,10 +3819,10 @@ You can also supply a value of 0 for the `codepage` argument. The behavior varie To get the encoding associated with the active code page, you can either supply a value of 0 for the `codepage` argument or, if your code is running on .NET Framework, retrieve the value of the property. To determine the current active code page, call the Windows [GetACP](/windows/win32/api/winnls/nf-winnls-getacp) function from .NET Framework. - returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. + returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. ## Examples - The following example demonstrates the method. + The following example demonstrates the method. :::code language="csharp" source="~/snippets/csharp/System.Text/EncoderReplacementFallback/Overview/fallEncRpl.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/EncoderReplacementFallback/Overview/fallEncRpl.vb" id="Snippet1"::: @@ -3903,19 +3903,19 @@ You can also supply a value of 0 for the `codepage` argument. The behavior varie ## Remarks -In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. +In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. - In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. + In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. In .NET 5 and later versions, the code page name `utf-7` is not supported. > [!NOTE] > The ANSI code pages can be different on different computers and can change on a single computer, leading to data corruption. For the most consistent results, you should use a Unicode encoding, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. - returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. + returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. ## Examples - The following example demonstrates the method. + The following example demonstrates the method. :::code language="csharp" source="~/snippets/csharp/System.Text/EncoderReplacementFallback/Overview/fallEncRpl.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/EncoderReplacementFallback/Overview/fallEncRpl.vb" id="Snippet1"::: @@ -3983,7 +3983,7 @@ In .NET 5 and later versions, the code page name `utf-7` is not supported. This method returns a list of supported encodings, uniquely distinguished by code page. For a table that lists the supported encodings, see . > [!NOTE] -> In .NET 5 and later versions, the list of supported encodings that returns includes any additional encodings made available by any implementations that were registered by calling . +> In .NET 5 and later versions, the list of supported encodings that returns includes any additional encodings made available by any implementations that were registered by calling . > > In .NET Framework and .NET Core, the returned list of supported encodings *does not* include these additional encodings. > @@ -3993,9 +3993,9 @@ In .NET 5 and later versions, the code page name `utf-7` is not supported. If you request the encoding name "iso-2022-jp", .NET Framework returns encoding 50220. However, the encoding that is appropriate for your app depends on the preferred treatment of the half-width Katakana characters. - To get a specific encoding, use the method. + To get a specific encoding, use the method. - is sometimes used to present the user with a list of encodings in a File **Save as** dialog box. However, many non-Unicode encodings are either incomplete and translate many characters to "?", or have subtly different behavior on different platforms. Consider using UTF-8 or UTF-16 as the default. + is sometimes used to present the user with a list of encodings in a File **Save as** dialog box. However, many non-Unicode encodings are either incomplete and translate many characters to "?", or have subtly different behavior on different platforms. Consider using UTF-8 or UTF-16 as the default. ## Examples The following example checks the values of the Boolean properties of each encoding. @@ -4112,15 +4112,15 @@ In .NET 5 and later versions, the code page name `utf-7` is not supported. ## Remarks The `charCount` parameter actually specifies the number of objects that represent the Unicode characters to encode, because .NET internally uses UTF-16 to represent Unicode characters. Consequently, most Unicode characters can be represented by one object, but a Unicode character represented by a surrogate pair, for example, requires two objects. - To calculate the exact array size required by to store the resulting bytes, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, retrieves large values, particularly in cases where the worst case for the encoding involves switching modes for every character. For example, this can happen for ISO-2022-JP. For more information, see the blog post "[What's with Encoding.GetMaxByteCount() and Encoding.GetMaxCharCount()?](https://blogs.msdn.microsoft.com/shawnste/2005/03/02/whats-with-encoding-getmaxbytecount-and-encoding-getmaxcharcount/). + retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, retrieves large values, particularly in cases where the worst case for the encoding involves switching modes for every character. For example, this can happen for ISO-2022-JP. For more information, see the blog post "[What's with Encoding.GetMaxByteCount() and Encoding.GetMaxCharCount()?](https://blogs.msdn.microsoft.com/shawnste/2005/03/02/whats-with-encoding-getmaxbytecount-and-encoding-getmaxcharcount/). - In most cases, this method retrieves reasonable values for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case when a more reasonable buffer is too small. You might also want to consider a different approach using or . + In most cases, this method retrieves reasonable values for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case when a more reasonable buffer is too small. You might also want to consider a different approach using or . - When using , you should allocate the output buffer based on the maximum size of the input buffer. If the output buffer is constrained in size, you might use the method. + When using , you should allocate the output buffer based on the maximum size of the input buffer. If the output buffer is constrained in size, you might use the method. - Note that considers potential leftover surrogates from a previous decoder operation. Because of the decoder, passing a value of 1 to the method retrieves 2 for a single-byte encoding, such as ASCII. You should use the property if this information is necessary. + Note that considers potential leftover surrogates from a previous decoder operation. Because of the decoder, passing a value of 1 to the method retrieves 2 for a single-byte encoding, such as ASCII. You should use the property if this information is necessary. > [!NOTE] > `GetMaxByteCount(N)` is not necessarily the same value as `N* GetMaxByteCount(1)`. @@ -4200,17 +4200,17 @@ In .NET 5 and later versions, the code page name `utf-7` is not supported. to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, retrieves large values. + retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, retrieves large values. - In most cases, this method retrieves reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is too small. You might also want to consider a different approach using or . + In most cases, this method retrieves reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is too small. You might also want to consider a different approach using or . - has no relation to . If you needs a similar function to use with , you should use . + has no relation to . If you needs a similar function to use with , you should use . - When using , you should allocate the output buffer based on the maximum size of the input buffer. If the output buffer is constrained in size, you might use the method. + When using , you should allocate the output buffer based on the maximum size of the input buffer. If the output buffer is constrained in size, you might use the method. - Note that considers the worst case for leftover bytes from a previous encoder operation. For most code pages, passing a value of 0 to this method retrieves values greater than or equal to 1. + Note that considers the worst case for leftover bytes from a previous encoder operation. For most code pages, passing a value of 0 to this method retrieves values greater than or equal to 1. > [!NOTE] > `GetMaxCharCount(N)` is not necessarily the same value as `N* GetMaxCharCount(1)`. @@ -4387,14 +4387,14 @@ In .NET 5 and later versions, the code page name `utf-7` is not supported. object returned by the method of a derived class. + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the object returned by the method of a derived class. - See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. + See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. - Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. + Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. ## Examples - The following example reads a UTF-8 encoded string from a binary file represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. + The following example reads a UTF-8 encoded string from a binary file represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetString/getstring1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoding/GetString/getstring1.vb" id="Snippet2"::: @@ -4476,13 +4476,13 @@ The goal is to save this file, then open and decode it as a binary stream. method is designed to optimize performance. Instead of creating a managed byte array and then decoding it, you can instead call this method without having to create any intermediate objects. + The method is designed to optimize performance. Instead of creating a managed byte array and then decoding it, you can instead call this method without having to create any intermediate objects. - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the object returned by the method of a derived class. + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the object returned by the method of a derived class. - See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. + See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. - Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. + Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. ]]> @@ -4552,13 +4552,13 @@ The goal is to save this file, then open and decode it as a binary stream. method is designed to optimize performance when you have a native pointer to a byte array. Instead of creating a managed byte array and then decoding it, you can instead call this method without having to create any intermediate objects. + The method is designed to optimize performance when you have a native pointer to a byte array. Instead of creating a managed byte array and then decoding it, you can instead call this method without having to create any intermediate objects. - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the object returned by the method of a derived class. + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the object returned by the method of a derived class. - See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. + See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. - Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. + Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. ]]> @@ -4633,12 +4633,12 @@ The goal is to save this file, then open and decode it as a binary stream. or the provided by the method or the method, respectively, of a derived class. + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. + See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. ## Examples - The following example reads a UTF-8 encoded string from a binary file that is represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. + The following example reads a UTF-8 encoded string from a binary file that is represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetString/getstring2.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoding/GetString/getstring2.vb" id="Snippet3"::: @@ -4726,14 +4726,14 @@ The goal is to save this file, then open and decode it as a binary stream. method with the property. Often the method retrieves a different encoding from the test encoding furnished in the call. Generally only email applications need to retrieve such an encoding. + If you need an encoding for a header name, you should call the method with the property. Often the method retrieves a different encoding from the test encoding furnished in the call. Generally only email applications need to retrieve such an encoding. In some cases, the value of the property corresponds to the international standard that defines that encoding. This doesn't mean that the implementation complies in full with that standard. - Note that returns the name to use to describe an encoding. The property defines a different encoding that might work better for an email application, for example. However, use of the property to define the encoding is not recommended. + Note that returns the name to use to describe an encoding. The property defines a different encoding that might work better for an email application, for example. However, use of the property to define the encoding is not recommended. ## Examples - The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. + The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoding/BodyName/names.vb" id="Snippet1"::: @@ -5214,7 +5214,7 @@ The goal is to save this file, then open and decode it as a binary stream. For a single-byte encoding, for example, , this property retrieves `true`. > [!CAUTION] -> You should be careful in what your application does with the value for . An assumption of how an Encoding will proceed may still be wrong. For example, Windows-1252 has a value of `true` for , but Encoding.GetMaxByteCount(1) returns 2. This is because the method considers potential leftover surrogates from a previous decoder operation. +> You should be careful in what your application does with the value for . An assumption of how an Encoding will proceed may still be wrong. For example, Windows-1252 has a value of `true` for , but Encoding.GetMaxByteCount(1) returns 2. This is because the method considers potential leftover surrogates from a previous decoder operation. ## Examples The following example checks the values of the Boolean properties of each encoding. @@ -5391,23 +5391,23 @@ The goal is to save this file, then open and decode it as a binary stream. method allows you to register a class derived from that makes character encodings available on a platform that does not otherwise support them. Once the encoding provider is registered, the encodings that it supports can be retrieved by calling any overload. If there are multiple encoding providers, the method attempts to retrieve a specified encoding from each provider starting with the one most recently registered. + The method allows you to register a class derived from that makes character encodings available on a platform that does not otherwise support them. Once the encoding provider is registered, the encodings that it supports can be retrieved by calling any overload. If there are multiple encoding providers, the method attempts to retrieve a specified encoding from each provider starting with the one most recently registered. -Registering an encoding provider by using the method also affects the behavior of when passed an argument of `0`. This is particularly important in .NET Core and later versions where the default behavior for with `codepage` 0 is to return UTF-8: +Registering an encoding provider by using the method also affects the behavior of when passed an argument of `0`. This is particularly important in .NET Core and later versions where the default behavior for with `codepage` 0 is to return UTF-8: - **If the registered provider is **: - On **Windows**, with `codepage` 0 returns the encoding that matches the system's active code page (same as .NET Framework behavior). - On **non-Windows platforms**, it still returns UTF-8. -- **If a custom encoding provider is registered**: The provider can choose which encoding to return when is passed an argument of `0`. The provider can also choose to not handle this case by returning `null` from its method, in which case the default UTF-8 behavior is used. +- **If a custom encoding provider is registered**: The provider can choose which encoding to return when is passed an argument of `0`. The provider can also choose to not handle this case by returning `null` from its method, in which case the default UTF-8 behavior is used. If multiple providers are registered, attempts to retrieve the encoding from the most recently registered provider first. Starting with .NET Framework 4.6, .NET Framework includes one encoding provider, , that makes the encodings available that are present in the full .NET Framework but are not available in the Universal Windows Platform. By default, the Universal Windows Platform only supports the Unicode encodings, ASCII, and code page 28591. - If the same encoding provider is used in multiple calls to the method, only the first method call registers the provider. Subsequent calls are ignored. + If the same encoding provider is used in multiple calls to the method, only the first method call registers the provider. Subsequent calls are ignored. - If the method is called to register multiple providers that handle the same encoding, the last registered provider is the used for all encoding and decoding operations. Any previously registered providers are ignored. + If the method is called to register multiple providers that handle the same encoding, the last registered provider is the used for all encoding and decoding operations. Any previously registered providers are ignored. ]]> @@ -5557,7 +5557,7 @@ Starting with .NET Framework 4.6, .NET Framework includes one encoding provider, ## Remarks For information about the encodings supported by .NET and a discussion of which Unicode encoding to use, see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). - The object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a little endian object whose fallback is either an or a , as the following example illustrates. + The object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a little endian object whose fallback is either an or a , as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Unicode/unicode1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoding/Unicode/unicode1.vb" id="Snippet2"::: @@ -5622,7 +5622,7 @@ Starting with .NET Framework 4.6, .NET Framework includes one encoding provider, object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with the Unicode REPLACEMENT CHARACTER (U+FFFE). Instead, you can call the constructor to instantiate a object whose fallback is either an or a , as the following example illustrates. + The object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with the Unicode REPLACEMENT CHARACTER (U+FFFE). Instead, you can call the constructor to instantiate a object whose fallback is either an or a , as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/UTF32/encoding.utf32.1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoding/UTF32/encoding.utf32.1.vb" id="Snippet1"::: @@ -5772,9 +5772,9 @@ Starting with .NET Framework 4.6, .NET Framework includes one encoding provider, The object that is returned by this property might not have the appropriate behavior for your app. -- It returns a object that provides a Unicode byte order mark (BOM). To instantiate a UTF8 encoding that doesn't provide a BOM, call any overload of the constructor. +- It returns a object that provides a Unicode byte order mark (BOM). To instantiate a UTF8 encoding that doesn't provide a BOM, call any overload of the constructor. -- It returns a object that uses replacement fallback to replace each string that it can't encode and each byte that it can't decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a object whose fallback is either an or a , as the following example illustrates. +- It returns a object that uses replacement fallback to replace each string that it can't encode and each byte that it can't decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a object whose fallback is either an or a , as the following example illustrates. :::code 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"::: @@ -5866,19 +5866,19 @@ Starting with .NET Framework 4.6, .NET Framework includes one encoding provider, ## Remarks The property is the same as the property. - Note that returns an IANA-registered name for the encoding. When its value is the name of a standard, the implementation of the encoding might not conform in full to that standard. The property defines a different encoding that might work better for email headers. However, most apps should use instead. + Note that returns an IANA-registered name for the encoding. When its value is the name of a standard, the implementation of the encoding might not conform in full to that standard. The property defines a different encoding that might work better for email headers. However, most apps should use instead. For more information on the IANA, go to [www.iana.org](https://www.iana.org/). - The is the same as the returned by . Some of the web names are duplicates; see the remarks for for more information. + The is the same as the returned by . Some of the web names are duplicates; see the remarks for for more information. ## Examples - The following example includes the in an HTML header. + The following example includes the in an HTML header. :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/WebName/webname.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoding/WebName/webname.vb" id="Snippet1"::: - The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. + The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoding/BodyName/names.vb" id="Snippet1"::: @@ -5937,7 +5937,7 @@ Starting with .NET Framework 4.6, .NET Framework includes one encoding provider, instead of to identify the code page. + This property is provided for compatibility with the Windows MultiLanguage (MLang) APIs, for example, in determining font families. For globalization, using one of the Unicode encodings is recommended instead. It is also recommended to use instead of to identify the code page. ## Examples The following example determines the Windows code page that most closely corresponds to each encoding. diff --git a/xml/System.Text/EncodingInfo.xml b/xml/System.Text/EncodingInfo.xml index 08cb353f12b..7458bb78b86 100644 --- a/xml/System.Text/EncodingInfo.xml +++ b/xml/System.Text/EncodingInfo.xml @@ -59,14 +59,14 @@ class. The method returns an array of this type. + This class is primarily used by the class. The method returns an array of this type. - This class is intended to provide minimal information about an encoding. To obtain additional information, the application should use the method to get an instance of the class, which contains more comprehensive information about the encoding it represents. + This class is intended to provide minimal information about an encoding. To obtain additional information, the application should use the method to get an instance of the class, which contains more comprehensive information about the encoding it represents. ## Examples - The following example uses the method to retrieve an object for each encoding supported by the .NET Framework. It then displays the value of each encoding's , , and property and compares them with the corresponding names. + The following example uses the method to retrieve an object for each encoding supported by the .NET Framework. It then displays the value of each encoding's , , and property and compares them with the corresponding names. :::code language="csharp" source="~/snippets/csharp/System.Text/EncodingInfo/Overview/encodinginfo.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/EncodingInfo/Overview/encodinginfo.vb" id="Snippet1"::: @@ -154,7 +154,7 @@ . + This member is equivalent to . @@ -211,7 +211,7 @@ property. Your applications should use for a name to pass to . + This property defines a display name that is the same as the name represented by the property. Your applications should use for a name to pass to . @@ -281,7 +281,7 @@ objects are equal if their properties are equal. + Two objects are equal if their properties are equal. ]]> @@ -391,7 +391,7 @@ method is not suitable for distinguishing one object from another. If your application needs a unique hash code, it should override the method. + The value returned by the method is not suitable for distinguishing one object from another. If your application needs a unique hash code, it should override the method. ]]> @@ -439,9 +439,9 @@ . This name is the same as the name represented by the property. When its value is the name of a standard, the actual implementation of the encoding may not conform in full to that standard. Your applications should use for a human-readable name. + This property defines the name that is appropriate for passing to . This name is the same as the name represented by the property. When its value is the name of a standard, the actual implementation of the encoding may not conform in full to that standard. Your applications should use for a human-readable name. - The method gets a complete list of supported encodings, uniquely distinguished by code page. If your application retrieves encodings using the property, note that some duplicate encodings are retrieved. For more about handling these duplicates, see the description of . + The method gets a complete list of supported encodings, uniquely distinguished by code page. If your application retrieves encodings using the property, note that some duplicate encodings are retrieved. For more about handling these duplicates, see the description of . For a list of supported names, see [Character Sets](https://www.iana.org/assignments/character-sets/character-sets.xhtml) on the [IANA website](https://www.iana.org). diff --git a/xml/System.Text/EncodingProvider.xml b/xml/System.Text/EncodingProvider.xml index 3d66452b1d1..ee1b1ea476e 100644 --- a/xml/System.Text/EncodingProvider.xml +++ b/xml/System.Text/EncodingProvider.xml @@ -73,7 +73,7 @@ ## Remarks An encoding provider supplies encodings that are not otherwise available on a particular target platform. - The .NET Framework supports a large number of character encodings and code pages. You can get a complete list of encodings available in the .NET Framework by calling the method. .NET Core, on the other hand, by default supports only the following encodings: + The .NET Framework supports a large number of character encodings and code pages. You can get a complete list of encodings available in the .NET Framework by calling the method. .NET Core, on the other hand, by default supports only the following encodings: - ASCII (code page 20127), which is returned by the property. @@ -85,7 +85,7 @@ - UTF-16 and UTF-16LE (code page 1200), which is returned by the property. -- UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. +- UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. - UTF-32 and UTF-32LE (code page 12000), which is returned by the property. @@ -93,15 +93,15 @@ Starting with the .NET Framework 4.6, is the base class that makes otherwise unavailable encodings available to the .NET Framework. This involves the following steps: -1. Define a subclass of that overrides the two abstract overloads, and . These overloads return the otherwise unsupported encoding by code page identifier and by name. Note that you can also choose to return a default encoding if the method is called with an argument of 0. +1. Define a subclass of that overrides the two abstract overloads, and . These overloads return the otherwise unsupported encoding by code page identifier and by name. Note that you can also choose to return a default encoding if the method is called with an argument of 0. -2. Optionally, you can override the virtual and methods. In most cases, this is not necessary, since the base class provides a default implementation. +2. Optionally, you can override the virtual and methods. In most cases, this is not necessary, since the base class provides a default implementation. -3. Pass the instance to the method to make the encodings supplied by the object available to the common language runtime. +3. Pass the instance to the method to make the encodings supplied by the object available to the common language runtime. -4. Call an overload to retrieve the encoding. The method will call the corresponding to determine whether it can supply the requested encoding. +4. Call an overload to retrieve the encoding. The method will call the corresponding to determine whether it can supply the requested encoding. - The .NET Framework Class Library provides one static property, , that returns an object that makes the full set of encodings available on the desktop .NET Framework Class Library available to .NET Core applications. In addition, you can derive from the class to make your own encodings available. + The .NET Framework Class Library provides one static property, , that returns an object that makes the full set of encodings available on the desktop .NET Framework Class Library available to .NET Core applications. In addition, you can derive from the class to make your own encodings available. ]]> @@ -345,7 +345,7 @@ This method is called by the [Encoding.GetEncoding(String)](, or the `decoderExceptionFallback` argument is an instance of , the encoding method throws an exception if characters cannot be encoded, and the decoding method throws an exception if a byte sequence cannot be decoded. -- Replacement fallback. If the `encoderFallback` argument is an instance of , or the `decoderExceptionFallback` argument is an instance of , the encoding and decoding methods substitute a replacement string for characters that cannot be encoded and byte sequences cannot be decoded. If you instantiated the replacement fallback object by calling the parameterless constructor, the replacement character is a "?". If you call the or constructor, you can specify the replacement string. +- Replacement fallback. If the `encoderFallback` argument is an instance of , or the `decoderExceptionFallback` argument is an instance of , the encoding and decoding methods substitute a replacement string for characters that cannot be encoded and byte sequences cannot be decoded. If you instantiated the replacement fallback object by calling the parameterless constructor, the replacement character is a "?". If you call the or constructor, you can specify the replacement string. - Best-fit fallback. You can derive from the or class to implement a best-fit replacement mechanism. @@ -418,7 +418,7 @@ This method is called by the [Encoding.GetEncoding(String)](, or the `decoderExceptionFallback` argument is an instance of , the encoding method throws an exception if characters cannot be encoded, and the decoding method throws an exception if a byte sequence cannot be decoded. -- Replacement fallback. If the `encoderFallback` argument is an instance of , or the `decoderExceptionFallback` argument is an instance of , the encoding and decoding methods substitute a replacement string for characters that cannot be encoded and byte sequences cannot be decoded. If you instantiated the replacement fallback object by calling the parameterless constructor, the replacement character is a "?". If you call the or constructor, you can specify the replacement string. +- Replacement fallback. If the `encoderFallback` argument is an instance of , or the `decoderExceptionFallback` argument is an instance of , the encoding and decoding methods substitute a replacement string for characters that cannot be encoded and byte sequences cannot be decoded. If you instantiated the replacement fallback object by calling the parameterless constructor, the replacement character is a "?". If you call the or constructor, you can specify the replacement string. - Best-fit fallback. You can derive from the or class to implement a best-fit replacement mechanism. @@ -470,7 +470,7 @@ This method is called by the [Encoding.GetEncoding(String)](, uniquely distinguished by code page. > [!NOTE] -> Starting in .NET 5, the list of supported encodings returned by includes encodings made available by any implementations that were registered by calls to the method. +> Starting in .NET 5, the list of supported encodings returned by includes encodings made available by any implementations that were registered by calls to the method. ]]> diff --git a/xml/System.Text/Rune.xml b/xml/System.Text/Rune.xml index 70cc5bed3e1..e748b542c16 100644 --- a/xml/System.Text/Rune.xml +++ b/xml/System.Text/Rune.xml @@ -692,7 +692,7 @@ This method is very similar to . Refer to that documentation for more information. +This method has behavior equivalent to . Refer to that documentation for more information. ]]> @@ -782,7 +782,7 @@ Throws an exception if `input` is `null`, `index` is out of range, or `index` do ## Remarks -This method has behavior equivalent to . Refer to that documentation for more information. +This method has behavior equivalent to . Refer to that documentation for more information. ]]> @@ -888,7 +888,7 @@ This method is equivalent to querying . +For more information, see . ]]> @@ -932,7 +932,7 @@ For more information, see and comparing the result against . -For more information, see . +For more information, see . ]]> @@ -976,7 +976,7 @@ For more information, see and comparing the result against any of the values , , , , and . -For more information, see . +For more information, see . ]]> @@ -1020,7 +1020,7 @@ For more information, see and comparing the result against any of the values , , , , , and . -For more information, see . +For more information, see . ]]> @@ -1065,7 +1065,7 @@ For more information, see and comparing the result against . -For more information, see . +For more information, see . ]]> @@ -1109,7 +1109,7 @@ For more information, see and comparing the result against any of the values , , and . -For more information, see . +For more information, see . ]]> @@ -1153,7 +1153,7 @@ For more information, see and comparing the result against any of the values , , , , , , and . -For more information, see . +For more information, see . ]]> @@ -1197,7 +1197,7 @@ For more information, see and comparing the result against any of the values , , and . -For more information, see . +For more information, see . ]]> @@ -1241,7 +1241,7 @@ For more information, see and comparing the result against any of the values , , , and . -For more information, see . +For more information, see . ]]> @@ -1285,7 +1285,7 @@ For more information, see and comparing the result against . -For more information, see . +For more information, see . ]]> @@ -1403,7 +1403,7 @@ For more information, see and comparing the result against any of the values , , and . However, there are some s in the category which are also classified as white space characters, and this method accounts for those values. -For more information, see . +For more information, see . ]]> diff --git a/xml/System.Text/SpanRuneEnumerator.xml b/xml/System.Text/SpanRuneEnumerator.xml index ceb1d6e1d8b..6596ac49ce9 100644 --- a/xml/System.Text/SpanRuneEnumerator.xml +++ b/xml/System.Text/SpanRuneEnumerator.xml @@ -53,7 +53,7 @@ ## Remarks -This type is not intended to be referenced directly by application code. Instead, use the method along with language-specific enumeration constructs to enumerate values within spans. +This type is not intended to be referenced directly by application code. Instead, use the method along with language-specific enumeration constructs to enumerate values within spans. The `foreach` statement of the C# language (`For Each` in Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. diff --git a/xml/System.Text/StringBuilder+ChunkEnumerator.xml b/xml/System.Text/StringBuilder+ChunkEnumerator.xml index 9f870d419d5..948ee6e7b65 100644 --- a/xml/System.Text/StringBuilder+ChunkEnumerator.xml +++ b/xml/System.Text/StringBuilder+ChunkEnumerator.xml @@ -33,11 +33,11 @@ Supports simple iteration over the chunks of a instance. - method. It supports both the and patterns so that the chunks can be enumerated with `foreach` in C# or `For Each` in Visual Basic. +A `ChunkEnumerator` is returned by the method. It supports both the and patterns so that the chunks can be enumerated with `foreach` in C# or `For Each` in Visual Basic. `ChunkEnumerator` is a public structure so that language compilers can use it to build a `foreach` statement. However, developers typically don't use it explicitly (which is why it is a nested type). diff --git a/xml/System.Text/StringBuilder.xml b/xml/System.Text/StringBuilder.xml index 5ad196f75b7..e0337d1c523 100644 --- a/xml/System.Text/StringBuilder.xml +++ b/xml/System.Text/StringBuilder.xml @@ -158,7 +158,7 @@ The following example shows how to call many of the methods defined by the constructor with no parameters. + The following example demonstrates how to call the constructor with no parameters. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet1"::: @@ -228,7 +228,7 @@ The following example shows how to call many of the methods defined by the constructor with a specified capacity. + The following example demonstrates how to call the constructor with a specified capacity. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet3"::: @@ -294,7 +294,7 @@ The following example shows how to call many of the methods defined by the constructor with the specified string. + The following example demonstrates how to call the constructor with the specified string. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet4"::: @@ -368,7 +368,7 @@ The following example shows how to call many of the methods defined by the constructor with a specified capacity and maximum capacity. + The following example demonstrates how to call the constructor with a specified capacity and maximum capacity. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet5"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet5"::: @@ -448,7 +448,7 @@ The following example shows how to call many of the methods defined by the constructor with an initial string and a specified capacity. + The following example demonstrates how to call the constructor with an initial string and a specified capacity. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet7"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet7"::: @@ -528,7 +528,7 @@ The following example shows how to call many of the methods defined by the constructor with the specified string. + The following example demonstrates how to call the constructor with the specified string. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet6"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet6"::: @@ -609,13 +609,13 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/StringBuilder/Append/append2.vb" id="Snippet2"::: - The method calls the method to get the string representation of `value`. The capacity of this instance is adjusted as needed. + The method calls the method to get the string representation of `value`. The capacity of this instance is adjusted as needed. ]]> @@ -677,13 +677,13 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/StringBuilder/Append/append2.vb" id="Snippet3"::: - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -753,7 +753,7 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet4"::: @@ -837,7 +837,7 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet6"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet6"::: @@ -904,13 +904,13 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet8"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/StringBuilder/Append/append2.vb" id="Snippet8"::: - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -974,13 +974,13 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet9"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/StringBuilder/Append/append2.vb" id="Snippet9"::: - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -1044,13 +1044,13 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet10"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/StringBuilder/Append/append3.vb" id="Snippet10"::: - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -1120,13 +1120,13 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet11"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/StringBuilder/Append/append3.vb" id="Snippet11"::: - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -1190,13 +1190,13 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet12"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet12"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/StringBuilder/Append/append3.vb" id="Snippet12"::: - The method calls the to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + The method calls the to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -1274,13 +1274,13 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. It defines a `Dog` class, creates a `Dog` object, and makes three calls to the method to create a string that contains the dog's name and breed. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. It defines a `Dog` class, creates a `Dog` object, and makes three calls to the method to create a string that contains the dog's name and breed. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append4.cs" id="Snippet18"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append4.fs" id="Snippet18"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/StringBuilder/Append/append4.vb" id="Snippet18"::: - The method calls the method to get the string representation of `value`. If `value` is `null`, no changes are made to the object. + The method calls the method to get the string representation of `value`. If `value` is `null`, no changes are made to the object. The capacity of this instance is adjusted as needed. @@ -1441,13 +1441,13 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet13"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet13"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/StringBuilder/Append/append3.vb" id="Snippet13"::: - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -1511,13 +1511,13 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" id="Snippet14"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet14"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/StringBuilder/Append/append3.vb" id="Snippet14"::: - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -1595,7 +1595,7 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet2"::: @@ -1793,13 +1793,13 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet15"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet15"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/StringBuilder/Append/append3.vb" id="Snippet15"::: - The method calls the method to get the string representation of `value`. To control the formatting of `value`, call the method. + The method calls the method to get the string representation of `value`. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -1869,13 +1869,13 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet16"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet16"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/StringBuilder/Append/append3.vb" id="Snippet16"::: - The calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + The calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -1945,13 +1945,13 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet17"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet17"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/StringBuilder/Append/append3.vb" id="Snippet17"::: - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -2023,7 +2023,7 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" id="Snippet5"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet5"::: @@ -2106,7 +2106,7 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object. The capacity of this instance is adjusted as needed. @@ -2249,7 +2249,7 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet7"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet7"::: @@ -2352,7 +2352,7 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet19"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet19"::: @@ -2553,7 +2553,7 @@ The following example shows how to call many of the methods defined by the method. + The following example demonstrates the method. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: @@ -2682,7 +2682,7 @@ The following example shows how to call many of the methods defined by the method. + The following example demonstrates the method. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: @@ -2865,7 +2865,7 @@ The index of a format item is less than 0 (zero), or greater than or equal to th |Element|Description| |-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . In this case, since the method has a single argument in the argument list, the value of *index* must always be 0. If it is not, a is thrown.| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . In this case, since the method has a single argument in the argument list, the value of *index* must always be 0. If it is not, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| |:*formatString*|A standard or custom format string that is supported by the parameter.| @@ -2887,7 +2887,7 @@ The index of a format item is less than 0 (zero), or greater than or equal to th `arg0` represents the object to be formatted. Each format item in `format` is replaced with the string representation of `arg0`. If the format item includes `formatString` and `arg0` implements the interface, then `arg0.ToString(formatString, provider)` defines the formatting. Otherwise, `arg0.ToString()` defines the formatting. ## Examples - The following includes two calls to the method. Both use the formatting conventions of the English-United Kingdom (en-GB) culture. The first inserts the string representation of a value currency in a result string. The second inserts a value in two places in a result string, the first including only the short date string and the second the short time string. + The following includes two calls to the method. Both use the formatting conventions of the English-United Kingdom (en-GB) culture. The first inserts the string representation of a value currency in a result string. The second inserts a value in two places in a result string, the first including only the short date string and the second the short time string. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appendformat1.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appendformat1.fs" id="Snippet2"::: @@ -3033,7 +3033,7 @@ The index of a format item is less than 0 (zero), or greater than or equal to th - A object that provides culture-specific formatting information for date and time values in `args`. -- A custom implementation that provides formatting information for one or more of the objects in `args`. Typically, such an implementation also implements the interface. The second example in the next section illustrates an method call with a custom implementation. +- A custom implementation that provides formatting information for one or more of the objects in `args`. Typically, such an implementation also implements the interface. The second example in the next section illustrates an method call with a custom implementation. If the `provider` parameter is `null`, format provider information is obtained from the current culture. @@ -3042,13 +3042,13 @@ The index of a format item is less than 0 (zero), or greater than or equal to th ## Examples - The following example demonstrates the method. + The following example demonstrates the method. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/StringBuilder/AppendFormat/appfmt.vb" id="Snippet1"::: - The following example defines a custom implementation named `CustomerFormatter` that formats a 10-digit customer number with hyphens after the fourth and seventh digits. It is passed to the method to create a string that includes the formatted customer number and customer name. + The following example defines a custom implementation named `CustomerFormatter` that formats a 10-digit customer number with hyphens after the fourth and seventh digits. It is passed to the method to create a string that includes the formatted customer number and customer name. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/customernumberformatter1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/customernumberformatter1.fs" id="Snippet1"::: @@ -3382,7 +3382,7 @@ The index of a format item is less than 0 (zero), or greater than or equal to th ## Examples - The following example demonstrates the method. + The following example demonstrates the method. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: @@ -3514,7 +3514,7 @@ The index of a format item is less than 0 (zero), or greater than or equal to th ## Examples - The following example uses the method to display time and temperature data stored in a generic object. Note that the format string has three format items, although there are only to objects to format. This is because the first object in the list (a date and time value) is used by two format items: The first format item displays the time, and the second displays the date. + The following example uses the method to display time and temperature data stored in a generic object. Note that the format string has three format items, although there are only to objects to format. This is because the first object in the list (a date and time value) is used by two format items: The first format item displays the time, and the second displays the date. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appendformat2.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appendformat2.fs" id="Snippet3"::: @@ -3639,7 +3639,7 @@ The index of a format item is less than 0 (zero), or greater than or equal to th ## Examples - The following example demonstrates the method. + The following example demonstrates the method. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: @@ -3773,7 +3773,7 @@ The index of a format item is less than 0 (zero), or greater than or equal to th ## Examples - The following example uses the method to illustrate the result of a Boolean `And` operation with integer values. Note that the format string includes six format items, but the method has only three items in its argument list, because each item is formatted in two different ways. + The following example uses the method to illustrate the result of a Boolean `And` operation with integer values. Note that the format string includes six format items, but the method has only three items in its argument list, because each item is formatted in two different ways. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appendformat3.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appendformat3.fs" id="Snippet4"::: @@ -4655,7 +4655,7 @@ The index of a format item is less than 0 (zero), or greater than or equal to th ## Examples - The following example demonstrates the method. + The following example demonstrates the method. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendLine/al.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendLine/al.fs" id="Snippet1"::: @@ -4895,9 +4895,9 @@ The index of a format item is less than 0 (zero), or greater than or equal to th does not affect the string value of the current instance. can be decreased as long as it is not less than . + does not affect the string value of the current instance. can be decreased as long as it is not less than . - The dynamically allocates more space when required and increases accordingly. For performance reasons, a might allocate more memory than needed. The amount of memory allocated is implementation-specific. + The dynamically allocates more space when required and increases accordingly. For performance reasons, a might allocate more memory than needed. The amount of memory allocated is implementation-specific. @@ -4966,7 +4966,7 @@ The index of a format item is less than 0 (zero), or greater than or equal to th The Unicode character at position . . The first character in the string is at index 0. The length of a string is the number of characters it contains. The last accessible character of a instance is at index - 1. +The `index` parameter is the position of a character within the . The first character in the string is at index 0. The length of a string is the number of characters it contains. The last accessible character of a instance is at index - 1. is the default property of the class. In C#, it is an indexer. This means that individual characters can be retrieved from the property as shown in the following example, which counts the number of alphabetic, white-space, and punctuation characters in a string. @@ -5031,11 +5031,11 @@ The `index` parameter is the position of a character within the is a convenience method that is equivalent to setting the property of the current instance to 0 (zero). + is a convenience method that is equivalent to setting the property of the current instance to 0 (zero). ## Examples -The following example instantiates a object with a string, calls the method, and then appends a new string. +The following example instantiates a object with a string, calls the method, and then appends a new string. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Clear/clear1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Clear/clear1.fs" id="Snippet1"::: @@ -5089,9 +5089,9 @@ The following example instantiates a object wit method is intended to be used in the rare situation when you need to efficiently copy successive sections of a object to an span. + The method is intended to be used in the rare situation when you need to efficiently copy successive sections of a object to an span. - For example, your code could populate a object with a large number of characters then use the method to copy small, successive pieces of the object to an span where the pieces are processed. When all the data in the object is processed, the size of the object is set to zero and the cycle is repeated. + For example, your code could populate a object with a large number of characters then use the method to copy small, successive pieces of the object to an span where the pieces are processed. When all the data in the object is processed, the size of the object is set to zero and the cycle is repeated. ]]> @@ -5162,14 +5162,14 @@ The following example instantiates a object wit method is intended to be used in the rare situation when you need to efficiently copy successive sections of a object to an array. The array should be a fixed size, preallocated, reusable, and possibly globally accessible. + The method is intended to be used in the rare situation when you need to efficiently copy successive sections of a object to an array. The array should be a fixed size, preallocated, reusable, and possibly globally accessible. - For example, your code could populate a object with a large number of characters then use the method to copy small, successive pieces of the object to an array where the pieces are processed. When all the data in the object is processed, the size of the object is set to zero and the cycle is repeated. + For example, your code could populate a object with a large number of characters then use the method to copy small, successive pieces of the object to an array where the pieces are processed. When all the data in the object is processed, the size of the object is set to zero and the cycle is repeated. ## Examples - The following example demonstrates the method. + The following example demonstrates the method. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/CopyTo/ct2.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/CopyTo/ct2.fs" id="Snippet1"::: @@ -5249,7 +5249,7 @@ The following example instantiates a object wit ## Examples - The following example demonstrates the method. + The following example demonstrates the method. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: @@ -5410,7 +5410,7 @@ The `Equals` method performs an ordinal comparison to determine whether the char **.NET Core 3.0 and later versions:** The current instance and `sb` are equal if the strings assigned to both objects are the same. To determine equality, the `Equals` method uses ordinal comparison. The and property values are not used in the comparison. ## Examples - The following code uses the method to check whether two objects are equal. The method is called repeatedly after small changes are made to each object, and the results are displayed to the console. + The following code uses the method to check whether two objects are equal. The method is called repeatedly after small changes are made to each object, and the results are displayed to the console. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: @@ -5468,9 +5468,9 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) The purpose of this method is to efficiently extract the data of a *constant* . If the is modified while the chunk enumeration is incomplete, the result is undefined. is also not thread-safe, so operating on it with concurrent threads is illegal. -The chunks returned are not guaranteed to remain unchanged if the is modified, so do not cache them for later use. +The chunks returned are not guaranteed to remain unchanged if the is modified, so do not cache them for later use. -Creating a from a (as the method does in the previous example) is expensive, so create a local variable for the span if you need to use it in a nested `for` statement. For example: +Creating a from a (as the method does in the previous example) is expensive, so create a local variable for the span if you need to use it in a nested `for` statement. For example: ```csharp foreach (ReadOnlyMemory chunk in sb.GetChunks()) @@ -5533,7 +5533,7 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) method. + The following example demonstrates the method. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Insert/insert.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Insert/insert.fs" id="Snippet1"::: @@ -5596,7 +5596,7 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed. ]]> @@ -5662,7 +5662,7 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. ]]> @@ -5734,7 +5734,7 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. ]]> @@ -5875,7 +5875,7 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. ]]> @@ -5941,7 +5941,7 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. ]]> @@ -6007,7 +6007,7 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. ]]> @@ -6073,7 +6073,7 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. ]]> @@ -6139,7 +6139,7 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. ]]> @@ -6213,7 +6213,7 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. If `value` is `null`, the value of this instance is unchanged. @@ -6343,7 +6343,7 @@ The existing characters are shifted to make room for the character sequence in t is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed. ]]> @@ -6409,7 +6409,7 @@ The existing characters are shifted to make room for the character sequence in t is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. ]]> @@ -6596,7 +6596,7 @@ The existing characters are shifted to make room for the character sequence in t is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. ]]> @@ -6668,7 +6668,7 @@ The existing characters are shifted to make room for the character sequence in t is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. ]]> @@ -6741,7 +6741,7 @@ The existing characters are shifted to make room for the character sequence in t is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. ]]> @@ -6995,7 +6995,7 @@ The existing characters are shifted to make room for the character sequence in t If the specified length is less than the current length, the current object is truncated to the specified length. If the specified length is greater than the current length, the end of the string value of the current object is padded with the Unicode NULL character (U+0000). - If the specified length is greater than the current capacity, increases so that it is greater than or equal to the specified length. + If the specified length is greater than the current capacity, increases so that it is greater than or equal to the specified length. @@ -7058,7 +7058,7 @@ The existing characters are shifted to make room for the character sequence in t . However, this value is implementation-specific and might be different in other or later implementations. You can explicitly set the maximum capacity of a object by calling the constructor. + The maximum capacity for this implementation is . However, this value is implementation-specific and might be different in other or later implementations. You can explicitly set the maximum capacity of a object by calling the constructor. In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. @@ -7128,12 +7128,12 @@ In .NET Core and in the .NET Framework 4.0 and later versions, when you instanti The current method removes the specified range of characters from the current instance. The characters at (`startIndex` + `length`) are moved to `startIndex`, and the string value of the current instance is shortened by `length`. The capacity of the current instance is unaffected. > [!NOTE] -> The method modifies the value of the current instance and returns that instance. It does not create and return a new object. +> The method modifies the value of the current instance and returns that instance. It does not create and return a new object. ## Examples - The following example demonstrates the method. + The following example demonstrates the method. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Remove/remove.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Remove/remove.fs" id="Snippet1"::: @@ -7160,7 +7160,7 @@ In .NET Core and in the .NET Framework 4.0 and later versions, when you instanti method. + The following example demonstrates the method. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Replace/replace.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Replace/replace.fs" id="Snippet1"::: @@ -7687,7 +7687,7 @@ In .NET Core and in the .NET Framework 4.0 and later versions, when you instanti ## Remarks The `context` parameter is reserved for future use and does not participate in this operation. - For more information, see the method. + For more information, see the method. ]]> @@ -7762,12 +7762,12 @@ In .NET Core and in the .NET Framework 4.0 and later versions, when you instanti method to convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. + You must call the method to convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. ## Examples - The following example demonstrates calling the method. This example is part of a larger example provided for the class. + The following example demonstrates calling the method. This example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/StringBuilder.cs" id="Snippet5"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/StringBuilder.fs" id="Snippet5"::: @@ -7836,7 +7836,7 @@ In .NET Core and in the .NET Framework 4.0 and later versions, when you instanti method to convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. + You must call the method to convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. ]]> diff --git a/xml/System.Text/StringRuneEnumerator.xml b/xml/System.Text/StringRuneEnumerator.xml index db00c6fc57e..22406657724 100644 --- a/xml/System.Text/StringRuneEnumerator.xml +++ b/xml/System.Text/StringRuneEnumerator.xml @@ -184,7 +184,7 @@ The `foreach` statement of the C# language (`For Each` in Visual Basic) hides th ## Remarks This member is an explicit interface member implementation. -It can be used only when the instance is cast to an interface. +It can be used only when the instance is cast to an interface. ]]> diff --git a/xml/System.Text/UTF32Encoding.xml b/xml/System.Text/UTF32Encoding.xml index 3827c279826..55902cb9351 100644 --- a/xml/System.Text/UTF32Encoding.xml +++ b/xml/System.Text/UTF32Encoding.xml @@ -82,25 +82,25 @@ Optionally, the object provides a byte order mark (BOM), which is an array of bytes that can be prefixed to the sequence of bytes resulting from the encoding process. If the preamble contains a byte order mark (BOM), it helps the decoder determine the byte order and the transformation format or UTF of a byte array. - If the instance is configured to provide a BOM, you can retrieve it by calling the method; otherwise, the method returns an empty array. Note that, even if a object is configured for BOM support, you must include the BOM at the beginning of the encoded byte stream as appropriate; the encoding methods of the class do not do this automatically. + If the instance is configured to provide a BOM, you can retrieve it by calling the method; otherwise, the method returns an empty array. Note that, even if a object is configured for BOM support, you must include the BOM at the beginning of the encoded byte stream as appropriate; the encoding methods of the class do not do this automatically. > [!CAUTION] -> To enable error detection and to make the class instance more secure, you should instantiate a object by calling the constructor and setting its `throwOnInvalidBytes` argument to `true`. With error detection, a method that detects an invalid sequence of characters or bytes throws an exception. Without error detection, no exception is thrown, and the invalid sequence is generally ignored. +> To enable error detection and to make the class instance more secure, you should instantiate a object by calling the constructor and setting its `throwOnInvalidBytes` argument to `true`. With error detection, a method that detects an invalid sequence of characters or bytes throws an exception. Without error detection, no exception is thrown, and the invalid sequence is generally ignored. You can instantiate a object in a number of ways, depending on whether you want to it to provide a byte order mark (BOM), whether you want big-endian or little-endian encoding, and whether you want to enable error detection. The following table lists the constructors and the properties that return a object. |Member|Endianness|BOM|Error detection| |------------|----------------|---------|---------------------| -||Little-endian|Yes|No (Replacement fallback)| +||Little-endian|Yes|No (Replacement fallback)| ||Little-endian|Yes|No (Replacement fallback)| -||Configurable|Configurable|No (Replacement fallback)| -||Configurable|Configurable|Configurable| +||Configurable|Configurable|No (Replacement fallback)| +||Configurable|Configurable|Configurable| - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. - Likewise, the method determines how many characters result in decoding a sequence of bytes, and the and methods perform the actual decoding. + Likewise, the method determines how many characters result in decoding a sequence of bytes, and the and methods perform the actual decoding. - For an encoder or decoder that is able to save state information when encoding or decoding data that spans multiple blocks (such as string of 1 million characters that is encoded in 100,000-character segments), use the and properties, respectively. + For an encoder or decoder that is able to save state information when encoding or decoding data that spans multiple blocks (such as string of 1 million characters that is encoded in 100,000-character segments), use the and properties, respectively. @@ -185,7 +185,7 @@ This constructor creates an instance that uses the little endian byte order, provides a Unicode byte order mark, and does not throw an exception when an invalid encoding is detected. > [!CAUTION] -> For security reasons, you should enable error detection by calling the constructor and setting its `throwOnInvalidCharacters` argument to `true`. +> For security reasons, you should enable error detection by calling the constructor and setting its `throwOnInvalidCharacters` argument to `true`. @@ -249,7 +249,7 @@ This constructor creates an instance that does not throw an exception when an invalid encoding is detected. > [!CAUTION] -> For security reasons, you should enable error detection by calling the constructor and setting its `throwOnInvalidCharacters` argument to `true`. +> For security reasons, you should enable error detection by calling the constructor and setting its `throwOnInvalidCharacters` argument to `true`. ## Examples The following example retrieves and displays the byte order mark for different instances. @@ -315,7 +315,7 @@ If `throwOnInvalidCharacters` is `true`, a method that detects an invalid byte sequence throws . Otherwise, the method does not throw an exception, and the invalid sequence is ignored. > [!CAUTION] -> For security reasons, you should enable error detection by calling the constructor and setting its `throwOnInvalidCharacters` argument to `true`. +> For security reasons, you should enable error detection by calling the constructor and setting its `throwOnInvalidCharacters` argument to `true`. ## Examples The following example demonstrates the behavior of , both with error detection enabled and without. @@ -471,16 +471,16 @@ to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble is not reflected in the value returned by the method. + To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble is not reflected in the value returned by the method. ## Examples - The following example calls the and methods to calculate the maximum and actual number of bytes required to encode a string. It also displays the actual number of bytes required to store a byte stream with a byte order mark. + The following example calls the and methods to calculate the maximum and actual number of bytes required to encode a string. It also displays the actual number of bytes required to store a byte stream with a byte order mark. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/GetByteCount/getbytecount1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF32Encoding/GetByteCount/getbytecount1.vb" id="Snippet1"::: @@ -559,11 +559,11 @@ to store the resulting bytes, you call the method. To calculate the maximum array size, you call the . The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, you call the method. To calculate the maximum array size, you call the . The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw an . Without error detection, invalid sequences are ignored, and no exception is thrown. - To ensure that the encoded bytes are decoded properly when they are saved as a file or a stream, you can prefix a stream of encoded bytes with a preamble. Inserting a preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble Is not reflected in the value returned by the method. + To ensure that the encoded bytes are decoded properly when they are saved as a file or a stream, you can prefix a stream of encoded bytes with a preamble. Inserting a preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble Is not reflected in the value returned by the method. ]]> @@ -643,16 +643,16 @@ to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - To ensure that the encoded bytes are decoded properly when they are saved as a file or a stream, you can prefix a stream of encoded bytes with a preamble. Inserting a preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble Is not reflected in the value returned by the method. + To ensure that the encoded bytes are decoded properly when they are saved as a file or a stream, you can prefix a stream of encoded bytes with a preamble. Inserting a preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble Is not reflected in the value returned by the method. ## Examples - The following example populates an array with a Latin uppercase and lowercase characters and calls the method to determine the number of bytes needed to encode the Latin lowercase characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Latin lowercase characters. The following example populates an array with a combination of Greek and Cyrillic characters and calls the method to determine the number of bytes needed to encode the Cyrillic characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Cyrillic characters. + The following example populates an array with a Latin uppercase and lowercase characters and calls the method to determine the number of bytes needed to encode the Latin lowercase characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Latin lowercase characters. The following example populates an array with a combination of Greek and Cyrillic characters and calls the method to determine the number of bytes needed to encode the Cyrillic characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Cyrillic characters. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/GetByteCount/getbytecount2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF32Encoding/GetByteCount/getbytecount2.vb" id="Snippet2"::: @@ -754,14 +754,14 @@ to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively. > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting a preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. +> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting a preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. ]]> @@ -849,14 +849,14 @@ to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively. > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting a preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. +> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting a preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. ## Examples The following example determines the number of bytes required to encode three characters from a character array, then encodes the characters and displays the resulting bytes. @@ -958,14 +958,14 @@ to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively. > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting a preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. +> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting a preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. ## Examples The following example determines the number of bytes required to encode a string, then encodes the string and displays the resulting bytes. @@ -1074,7 +1074,7 @@ calculates the exact array size required by the method to store the resulting characters. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. + calculates the exact array size required by the method to store the resulting characters. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. @@ -1156,7 +1156,7 @@ method calculates the exact array size required by the method to store the resulting characters. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. + The method calculates the exact array size required by the method to store the resulting characters. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. @@ -1265,13 +1265,13 @@ to store the resulting characters, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively. ]]> @@ -1360,13 +1360,13 @@ to store the resulting characters, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively. @@ -1454,7 +1454,7 @@ method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. If error detection is enabled, that is, the `throwOnInvalidCharacters` parameter of the constructor was set to `true`, error detection is also enabled in the returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the decoder is undefined and processing must stop. @@ -1520,7 +1520,7 @@ method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method. However, a maintains state information between calls so it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high-surrogate, and the matching low-surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method. However, a maintains state information between calls so it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high-surrogate, and the matching low-surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. If error detection is enabled, that is, the `throwOnInvalidCharacters` parameter of the constructor was set to `true`, error detection is also enabled in the returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the encoder is undefined and processing must stop. @@ -1632,13 +1632,13 @@ to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. - is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. + is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. - In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach and use or . + In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach and use or . - has no relationship to . If you need a similar function to use with , use . + has no relationship to . If you need a similar function to use with , use . > [!NOTE] > `GetMaxByteCount(N)` is not necessarily the same value as `N* GetMaxByteCount(1)`. @@ -1714,13 +1714,13 @@ to store the resulting characters, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. - is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. + is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. - In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach and use or . + In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach and use or . - has no relationship to . If you need a similar function to use with , use . + has no relationship to . If you need a similar function to use with , use . > [!NOTE] > `GetMaxCharCount(N)` is not necessarily the same value as `N* GetMaxCharCount(1)`. @@ -1800,13 +1800,13 @@ - Little endian byte order: FF FE 00 00 - You can instantiate a object whose method returns a valid BOM in the following ways: + You can instantiate a object whose method returns a valid BOM in the following ways: - By retrieving the object returned by the property. - By calling the parameterless constructor to instantiate a object. -- By supplying `true` as the value of the `byteOrderMark` argument to the and constructors. +- By supplying `true` as the value of the `byteOrderMark` argument to the and constructors. We recommend that you use the BOM, since it provides nearly certain identification of an encoding for files that otherwise have lost reference to the object, for example, untagged or improperly tagged web data, or random text files stored when a business did not have international concerns or other data. Often, user problems might be avoided if data is consistently and properly tagged. @@ -1817,7 +1817,7 @@ For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://go.microsoft.com/fwlink/?LinkId=37123). > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly, you should prefix encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. +> To ensure that the encoded bytes are decoded properly, you should prefix encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. ## Examples The following code example retrieves and displays the byte order mark for different instances. @@ -1825,7 +1825,7 @@ :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/.ctor/getpreamble.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF32Encoding/.ctor/GetPreamble.vb" id="Snippet1"::: - The following example instantiates two objects, the first of which does not provide a BOM and the second of which does. It then calls the method to write the BOM to a file before writing a UTF-32-encoded string. As the output from the example shows, the file that saves the bytes from the second encoder has four more bytes that the first. + The following example instantiates two objects, the first of which does not provide a BOM and the second of which does. It then calls the method to write the BOM to a file before writing a UTF-32-encoded string. As the output from the example shows, the file that saves the bytes from the second encoder has four more bytes that the first. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/.ctor/getpreamble1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF32Encoding/.ctor/getpreamble1.vb" id="Snippet2"::: @@ -1895,9 +1895,9 @@ ## Remarks With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - If the range of bytes to be decoded includes the byte order mark (BOM), and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + If the range of bytes to be decoded includes the byte order mark (BOM), and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. @@ -1907,7 +1907,7 @@ :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/GetString/getstring.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF32Encoding/GetString/GetString.vb" id="Snippet1"::: - The following example initializes an array by calling the method to determine exactly how many bytes are required for an encoded string and then adding the size of the byte order mark (BOM). The example then calls the method to store the BOM to the array before calling the method to store the encoded bytes to the array. The example then calls the method to decode the string. + The following example initializes an array by calling the method to determine exactly how many bytes are required for an encoded string and then adding the size of the byte order mark (BOM). The example then calls the method to store the BOM to the array before calling the method to store the encoded bytes to the array. The example then calls the method to decode the string. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/GetString/GetString1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF32Encoding/GetString/GetString1.vb" id="Snippet2"::: @@ -1990,7 +1990,7 @@ - By calling the parameterless constructor to instantiate a object. -- By supplying `true` as the value of the `byteOrderMark` argument to the and constructors. +- By supplying `true` as the value of the `byteOrderMark` argument to the and constructors. We recommend that you use the BOM, since it provides nearly certain identification of an encoding for files that otherwise have lost a reference to the object, such as untagged or improperly tagged web data, or random text files stored when a business did not have international concerns or other data. Often, user problems might be avoided if data is consistently and properly tagged. @@ -2001,7 +2001,7 @@ For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://go.microsoft.com/fwlink/?LinkId=37123). > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly, you should prefix encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. +> To ensure that the encoded bytes are decoded properly, you should prefix encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. ]]> diff --git a/xml/System.Text/UTF7Encoding.xml b/xml/System.Text/UTF7Encoding.xml index 0195bd95eca..c7cf740334a 100644 --- a/xml/System.Text/UTF7Encoding.xml +++ b/xml/System.Text/UTF7Encoding.xml @@ -74,9 +74,9 @@ For more information about the UTFs and other encodings supported by , see [Character Encoding in the .NET Framework](/dotnet/standard/base-types/character-encoding). - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. - Likewise, the method determines how many characters result in decoding a sequence of bytes, and the and methods perform the actual decoding. + Likewise, the method determines how many characters result in decoding a sequence of bytes, and the and methods perform the actual decoding. corresponds to the Windows code page 65000. @@ -154,7 +154,7 @@ constructor is equivalent to calling the constructor that takes an `allowOptionals` parameter and specifying `false` for that parameter. + This constructor creates an instance that does not allow optional characters. Calling the constructor is equivalent to calling the constructor that takes an `allowOptionals` parameter and specifying `false` for that parameter. If an instance allows optional characters, Unicode code points are encoded with a corresponding optional character instead of a modified base 64 character. The optional characters are exclamation point ("!"), backward slash ("\\"), vertical line ("|"), double quote ("""), number sign ("#"), dollar sign ("$"), percent sign ("%"), ampersand ("&"), asterisk ("*"), semicolon (";"), left angle bracket ("\<"), right angle bracket (">"), left curly bracket ("{"), right curly bracket ("}"), left square bracket ("["), right square bracket ("]"), equal sign ("="), at sign ("@"), circumflex accent ("^"), underscore ("_"), and grave accent ("`"). @@ -303,7 +303,7 @@ objects are equal if they both either allow or disallow optional characters, and if their underlying and properties are equal. + Two objects are equal if they both either allow or disallow optional characters, and if their underlying and properties are equal. ]]> @@ -378,12 +378,12 @@ requires to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size that requires to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. ## Examples - The following code example demonstrates how to use the method to return the number of bytes required to encode a character array. + The following code example demonstrates how to use the method to return the number of bytes required to encode a character array. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/GetByteCount/getbytecount-char[]-int32-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/GetByteCount/getbytecount-char[]-int32-int32.vb" id="Snippet1"::: @@ -465,7 +465,7 @@ requires to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size that requires to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. ]]> @@ -545,12 +545,12 @@ to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. ## Examples - The following code example demonstrates how to use the method to return the number of bytes required to encode an array of Unicode characters. + The following code example demonstrates how to use the method to return the number of bytes required to encode an array of Unicode characters. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/GetByteCount/getbytecount-char[]-int32-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/GetByteCount/getbytecount-char[]-int32-int32.vb" id="Snippet1"::: @@ -655,9 +655,9 @@ to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. > [!NOTE] > does not provide error detection. Invalid characters are encoded as a modified base 64 character. For security reasons, your applications are recommended to use , , or and enable error detection. @@ -746,9 +746,9 @@ to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. > [!NOTE] > does not provide error detection. Invalid characters are encoded as a modified base 64 character. For security reasons, your applications are recommended to use , , or and enable error detection. @@ -756,7 +756,7 @@ ## Examples - The following code example demonstrates how to use the method to encode a range of characters from a and store the encoded bytes in a range of elements in a byte array. + The following code example demonstrates how to use the method to encode a range of characters from a and store the encoded bytes in a range of elements in a byte array. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/GetBytes/getbytes-char[]-int32-int32-byte[]-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/GetBytes/getbytes-char[]-int32-int32-byte[]-int32.vb" id="Snippet1"::: @@ -856,9 +856,9 @@ to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. > [!NOTE] > does not provide error detection. Invalid characters are encoded as a modified base 64 character. For security reasons, your applications are recommended to use , , or and enable error detection. @@ -866,7 +866,7 @@ ## Examples - The following code example demonstrates how to use the method to encode a range of elements from a Unicode character array, and store the encoded bytes in a range of elements in a byte array. + The following code example demonstrates how to use the method to encode a range of elements from a Unicode character array, and store the encoded bytes in a range of elements in a byte array. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/GetBytes/getbytes-char[]-int32-int32-byte[]-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/GetBytes/getbytes-char[]-int32-int32-byte[]-int32.vb" id="Snippet1"::: @@ -973,7 +973,7 @@ to store the resulting characters, use . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, use . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. ]]> @@ -1053,12 +1053,12 @@ to store the resulting characters, use . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, use . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. ## Examples - The following code example demonstrates how to use the method to return the number of characters produced by decoding a range of elements in a byte array. + The following code example demonstrates how to use the method to return the number of characters produced by decoding a range of elements in a byte array. :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetCharCount/getcharcount-byte[]-int32-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UnicodeEncoding/GetCharCount/getcharcount-byte[]-int32-int32.vb" id="Snippet1"::: @@ -1163,9 +1163,9 @@ to store the resulting characters, use . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, use . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. > [!NOTE] > does not provide error detection. When invalid bytes are encountered, generally emits the invalid bytes. If a byte is larger than hexadecimal 0x7F, the byte value is zero-extended into a Unicode character, the result is stored in the `chars` array, and any shift sequence is terminated. For example, if the byte to encode is hexadecimal 0x81, the resulting character is U+0081. For security reasons, your applications are recommended to use , , or and enable error detection. @@ -1255,9 +1255,9 @@ to store the resulting characters, use . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, use . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. > [!NOTE] > does not provide error detection. When invalid bytes are encountered, generally emits the invalid bytes. If a byte is larger than hexadecimal 0x7F, the byte value is zero-extended into a Unicode character, the result is stored in the `chars` array, and any shift sequence is terminated. For example, if the byte to encode is hexadecimal 0x81, the resulting character is U+0081. For security reasons, your applications are recommended to use , , or and enable error detection. @@ -1265,7 +1265,7 @@ ## Examples - The following code example demonstrates how to use the method to decode a range of elements in a byte array and store the result in a character array. + The following code example demonstrates how to use the method to decode a range of elements in a byte array and store the result in a character array. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/GetChars/getchars-byte[]-int32-int32-char[]-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/GetChars/getchars-byte[]-int32-int32-char[]-int32.vb" id="Snippet1"::: @@ -1346,12 +1346,12 @@ method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. ## Examples - The following code example demonstrates how to use the method to obtain a decoder to convert the UTF-7 encoded bytes into a sequence of characters. + The following code example demonstrates how to use the method to obtain a decoder to convert the UTF-7 encoded bytes into a sequence of characters. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/GetDecoder/getdecoder-.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/GetDecoder/getdecoder-.vb" id="Snippet1"::: @@ -1411,12 +1411,12 @@ method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. ## Examples - The following code example demonstrates how to use the method to obtain an encoder to convert a sequence of characters into a UTF-7 encoded sequence of bytes. + The following code example demonstrates how to use the method to obtain an encoder to convert a sequence of characters into a UTF-7 encoded sequence of bytes. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/GetEncoder/getencoder-.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/GetEncoder/getencoder-.vb" id="Snippet1"::: @@ -1480,7 +1480,7 @@ method is not suitable for distinguishing one object from another. If your application needs a unique hash code, it should override the method. + The value returned by the method is not suitable for distinguishing one object from another. If your application needs a unique hash code, it should override the method. ]]> @@ -1534,13 +1534,13 @@ to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. - is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. + is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. - In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . While UTF-7 is very efficient at encoding ASCII data, one byte per character, it is extremely inefficient for other data. As remarked above, deals with a worst case. If the data to be encoded is largely ASCII, and especially if the ASCII characters cluster together, UTF-7 is significantly more efficient than the number returned by this method suggests. + In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . While UTF-7 is very efficient at encoding ASCII data, one byte per character, it is extremely inefficient for other data. As remarked above, deals with a worst case. If the data to be encoded is largely ASCII, and especially if the ASCII characters cluster together, UTF-7 is significantly more efficient than the number returned by this method suggests. - has no relation to . If your application needs a similar function to use with , it should use . + has no relation to . If your application needs a similar function to use with , it should use . > [!NOTE] > `GetMaxByteCount(N)` is not necessarily the same value as `N* GetMaxByteCount(1)`. @@ -1548,7 +1548,7 @@ ## Examples - The following code example demonstrates how to use the method to return the maximum number of bytes required to encode a specified number of characters. + The following code example demonstrates how to use the method to return the maximum number of bytes required to encode a specified number of characters. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/GetMaxByteCount/getmaxbytecount-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/GetMaxByteCount/getmaxbytecount-int32.vb" id="Snippet1"::: @@ -1619,13 +1619,13 @@ to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster. - is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. + is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. - In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . + In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . - has no relation to . If your application needs a similar function to use with , it should use . + has no relation to . If your application needs a similar function to use with , it should use . > [!NOTE] > `GetMaxCharCount(N)` is not necessarily the same value as `N* GetMaxCharCount(1)`. @@ -1633,7 +1633,7 @@ ## Examples - The following code example demonstrates how to use the method to return the maximum number of characters produced by decoding a specified number of bytes. + The following code example demonstrates how to use the method to return the maximum number of characters produced by decoding a specified number of bytes. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/GetMaxCharCount/getmaxcharcount-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/GetMaxCharCount/getmaxcharcount-int32.vb" id="Snippet1"::: @@ -1718,7 +1718,7 @@ or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. > [!NOTE] > does not provide error detection. When invalid bytes are encountered, generally emits the invalid bytes. If a byte is larger than hexadecimal 0x7F, the byte value is zero-extended into a Unicode character, the result is stored in the `chars` array, and any shift sequence is terminated. For example, if the byte to encode is hexadecimal 0x81, the resulting character is U+0081. For security reasons, your applications are recommended to use , , or and enable error detection. diff --git a/xml/System.Text/UTF8Encoding.xml b/xml/System.Text/UTF8Encoding.xml index 89bb781e40c..f6c0b45820c 100644 --- a/xml/System.Text/UTF8Encoding.xml +++ b/xml/System.Text/UTF8Encoding.xml @@ -71,23 +71,23 @@ |Member|BOM|Error detection| |------------|---------|---------------------| -||Yes|No (Replacement fallback)| +||Yes|No (Replacement fallback)| ||No|No (Replacement fallback)| -||Configurable|No (Replacement fallback)| -||Configurable|Configurable| +||Configurable|No (Replacement fallback)| +||Configurable|Configurable| - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. - Likewise, the method determines how many characters result in decoding a sequence of bytes, and the and methods perform the actual decoding. + Likewise, the method determines how many characters result in decoding a sequence of bytes, and the and methods perform the actual decoding. - For an encoder or decoder that is able to save state information when encoding or decoding data that spans multiple blocks (such as string of 1 million characters that is encoded in 100,000-character segments), use the and properties, respectively. + For an encoder or decoder that is able to save state information when encoding or decoding data that spans multiple blocks (such as string of 1 million characters that is encoded in 100,000-character segments), use the and properties, respectively. Optionally, the object provides a byte order mark (BOM), which is an array of bytes that can be prefixed to the beginning of the byte stream that results from the encoding process. If a UTF-8 encoded byte stream is prefaced with a byte order mark (BOM), it helps the decoder determine the byte order and the transformation format or UTF. Note, however, that the Unicode Standard neither requires nor recommends a BOM in UTF-8 encoded streams. For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://go.microsoft.com/fwlink/?LinkId=37123). - If the encoder is configured to provide a BOM, you can retrieve it by calling the method; otherwise, the method returns an empty array. Note that, even if a object is configured for BOM support, you must include the BOM at the beginning of the encoded byte stream as appropriate; the encoding methods of the class do not do this automatically. + If the encoder is configured to provide a BOM, you can retrieve it by calling the method; otherwise, the method returns an empty array. Note that, even if a object is configured for BOM support, you must include the BOM at the beginning of the encoded byte stream as appropriate; the encoding methods of the class do not do this automatically. > [!CAUTION] -> To enable error detection and to make the class instance more secure, you should call the constructor and set the `throwOnInvalidBytes` parameter to `true`. With error detection enabled, a method that detects an invalid sequence of characters or bytes throws an exception. Without error detection, no exception is thrown, and the invalid sequence is generally ignored. +> To enable error detection and to make the class instance more secure, you should call the constructor and set the `throwOnInvalidBytes` parameter to `true`. With error detection enabled, a method that detects an invalid sequence of characters or bytes throws an exception. Without error detection, no exception is thrown, and the invalid sequence is generally ignored. > [!NOTE] > The state of a UTF-8 encoded object is not preserved if the object is serialized and deserialized using different .NET Framework versions. @@ -233,12 +233,12 @@ > [!CAUTION] > For security reasons, you should enable error detection by calling a constructor that includes a `throwOnInvalidBytes` parameter and setting its value to `true`. - The `encoderShouldEmitUTF8Identifier` parameter controls the operation of the method. If `true`, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-8 format. If `false`, it returns a zero-length byte array. However, setting `encoderShouldEmitUTF8Identifier` to `true` does not cause the method to prefix the BOM at the beginning of the byte array, nor does it cause the method to include the number of bytes in the BOM in the byte count. + The `encoderShouldEmitUTF8Identifier` parameter controls the operation of the method. If `true`, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-8 format. If `false`, it returns a zero-length byte array. However, setting `encoderShouldEmitUTF8Identifier` to `true` does not cause the method to prefix the BOM at the beginning of the byte array, nor does it cause the method to include the number of bytes in the BOM in the byte count. ## Examples - The following example creates a new instance and specifies that a Unicode byte order mark prefix should be emitted by the method. The method then returns the Unicode byte order mark prefix. + The following example creates a new instance and specifies that a Unicode byte order mark prefix should be emitted by the method. The method then returns the Unicode byte order mark prefix. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/.ctor/ctor-boolean.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF8Encoding/.ctor/ctor-boolean.vb" id="Snippet1"::: @@ -297,7 +297,7 @@ method. If `true`, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-8 format. If `false`, it returns a zero-length byte array. However, setting `encoderShouldEmitUTF8Identifier` to `true` does not cause the method to prefix the BOM at the beginning of the byte array, nor does it cause the method to include the number of bytes in the BOM in the byte count. + The `encoderShouldEmitUTF8Identifier` parameter controls the operation of the method. If `true`, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-8 format. If `false`, it returns a zero-length byte array. However, setting `encoderShouldEmitUTF8Identifier` to `true` does not cause the method to prefix the BOM at the beginning of the byte array, nor does it cause the method to include the number of bytes in the BOM in the byte count. If `throwOnInvalidBytes` is `true`, a method that detects an invalid byte sequence throws an exception. Otherwise, the method does not throw an exception, and the invalid sequence is ignored. @@ -307,7 +307,7 @@ ## Examples - The following example creates a new instance, specifying that the method should not emit a Unicode byte order mark prefix, and an exception should be thrown when an invalid encoding is detected. The behavior of this constructor is compared to the default constructor, which does not throw an exception when an invalid encoding is detected. The two instances encode a character array that contains two high surrogates (U+D801 and U+D802) in a row, which is an invalid character sequence; a high surrogate should always be followed by a low surrogate. + The following example creates a new instance, specifying that the method should not emit a Unicode byte order mark prefix, and an exception should be thrown when an invalid encoding is detected. The behavior of this constructor is compared to the default constructor, which does not throw an exception when an invalid encoding is detected. The two instances encode a character array that contains two high surrogates (U+D801 and U+D802) in a row, which is an invalid character sequence; a high surrogate should always be followed by a low surrogate. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/.ctor/ctor-boolean-boolean.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF8Encoding/.ctor/ctor-boolean-boolean.vb" id="Snippet1"::: @@ -386,7 +386,7 @@ ## Examples - The following example uses the method to test whether the current object is equal to a different object. Four objects are created and compared and the results of the comparisons are displayed. + The following example uses the method to test whether the current object is equal to a different object. Four objects are created and compared and the results of the comparisons are displayed. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/Equals/equals-object.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF8Encoding/Equals/equals-object.vb" id="Snippet1"::: @@ -448,11 +448,11 @@ to store the resulting bytes, you call the method. To calculate the maximum size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact size required by to store the resulting bytes, you call the method. To calculate the maximum size, you call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble is not reflected in the value returned by the method. + To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble is not reflected in the value returned by the method. ]]> @@ -519,16 +519,16 @@ to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble is not reflected in the value returned by the method. + To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble is not reflected in the value returned by the method. ## Examples - The following example calls the and methods to calculate the maximum and actual number of bytes required to encode a string. It also displays the actual number of bytes required to store a byte stream with a byte order mark. + The following example calls the and methods to calculate the maximum and actual number of bytes required to encode a string. It also displays the actual number of bytes required to store a byte stream with a byte order mark. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetByteCount/getbytecount1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF8Encoding/GetByteCount/getbytecount1.vb" id="Snippet1"::: @@ -611,11 +611,11 @@ method to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by the method to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble is not reflected in the value returned by the method. + To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble is not reflected in the value returned by the method. ]]> @@ -697,16 +697,16 @@ to store the resulting bytes, you call the uses method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, you call the uses method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble is not reflected in the value returned by the method. + To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble is not reflected in the value returned by the method. ## Examples - The following example populates an array with a Latin uppercase and lowercase characters and calls the method to determine the number of bytes needed to encode the Latin lowercase characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Latin lowercase characters. + The following example populates an array with a Latin uppercase and lowercase characters and calls the method to determine the number of bytes needed to encode the Latin lowercase characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Latin lowercase characters. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetByteCount/getbytecount2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF8Encoding/GetByteCount/getbytecount2.vb" id="Snippet2"::: @@ -819,13 +819,13 @@ to store the resulting bytes, you call the method. To calculate the maximum size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact size required by to store the resulting bytes, you call the method. To calculate the maximum size, you call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the returned by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the returned by the method or the method, respectively. - To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. + To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. ]]> @@ -897,13 +897,13 @@ to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the returned by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the returned by the method or the method, respectively. - To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. + To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. ]]> @@ -993,18 +993,18 @@ to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the provided by the method or the method, respectively. - To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. + To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. ## Examples - The following example uses the method to encode a range of characters from a string and stores the encoded bytes in a range of elements in a byte array. + The following example uses the method to encode a range of characters from a string and stores the encoded bytes in a range of elements in a byte array. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetBytes/getbytes-string-int32-int32-byte[]-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF8Encoding/GetBytes/getbytes-string-int32-int32-byte[]-int32.vb" id="Snippet1"::: @@ -1105,18 +1105,18 @@ to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the provided by the method or the method, respectively. - To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. + To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. ## Examples - The following example uses the method to encode a range of elements from a Unicode character array and store the encoded bytes in a range of elements in a byte array. + The following example uses the method to encode a range of elements from a Unicode character array and store the encoded bytes in a range of elements in a byte array. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetBytes/getbytes-char[]-int32-int32-byte[]-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF8Encoding/GetBytes/getbytes-char[]-int32-int32-byte[]-int32.vb" id="Snippet1"::: @@ -1204,7 +1204,7 @@ to store the resulting characters, call the method. To calculate the maximum size, call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact size required by to store the resulting characters, call the method. To calculate the maximum size, call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. @@ -1274,7 +1274,7 @@ to store the resulting characters, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. @@ -1358,14 +1358,14 @@ to store the resulting characters, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. ## Examples - The following example uses the method to return the number of characters produced by decoding a range of elements in a byte array. + The following example uses the method to return the number of characters produced by decoding a range of elements in a byte array. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetCharCount/getcharcount-byte[]-int32-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF8Encoding/GetCharCount/getcharcount-byte[]-int32-int32.vb" id="Snippet1"::: @@ -1447,13 +1447,13 @@ to store the resulting characters, call the method. To calculate the maximum size, call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact size required by to store the resulting characters, call the method. To calculate the maximum size, call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - If the set of bytes to be decoded includes the byte order mark (BOM) and the span of bytes was returned by a method of a non-BOM aware type, the character `U+FFFE` is included in the span of characters returned by this method. You can remove it by calling the method. + If the set of bytes to be decoded includes the byte order mark (BOM) and the span of bytes was returned by a method of a non-BOM aware type, the character `U+FFFE` is included in the span of characters returned by this method. You can remove it by calling the method. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the object provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the object provided by the method or the method, respectively. ]]> @@ -1525,13 +1525,13 @@ to store the resulting characters, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the object provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the object provided by the method or the method, respectively. ]]> @@ -1622,18 +1622,18 @@ to store the resulting characters, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the provided by the method or the method, respectively. ## Examples - The following example uses the method to decode a range of elements in a byte array and store the result in a character array. + The following example uses the method to decode a range of elements in a byte array and store the result in a character array. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetChars/getchars-byte[]-int32-int32-char[]-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF8Encoding/GetChars/getchars-byte[]-int32-int32-char[]-int32.vb" id="Snippet1"::: @@ -1718,14 +1718,14 @@ method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. If error detection is enabled, that is, the `throwOnInvalidCharacters` parameter of the constructor is set to `true`, error detection is also enabled in the returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the decoder is undefined and processing must stop. ## Examples - The following example uses the method to obtain a UTF-8 decoder. The decoder converts a sequence of bytes into a sequence of characters. + The following example uses the method to obtain a UTF-8 decoder. The decoder converts a sequence of bytes into a sequence of characters. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetDecoder/getdecoder-.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF8Encoding/GetDecoder/getdecoder-.vb" id="Snippet1"::: @@ -1786,14 +1786,14 @@ method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method. However, a maintains state information between calls so it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method. However, a maintains state information between calls so it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. If error detection is enabled, that is, the `throwOnInvalidCharacters` parameter of the constructor is set to `true`, error detection is also enabled in the returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the encoder is undefined and processing must stop. ## Examples - The following example uses the method to obtain an encoder to convert a sequence of characters into a UTF-8 encoded sequence of bytes. + The following example uses the method to obtain an encoder to convert a sequence of characters into a UTF-8 encoded sequence of bytes. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetEncoder/getencoder-.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF8Encoding/GetEncoder/getencoder-.vb" id="Snippet1"::: @@ -1853,7 +1853,7 @@ method to return a hash code for instances. Notice that the hash code returned by this method depends on the constructor used to create the object. + The following example uses the method to return a hash code for instances. Notice that the hash code returned by this method depends on the constructor used to create the object. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetHashCode/gethashcode-.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF8Encoding/GetHashCode/gethashcode-.vb" id="Snippet1"::: @@ -1912,13 +1912,13 @@ to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. - is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. + is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. - In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . For example, text in English and many other languages often needs only one UTF-8 byte to represent a character, but the number returned by has to allow for the possibility that the string to be converted will consist entirely of characters that each require four bytes. + In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . For example, text in English and many other languages often needs only one UTF-8 byte to represent a character, but the number returned by has to allow for the possibility that the string to be converted will consist entirely of characters that each require four bytes. - has no relation to . If your application needs a similar function to use with , it should use . + has no relation to . If your application needs a similar function to use with , it should use . > [!NOTE] > `GetMaxByteCount(N)` is not necessarily the same value as `N* GetMaxByteCount(1)`. @@ -1926,7 +1926,7 @@ ## Examples - The following example uses the method to return the maximum number of bytes required to encode a specified number of characters. + The following example uses the method to return the maximum number of bytes required to encode a specified number of characters. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetMaxByteCount/getmaxbytecount-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF8Encoding/GetMaxByteCount/getmaxbytecount-int32.vb" id="Snippet1"::: @@ -1998,13 +1998,13 @@ to store the resulting characters, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. - is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. + is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. - In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . + In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . - has no relation to . If your application needs a similar function to use with , it should use . + has no relation to . If your application needs a similar function to use with , it should use . > [!NOTE] > `GetMaxCharCount(N)` is not necessarily the same value as `N* GetMaxCharCount(1)`. @@ -2012,7 +2012,7 @@ ## Examples - The following example uses the method to return the maximum number of characters produced by decoding a specified number of bytes. + The following example uses the method to return the maximum number of characters produced by decoding a specified number of bytes. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetMaxCharCount/getmaxcharcount-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF8Encoding/GetMaxCharCount/getmaxcharcount-int32.vb" id="Snippet1"::: @@ -2084,7 +2084,7 @@ ## Remarks The object can provide a preamble, which is a byte array that can be prefixed to the sequence of bytes that result from the encoding process. Prefacing a sequence of encoded bytes with a byte order mark (code point U+FEFF) helps the decoder determine the byte order and the transformation format, or UTF. The Unicode byte order mark (BOM) is serialized as 0xEF 0xBB 0xBF. Note that the Unicode Standard neither requires nor recommends the use of a BOM for UTF-8 encoded streams. - You can instantiate a object whose method returns a valid BOM in the following ways: + You can instantiate a object whose method returns a valid BOM in the following ways: - By retrieving the object returned by the property. @@ -2101,15 +2101,15 @@ For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://go.microsoft.com/fwlink/?LinkId=37123). > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix the beginning of a stream of encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. +> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix the beginning of a stream of encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. ## Examples - The following example uses the method to return the Unicode byte order mark encoded in UTF-8 format. Notice that the parameterless constructor for does not provide a preamble. + The following example uses the method to return the Unicode byte order mark encoded in UTF-8 format. Notice that the parameterless constructor for does not provide a preamble. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetPreamble/getpreamble-.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF8Encoding/GetPreamble/getpreamble-.vb" id="Snippet1"::: - The following example instantiates two objects, the first by calling the parameterless constructor, which does not provide a BOM, and the second by calling the constructor with its `encoderShouldEmitUTF8Identifier` argument set to `true`. It then calls the method to write the BOM to a file before writing a UF8-encoded string. As the console output from the example shows, the file that saves the bytes from the second encoder has three more bytes than the first. + The following example instantiates two objects, the first by calling the parameterless constructor, which does not provide a BOM, and the second by calling the constructor with its `encoderShouldEmitUTF8Identifier` argument set to `true`. It then calls the method to write the BOM to a file before writing a UF8-encoded string. As the console output from the example shows, the file that saves the bytes from the second encoder has three more bytes than the first. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetPreamble/getpreamble1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF8Encoding/GetPreamble/getpreamble1.vb" id="Snippet1"::: @@ -2184,19 +2184,19 @@ ## Remarks With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the provided by the method or the method, respectively. ## Examples - The following example initializes an array by calling the method to determine exactly how many bytes are required for an encoded string and then adding the size of the byte order mark (BOM). The example then calls the method to store the BOM to the array before calling the method to store the encoded bytes to the array. The example then calls the method to decode the string. + The following example initializes an array by calling the method to determine exactly how many bytes are required for an encoded string and then adding the size of the byte order mark (BOM). The example then calls the method to store the BOM to the array before calling the method to store the encoded bytes to the array. The example then calls the method to decode the string. :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetString/getstring1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UnicodeEncoding/GetString/getstring1.vb" id="Snippet1"::: - Note that in this case the decoded string differs from the original string, since it begins with a 16-bit byte order mark U+FFFD. This means that the two strings will compare as unequal, and that if the string is output, the BOM will be displayed as the replacement character "?". To remove the BOM at the beginning of the string, you can call the method. + Note that in this case the decoded string differs from the original string, since it begins with a 16-bit byte order mark U+FFFD. This means that the two strings will compare as unequal, and that if the string is output, the BOM will be displayed as the replacement character "?". To remove the BOM at the beginning of the string, you can call the method. ]]> @@ -2275,7 +2275,7 @@ For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://go.microsoft.com/fwlink/?LinkId=37123). > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix the beginning of a stream of encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. +> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix the beginning of a stream of encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. ]]> diff --git a/xml/System.Text/UnicodeEncoding.xml b/xml/System.Text/UnicodeEncoding.xml index 4b76b81dd0b..a222add878a 100644 --- a/xml/System.Text/UnicodeEncoding.xml +++ b/xml/System.Text/UnicodeEncoding.xml @@ -89,26 +89,26 @@ Optionally, the object provides a byte order mark (BOM), which is an array of bytes that can be prefixed to the sequence of bytes resulting from the encoding process. If the preamble contains a byte order mark (BOM), it helps the decoder determine the byte order and the transformation format or UTF. - If the instance is configured to provide a BOM, you can retrieve it by calling the method; otherwise, the method returns an empty array. Note that, even if a object is configured for BOM support, you must include the BOM at the beginning of the encoded byte stream as appropriate; the encoding methods of the class do not do this automatically. + If the instance is configured to provide a BOM, you can retrieve it by calling the method; otherwise, the method returns an empty array. Note that, even if a object is configured for BOM support, you must include the BOM at the beginning of the encoded byte stream as appropriate; the encoding methods of the class do not do this automatically. > [!CAUTION] -> To enable error detection and to make the class instance more secure, you should instantiate a object by calling the constructor and setting its `throwOnInvalidBytes` argument to `true`. With error detection, a method that detects an invalid sequence of characters or bytes throws a . Without error detection, no exception is thrown, and the invalid sequence is generally ignored. +> To enable error detection and to make the class instance more secure, you should instantiate a object by calling the constructor and setting its `throwOnInvalidBytes` argument to `true`. With error detection, a method that detects an invalid sequence of characters or bytes throws a . Without error detection, no exception is thrown, and the invalid sequence is generally ignored. You can instantiate a object in a number of ways, depending on whether you want to it to provide a byte order mark (BOM), whether you want big-endian or little-endian encoding, and whether you want to enable error detection. The following table lists the constructors and the properties that return a object. |Member|Endianness|BOM|Error detection| |------------|----------------|---------|---------------------| -||Big-endian|Yes|No (Replacement fallback)| -||Little-endian|Yes|No (Replacement fallback)| +||Big-endian|Yes|No (Replacement fallback)| +||Little-endian|Yes|No (Replacement fallback)| ||Little-endian|Yes|No (Replacement fallback)| -||Configurable|Configurable|No (Replacement fallback)| -||Configurable|Configurable|Configurable| +||Configurable|Configurable|No (Replacement fallback)| +||Configurable|Configurable|Configurable| - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. - Likewise, the method determines how many characters result in decoding a sequence of bytes, and the and methods perform the actual decoding. + Likewise, the method determines how many characters result in decoding a sequence of bytes, and the and methods perform the actual decoding. - For an encoder or decoder that is able to save state information when encoding or decoding data that spans multiple blocks (such as string of 1 million characters that is encoded in 100,000-character segments), use the and properties, respectively. + For an encoder or decoder that is able to save state information when encoding or decoding data that spans multiple blocks (such as string of 1 million characters that is encoded in 100,000-character segments), use the and properties, respectively. @@ -192,7 +192,7 @@ This constructor creates an instance that uses the little endian byte order, provides a Unicode byte order mark, and does not throw an exception when an invalid encoding is detected. > [!CAUTION] -> For security reasons, you should enable error detection by calling the constructor and setting its `throwOnInvalidBytes` argument to `true`. +> For security reasons, you should enable error detection by calling the constructor and setting its `throwOnInvalidBytes` argument to `true`. ## Examples The following example demonstrates how to create a new instance and display the name of the encoding. @@ -256,9 +256,9 @@ This constructor creates an instance that does not throw an exception when an invalid encoding is detected. > [!CAUTION] -> For security reasons, you should enable error detection by calling the constructor and setting its `throwOnInvalidBytes` argument to `true`. +> For security reasons, you should enable error detection by calling the constructor and setting its `throwOnInvalidBytes` argument to `true`. - The `byteOrderMark` parameter controls the operation of the method. If `true`, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-16 format. If `false`, it returns a zero-length byte array. However, setting `byteOrderMark` to `true` does not cause the method to prefix the BOM at the beginning of the byte array, nor does it cause the method to include the number of bytes in the BOM in the byte count. + The `byteOrderMark` parameter controls the operation of the method. If `true`, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-16 format. If `false`, it returns a zero-length byte array. However, setting `byteOrderMark` to `true` does not cause the method to prefix the BOM at the beginning of the byte array, nor does it cause the method to include the number of bytes in the BOM in the byte count. @@ -324,7 +324,7 @@ method. If `true`, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-16 format. If `false`, it returns a zero-length byte array. However, setting `byteOrderMark` to `true` does not cause the method to prefix the BOM at the beginning of the byte array, nor does it cause the method to include the number of bytes in the BOM in the byte count. + The `byteOrderMark` parameter controls the operation of the method. If `true`, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-16 format. If `false`, it returns a zero-length byte array. However, setting `byteOrderMark` to `true` does not cause the method to prefix the BOM at the beginning of the byte array, nor does it cause the method to include the number of bytes in the BOM in the byte count. If the `throwOnInvalidBytes` parameter is `true`, a method that detects an invalid byte sequence throws . Otherwise, the method does not throw an exception, and the invalid sequence is ignored. @@ -470,7 +470,7 @@ ## Examples - The following example demonstrates how to use the method to test whether the current object is equal to a different object. Five objects are created and compared, and the results of the comparisons are displayed. + The following example demonstrates how to use the method to test whether the current object is equal to a different object. Five objects are created and compared, and the results of the comparisons are displayed. :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/.ctor/ctor-boolean-boolean.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UnicodeEncoding/.ctor/ctor-boolean-boolean.vb" id="Snippet1"::: @@ -547,17 +547,17 @@ to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble is not reflected in the value returned by the method. +> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble is not reflected in the value returned by the method. ## Examples - The following example calls the and methods to calculate the maximum and actual number of bytes required to encode a string. It also displays the actual number of bytes required to store a byte stream with a byte order mark. + The following example calls the and methods to calculate the maximum and actual number of bytes required to encode a string. It also displays the actual number of bytes required to store a byte stream with a byte order mark. :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetByteCount/getbytecount1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UnicodeEncoding/GetByteCount/getbytecount1.vb" id="Snippet1"::: @@ -639,12 +639,12 @@ requires to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size that requires to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble is not reflected in the value returned by the method. +> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble is not reflected in the value returned by the method. ]]> @@ -726,16 +726,16 @@ to store the resulting bytes, the application uses . To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. With error detection enabled, an invalid sequence causes this method to throw an . Without error detection, invalid sequences are ignored, and no exception is thrown. - To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble Is not reflected in the value returned by the method. + To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble Is not reflected in the value returned by the method. ## Examples - The following example populates an array with a Latin uppercase and lowercase characters and calls the method to determine the number of bytes needed to encode the Latin lowercase characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Latin lowercase characters. The following example populates an array with a combination of Greek and Cyrillic characters and calls the method to determine the number of bytes needed to encode the Cyrillic characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Cyrillic characters. + The following example populates an array with a Latin uppercase and lowercase characters and calls the method to determine the number of bytes needed to encode the Latin lowercase characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Latin lowercase characters. The following example populates an array with a combination of Greek and Cyrillic characters and calls the method to determine the number of bytes needed to encode the Cyrillic characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Cyrillic characters. :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetByteCount/getbytecount2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UnicodeEncoding/GetByteCount/getbytecount2.vb" id="Snippet2"::: @@ -871,14 +871,14 @@ requires to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size that requires to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the object provided by the or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the object provided by the or the method, respectively. > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. +> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. ]]> @@ -968,19 +968,19 @@ to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. +> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. ## Examples - The following example demonstrates how to use the method to encode a range of characters from a and store the encoded bytes in a range of elements in a byte array. + The following example demonstrates how to use the method to encode a range of characters from a and store the encoded bytes in a range of elements in a byte array. :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetBytes/getbytes-string-int32-int32-byte[]-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UnicodeEncoding/GetBytes/getbytes-string-int32-int32-byte[]-int32.vb" id="Snippet1"::: @@ -1081,14 +1081,14 @@ to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. +> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. ## Examples The following example demonstrates how to encode a range of elements from a Unicode character array and store the encoded bytes in a range of elements in a byte array. @@ -1200,7 +1200,7 @@ requires to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size that requires to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. @@ -1284,14 +1284,14 @@ to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. ## Examples - The following example demonstrates how to use the method to return the number of characters produced by decoding a range of elements in a byte array using . + The following example demonstrates how to use the method to return the number of characters produced by decoding a range of elements in a byte array using . :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetCharCount/getcharcount-byte[]-int32-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UnicodeEncoding/GetCharCount/getcharcount-byte[]-int32-int32.vb" id="Snippet1"::: @@ -1396,13 +1396,13 @@ requires to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size that requires to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the object provided by the or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the object provided by the or the method, respectively. ]]> @@ -1493,18 +1493,18 @@ to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. ## Examples - The following example demonstrates how to use the method to decode a range of elements in a byte array and store the result in a character array. + The following example demonstrates how to use the method to decode a range of elements in a byte array and store the result in a character array. :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetChars/getchars-byte[]-int32-int32-char[]-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UnicodeEncoding/GetChars/getchars-byte[]-int32-int32-char[]-int32.vb" id="Snippet1"::: @@ -1589,7 +1589,7 @@ method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the . However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the . However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. If error detection is enabled, that is, the `throwOnInvalidBytes` parameter of the constructor is set to `true`, error detection is also enabled in the returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the decoder is undefined and processing must stop. @@ -1662,7 +1662,7 @@ method converts sequential blocks of characters into sequential blocks of bytes in a manner similar to the method of this class. However, a object maintains state information between calls so that it can correctly encode character sequences that span blocks. The object also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of characters into sequential blocks of bytes in a manner similar to the method of this class. However, a object maintains state information between calls so that it can correctly encode character sequences that span blocks. The object also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. If error detection is enabled, that is, the `throwOnInvalidBytes` parameter of the constructor is set to `true`, error detection is also enabled in the object returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the encoder is undefined and processing must stop. @@ -1778,13 +1778,13 @@ to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. - retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. + retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. - In most cases, this method retrieves reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . + In most cases, this method retrieves reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . - has no relation to . If your application needs a similar function to use with , it should use . + has no relation to . If your application needs a similar function to use with , it should use . > [!NOTE] > `GetMaxByteCount(N)` is not necessarily the same value as `N* GetMaxByteCount(1)`. @@ -1792,7 +1792,7 @@ ## Examples - The following example demonstrates how to use the method to return the maximum number of bytes required to encode a specified number of characters. + The following example demonstrates how to use the method to return the maximum number of bytes required to encode a specified number of characters. :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetMaxByteCount/getmaxbytecount-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UnicodeEncoding/GetMaxByteCount/getmaxbytecount-int32.vb" id="Snippet1"::: @@ -1864,13 +1864,13 @@ to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. - retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, retrieves large values. + retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, retrieves large values. - In most cases, this method retrieves reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . + In most cases, this method retrieves reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . - has no relation to . If your application needs a similar function to use with , it should use . + has no relation to . If your application needs a similar function to use with , it should use . > [!NOTE] > `GetMaxCharCount(N)` is not necessarily the same value as `N* GetMaxCharCount(1)`. @@ -1878,7 +1878,7 @@ ## Examples - The following example demonstrates how to use the method to return the maximum number of characters produced by decoding a specified number of bytes. + The following example demonstrates how to use the method to return the maximum number of characters produced by decoding a specified number of bytes. :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetMaxCharCount/getmaxcharcount-int32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UnicodeEncoding/GetMaxCharCount/getmaxcharcount-int32.vb" id="Snippet1"::: @@ -1954,13 +1954,13 @@ - Little endian byte order: FF FE - You can instantiate a object whose method returns a valid BOM in the following ways: + You can instantiate a object whose method returns a valid BOM in the following ways: -- By retrieving the object returned by the or property. +- By retrieving the object returned by the or property. - By calling the parameterless constructor to instantiate a object. -- By supplying `true` as the value of the `byteOrderMark` argument to the or constructors. +- By supplying `true` as the value of the `byteOrderMark` argument to the or constructors. We recommended that you use the BOM, since it provides nearly certain identification of an encoding for files that otherwise have lost a reference to their encoding, such as untagged or improperly tagged web data or random text files stored when a business did not have international concerns. Often user problems might be avoided if data is consistently and properly tagged. @@ -1969,17 +1969,17 @@ There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. In spite of the few disadvantages, however, the use of a BOM is highly recommended. > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly, you should prefix the beginning of a stream of encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. +> To ensure that the encoded bytes are decoded properly, you should prefix the beginning of a stream of encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. ## Examples - The following example demonstrates how to use the method to retrieve the Unicode byte order mark in big endian or little endian byte order for an instance of a . + The following example demonstrates how to use the method to retrieve the Unicode byte order mark in big endian or little endian byte order for an instance of a . :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetPreamble/getpreamble-.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UnicodeEncoding/GetPreamble/getpreamble-.vb" id="Snippet1"::: - The following example instantiates two objects, the first of which does not provide a BOM, and the second of which does. It then calls the method to write the BOM to a file before writing a Unicode-encoded string. As the console output from the example shows, the file that saves the bytes from the second encoder has three more bytes than the first. + The following example instantiates two objects, the first of which does not provide a BOM, and the second of which does. It then calls the method to write the BOM to a file before writing a Unicode-encoded string. As the console output from the example shows, the file that saves the bytes from the second encoder has three more bytes than the first. :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetPreamble/GetPreamble1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UnicodeEncoding/GetPreamble/GetPreamble1.vb" id="Snippet1"::: @@ -2054,19 +2054,19 @@ ## Remarks With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the object provided by the or the method, respectively. + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the object provided by the or the method, respectively. ## Examples - The following example initializes an array by calling the method to determine exactly how many bytes are required for an encoded string and then adding the size of the byte order mark (BOM). The example then calls the method to store the BOM to the array before calling the method to store the encoded bytes to the array. The example then calls the method to decode the string. + The following example initializes an array by calling the method to determine exactly how many bytes are required for an encoded string and then adding the size of the byte order mark (BOM). The example then calls the method to store the BOM to the array before calling the method to store the encoded bytes to the array. The example then calls the method to decode the string. :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetString/getstring1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UnicodeEncoding/GetString/getstring1.vb" id="Snippet1"::: - Note that in this case the decoded string differs from the original string, since it begins with a 16-bit byte order mark U+FFFD. This means that the two strings will compare as unequal, and that if the string is output, the BOM will be displayed as the replacement character "?". To remove the BOM at the beginning of the string, you can call the method. + Note that in this case the decoded string differs from the original string, since it begins with a 16-bit byte order mark U+FFFD. This means that the two strings will compare as unequal, and that if the string is output, the BOM will be displayed as the replacement character "?". To remove the BOM at the beginning of the string, you can call the method. ]]> @@ -2140,11 +2140,11 @@ You can instantiate a object whose is a valid BOM in the following ways: -- By retrieving the object returned by the or property. +- By retrieving the object returned by the or property. - By calling the parameterless constructor to instantiate a object. -- By supplying `true` as the value of the `byteOrderMark` argument to the or constructors. +- By supplying `true` as the value of the `byteOrderMark` argument to the or constructors. We recommended that you use the BOM, since it provides nearly certain identification of an encoding for files that otherwise have lost a reference to their encoding, such as untagged or improperly tagged web data or random text files stored when a business did not have international concerns. Often user problems might be avoided if data is consistently and properly tagged. @@ -2153,7 +2153,7 @@ There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. In spite of the few disadvantages, however, the use of a BOM is highly recommended. > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly, you should prefix the beginning of a stream of encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. +> To ensure that the encoded bytes are decoded properly, you should prefix the beginning of a stream of encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. ]]> diff --git a/xml/System.Threading.Channels/ChannelReader`1.xml b/xml/System.Threading.Channels/ChannelReader`1.xml index f34f4ab9382..e4c86f45065 100644 --- a/xml/System.Threading.Channels/ChannelReader`1.xml +++ b/xml/System.Threading.Channels/ChannelReader`1.xml @@ -227,10 +227,10 @@ The created async enumerable. call that returns `true` will read the next item out of the channel. - returns `false` once no more data is or will ever be available to read. +Each call that returns `true` will read the next item out of the channel. + + returns `false` once no more data is or will ever be available to read. ]]> diff --git a/xml/System.Threading.Tasks.Dataflow/ActionBlock`1.xml b/xml/System.Threading.Tasks.Dataflow/ActionBlock`1.xml index f059357814c..58afc7672c0 100644 --- a/xml/System.Threading.Tasks.Dataflow/ActionBlock`1.xml +++ b/xml/System.Threading.Tasks.Dataflow/ActionBlock`1.xml @@ -71,7 +71,7 @@ [!INCLUDE [tpl-install-instructions](~/includes/tpl-install-instructions.md)] ## Examples - The following example shows the use of the class to perform several computations using dataflow blocks, and returns the elapsed time required to perform the computations. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) article. + The following example shows the use of the class to perform several computations using dataflow blocks, and returns the elapsed time required to perform the computations. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) article. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks.Dataflow/ActionBlock`1/dataflowdegreeofparallelism.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_degreeofparallelism/vb/dataflowdegreeofparallelism.vb" id="Snippet2"::: @@ -189,7 +189,7 @@ constructor to create a new object. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) topic. + The following example shows how to use the constructor to create a new object. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) topic. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks.Dataflow/ActionBlock`1/dataflowdegreeofparallelism.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_degreeofparallelism/vb/dataflowdegreeofparallelism.vb" id="Snippet2"::: @@ -284,12 +284,12 @@ has been called on a dataflow block, that block will complete (so that its task will enter a final state) after it has processed all previously available data. This method will not block waiting for completion to occur, but will initiate the request. To wait for completion to occur, use the property. + After has been called on a dataflow block, that block will complete (so that its task will enter a final state) after it has processed all previously available data. This method will not block waiting for completion to occur, but will initiate the request. To wait for completion to occur, use the property. ## Examples - The following example shows the use of the method to signal to the dataflow block that it shouldn't accept or produce any more messages nor consume any more postponed messages. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) topic. + The following example shows the use of the method to signal to the dataflow block that it shouldn't accept or produce any more messages nor consume any more postponed messages. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) topic. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks.Dataflow/ActionBlock`1/dataflowdegreeofparallelism.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_degreeofparallelism/vb/dataflowdegreeofparallelism.vb" id="Snippet2"::: @@ -341,7 +341,7 @@ ## Examples - The following example shows how to use the property to wait for all messages to propagate through the network. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) topic. + The following example shows how to use the property to wait for all messages to propagate through the network. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) topic. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks.Dataflow/ActionBlock`1/dataflowdegreeofparallelism.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_degreeofparallelism/vb/dataflowdegreeofparallelism.vb" id="Snippet2"::: @@ -385,7 +385,7 @@ does not include any items that are currently being processed by the block or any items that have already been processed by the block. + The does not include any items that are currently being processed by the block or any items that have already been processed by the block. ]]> @@ -431,7 +431,7 @@ method to post an item to the target dataflow block. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) topic. + The following example shows how to use the method to post an item to the target dataflow block. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) topic. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks.Dataflow/ActionBlock`1/dataflowdegreeofparallelism.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_degreeofparallelism/vb/dataflowdegreeofparallelism.vb" id="Snippet2"::: @@ -481,7 +481,7 @@ has been called on a dataflow block, that block will complete and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. + After has been called on a dataflow block, that block will complete and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. ]]> @@ -583,7 +583,7 @@ . Uses the option. + Inherited from . Uses the option. ]]> diff --git a/xml/System.Threading.Tasks.Dataflow/BatchBlock`1.xml b/xml/System.Threading.Tasks.Dataflow/BatchBlock`1.xml index 60247914967..f7e8ee9b5c2 100644 --- a/xml/System.Threading.Tasks.Dataflow/BatchBlock`1.xml +++ b/xml/System.Threading.Tasks.Dataflow/BatchBlock`1.xml @@ -79,12 +79,12 @@ Specifies the type of data put into batches. Provides a dataflow block that batches inputs into arrays. - @@ -158,10 +158,10 @@ The options with which to configure this . Initializes a new with the specified batch size, declining option, and block options. To be added. - The must be positive. - - -or- - + The must be positive. + + -or- + The must be smaller than the value of the option if a non-default value has been set. The is . @@ -198,11 +198,11 @@ Gets the size of the batches generated by this . The batch size. - @@ -242,11 +242,11 @@ Signals to the that it should not accept nor produce any more messages nor consume any more postponed messages. - has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. - + has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. + ]]> @@ -286,11 +286,11 @@ Gets a that represents the asynchronous operation and completion of the dataflow block. The task. - will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. - + will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. + ]]> @@ -412,11 +412,11 @@ The that caused the faulting. Causes the to complete in a state. - has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. - + has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. + ]]> The is . @@ -464,15 +464,15 @@ if the message was successfully consumed; otherwise, . Called by a linked to accept and consume a previously offered by this . - The value of the consumed message. This may correspond to a different instance than was previously reserved and passed as the to . The consuming must use the returned value instead of the value passed as messageValue through . - + The value of the consumed message. This may correspond to a different instance than was previously reserved and passed as the to . The consuming must use the returned value instead of the value passed as messageValue through . + If the message requested is not available, the return value will be . - instances linked to this instance may use , and it must only be used to consume instances previously offered by this source to the target. - + instances linked to this instance may use , and it must only be used to consume instances previously offered by this source to the target. + ]]> The is not valid. @@ -519,11 +519,11 @@ The releasing the message it previously reserved. Called by a linked to release a previously reserved by this . - instances linked to this instance may use `ReleaseReservation`, and it must only be used to release instances previously and successfully reserved by the target. - + instances linked to this instance may use `ReleaseReservation`, and it must only be used to release instances previously and successfully reserved by the target. + ]]> The is not valid. @@ -573,15 +573,15 @@ if the message was successfully reserved; otherwise, . - instances linked to this instance may use , and it must only be used to reserve instances previously offered by this source to the target. - - If `true` is returned, the must subsequently call either or for this message. Failure to do so may result in the source being unable to propagate any further messages to this or other targets. - - must not be called while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. - + instances linked to this instance may use , and it must only be used to reserve instances previously offered by this source to the target. + + If `true` is returned, the must subsequently call either or for this message. Failure to do so may result in the source being unable to propagate any further messages to this or other targets. + + must not be called while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. + ]]> The is not valid. @@ -631,16 +631,16 @@ The offering the message. This may be null. Set to to instruct the target to call synchronously during the call to , prior to returning , in order to consume the message. Offers a message to the , giving the target the opportunity to consume or postpone the message. - The status of the offered message. If the message was accepted by the target, is returned, and the source should no longer use the offered message, because it is now owned by the target. If the message was postponed by the target, is returned as a notification that the target may later attempt to consume or reserve the message; in the meantime, the source still owns the message and may offer it to other blocks. - - If the target would have otherwise postponed message, but was , is instead returned. - - If the target tried to accept the message but missed it due to the source delivering the message to another target or simply discarding it, is returned. - + The status of the offered message. If the message was accepted by the target, is returned, and the source should no longer use the offered message, because it is now owned by the target. If the message was postponed by the target, is returned as a notification that the target may later attempt to consume or reserve the message; in the meantime, the source still owns the message and may offer it to other blocks. + + If the target would have otherwise postponed message, but was , is instead returned. + + If the target tried to accept the message but missed it due to the source delivering the message to another target or simply discarding it, is returned. + If the target chose not to accept the message, is returned. If the target chose not to accept the message and will never accept another message from this source, is returned. To be added. - The is not valid. - + The is not valid. + -or- may only be true if provided with a non-null . @@ -677,11 +677,11 @@ Returns a string that represents the formatted name of this instance. A string that represents the formatted name of this instance. - . Uses the option. - + . Uses the option. + ]]> @@ -718,13 +718,13 @@ Triggers the to initiate a batching operation even if the number of currently queued or postponed items is less than the . - @@ -787,13 +787,13 @@ if an item could be received; otherwise, . - @@ -847,13 +847,13 @@ if one or more items could be received; otherwise, . - diff --git a/xml/System.Threading.Tasks.Dataflow/BatchedJoinBlock`2.xml b/xml/System.Threading.Tasks.Dataflow/BatchedJoinBlock`2.xml index 148a64c94ec..9bf7c33d853 100644 --- a/xml/System.Threading.Tasks.Dataflow/BatchedJoinBlock`2.xml +++ b/xml/System.Threading.Tasks.Dataflow/BatchedJoinBlock`2.xml @@ -79,12 +79,12 @@ Specifies the type of data accepted by the block's second target. Provides a dataflow block that batches a specified number of inputs of potentially differing types provided to one or more of its targets. - @@ -233,11 +233,11 @@ Signals to the that it should not accept nor produce any more messages nor consume any more postponed messages. - has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. - + has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. + ]]> @@ -277,11 +277,11 @@ Gets a that represents the asynchronous operation and completion of the dataflow block. The task. - will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. - + will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. + ]]> @@ -404,8 +404,8 @@ Causes the to complete in a state. task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. + +After `Fault` has been called on a dataflow block, that block will complete, such that its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. ]]> @@ -460,7 +460,7 @@ After `Fault` has been called on a dataflow block, that block will complete, suc ## Remarks - The for which the message is to be consumed need not be linked from this instance. Moreover, this instance may have never offered the message directly to the . + The for which the message is to be consumed need not be linked from this instance. Moreover, this instance may have never offered the message directly to the . ]]> @@ -514,7 +514,7 @@ After `Fault` has been called on a dataflow block, that block will complete, suc The that holds the reservation need not be linked from this instance. Moreover, this instance may have never offered the message directly to the . It is required that this message has been previously reserved for the same . - + ]]> @@ -571,9 +571,9 @@ After `Fault` has been called on a dataflow block, that block will complete, suc The for which the message is to be reserved need not be linked from this instance. Moreover, this instance may have never offered the message directly to the . -If `true` is returned, you must subsequently call either or for this message with the same and . If you don't, the source may be unable to propagate any further messages to any target. +If `true` is returned, you must subsequently call either or for this message with the same and . If you don't, the source may be unable to propagate any further messages to any target. -Don't call while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. +Don't call while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. ]]> @@ -682,11 +682,11 @@ Don't call Returns a string that represents the formatted name of this instance. A string that represents the formatted name of this instance. - . Uses the option. - + . Uses the option. + ]]> @@ -749,13 +749,13 @@ Don't call if an item could be received; otherwise, . - @@ -809,13 +809,13 @@ Don't call if one or more items could be received; otherwise, . - diff --git a/xml/System.Threading.Tasks.Dataflow/BatchedJoinBlock`3.xml b/xml/System.Threading.Tasks.Dataflow/BatchedJoinBlock`3.xml index df96883b33e..0e54381503d 100644 --- a/xml/System.Threading.Tasks.Dataflow/BatchedJoinBlock`3.xml +++ b/xml/System.Threading.Tasks.Dataflow/BatchedJoinBlock`3.xml @@ -88,12 +88,12 @@ Specifies the type of data accepted by the block's third target. Provides a dataflow block that batches a specified number of inputs of potentially differing types provided to one or more of its targets. - @@ -240,11 +240,11 @@ Signals to the that it should not accept nor produce any more messages nor consume any more postponed messages. - has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. - + has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. + ]]> @@ -284,11 +284,11 @@ Gets a that represents the asynchronous operation and completion of the dataflow block. The task. - will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics, it will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. - + will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics, it will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. + ]]> @@ -411,11 +411,11 @@ The that caused the faulting. Causes the to complete in a state. - has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. - + has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. + ]]> The is . @@ -469,7 +469,7 @@ ## Remarks - The for which the message is to be consumed need not be linked from this instance. Moreover, this instance may have never offered the message directly to the . + The for which the message is to be consumed need not be linked from this instance. Moreover, this instance may have never offered the message directly to the . ]]> @@ -523,7 +523,7 @@ The that holds the reservation need not be linked from this instance. Moreover, this instance may have never offered the message directly to the . It is required that this message has been previously reserved for the same . - + ]]> @@ -580,9 +580,9 @@ The for which the message is to be reserved need not be linked from this instance. Moreover, this instance may have never offered the message directly to the . -If `true` is returned, you must subsequently call either or for this message with the same and . If you don't, the source may be unable to propagate any further messages to any target. +If `true` is returned, you must subsequently call either or for this message with the same and . If you don't, the source may be unable to propagate any further messages to any target. -Don't call while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. +Don't call while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. ]]> @@ -726,7 +726,7 @@ Don't call A string that represents the formatted name of this instance. . Uses the option. ]]> @@ -791,13 +791,13 @@ Inherited from . Uses the if an item could be received; otherwise, . - @@ -851,13 +851,13 @@ Inherited from . Uses the if one or more items could be received; otherwise, . - diff --git a/xml/System.Threading.Tasks.Dataflow/BroadcastBlock`1.xml b/xml/System.Threading.Tasks.Dataflow/BroadcastBlock`1.xml index c53cc6c2951..b6492707b3e 100644 --- a/xml/System.Threading.Tasks.Dataflow/BroadcastBlock`1.xml +++ b/xml/System.Threading.Tasks.Dataflow/BroadcastBlock`1.xml @@ -79,14 +79,14 @@ Specifies the type of the data buffered by this dataflow block. Provides a buffer for storing at most one element at time, overwriting each message with the next as it arrives. - exposes at most one element at a time. However, unlike , that element will be overwritten as new elements are provided to the block. ensures that the current element is broadcast to any linked targets before allowing the element to be overwritten. - + + exposes at most one element at a time. However, unlike , that element will be overwritten as new elements are provided to the block. ensures that the current element is broadcast to any linked targets before allowing the element to be overwritten. + ]]> @@ -213,11 +213,11 @@ Signals to the that it should not accept nor produce any more messages nor consume any more postponed messages. - has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. - + has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. + ]]> @@ -257,11 +257,11 @@ Gets a that represents the asynchronous operation and completion of the dataflow block. The task. - will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. - + will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. + ]]> @@ -349,11 +349,11 @@ The that caused the faulting. Causes the to complete in a state. - has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. - + has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. + ]]> The is . @@ -403,13 +403,13 @@ if one or more items could be received; otherwise, . - @@ -456,15 +456,15 @@ if the message was successfully consumed; otherwise, . Called by a linked to accept and consume a previously offered by this . - The value of the consumed message. This may correspond to a different instance than was previously reserved and passed as the to . The consuming must use the returned value instead of the value passed as through . - + The value of the consumed message. This may correspond to a different instance than was previously reserved and passed as the to . The consuming must use the returned value instead of the value passed as through . + If the message requested is not available, the return value will be . - instances linked to this instance may use , and it must only be used to consume instances previously offered by this source to the target. - + instances linked to this instance may use , and it must only be used to consume instances previously offered by this source to the target. + ]]> The is not valid. @@ -511,11 +511,11 @@ The releasing the message it previously reserved. Called by a linked to release a previously reserved by this . - instances linked to this instance may use `ReleaseReservation`, and it must only be used to release instances previously and successfully reserved by the target. - + instances linked to this instance may use `ReleaseReservation`, and it must only be used to release instances previously and successfully reserved by the target. + ]]> The is not valid. @@ -565,15 +565,15 @@ if the message was successfully reserved; otherwise, . - instances linked to this instance may use , and it must only be used to reserve instances previously offered by this source to the target. - - If `true` is returned, the must subsequently call either or for this message. Failure to do so may result in the source being unable to propagate any further messages to this or other targets. - - must not be called while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. - + instances linked to this instance may use , and it must only be used to reserve instances previously offered by this source to the target. + + If `true` is returned, the must subsequently call either or for this message. Failure to do so may result in the source being unable to propagate any further messages to this or other targets. + + must not be called while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. + ]]> The is not valid. @@ -623,16 +623,16 @@ The offering the message. This may be null. Set to to instruct the target to call synchronously during the call to , prior to returning , in order to consume the message. Offers a message to the , giving the target the opportunity to consume or postpone the message. - The status of the offered message. If the message was accepted by the target, is returned, and the source should no longer use the offered message, because it is now owned by the target. If the message was postponed by the target, is returned as a notification that the target may later attempt to consume or reserve the message; in the meantime, the source still owns the message and may offer it to other blocks. - - If the target would have otherwise postponed message, but was , is instead returned. - - If the target tried to accept the message but missed it due to the source delivering the message to another target or simply discarding it, is returned. - + The status of the offered message. If the message was accepted by the target, is returned, and the source should no longer use the offered message, because it is now owned by the target. If the message was postponed by the target, is returned as a notification that the target may later attempt to consume or reserve the message; in the meantime, the source still owns the message and may offer it to other blocks. + + If the target would have otherwise postponed message, but was , is instead returned. + + If the target tried to accept the message but missed it due to the source delivering the message to another target or simply discarding it, is returned. + If the target chose not to accept the message, is returned. If the target chose not to accept the message and will never accept another message from this source, is returned. To be added. - The is not valid. - + The is not valid. + -or- may only be true if provided with a non-null . @@ -669,11 +669,11 @@ Returns a string that represents the formatted name of this instance. A string that represents the formatted name of this instance. - . Uses the option. - + . Uses the option. + ]]> @@ -732,13 +732,13 @@ if an item could be received; otherwise, . - diff --git a/xml/System.Threading.Tasks.Dataflow/BufferBlock`1.xml b/xml/System.Threading.Tasks.Dataflow/BufferBlock`1.xml index ab49eb9ee75..0e51770d28c 100644 --- a/xml/System.Threading.Tasks.Dataflow/BufferBlock`1.xml +++ b/xml/System.Threading.Tasks.Dataflow/BufferBlock`1.xml @@ -79,12 +79,12 @@ Specifies the type of the data buffered by this dataflow block. Provides a buffer for storing data for a Dataflow. - @@ -189,11 +189,11 @@ Signals to the that it should not accept nor produce any more messages nor consume any more postponed messages. - has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. - + has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. + ]]> @@ -233,11 +233,11 @@ Gets a that represents the asynchronous operation and completion of the dataflow block. The task. - will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. - + will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. + ]]> @@ -359,11 +359,11 @@ The that caused the faulting. Causes the to complete in a state. - has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. - + has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. + ]]> The is . @@ -411,15 +411,15 @@ if the message was successfully consumed; otherwise, . Called by a linked to accept and consume a previously offered by this . - The value of the consumed message. This may correspond to a different instance than was previously reserved and passed as the to . The consuming must use the returned value instead of the value passed as through . - + The value of the consumed message. This may correspond to a different instance than was previously reserved and passed as the to . The consuming must use the returned value instead of the value passed as through . + If the message requested is not available, the return value will be . - instances linked to this instance may use , and it must only be used to consume instances previously offered by this source to the target. - + instances linked to this instance may use , and it must only be used to consume instances previously offered by this source to the target. + ]]> The is not valid. @@ -466,11 +466,11 @@ The releasing the message it previously reserved. Called by a linked to release a previously reserved by this . - instances linked to this instance may use `ReleaseReservation`, and it must only be used to release instances previously and successfully reserved by the target. - + instances linked to this instance may use `ReleaseReservation`, and it must only be used to release instances previously and successfully reserved by the target. + ]]> The is not valid. @@ -520,15 +520,15 @@ if the message was successfully reserved; otherwise, . - instances linked to this instance may use , and it must only be used to reserve instances previously offered by this source to the target. - - If `true` is returned, the must subsequently call either or for this message. Failure to do so may result in the source being unable to propagate any further messages to this or other targets. - - must not be called while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. - + instances linked to this instance may use , and it must only be used to reserve instances previously offered by this source to the target. + + If `true` is returned, the must subsequently call either or for this message. Failure to do so may result in the source being unable to propagate any further messages to this or other targets. + + must not be called while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. + ]]> The is not valid. @@ -578,16 +578,16 @@ The offering the message. This may be . Set to true to instruct the target to call synchronously during the call to , prior to returning , in order to consume the message. Offers a message to the , giving the target the opportunity to consume or postpone the message. - The status of the offered message. If the message was accepted by the target, is returned, and the source should no longer use the offered message, because it is now owned by the target. If the message was postponed by the target, is returned as a notification that the target may later attempt to consume or reserve the message; in the meantime, the source still owns the message and may offer it to other blocks. - - If the target would have otherwise postponed message, but was , is instead returned. - - If the target tried to accept the message but missed it due to the source delivering the message to another target or simply discarding it, is returned. - + The status of the offered message. If the message was accepted by the target, is returned, and the source should no longer use the offered message, because it is now owned by the target. If the message was postponed by the target, is returned as a notification that the target may later attempt to consume or reserve the message; in the meantime, the source still owns the message and may offer it to other blocks. + + If the target would have otherwise postponed message, but was , is instead returned. + + If the target tried to accept the message but missed it due to the source delivering the message to another target or simply discarding it, is returned. + If the target chose not to accept the message, is returned. If the target chose not to accept the message and will never accept another message from this source, is returned. To be added. - The is not valid. - + The is not valid. + -or- may only be true if provided with a non-null . @@ -624,11 +624,11 @@ Returns a string that represents the formatted name of this instance. A string that represents the formatted name of this instance. - . Uses the option. - + . Uses the option. + ]]> @@ -687,13 +687,13 @@ if an item could be received; otherwise, . - @@ -747,13 +747,13 @@ if one or more items could be received; otherwise, . - diff --git a/xml/System.Threading.Tasks.Dataflow/DataflowBlock.xml b/xml/System.Threading.Tasks.Dataflow/DataflowBlock.xml index ec69917504d..f10c254cacd 100644 --- a/xml/System.Threading.Tasks.Dataflow/DataflowBlock.xml +++ b/xml/System.Threading.Tasks.Dataflow/DataflowBlock.xml @@ -574,7 +574,7 @@ method requires two existing blocks: a target block (an instance of a class that implements ) and a source block (an instance of a class that implements ). creates a new instance of an internal class that connects the interface members to the `target` parameter and the interface members to the `source` parameter. Both and derive from . Block completion is explicitly passed from sources to targets. Therefore, the and methods are connected to the target while the property is connected to the source. You must ensure that when the target half completes, the source half gets completed in the most appropriate manner; for example: + The method requires two existing blocks: a target block (an instance of a class that implements ) and a source block (an instance of a class that implements ). creates a new instance of an internal class that connects the interface members to the `target` parameter and the interface members to the `source` parameter. Both and derive from . Block completion is explicitly passed from sources to targets. Therefore, the and methods are connected to the target while the property is connected to the source. You must ensure that when the target half completes, the source half gets completed in the most appropriate manner; for example: `target.Completion.ContinueWith(completion => source.Complete());` @@ -590,7 +590,7 @@ batchBlock.Complete(); ``` - You must also explicitly provide the message propagation from target to source. The benefit of this explicit connection is that it gives you the freedom to perform any unconstrained processing between the two encapsulated blocks. You may do that either by encoding the necessary processing into the blocks' delegates (if the blocks take delegates), or by embedding a sub-network of blocks between them. The easier way is to use a block that takes delegates; for example, use , , (if applicable), or a custom block. + You must also explicitly provide the message propagation from target to source. The benefit of this explicit connection is that it gives you the freedom to perform any unconstrained processing between the two encapsulated blocks. You may do that either by encoding the necessary processing into the blocks' delegates (if the blocks take delegates), or by embedding a sub-network of blocks between them. The easier way is to use a block that takes delegates; for example, use , , (if applicable), or a custom block. ]]> @@ -984,7 +984,7 @@ batchBlock.Complete(); will return from as soon as it has stored the posted item into its input queue). From the perspective of the block's processing, `Post` is asynchronous. For target blocks that support postponing offered messages, or for blocks that may do more processing in their `Post` implementation, consider using , which will return immediately and will enable the target to postpone the posted message and later consume it after `SendAsync` returns. + This method will return once the target block has decided to accept or decline the item, but unless otherwise dictated by special semantics of the target block, it does not wait for the item to actually be processed. For example, will return from as soon as it has stored the posted item into its input queue). From the perspective of the block's processing, `Post` is asynchronous. For target blocks that support postponing offered messages, or for blocks that may do more processing in their `Post` implementation, consider using , which will return immediately and will enable the target to postpone the posted message and later consume it after `SendAsync` returns. ]]> diff --git a/xml/System.Threading.Tasks.Dataflow/DataflowBlockOptions.xml b/xml/System.Threading.Tasks.Dataflow/DataflowBlockOptions.xml index 2c1aa5ba50e..61cdedb3db5 100644 --- a/xml/System.Threading.Tasks.Dataflow/DataflowBlockOptions.xml +++ b/xml/System.Threading.Tasks.Dataflow/DataflowBlockOptions.xml @@ -41,25 +41,25 @@ Provides options used to configure the processing performed by dataflow blocks. - is mutable and can be configured through its properties. - - When specific configuration options are not set, the following defaults are used: - -|Options|Default| -|-------------|-------------| -|TaskScheduler|| -|MaxMessagesPerTask|DataflowBlockOptions.Unbounded (-1)| -|CancellationToken|| -|BoundedCapacity|DataflowBlockOptions.Unbounded (-1)| - - Dataflow blocks capture the state of the options at their construction. Subsequent changes to the provided instance should not affect the behavior of a dataflow block. - + + is mutable and can be configured through its properties. + + When specific configuration options are not set, the following defaults are used: + +|Options|Default| +|-------------|-------------| +|TaskScheduler|| +|MaxMessagesPerTask|DataflowBlockOptions.Unbounded (-1)| +|CancellationToken|| +|BoundedCapacity|DataflowBlockOptions.Unbounded (-1)| + + Dataflow blocks capture the state of the options at their construction. Subsequent changes to the provided instance should not affect the behavior of a dataflow block. + ]]> @@ -199,8 +199,8 @@ ## Remarks By default, dataflow blocks enforce ordering on the processing of messages. This means that a -block like will ensure that messages are output in the same -order they were input, even if parallelism is employed by the block, and the processing of a message N finishes +block like will ensure that messages are output in the same +order they were input, even if parallelism is employed by the block, and the processing of a message N finishes after the processing of a subsequent message N+1 (the block will reorder the results to maintain the input ordering prior to making those results available to a consumer). Some blocks may allow this to be relaxed, however. Setting to false tells a block that it may relax this ordering if @@ -277,11 +277,11 @@ is more important than maintaining the input-to-output ordering. Gets or sets the format string to use when a block is queried for its name. The format string to use when a block is queried for its name. - diff --git a/xml/System.Threading.Tasks.Dataflow/ExecutionDataflowBlockOptions.xml b/xml/System.Threading.Tasks.Dataflow/ExecutionDataflowBlockOptions.xml index 9a57f55c8e8..5e82045d6c2 100644 --- a/xml/System.Threading.Tasks.Dataflow/ExecutionDataflowBlockOptions.xml +++ b/xml/System.Threading.Tasks.Dataflow/ExecutionDataflowBlockOptions.xml @@ -37,26 +37,26 @@ Provides options used to configure the processing performed by dataflow blocks that process each message through the invocation of a user-provided delegate. These are dataflow blocks such as and . - is mutable and can be configured through its properties. - - When specific configuration options are not set, the following defaults are used: - -|Options|Default| -|-------------|-------------| -|TaskScheduler|| -|CancellationToken|| -|MaxMessagesPerTask|DataflowBlockOptions.Unbounded (-1)| -|BoundedCapacity|DataflowBlockOptions.Unbounded (-1)| -|MaxDegreeOfParallelism|1| - - Dataflow blocks capture the state of the options at their construction. Subsequent changes to the provided instance should not affect the behavior of a dataflow block. - + + is mutable and can be configured through its properties. + + When specific configuration options are not set, the following defaults are used: + +|Options|Default| +|-------------|-------------| +|TaskScheduler|| +|CancellationToken|| +|MaxMessagesPerTask|DataflowBlockOptions.Unbounded (-1)| +|BoundedCapacity|DataflowBlockOptions.Unbounded (-1)| +|MaxDegreeOfParallelism|1| + + Dataflow blocks capture the state of the options at their construction. Subsequent changes to the provided instance should not affect the behavior of a dataflow block. + ]]> @@ -157,11 +157,11 @@ Gets whether code using the dataflow block is constrained to one producer at a time. Returns . - diff --git a/xml/System.Threading.Tasks.Dataflow/GroupingDataflowBlockOptions.xml b/xml/System.Threading.Tasks.Dataflow/GroupingDataflowBlockOptions.xml index c3861ea383c..e0eae25e9d0 100644 --- a/xml/System.Threading.Tasks.Dataflow/GroupingDataflowBlockOptions.xml +++ b/xml/System.Threading.Tasks.Dataflow/GroupingDataflowBlockOptions.xml @@ -37,27 +37,27 @@ Provides options used to configure the processing performed by dataflow blocks that group together multiple messages. These are dataflow blocks such as and . - is mutable and can be configured through its properties. - - When specific configuration options are not set, the following defaults are used: - -|Options|Default| -|-------------|-------------| -|TaskScheduler|| -|CancellationToken|| -|MaxMessagesPerTask|DataflowBlockOptions.Unbounded (-1)| -|BoundedCapacity|DataflowBlockOptions.Unbounded (-1)| -|MaxNumberOfGroups|GroupingDataflowBlockOptions.Unbounded (-1)| -|Greedy|`true`| - - Dataflow block capture the state of the options at their construction. Subsequent changes to the provided instance should not affect the behavior of a dataflow block. - + + is mutable and can be configured through its properties. + + When specific configuration options are not set, the following defaults are used: + +|Options|Default| +|-------------|-------------| +|TaskScheduler|| +|CancellationToken|| +|MaxMessagesPerTask|DataflowBlockOptions.Unbounded (-1)| +|BoundedCapacity|DataflowBlockOptions.Unbounded (-1)| +|MaxNumberOfGroups|GroupingDataflowBlockOptions.Unbounded (-1)| +|Greedy|`true`| + + Dataflow block capture the state of the options at their construction. Subsequent changes to the provided instance should not affect the behavior of a dataflow block. + ]]> diff --git a/xml/System.Threading.Tasks.Dataflow/IDataflowBlock.xml b/xml/System.Threading.Tasks.Dataflow/IDataflowBlock.xml index 3ac05360668..5bf8c34c86e 100644 --- a/xml/System.Threading.Tasks.Dataflow/IDataflowBlock.xml +++ b/xml/System.Threading.Tasks.Dataflow/IDataflowBlock.xml @@ -29,12 +29,12 @@ Represents a dataflow block. - @@ -71,11 +71,11 @@ Signals to the that it should not accept nor produce any more messages nor consume any more postponed messages. - has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. - + has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. + ]]> @@ -112,11 +112,11 @@ Gets a that represents the asynchronous operation and completion of the dataflow block. The task. - will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. - + will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. + ]]> @@ -156,11 +156,11 @@ The that caused the faulting. Causes the to complete in a state. - has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. - + has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. + ]]> The is . diff --git a/xml/System.Threading.Tasks.Dataflow/ISourceBlock`1.xml b/xml/System.Threading.Tasks.Dataflow/ISourceBlock`1.xml index 1bd7c1ea5ea..0d10489afbc 100644 --- a/xml/System.Threading.Tasks.Dataflow/ISourceBlock`1.xml +++ b/xml/System.Threading.Tasks.Dataflow/ISourceBlock`1.xml @@ -47,12 +47,12 @@ Specifies the type of data supplied by the . Represents a dataflow block that is a source of data. - @@ -96,15 +96,15 @@ if the message was successfully consumed; otherwise, . Called by a linked to accept and consume a previously offered by this . - The value of the consumed message. This may correspond to a different instance than was previously reserved and passed as the to . The consuming must use the returned value instead of the value passed as through . - + The value of the consumed message. This may correspond to a different instance than was previously reserved and passed as the to . The consuming must use the returned value instead of the value passed as through . + If the message requested is not available, the return value will be null. - instances linked to this instance may use , and it must only be used to consume instances previously offered by this source to the target. - + instances linked to this instance may use , and it must only be used to consume instances previously offered by this source to the target. + ]]> The messageHeader is not valid. @@ -190,11 +190,11 @@ The releasing the message it previously reserved. Called by a linked to release a previously reserved by this . - instances linked to this instance may use `ReleaseReservation`, and it must only be used to release instances previously and successfully reserved by the target. - + instances linked to this instance may use `ReleaseReservation`, and it must only be used to release instances previously and successfully reserved by the target. + ]]> The is not valid. @@ -241,15 +241,15 @@ if the message was successfully reserved; otherwise, . - instances linked to this instance may use , and it must only be used to reserve instances previously offered by this source to the target. - - If `true` is returned, the must subsequently call either or for this message. Failure to do so may result in the source being unable to propagate any further messages to this or other targets. - - must not be called while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. - + instances linked to this instance may use , and it must only be used to reserve instances previously offered by this source to the target. + + If `true` is returned, the must subsequently call either or for this message. Failure to do so may result in the source being unable to propagate any further messages to this or other targets. + + must not be called while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. + ]]> The is not valid. diff --git a/xml/System.Threading.Tasks.Dataflow/JoinBlock`2.xml b/xml/System.Threading.Tasks.Dataflow/JoinBlock`2.xml index 66a3a3b3347..0de42ea1559 100644 --- a/xml/System.Threading.Tasks.Dataflow/JoinBlock`2.xml +++ b/xml/System.Threading.Tasks.Dataflow/JoinBlock`2.xml @@ -79,12 +79,12 @@ Specifies the type of data accepted by the block's second target. Provides a dataflow block that joins across multiple dataflow sources, not necessarily of the same type, waiting for one item to arrive for each type before they're all released together as a tuple consisting of one item per type. - @@ -189,11 +189,11 @@ Signals to the that it should not accept nor produce any more messages nor consume any more postponed messages. - has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. - + has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. + ]]> @@ -233,11 +233,11 @@ Gets a that represents the asynchronous operation and completion of the dataflow block. The task. - will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. - + will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. + ]]> @@ -359,11 +359,11 @@ The that caused the faulting. Causes the to complete in a state. - has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. - + has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. + ]]> The is . @@ -417,7 +417,7 @@ ## Remarks - The for which the message is to be consumed need not be linked from this instance. Moreover, this instance may have never offered the message directly to the . + The for which the message is to be consumed need not be linked from this instance. Moreover, this instance may have never offered the message directly to the . ]]> @@ -471,7 +471,7 @@ The that holds the reservation need not be linked from this instance. Moreover, this instance may have never offered the message directly to the . It is required that this message has been previously reserved for the same . - + ]]> @@ -528,9 +528,9 @@ The for which the message is to be reserved need not be linked from this instance. Moreover, this instance may have never offered the message directly to the . -If `true` is returned, you must subsequently call either or for this message with the same and . If you don't, the source may be unable to propagate any further messages to any target. +If `true` is returned, you must subsequently call either or for this message with the same and . If you don't, the source may be unable to propagate any further messages to any target. -Don't call while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. +Don't call while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. ]]> @@ -639,11 +639,11 @@ Don't call Returns a string that represents the formatted name of this instance. A string that represents the formatted name of this instance. - . Uses the option. - + . Uses the option. + ]]> @@ -706,13 +706,13 @@ Don't call if an item could be received; otherwise, . - @@ -766,13 +766,13 @@ Don't call if one or more items could be received; otherwise, . - diff --git a/xml/System.Threading.Tasks.Dataflow/JoinBlock`3.xml b/xml/System.Threading.Tasks.Dataflow/JoinBlock`3.xml index 3faee470ff4..177b0d13b16 100644 --- a/xml/System.Threading.Tasks.Dataflow/JoinBlock`3.xml +++ b/xml/System.Threading.Tasks.Dataflow/JoinBlock`3.xml @@ -88,12 +88,12 @@ Specifies the type of data accepted by the block's third target. Provides a dataflow block that joins across multiple dataflow sources, which are not necessarily of the same type, waiting for one item to arrive for each type before they're all released together as a tuple that contains one item per type. - @@ -198,11 +198,11 @@ Signals to the that it should not accept nor produce any more messages nor consume any more postponed messages. - has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. - + has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. + ]]> @@ -242,11 +242,11 @@ Gets a that represents the asynchronous operation and completion of the dataflow block. The task. - will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. - + will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. + ]]> @@ -293,10 +293,10 @@ A disposable object that unlinks the source from the target when its method is called. To be added. - is . - - -or- - + is . + + -or- + is . @@ -372,11 +372,11 @@ The that caused the faulting. Causes the to complete in a state. - has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. - + has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. + ]]> The is . @@ -430,7 +430,7 @@ ## Remarks - The for which the message is to be consumed need not be linked from this instance. Moreover, this instance may have never offered the message directly to the . + The for which the message is to be consumed need not be linked from this instance. Moreover, this instance may have never offered the message directly to the . ]]> @@ -484,7 +484,7 @@ The that holds the reservation need not be linked from this instance. Moreover, this instance may have never offered the message directly to the . It is required that this message has been previously reserved for the same . - + ]]> @@ -541,9 +541,9 @@ The for which the message is to be reserved need not be linked from this instance. Moreover, this instance may have never offered the message directly to the . -If `true` is returned, you must subsequently call either or for this message with the same and . If you don't, the source may be unable to propagate any further messages to any target. +If `true` is returned, you must subsequently call either or for this message with the same and . If you don't, the source may be unable to propagate any further messages to any target. -Don't call while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. +Don't call while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. ]]> @@ -686,11 +686,11 @@ Don't call Returns a string that represents the formatted name of this instance. A string that represents the formatted name of this instance. - . Uses the option. - + . Uses the option. + ]]> @@ -753,13 +753,13 @@ Don't call if an item could be received; otherwise, . - @@ -813,13 +813,13 @@ Don't call if one or more items could be received; otherwise, . - diff --git a/xml/System.Threading.Tasks.Dataflow/TransformBlock`2.xml b/xml/System.Threading.Tasks.Dataflow/TransformBlock`2.xml index b0d9f97e056..4187d7f92c9 100644 --- a/xml/System.Threading.Tasks.Dataflow/TransformBlock`2.xml +++ b/xml/System.Threading.Tasks.Dataflow/TransformBlock`2.xml @@ -82,12 +82,12 @@ Specifies the type of data output by this . Provides a dataflow block that invokes a provided delegate for every data element received. - @@ -196,10 +196,10 @@ The options with which to configure this . Initializes a new with the specified and . To be added. - The is . - - -or- - + The is . + + -or- + The is . @@ -237,10 +237,10 @@ The options with which to configure this . Initializes a new with the specified and . To be added. - The is . - - -or- - + The is . + + -or- + The is . @@ -279,11 +279,11 @@ Signals to the that it should not accept nor produce any more messages nor consume any more postponed messages. - has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. - + has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. + ]]> @@ -323,11 +323,11 @@ Gets a that represents the asynchronous operation and completion of the dataflow block. The task. - will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. - + will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. + ]]> @@ -364,11 +364,11 @@ Gets the number of input items waiting to be processed by this block. The number of input items. - does not include any items currently being processed by the block or any items that have already been processed by the block. - + does not include any items currently being processed by the block or any items that have already been processed by the block. + ]]> @@ -490,11 +490,11 @@ The that caused the faulting. Causes the to complete in a state. - has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. - + has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. + ]]> The is . @@ -542,15 +542,15 @@ if the message was successfully consumed; otherwise, . Called by a linked to accept and consume a previously offered by this . - The value of the consumed message. This may correspond to a different instance than was previously reserved and passed as the to . The consuming must use the returned value instead of the value passed as through . - + The value of the consumed message. This may correspond to a different instance than was previously reserved and passed as the to . The consuming must use the returned value instead of the value passed as through . + If the message requested is not available, the return value will be . - instances linked to this instance may use , and it must only be used to consume instances previously offered by this source to the target. - + instances linked to this instance may use , and it must only be used to consume instances previously offered by this source to the target. + ]]> The is not valid. @@ -597,11 +597,11 @@ The releasing the message it previously reserved. Called by a linked to release a previously reserved by this . - instances linked to this instance may use , and it must only be used to release instances previously and successfully reserved by the target. - + instances linked to this instance may use , and it must only be used to release instances previously and successfully reserved by the target. + ]]> The is not valid. @@ -651,15 +651,15 @@ if the message was successfully reserved; otherwise, . - instances linked to this instance may use , and it must only be used to reserve instances previously offered by this source to the target. - - If `true` is returned, the must subsequently call either or for this message. Failure to do so may result in the source being unable to propagate any further messages to this or other targets. - - must not be called while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. - + instances linked to this instance may use , and it must only be used to reserve instances previously offered by this source to the target. + + If `true` is returned, the must subsequently call either or for this message. Failure to do so may result in the source being unable to propagate any further messages to this or other targets. + + must not be called while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. + ]]> The is not valid. @@ -710,16 +710,16 @@ if the target must call synchronously during the call to , prior to returning , in order to consume the message. Offers a message to the , giving the target the opportunity to consume or postpone the message. - The status of the offered message. If the message was accepted by the target, is returned, and the source should no longer use the offered message, because it is now owned by the target. If the message was postponed by the target, is returned as a notification that the target may later attempt to consume or reserve the message; in the meantime, the source still owns the message and may offer it to other blocks. - - If the target would have otherwise postponed but source was , is instead returned. - - If the target tried to accept the message but missed it due to the source delivering the message to another target or simply discarding it, is returned. - + The status of the offered message. If the message was accepted by the target, is returned, and the source should no longer use the offered message, because it is now owned by the target. If the message was postponed by the target, is returned as a notification that the target may later attempt to consume or reserve the message; in the meantime, the source still owns the message and may offer it to other blocks. + + If the target would have otherwise postponed but source was , is instead returned. + + If the target tried to accept the message but missed it due to the source delivering the message to another target or simply discarding it, is returned. + If the target chose not to accept the message, is returned. If the target chose not to accept the message and will never accept another message from this source, is returned. To be added. - The is not valid. - + The is not valid. + -or- may only be true if provided with a non-null . @@ -756,11 +756,11 @@ Returns a string that represents the formatted name of this instance. A string that represents the formatted name of this instance. - . Uses the option. - + . Uses the option. + ]]> @@ -822,13 +822,13 @@ if an item could be received; otherwise, . - @@ -885,13 +885,13 @@ if one or more items could be received; otherwise, . - diff --git a/xml/System.Threading.Tasks.Dataflow/TransformManyBlock`2.xml b/xml/System.Threading.Tasks.Dataflow/TransformManyBlock`2.xml index de57d29741d..0ac00f2ec2e 100644 --- a/xml/System.Threading.Tasks.Dataflow/TransformManyBlock`2.xml +++ b/xml/System.Threading.Tasks.Dataflow/TransformManyBlock`2.xml @@ -82,12 +82,12 @@ Specifies the type of data output by this . Provides a dataflow block that invokes a provided delegate for every data element received. - @@ -250,10 +250,10 @@ The options with which to configure this . Initializes a new with the specified function and . To be added. - The is . - - -or- - + The is . + + -or- + The is . @@ -291,10 +291,10 @@ The options with which to configure this . Initializes a new with the specified function and . To be added. - The is . - - -or- - + The is . + + -or- + The is . @@ -333,11 +333,11 @@ Signals to the that it should not accept nor produce any more messages nor consume any more postponed messages. - has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. - + has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. + ]]> @@ -377,11 +377,11 @@ Gets a that represents the asynchronous operation and completion of the dataflow block. The task. - will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. - + will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. + ]]> @@ -418,11 +418,11 @@ Gets the number of input items waiting to be processed by this block. The number of input items. - does not include any items currently being processed by the block or any items that have already been processed by the block. - + does not include any items currently being processed by the block or any items that have already been processed by the block. + ]]> @@ -544,11 +544,11 @@ The that caused the faulting. Causes the to complete in a state. - has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. - + has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. + ]]> The is . @@ -596,15 +596,15 @@ if the message was successfully consumed; otherwise, . Called by a linked to accept and consume a previously offered by this . - The value of the consumed message. This may correspond to a different instance than was previously reserved and passed as the to . The consuming must use the returned value instead of the value passed as through OfferMessage - + The value of the consumed message. This may correspond to a different instance than was previously reserved and passed as the to . The consuming must use the returned value instead of the value passed as through OfferMessage + If the message requested is not available, the return value will be . - instances linked to this instance may use , and it must only be used to consume instances previously offered by this source to the target. - + instances linked to this instance may use , and it must only be used to consume instances previously offered by this source to the target. + ]]> The is not valid. @@ -651,11 +651,11 @@ The releasing the message it previously reserved. Called by a linked to release a previously reserved by this . - instances linked to this instance may use , and it must only be used to release instances previously and successfully reserved by the target. - + instances linked to this instance may use , and it must only be used to release instances previously and successfully reserved by the target. + ]]> The is not valid. @@ -705,15 +705,15 @@ if the message was successfully reserved; otherwise, . - instances linked to this instance may use , and it must only be used to reserve instances previously offered by this source to the target. - - If `true` is returned, the must subsequently call either or for this message. Failure to do so may result in the source being unable to propagate any further messages to this or other targets. - - must not be called while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. - + instances linked to this instance may use , and it must only be used to reserve instances previously offered by this source to the target. + + If `true` is returned, the must subsequently call either or for this message. Failure to do so may result in the source being unable to propagate any further messages to this or other targets. + + must not be called while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. + ]]> The is not valid. @@ -764,18 +764,18 @@ if the target must call synchronously during the call to , prior to returning , in order to consume the message. Offers a message to the , giving the target the opportunity to consume or postpone the message. - The status of the offered message. If the message was accepted by the target, is returned, and the source should no longer use the offered message, as it is now owned by the target. If the message was postponed by the target, is returned as a notification that the target may later attempt to consume or reserve the message; in the meantime, the source still owns the message and may offer it to other blocks. - - If the target would have otherwise postponed but source was , is instead returned. - - If the target tried to accept the message but missed it due to the source delivering the message to another target or simply discarding it, is returned. - + The status of the offered message. If the message was accepted by the target, is returned, and the source should no longer use the offered message, as it is now owned by the target. If the message was postponed by the target, is returned as a notification that the target may later attempt to consume or reserve the message; in the meantime, the source still owns the message and may offer it to other blocks. + + If the target would have otherwise postponed but source was , is instead returned. + + If the target tried to accept the message but missed it due to the source delivering the message to another target or simply discarding it, is returned. + If the target chose not to accept the message, is returned. If the target chose not to accept the message and will never accept another message from this source, is returned. To be added. - The is not valid. - - -or- - + The is not valid. + + -or- + may only be true if provided with a non-null . @@ -812,11 +812,11 @@ Returns a string that represents the formatted name of this instance. A string that represents the formatted name of this instance. - . Uses the option. - + . Uses the option. + ]]> @@ -878,13 +878,13 @@ if an item could be received; otherwise, . - @@ -941,13 +941,13 @@ if one or more items could be received; otherwise, . - diff --git a/xml/System.Threading.Tasks.Dataflow/WriteOnceBlock`1.xml b/xml/System.Threading.Tasks.Dataflow/WriteOnceBlock`1.xml index 7f5d04b0701..537ed2cbe22 100644 --- a/xml/System.Threading.Tasks.Dataflow/WriteOnceBlock`1.xml +++ b/xml/System.Threading.Tasks.Dataflow/WriteOnceBlock`1.xml @@ -79,12 +79,12 @@ Specifies the type of the data buffered by this dataflow block. Provides a buffer for receiving and storing at most one element in a network of dataflow blocks. - @@ -211,11 +211,11 @@ Signals to the that it should not accept nor produce any more messages nor consume any more postponed messages. - has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. - + has been called on a dataflow block, that block will complete, and its task will enter a final state after it has processed all previously available data. will not block waiting for completion to occur, but rather will initiate the request; to wait for completion to occur, the task may be used. + ]]> @@ -255,11 +255,11 @@ Gets a that represents the asynchronous operation and completion of the dataflow block. The task. - will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. - + will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely due to receiving a cancellation request. If the task completes in the state, its `Exception` property will return an containing the one or more exceptions that caused the block to fail. + ]]> @@ -347,11 +347,11 @@ The that caused the faulting. Causes the to complete in a state. - has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. - + has been called on a dataflow block, that block will complete, and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. + ]]> The is . @@ -401,13 +401,13 @@ if one or more items could be received; otherwise, . - @@ -454,15 +454,15 @@ if the message was successfully consumed; otherwise, . Called by a linked to accept and consume a previously offered by this . - The value of the consumed message. This may correspond to a different instance than was previously reserved and passed as the to . The consuming must use the returned value instead of the value passed as through . - + The value of the consumed message. This may correspond to a different instance than was previously reserved and passed as the to . The consuming must use the returned value instead of the value passed as through . + If the message requested is not available, the return value will be . - instances linked to this instance may use , and it must only be used to consume instances previously offered by this source to the target. - + instances linked to this instance may use , and it must only be used to consume instances previously offered by this source to the target. + ]]> The is not valid. @@ -509,11 +509,11 @@ The releasing the message it previously reserved. Called by a linked to release a previously reserved by this . - instances linked to this instance may use `ReleaseReservation`, and it must only be used to release instances previously and successfully reserved by the target. - + instances linked to this instance may use `ReleaseReservation`, and it must only be used to release instances previously and successfully reserved by the target. + ]]> The is not valid. @@ -563,15 +563,15 @@ if the message was successfully reserved; otherwise, . - instances linked to this instance may use , and it must only be used to reserve instances previously offered by this source to the target. - - If `true` is returned, the must subsequently call either or for this message. Failure to do so may result in the source being unable to propagate any further messages to this or other targets. - - must not be called while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. - + instances linked to this instance may use , and it must only be used to reserve instances previously offered by this source to the target. + + If `true` is returned, the must subsequently call either or for this message. Failure to do so may result in the source being unable to propagate any further messages to this or other targets. + + must not be called while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network. + ]]> The is not valid. @@ -621,16 +621,16 @@ The offering the message. This may be . Set to to instruct the target to call synchronously during the call to , prior to returning , in order to consume the message. Offers a message to the , giving the target the opportunity to consume or postpone the message. - The status of the offered message. If the message was accepted by the target, is returned, and the source should no longer use the offered message, because it is now owned by the target. If the message was postponed by the target, is returned as a notification that the target may later attempt to consume or reserve the message; in the meantime, the source still owns the message and may offer it to other blocks. - - If the target would have otherwise postponed message, but was , is instead returned. - - If the target tried to accept the message but missed it due to the source delivering the message to another target or simply discarding it, is returned. - + The status of the offered message. If the message was accepted by the target, is returned, and the source should no longer use the offered message, because it is now owned by the target. If the message was postponed by the target, is returned as a notification that the target may later attempt to consume or reserve the message; in the meantime, the source still owns the message and may offer it to other blocks. + + If the target would have otherwise postponed message, but was , is instead returned. + + If the target tried to accept the message but missed it due to the source delivering the message to another target or simply discarding it, is returned. + If the target chose not to accept the message, is returned. If the target chose not to accept the message and will never accept another message from this source, is returned. To be added. - The is not valid. - + The is not valid. + -or- may only be true if provided with a non-null . @@ -667,11 +667,11 @@ Returns a string that represents the formatted name of this instance. A string that represents the formatted name of this instance. - . Uses the option. - + . Uses the option. + ]]> @@ -730,13 +730,13 @@ if an item could be received; otherwise, . - diff --git a/xml/System.Threading.Tasks.Sources/ValueTaskSourceOnCompletedFlags.xml b/xml/System.Threading.Tasks.Sources/ValueTaskSourceOnCompletedFlags.xml index df973c2be0c..9117bc2806b 100644 --- a/xml/System.Threading.Tasks.Sources/ValueTaskSourceOnCompletedFlags.xml +++ b/xml/System.Threading.Tasks.Sources/ValueTaskSourceOnCompletedFlags.xml @@ -58,9 +58,9 @@ Provides flags passed from and to the method to control the behavior of a continuation. - to the method, and from a to the method. +This value is passed from a to the method, and from a to the method. ]]> diff --git a/xml/System.Threading.Tasks/ConcurrentExclusiveSchedulerPair.xml b/xml/System.Threading.Tasks/ConcurrentExclusiveSchedulerPair.xml index 4eb7e6b8c7a..bbeebffd597 100644 --- a/xml/System.Threading.Tasks/ConcurrentExclusiveSchedulerPair.xml +++ b/xml/System.Threading.Tasks/ConcurrentExclusiveSchedulerPair.xml @@ -136,7 +136,7 @@ constructor to create a new object. This code example is part of a larger example provided for the [How to: Specify a Task Scheduler in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block) article. + The following example shows the use of the constructor to create a new object. This code example is part of a larger example provided for the [How to: Specify a Task Scheduler in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block) article. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/ConcurrentExclusiveSchedulerPair/form1.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/vb/writerreaderswinforms/form1.vb" id="Snippet4"::: @@ -332,7 +332,7 @@ is optional. It is necessary only if you're relying on the property for notification that all processing has been completed. + Calling is optional. It is necessary only if you're relying on the property for notification that all processing has been completed. ]]> diff --git a/xml/System.Threading.Tasks/Parallel.xml b/xml/System.Threading.Tasks/Parallel.xml index 8958b013a01..f9135bfcb10 100644 --- a/xml/System.Threading.Tasks/Parallel.xml +++ b/xml/System.Threading.Tasks/Parallel.xml @@ -134,11 +134,11 @@ - A instance that can be used to break out of the loop prematurely. The object is created by the compiler; it cannot be instantiated in user code. - Calling the method informs the `for` operation that iterations after the current one don't have to execute. However, all iterations before the current one will still have to be executed if they haven't already. + Calling the method informs the `for` operation that iterations after the current one don't have to execute. However, all iterations before the current one will still have to be executed if they haven't already. - Therefore, calling is similar to using a break operation within a conventional `for` loop in a language like C#, but it is not a perfect substitute: For example, there is no guarantee that iterations after the current one will definitely not execute. + Therefore, calling is similar to using a break operation within a conventional `for` loop in a language like C#, but it is not a perfect substitute: For example, there is no guarantee that iterations after the current one will definitely not execute. - If executing all iterations before the current one is not necessary, use the method instead of using . Calling informs the `for` loop that it may abandon all remaining iterations, regardless of whether they're before or after the current iteration, because all required work will have already been completed. However, as with , there are no guarantees regarding which other iterations will not execute. + If executing all iterations before the current one is not necessary, use the method instead of using . Calling informs the `for` loop that it may abandon all remaining iterations, regardless of whether they're before or after the current iteration, because all required work will have already been completed. However, as with , there are no guarantees regarding which other iterations will not execute. If a loop is ended prematurely, the structure that is returned will contain relevant information about the loop's completion. @@ -147,12 +147,12 @@ ## Examples - The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. As the output from the example shows, no iterations whose index is greater than the property value start after the call to the method. + The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. As the output from the example shows, no iterations whose index is greater than the property value start after the call to the method. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Parallel/For/break1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Parallel/For/break1.vb" id="Snippet2"::: - Because iterations of the loop are still likely to be executing when the method is called, each iteration calls the property to check whether another iteration has called the method. If the property value is `true`, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. + Because iterations of the loop are still likely to be executing when the method is called, each iteration calls the property to check whether another iteration has called the method. If the property value is `true`, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. ]]> @@ -218,7 +218,7 @@ ## Examples - The following example uses the method for 100 invocations of a delegate that generates random byte values and computes their sum. + The following example uses the method for 100 invocations of a delegate that generates random byte values and computes their sum. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Parallel/For/for1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Parallel/For/for1.vb" id="Snippet1"::: @@ -281,11 +281,11 @@ ## Remarks The `body` delegate is invoked once for each value in the iteration range (`fromInclusive`, `toExclusive`). It is provided with the following parameters: the iteration count (), and a instance that may be used to break out of the loop prematurely. - Calling the method informs the `for` operation that iterations after the current one don't have to be executed, but all iterations before the current one do. + Calling the method informs the `for` operation that iterations after the current one don't have to be executed, but all iterations before the current one do. Therefore, calling Break is similar to using a break operation within a conventional `for` loop in a language like C#, but it is not a perfect substitute: For example, there is no guarantee that iterations after the current one will definitely not execute. - If executing all iterations before the current one is not necessary, use the method instead of using . Calling informs the `for` loop that it may abandon all remaining iterations, regardless of whether they're before or after the current iteration, because all required work will have already been completed. However, as with , there are no guarantees regarding which other iterations will not execute. + If executing all iterations before the current one is not necessary, use the method instead of using . Calling informs the `for` loop that it may abandon all remaining iterations, regardless of whether they're before or after the current iteration, because all required work will have already been completed. However, as with , there are no guarantees regarding which other iterations will not execute. If a loop is ended prematurely, the structure that is returned will contain relevant information about the loop's completion. @@ -560,7 +560,7 @@ ## Examples - The following example shows how to use the method with a object: + The following example shows how to use the method with a object: :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Parallel/Overview/parallelfor.cs" id="Snippet03"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Parallel/Overview/parallelfor.vb" id="Snippet03"::: @@ -722,7 +722,7 @@ The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per task to perform a final action on each task's local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. If `fromInclusive` is greater than or equal to `toExclusive`, then the method returns immediately without performing any iterations. @@ -811,7 +811,7 @@ The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per task to perform a final action on each task's local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. If `fromInclusive` is greater than or equal to `toExclusive`, then the method returns immediately without performing any iterations. @@ -902,7 +902,7 @@ The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per task to perform a final action on each task's local state. This delegate might be invoked concurrently on multiple threads; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. If `fromInclusive` is greater than or equal to `toExclusive`, then the method returns immediately without performing any iterations. @@ -1005,7 +1005,7 @@ The `localInit` delegate is invoked once for each thread that participates in the loop's execution and returns the initial local state for each of those threads. These initial states are passed to the first `body` invocations on each thread. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each thread returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per thread to perform a final action on each thread's local state. This delegate might be invoked concurrently on multiple threads; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. If `fromInclusive` is greater than or equal to `toExclusive`, then the method returns immediately without performing any iterations. @@ -1244,7 +1244,7 @@ method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). + This overload is provided for scenarios where you want to override the default partitioning scheme. For example, small loop bodies might benefit from partitioning the range. The method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). ]]> @@ -1324,7 +1324,7 @@ method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). + This overload is provided for scenarios where you want to override the default partitioning scheme. For example, small loop bodies might benefit from partitioning the range. The method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). ]]> @@ -1404,12 +1404,12 @@ method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). + This overload is provided for scenarios where you want to override the default partitioning scheme. For example, small loop bodies might benefit from partitioning the range. The method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). ## Examples - The following example shows how to implement a range partitioner for use with : + The following example shows how to implement a range partitioner for use with : :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Parallel/ForEachTSource/rangepartitioner.cs" id="Snippet01"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Parallel/ForEachTSource/rangepart.vb" id="Snippet01"::: @@ -1639,7 +1639,7 @@ ## Examples - The following example uses the method to count the number of vowels and non-white-space characters in a text file. In this case, the value returned by the method is ignored. Note that, because operations can run in parallel, you must ensure that incrementing the counter variables is an atomic operation, and that multiple threads do not attempt to access the counter variables simultaneously. For this purpose, the example uses the `lock` statement (in C#) and the `SyncLock` statement (in Visual Basic). + The following example uses the method to count the number of vowels and non-white-space characters in a text file. In this case, the value returned by the method is ignored. Note that, because operations can run in parallel, you must ensure that incrementing the counter variables is an atomic operation, and that multiple threads do not attempt to access the counter variables simultaneously. For this purpose, the example uses the `lock` statement (in C#) and the `SyncLock` statement (in Visual Basic). :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Parallel/ForEachTSource/foreach1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Parallel/ForEachTSource/foreach1.vb" id="Snippet1"::: @@ -1715,7 +1715,7 @@ method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). + This overload is provided for scenarios where you want to override the default partitioning scheme. For example, small loop bodies might benefit from partitioning the range. The method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). ]]> @@ -1803,7 +1803,7 @@ method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). + This overload is provided for scenarios where you want to override the default partitioning scheme. For example, small loop bodies might benefit from partitioning the range. The method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). ]]> @@ -1887,7 +1887,7 @@ method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). + This overload is provided for scenarios where you want to override the default partitioning scheme. For example, small loop bodies might benefit from partitioning the range. The method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). ]]> @@ -2219,11 +2219,11 @@ method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). + This overload is provided for scenarios where you want to override the default partitioning scheme. For example, small loop bodies might benefit from partitioning the range. The method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per task to perform a final action on each task's local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. ]]> @@ -2316,11 +2316,11 @@ method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). + This overload is provided for scenarios where you want to override the default partitioning scheme. For example, small loop bodies might benefit from partitioning the range. The method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). The `localInit` delegate is invoked once for each thread that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per task to perform a final action on each task's local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. ]]> @@ -2417,7 +2417,7 @@ The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per task to perform a final action on each task's local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. ]]> @@ -2513,12 +2513,12 @@ The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per thread to perform a final action on each task's local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. ## Examples - The following example shows how to use a method with local state: + The following example shows how to use a method with local state: :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Parallel/Overview/parallelforeach.cs" id="Snippet02"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Parallel/Overview/parallelforeach.vb" id="Snippet02"::: @@ -2615,11 +2615,11 @@ method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). + This overload is provided for scenarios where you want to override the default partitioning scheme. For example, small loop bodies might benefit from partitioning the range. The method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each thread returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per task to perform a final action on each task's local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. ]]> @@ -2716,11 +2716,11 @@ method expects custom partitioners to support dynamic partitioning. This overload is provided for scenarios with small loop bodies that might benefit from static range partitioning. Partitioners must support dynamic partitions. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). + This overload is provided for scenarios where you want to override the default partitioning scheme. For example, small loop bodies might benefit from partitioning the range. The method expects custom partitioners to support dynamic partitioning. This overload is provided for scenarios with small loop bodies that might benefit from static range partitioning. Partitioners must support dynamic partitions. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl) and [How to: Implement Dynamic Partitions](/dotnet/standard/parallel-programming/how-to-implement-dynamic-partitions). The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per task to perform a final action on each task's local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. ]]> @@ -2825,7 +2825,7 @@ The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per thread to perform a final action on each task's local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. ]]> @@ -2929,7 +2929,7 @@ The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per thread to perform a final action on each task's local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. ]]> @@ -3374,7 +3374,7 @@ The operation will execute at most oper ## Examples - This example demonstrates how to use the method with other methods, anonymous delegates, and lambda expressions. + This example demonstrates how to use the method with other methods, anonymous delegates, and lambda expressions. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Parallel/Overview/parallelinvoke.cs" id="Snippet01"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Parallel/Overview/parallelinvoke.vb" id="Snippet01"::: diff --git a/xml/System.Threading.Tasks/ParallelLoopResult.xml b/xml/System.Threading.Tasks/ParallelLoopResult.xml index b140ad8050c..e88117799bd 100644 --- a/xml/System.Threading.Tasks/ParallelLoopResult.xml +++ b/xml/System.Threading.Tasks/ParallelLoopResult.xml @@ -45,11 +45,11 @@ Provides completion status on the execution of a loop. - returns true, then the loop ran to completion, such that all iterations of the loop were executed. If returns false and returns null, a call to was used to end the loop prematurely. If returns false and returns a non-null integral value, was used to end the loop prematurely. - + returns true, then the loop ran to completion, such that all iterations of the loop were executed. If returns false and returns null, a call to was used to end the loop prematurely. If returns false and returns a non-null integral value, was used to end the loop prematurely. + ]]> All public members of are thread safe and may be called from multiple threads concurrently. @@ -135,11 +135,11 @@ Gets the index of the lowest iteration from which was called. Returns an integer that represents the lowest iteration from which the Break statement was called. - was not employed, this property will return null. - + was not employed, this property will return null. + ]]> diff --git a/xml/System.Threading.Tasks/ParallelLoopState.xml b/xml/System.Threading.Tasks/ParallelLoopState.xml index 86ad5065de9..94d051f2847 100644 --- a/xml/System.Threading.Tasks/ParallelLoopState.xml +++ b/xml/System.Threading.Tasks/ParallelLoopState.xml @@ -54,31 +54,31 @@ or method. The example provides an illustration. + Note that you cannot instantiate an instance of this class. It is automatically generated by the compiler as an argument in a call to the or method. The example provides an illustration. - Constructs such as `for` and `foreach` (in C#) and `For` and `For Each` (in Visual Basic) execute sequentially from the lowest index to the highest or from the first object in a set to the last. In contrast, the and methods do not. Because individual iterations of the loop run in parallel, they can begin and end in any order. The class allows individual iterations of parallel loops to interact with one another. The class allows you to: + Constructs such as `for` and `foreach` (in C#) and `For` and `For Each` (in Visual Basic) execute sequentially from the lowest index to the highest or from the first object in a set to the last. In contrast, the and methods do not. Because individual iterations of the loop run in parallel, they can begin and end in any order. The class allows individual iterations of parallel loops to interact with one another. The class allows you to: -- Exit the current iteration and prevent any additional iterations from starting by calling the method. This does not affect iterations that have already begun execution. +- Exit the current iteration and prevent any additional iterations from starting by calling the method. This does not affect iterations that have already begun execution. -- Prevent any iterations with an index greater than the current index from executing by calling the method. This does not affect iterations that have already begun execution. +- Prevent any iterations with an index greater than the current index from executing by calling the method. This does not affect iterations that have already begun execution. - Determine whether an exception has occurred in any loop iteration by retrieving the value of the property. -- Determine whether any iteration of the loop has called the method by retrieving the value of the property. You can use this property to return from iterations of the loop that started before the call to the method but are still executing. +- Determine whether any iteration of the loop has called the method by retrieving the value of the property. You can use this property to return from iterations of the loop that started before the call to the method but are still executing. -- Determine whether any iteration of the loop has called the or method or has thrown an exception by retrieving the value of the property. +- Determine whether any iteration of the loop has called the or method or has thrown an exception by retrieving the value of the property. - Exit from a long-running iteration whose index is greater than the index of an iteration in which Break was called by retrieving the value of the property. ## Examples - The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. As the output from the example shows, no iterations whose index is greater than the property value start after the call to the method. + The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. As the output from the example shows, no iterations whose index is greater than the property value start after the call to the method. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Parallel/For/break1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Parallel/For/break1.vb" id="Snippet2"::: - Because iterations of the loop are still likely to be executing when the method is called, each iteration calls the property to check whether another iteration has called the method. If the property value is `true`, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. + Because iterations of the loop are still likely to be executing when the method is called, each iteration calls the property to check whether another iteration has called the method. If the property value is `true`, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. ]]> @@ -127,9 +127,9 @@ indicates that no iterations after the current iteration should be run. It effectively cancels any additional iterations of the loop. However, it does not stop any iterations that have already begun execution. For example, if is called from the 100th iteration of a parallel loop iterating from 0 to 1,000, all iterations less than 100 should still be run, but the iterations from 101 through to 1000 that have not yet started are not executed. + indicates that no iterations after the current iteration should be run. It effectively cancels any additional iterations of the loop. However, it does not stop any iterations that have already begun execution. For example, if is called from the 100th iteration of a parallel loop iterating from 0 to 1,000, all iterations less than 100 should still be run, but the iterations from 101 through to 1000 that have not yet started are not executed. - For long-running iterations that may already be executing, sets the property to the current iteration's index if the current index is less than the current value of . To stop iterations whose index is greater than the lowest break iteration from competing execution, you should do the following: + For long-running iterations that may already be executing, sets the property to the current iteration's index if the current index is less than the current value of . To stop iterations whose index is greater than the lowest break iteration from competing execution, you should do the following: 1. Check whether the property is `true`. @@ -137,17 +137,17 @@ The example provides an illustration. - is typically employed in search-based algorithms where an ordering is present in the data source. + is typically employed in search-based algorithms where an ordering is present in the data source. ## Examples - The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. As the output from the example shows, no iterations whose index is greater than the property value start after the call to the method. + The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. As the output from the example shows, no iterations whose index is greater than the property value start after the call to the method. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Parallel/For/break1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Parallel/For/break1.vb" id="Snippet2"::: - Because iterations of the loop are still likely to be executing when the method is called, each iteration calls the property to check whether another iteration has called the method. If the property value is `true`, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. + Because iterations of the loop are still likely to be executing when the method is called, each iteration calls the property to check whether another iteration has called the method. If the property value is `true`, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. ]]> @@ -241,12 +241,12 @@ property to determine whether any iterations of the loop that began execution before the call to the method are still executing. You can then use the value of the property to determine whether they should return immediately or execute normally. + For long-running iterations of the loop, you can retrieve the value of the property to determine whether any iterations of the loop that began execution before the call to the method are still executing. You can then use the value of the property to determine whether they should return immediately or execute normally. ## Examples - The following example executes up to 10,000 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. Because iterations of the loop are still likely to be executing when the method is called, the lambda expression calls the method to check whether another iteration has called the method. If it returns `true`, the iteration returns immediately. + The following example executes up to 10,000 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. Because iterations of the loop are still likely to be executing when the method is called, the lambda expression calls the method to check whether another iteration has called the method. If it returns `true`, the iteration returns immediately. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Parallel/For/stop1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Parallel/For/stop1.vb" id="Snippet1"::: @@ -297,9 +297,9 @@ method. If they do, this value is the smallest index of an iteration that called . If no iteration of the loop called , this property returns `null`. Note that the property value is unaffected by calls to the method. + It is possible for multiple iterations of a parallel loop to call the method. If they do, this value is the smallest index of an iteration that called . If no iteration of the loop called , this property returns `null`. Note that the property value is unaffected by calls to the method. - In long-running iterations in which all iterations after the iteration that calls the method need not run, the property is used to terminate iterations that began execution before the call to the method. To stop iterations whose index is greater than the lowest break iteration from competing execution, you should do the following: + In long-running iterations in which all iterations after the iteration that calls the method need not run, the property is used to terminate iterations that began execution before the call to the method. To stop iterations whose index is greater than the lowest break iteration from competing execution, you should do the following: 1. Check whether the property is `true`. @@ -310,12 +310,12 @@ ## Examples - The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. This prevents iterations whose index is greater than the property value from starting after the call to the method, but it does not affect any iterations that have already begun executing. To prevent these from completing, each iteration calls the method to check whether another iteration has called the method. If so, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. + The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. This prevents iterations whose index is greater than the property value from starting after the call to the method, but it does not affect any iterations that have already begun executing. To prevent these from completing, each iteration calls the method to check whether another iteration has called the method. If so, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Parallel/For/break1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Parallel/For/break1.vb" id="Snippet2"::: - Note that, because the value is out of scope outside of the parallel loop, you must assign it to a variable that is visible outside of the loop if you want to preserve its value. + Note that, because the value is out of scope outside of the parallel loop, you must assign it to a variable that is visible outside of the loop if you want to preserve its value. ]]> @@ -368,7 +368,7 @@ ## Remarks The property is set to `true` under any of the following conditions: -- An iteration of the loop calls or . +- An iteration of the loop calls or . - An iteration of the loop throws an exception. @@ -381,7 +381,7 @@ ## Examples - The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. This prevents iterations whose index is greater than the property value from starting after the call to the method, but it does not affect any iterations that have already begun executing. To prevent these from completing, each iteration calls the method to check whether another iteration has called the method. If so, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. + The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. This prevents iterations whose index is greater than the property value from starting after the call to the method, but it does not affect any iterations that have already begun executing. To prevent these from completing, each iteration calls the method to check whether another iteration has called the method. If so, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Parallel/For/break1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Parallel/For/break1.vb" id="Snippet2"::: @@ -435,21 +435,21 @@ method indicates that any iterations of the loop that have not yet started need not be run. It effectively cancels any additional iterations of the loop. However, it does not stop any iterations that have already begun execution. + Calling the method indicates that any iterations of the loop that have not yet started need not be run. It effectively cancels any additional iterations of the loop. However, it does not stop any iterations that have already begun execution. - Calling the method causes the property to return `true` for any iteration of the loop that is still executing. This is particularly useful for long-running iterations, which can check the property and exit early if its value is `true`. + Calling the method causes the property to return `true` for any iteration of the loop that is still executing. This is particularly useful for long-running iterations, which can check the property and exit early if its value is `true`. - is typically employed in search-based algorithms, where once a result is found, no other iterations need be executed. + is typically employed in search-based algorithms, where once a result is found, no other iterations need be executed. ## Examples - The following example executes up to 10,000 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. As the output from the example shows, no iterations execute after the call to the method. + The following example executes up to 10,000 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. As the output from the example shows, no iterations execute after the call to the method. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Parallel/For/stop1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Parallel/For/stop1.vb" id="Snippet1"::: - Because iterations of the loop are still likely to be executing when the method is called, each iteration calls the method to check whether another iteration has called the method. If it returns `true`, the iteration returns immediately. + Because iterations of the loop are still likely to be executing when the method is called, each iteration calls the method to check whether another iteration has called the method. If it returns `true`, the iteration returns immediately. ]]> diff --git a/xml/System.Threading.Tasks/ParallelOptions.xml b/xml/System.Threading.Tasks/ParallelOptions.xml index 5c6c55a9dd6..d7964b5313f 100644 --- a/xml/System.Threading.Tasks/ParallelOptions.xml +++ b/xml/System.Threading.Tasks/ParallelOptions.xml @@ -100,7 +100,7 @@ By default, methods on the class attempt is initialized to -1, signifying that there is no upper bound set on how much parallelism should be employed. is initialized to a non-cancelable token, and is initialized to the default scheduler (TaskScheduler.Default). + This constructor initializes the instance with default values. is initialized to -1, signifying that there is no upper bound set on how much parallelism should be employed. is initialized to a non-cancelable token, and is initialized to the default scheduler (TaskScheduler.Default). All of these defaults may be overwritten using the property set accessors on the instance. @@ -196,15 +196,15 @@ By default, methods on the class attempt property affects the number of concurrent operations run by method calls that are passed this instance. A positive property value limits the number of concurrent operations to the set value. If it is -1, there is no limit on the number of concurrently running operations (with the exception of the method, where -1 means ). + The property affects the number of concurrent operations run by method calls that are passed this instance. A positive property value limits the number of concurrent operations to the set value. If it is -1, there is no limit on the number of concurrently running operations (with the exception of the method, where -1 means ). - By default, and will utilize however many threads the underlying scheduler provides, so changing from the default only limits how many concurrent tasks will be used. + By default, and will utilize however many threads the underlying scheduler provides, so changing from the default only limits how many concurrent tasks will be used. Generally, you do not need to modify this setting. However, you may choose to set it explicitly in advanced usage scenarios such as these: - When you know that a particular algorithm you're using won't scale beyond a certain number of cores. You can set the property to avoid wasting cycles on additional cores. -- When you're running multiple algorithms concurrently and want to manually define how much of the system each algorithm can utilize. You can set a value for each. +- When you're running multiple algorithms concurrently and want to manually define how much of the system each algorithm can utilize. You can set a value for each. - When the thread pool's heuristics is unable to determine the right number of threads to use and could end up injecting too many threads. For example, in long-running loop body iterations, the thread pool might not be able to tell the difference between reasonable progress or livelock or deadlock, and might not be able to reclaim threads that were added to improve performance. In this case, you can set the property to ensure that you don't use more than a reasonable number of threads. diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index 28d853e7c1c..bac63e0168b 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -153,18 +153,18 @@ ## Remarks This constructor should only be used in advanced scenarios where it is required that the creation and starting of the task is separated. - Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static or method. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static or method. - If a task with no action is needed just for the consumer of an API to have something to await, a should be used. + If a task with no action is needed just for the consumer of an API to have something to await, a should be used. ## Examples - The following example uses the constructor to create tasks that retrieve the filenames in specified directories. All tasks write the file names to a single object. The example then calls the method to ensure that all tasks have completed, and then displays a count of the total number of file names written to the object. + The following example uses the constructor to create tasks that retrieve the filenames in specified directories. All tasks write the file names to a single object. The example then calls the method to ensure that all tasks have completed, and then displays a count of the total number of file names written to the object. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/ctor1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/ctor1.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Task/.ctor/ctor1.vb" id="Snippet1"::: - The following example is identical, except that it used the method to instantiate and run the task in a single operation. The method returns the object that represents the task. + The following example is identical, except that it used the method to instantiate and run the task in a single operation. The method returns the object that represents the task. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run2.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run2.fs" id="Snippet1"::: @@ -224,12 +224,12 @@ object and launch a task is by calling the static and methods. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static and methods. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. For more information, see [Task Parallelism (Task Parallel Library)](/dotnet/standard/parallel-programming/task-based-asynchronous-programming) and [Cancellation in Managed Threads](/dotnet/standard/threading/cancellation-in-managed-threads). ## Examples - The following example calls the constructor to create a task that iterates the files in the C:\Windows\System32 directory. The lambda expression calls the method to add information about each file to a object. Each detached nested task invoked by the loop checks the state of the cancellation token and, if cancellation is requested, calls the method. The method throws an exception that is handled in a `catch` block when the calling thread calls the method. The method is then called to start the task. + The following example calls the constructor to create a task that iterates the files in the C:\Windows\System32 directory. The lambda expression calls the method to add information about each file to a object. Each detached nested task invoked by the loop checks the state of the cancellation token and, if cancellation is requested, calls the method. The method throws an exception that is handled in a `catch` block when the calling thread calls the method. The method is then called to start the task. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run4.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run4.fs" id="Snippet4"::: @@ -289,7 +289,7 @@ object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -353,10 +353,10 @@ object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ## Examples - The following example defines an array of 6-letter words. Each word is then passed as an argument to the constructor, whose delegate scrambles the characters in the word, then displays the original word and its scrambled version. + The following example defines an array of 6-letter words. Each word is then passed as an argument to the constructor, whose delegate scrambles the characters in the word, then displays the original word and its scrambled version. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/startnew3.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/startnew3.fs" id="Snippet3"::: @@ -418,7 +418,7 @@ object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. For more information, see [Task Parallelism (Task Parallel Library)](/dotnet/standard/parallel-programming/task-based-asynchronous-programming) and [Task Cancellation](/dotnet/standard/parallel-programming/task-cancellation). @@ -487,7 +487,7 @@ object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -553,7 +553,7 @@ object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -621,7 +621,7 @@ object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -738,7 +738,7 @@ To retrieve the object's data, cast it back to the original type. property is set to . To create a task that returns a value and runs to completion, call the method. + This property returns a task whose property is set to . To create a task that returns a value and runs to completion, call the method. Repeated attempts to retrieve this property value may not always return the same instance. @@ -915,7 +915,7 @@ When an asynchronous method awaits a directly ## Examples - The following example defines a task that populates an array with 100 random date and time values. It uses the method to select the earliest and the latest date values once the array is fully populated. + The following example defines a task that populates an array with 100 random date and time values. It uses the method to select the earliest and the latest date values once the array is fully populated. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/ContinueWith/continuewith1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/ContinueWith/continuewith1.fs" id="Snippet1"::: @@ -1119,7 +1119,7 @@ When an asynchronous method awaits a directly The returned will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. ## Examples - The following example demonstrates using to specify that a continuation task should run synchronously when the antecedent task completes. (If the specified task has already completed by the time is called, the synchronous continuation will run on the thread calling .) + The following example demonstrates using to specify that a continuation task should run synchronously when the antecedent task completes. (If the specified task has already completed by the time is called, the synchronous continuation will run on the thread calling .) ```csharp public class TaskCounter @@ -1705,7 +1705,7 @@ End Sub will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + The returned will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. @@ -1786,7 +1786,7 @@ End Sub will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + The returned will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. ]]> @@ -1856,7 +1856,7 @@ End Sub will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + The returned will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. ]]> @@ -1931,7 +1931,7 @@ End Sub will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. + The returned will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. ]]> @@ -2003,7 +2003,7 @@ End Sub will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + The returned will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. ]]> @@ -2081,7 +2081,7 @@ End Sub will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + The returned will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. ]]> @@ -2155,7 +2155,7 @@ End Sub will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. + The returned will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. ]]> @@ -2243,7 +2243,7 @@ End Sub will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + The returned will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. ]]> @@ -2317,7 +2317,7 @@ End Sub will not be scheduled for execution until the current task has completed. If the criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. + The returned will not be scheduled for execution until the current task has completed. If the criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. ## Examples The following example shows how to use the ContinueWith method with continuation options: @@ -2425,7 +2425,7 @@ End Sub will not be scheduled for execution until the current task has completed. If the criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. + The returned will not be scheduled for execution until the current task has completed. If the criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. ]]> @@ -2525,7 +2525,7 @@ End Sub is a `static` (`Shared` in Visual Basic) property that is used to get the identifier of the currently executing task from the code that the task is executing. It differs from the property, which returns the identifier of a particular instance. If you attempt to retrieve the value from outside the code that a task is executing, the property returns `null`. + is a `static` (`Shared` in Visual Basic) property that is used to get the identifier of the currently executing task from the code that the task is executing. It differs from the property, which returns the identifier of a particular instance. If you attempt to retrieve the value from outside the code that a task is executing, the property returns `null`. Note that although collisions are very rare, task identifiers are not guaranteed to be unique. @@ -2594,7 +2594,7 @@ End Sub method is typically used to delay the operation of all or part of a task for a specified time interval. Most commonly, the time delay is introduced: + The method is typically used to delay the operation of all or part of a task for a specified time interval. Most commonly, the time delay is introduced: - At the beginning of the task, as the following example shows. @@ -2602,7 +2602,7 @@ End Sub :::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. +- 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"::: @@ -2618,7 +2618,7 @@ End Sub ## Examples - The following example shows a simple use of the method. + The following example shows a simple use of the method. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay1.fs" id="Snippet1"::: @@ -2681,7 +2681,7 @@ End Sub ## Remarks After the specified time delay, the task is completed in state. - For usage scenarios and additional examples, see the documentation for the overload. + For usage scenarios and additional examples, see the documentation for the overload. This method depends on the system clock. This means that the time delay will approximately equal the resolution of the system clock if the `delay` argument is less than the resolution of the system clock, which is approximately 15 milliseconds on Windows systems. @@ -2691,7 +2691,7 @@ End Sub ## Examples - The following example shows a simple use of the method. + The following example shows a simple use of the method. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay2.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay2.fs" id="Snippet2"::: @@ -2761,7 +2761,7 @@ End Sub ## Remarks If the cancellation token is signaled before the specified time delay, a exception results, and the task is completed in the state. Otherwise, the task is completed in the state once the specified time delay has elapsed. - For usage scenarios and additional examples, see the documentation for the overload. + For usage scenarios and additional examples, see the documentation for the overload. This method depends on the system clock. This means that the time delay will approximately equal the resolution of the system clock if the `millisecondsDelay` argument is less than the resolution of the system clock, which is approximately 15 milliseconds on Windows systems. @@ -2769,7 +2769,7 @@ End Sub > 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). ## Examples - The following example launches a task that includes a call to the method with a one second delay. Before the delay interval elapses, the token is cancelled. The output from the example shows that, as a result, a is thrown, and the tasks' property is set to . + The following example launches a task that includes a call to the method with a one second delay. Before the delay interval elapses, the token is cancelled. The output from the example shows that, as a result, a is thrown, and the tasks' property is set to . :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay3.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay3.fs" id="Snippet3"::: @@ -2837,7 +2837,7 @@ End Sub ## Remarks If the cancellation token is signaled before the specified time delay, a exception results, and the task is completed in the state. Otherwise, the task is completed in the state once the specified time delay has elapsed. - For usage scenarios and additional examples, see the documentation for the overload. + For usage scenarios and additional examples, see the documentation for the overload. This method depends on the system clock. This means that the time delay will approximately equal the resolution of the system clock if the `delay` argument is less than the resolution of the system clock, which is approximately 15 milliseconds on Windows systems. @@ -2847,13 +2847,13 @@ End Sub ## Examples - The following example launches a task that includes a call to the method with a 1.5 second delay. Before the delay interval elapses, the token is cancelled. The output from the example shows that, as a result, a is thrown, and the tasks' property is set to . + The following example launches a task that includes a call to the method with a 1.5 second delay. Before the delay interval elapses, the token is cancelled. The output from the example shows that, as a result, a is thrown, and the tasks' property is set to . :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay4.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay4.fs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Task/Delay/delay4.vb" id="Snippet4"::: - Note that this example includes a potential race condition: it depends on the task asynchronously executing the delay when the token is cancelled. Although the 1.5 second delay from the call to the method makes that assumption likely, it is nevertheless possible that the call to the method could return before the token is cancelled. In that case, the example produces the following output: + Note that this example includes a potential race condition: it depends on the task asynchronously executing the delay when the token is cancelled. Although the 1.5 second delay from the call to the method makes that assumption likely, it is nevertheless possible that the call to the method could return before the token is cancelled. In that case, the example produces the following output: ```txt Task t Status: RanToCompletion, Result: 42 @@ -3026,7 +3026,7 @@ Task t Status: RanToCompletion, Result: 42 class implements the interface because internally it uses resources that also implement . However, particularly if your app targets .NET Framework 4.5 or later, there is no need to call unless performance or scalability testing indicates that, based on your usage patterns, your app's performance would be improved by disposing of tasks. For more information, see [Do I need to dispose of Tasks?](https://devblogs.microsoft.com/pfxteam/do-i-need-to-dispose-of-tasks/) in the Parallel Programming with .NET blog. + The class implements the interface because internally it uses resources that also implement . However, particularly if your app targets .NET Framework 4.5 or later, there is no need to call unless performance or scalability testing indicates that, based on your usage patterns, your app's performance would be improved by disposing of tasks. For more information, see [Do I need to dispose of Tasks?](https://devblogs.microsoft.com/pfxteam/do-i-need-to-dispose-of-tasks/) in the Parallel Programming with .NET blog. ]]> @@ -3080,7 +3080,7 @@ Task t Status: RanToCompletion, Result: 42 class implements the interface because internally it uses resources that also implement . However, particularly if your app targets .NET Framework 4.5 or later, there is no need to call unless performance or scalability testing indicates that, based on your usage patterns, your app's performance would be improved by disposing of tasks. For more information, see [Do I need to dispose of Tasks?](https://devblogs.microsoft.com/pfxteam/do-i-need-to-dispose-of-tasks/) in the Parallel Programming with .NET blog. + The class implements the interface because internally it uses resources that also implement . However, particularly if your app targets .NET Framework 4.5 or later, there is no need to call unless performance or scalability testing indicates that, based on your usage patterns, your app's performance would be improved by disposing of tasks. For more information, see [Do I need to dispose of Tasks?](https://devblogs.microsoft.com/pfxteam/do-i-need-to-dispose-of-tasks/) in the Parallel Programming with .NET blog. ]]> @@ -3141,7 +3141,7 @@ Task t Status: RanToCompletion, Result: 42 in calls to or in accesses to the property. On .NET Framework 4.0, any exceptions not observed by the time the task instance is garbage collected will be propagated on the finalizer thread, which crashes the process. On .NET Framework 4.5 and later the default behavior changed so unobserved exceptions are not rethrown from the Finalizer. .NET Core does not rethrow the exception on the Finalizer. For more information and an example, see [Exception Handling (Task Parallel Library)](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). + Tasks that throw unhandled exceptions store the resulting exception and propagate it wrapped in a in calls to or in accesses to the property. On .NET Framework 4.0, any exceptions not observed by the time the task instance is garbage collected will be propagated on the finalizer thread, which crashes the process. On .NET Framework 4.5 and later the default behavior changed so unobserved exceptions are not rethrown from the Finalizer. .NET Core does not rethrow the exception on the Finalizer. For more information and an example, see [Exception Handling (Task Parallel Library)](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). ]]> @@ -3197,17 +3197,17 @@ Task t Status: RanToCompletion, Result: 42 |Property|Value| |--------------|-----------| -||| -||| -||| -||`null`, or | +||| +||| +||| +||`null`, or | - The most common use of this property is to create and start a new task in a single call to the method. + The most common use of this property is to create and start a new task in a single call to the method. > [!NOTE] -> Starting with .NET Framework 4.5, the method provides the easiest way to create a object with default configuration values. +> Starting with .NET Framework 4.5, the method provides the easiest way to create a object with default configuration values. - The following example uses the static property to make two calls to the method. The first populates an array with the names of files in the user's MyDocuments directory, while the second populates an array with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the two arrays after the first two tasks have completed execution. + The following example uses the static property to make two calls to the method. The first populates an array with the names of files in the user's MyDocuments directory, while the second populates an array with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the two arrays after the first two tasks have completed execution. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Factory/factory1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Factory/factory1.fs" id="Snippet1"::: @@ -3376,7 +3376,7 @@ Task t Status: RanToCompletion, Result: 42 object whose property is and whose property contains `exception`. The method is commonly used when you immediately know that the work that a task performs will throw an exception before executing a longer code path. For an example, see the overload. + This method creates a object whose property is and whose property contains `exception`. The method is commonly used when you immediately know that the work that a task performs will throw an exception before executing a longer code path. For an example, see the overload. ]]> @@ -3442,12 +3442,12 @@ Task t Status: RanToCompletion, Result: 42 object whose property is and whose property contains `exception`. The method is commonly used when you immediately know that the work that a task performs will throw an exception before executing a longer code path. The example provides an illustration. + This method creates a object whose property is and whose property contains `exception`. The method is commonly used when you immediately know that the work that a task performs will throw an exception before executing a longer code path. The example provides an illustration. ## Examples - The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. Rather than executing a longer code path that instantiates a object and retrieves the value of its property for each file in the directory, the example simply calls the method to create a faulted task if a particular subdirectory does not exist. + The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. Rather than executing a longer code path that instantiates a object and retrieves the value of its property for each file in the directory, the example simply calls the method to create a faulted task if a particular subdirectory does not exist. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.fs" id="Snippet1"::: @@ -3519,14 +3519,14 @@ Task t Status: RanToCompletion, Result: 42 ## Remarks -This method creates a object whose property is `result` and whose property is . The method is commonly used when the return value of a task is immediately known without executing a longer code path. The example provides an illustration. +This method creates a object whose property is `result` and whose property is . The method is commonly used when the return value of a task is immediately known without executing a longer code path. The example provides an illustration. To create a `Task` object that does not return a value, retrieve the `Task` object from the property. Starting in .NET 6, for some `TResult` types and some result values, this method may return a cached singleton object rather than allocating a new object. ## Examples - The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. Rather than executing a longer code path that instantiates a object and retrieves the value of its property for each file in the directory, the example simply calls the method to create a task whose property is zero (0) if a directory has no files. + The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. Rather than executing a longer code path that instantiates a object and retrieves the value of its property for each file in the directory, the example simply calls the method to create a task whose property is zero (0) if a directory has no files. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.fs" id="Snippet1"::: @@ -3701,11 +3701,11 @@ This method is intended for compiler use rather than use directly in code. ## Remarks A will complete in the state under any of the following conditions: -- Its was marked for cancellation before the task started executing, +- Its was marked for cancellation before the task started executing, -- The task acknowledged the cancellation request on its already signaled by throwing an that bears the same . +- The task acknowledged the cancellation request on its already signaled by throwing an that bears the same . -- The task acknowledged the cancellation request on its already signaled by calling the method on the . +- The task acknowledged the cancellation request on its already signaled by calling the method on the . > [!IMPORTANT] > Retrieving the value of the property does not block the calling thread until the task has completed. @@ -3876,7 +3876,7 @@ This method is intended for compiler use rather than use directly in code. is `true`, the task's is equal to , and its property will be non-null. + If is `true`, the task's is equal to , and its property will be non-null. > [!IMPORTANT] > Retrieving the value of the property does not block the calling thread until the task has completed. @@ -3897,7 +3897,7 @@ This method is intended for compiler use rather than use directly in code. method provides a set of overloads that make it easy to start a task by using default values. It is a lightweight alternative to the overloads. + The method provides a set of overloads that make it easy to start a task by using default values. It is a lightweight alternative to the overloads. ]]> @@ -3953,9 +3953,9 @@ This method is intended for compiler use rather than use directly in code. method allows you to create and execute a task in a single method call and is a simpler alternative to the method. It creates a task with the following default values: + The method allows you to create and execute a task in a single method call and is a simpler alternative to the method. It creates a task with the following default values: -- Its cancellation token is . +- Its cancellation token is . - Its property value is . @@ -3966,7 +3966,7 @@ This method is intended for compiler use rather than use directly in code. ## Examples - The following example defines a `ShowThreadInfo` method that displays the of the current thread. It is called directly from the application thread, and is called from the delegate passed to the method. + The following example defines a `ShowThreadInfo` method that displays the of the current thread. It is called directly from the application thread, and is called from the delegate passed to the method. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/Run11.cs" id="Snippet11"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/Run11.fs" id="Snippet11"::: @@ -3980,9 +3980,9 @@ This method is intended for compiler use rather than use directly in code. The examples show that the asynchronous task executes on a different thread than the main application thread. - The call to the method ensures that the task completes and displays its output before the application ends. Otherwise, it is possible that the `Main` method will complete before the task finishes. + The call to the method ensures that the task completes and displays its output before the application ends. Otherwise, it is possible that the `Main` method will complete before the task finishes. - The following example illustrates the method. It defines an array of directory names and starts a separate task to retrieve the file names in each directory. All tasks write the file names to a single object. The example then calls the method to ensure that all tasks have completed, and then displays a count of the total number of file names written to the object. + The following example illustrates the method. It defines an array of directory names and starts a separate task to retrieve the file names in each directory. All tasks write the file names to a single object. The example then calls the method to ensure that all tasks have completed, and then displays a count of the total number of file names written to the object. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run2.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run2.fs" id="Snippet1"::: @@ -4114,7 +4114,7 @@ This method is intended for compiler use rather than use directly in code. ## Remarks If cancellation is requested before the task begins execution, the task does not execute. Instead it is set to the state and throws a exception. - The method is a simpler alternative to the method. It creates a task with the following default values: + The method is a simpler alternative to the method. It creates a task with the following default values: - Its property value is . @@ -4125,7 +4125,7 @@ This method is intended for compiler use rather than use directly in code. ## Examples - The following example calls the method to create a task that iterates the files in the C:\Windows\System32 directory. The lambda expression calls the method to add information about each file to a object. Each detached nested task invoked by the loop checks the state of the cancellation token and, if cancellation is requested, calls the method. The method throws an exception that is handled in a `catch` block when the calling thread calls the method. + The following example calls the method to create a task that iterates the files in the C:\Windows\System32 directory. The lambda expression calls the method to add information about each file to a object. Each detached nested task invoked by the loop checks the state of the cancellation token and, if cancellation is requested, calls the method. The method throws an exception that is handled in a `catch` block when the calling thread calls the method. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run41.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run41.fs" id="Snippet4"::: @@ -4350,9 +4350,9 @@ This method is intended for compiler use rather than use directly in code. method is a simpler alternative to the method. It creates a task with the following default values: + The method is a simpler alternative to the method. It creates a task with the following default values: -- Its cancellation token is . +- Its cancellation token is . - Its property value is . @@ -4363,7 +4363,7 @@ This method is intended for compiler use rather than use directly in code. ## Examples - The following example counts the approximate number of words in text files that represent published books. Each task is responsible for opening a file, reading its entire contents asynchronously, and calculating the word count by using a regular expression. The method is called to ensure that all tasks have completed before displaying the word count of each book to the console. + The following example counts the approximate number of words in text files that represent published books. Each task is responsible for opening a file, reading its entire contents asynchronously, and calculating the word count by using a regular expression. The method is called to ensure that all tasks have completed before displaying the word count of each book to the console. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run31.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run31.fs" id="Snippet2"::: @@ -4525,7 +4525,7 @@ This method is intended for compiler use rather than use directly in code. ## Remarks If cancellation is requested before the task begins execution, the task does not execute. Instead it is set to the state and throws a exception. - The method is a simpler alternative to the method. It creates a task with the following default values: + The method is a simpler alternative to the method. It creates a task with the following default values: - Its property value is . @@ -4618,14 +4618,14 @@ This method is intended for compiler use rather than use directly in code. method are associated with the current and are run on the calling thread. If the target scheduler does not support running this task on the calling thread, the task will be scheduled for execution on the scheduler, and the calling thread will block until the task has completed execution. Even though the task runs synchronously, the calling thread should still call to handle any exceptions that the task might throw. For more information on exception handling, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). + Ordinarily, tasks are executed asynchronously on a thread pool thread and do not block the calling thread. Tasks executed by calling the method are associated with the current and are run on the calling thread. If the target scheduler does not support running this task on the calling thread, the task will be scheduled for execution on the scheduler, and the calling thread will block until the task has completed execution. Even though the task runs synchronously, the calling thread should still call to handle any exceptions that the task might throw. For more information on exception handling, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). - Tasks executed by calling the method are instantiated by calling a or class constructor. The task to be run synchronously must be in the state. A task may be started and run only once. Any attempts to schedule a task a second time results in an exception. + Tasks executed by calling the method are instantiated by calling a or class constructor. The task to be run synchronously must be in the state. A task may be started and run only once. Any attempts to schedule a task a second time results in an exception. ## Examples - The following example compares a task executed by calling the method with one executed asynchronously. In both cases, the tasks execute identical lambda expressions that display the task ID and the ID of the thread on which the task is running. The task calculates the sum of the integers between 1 and 1,000,000. As the output from the example shows, the task executed by calling the method runs on the application thread, while the asynchronous task does not. + The following example compares a task executed by calling the method with one executed asynchronously. In both cases, the tasks execute identical lambda expressions that display the task ID and the ID of the thread on which the task is running. The task calculates the sum of the integers between 1 and 1,000,000. As the output from the example shows, the task executed by calling the method runs on the application thread, while the asynchronous task does not. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/RunSynchronously/runsynchronously1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/RunSynchronously/runsynchronously1.fs" id="Snippet1"::: @@ -4687,9 +4687,9 @@ This method is intended for compiler use rather than use directly in code. method are instantiated by calling a or class constructor. The task to be run synchronously must be in the state. A task may be started and run only once. Any attempts to schedule a task a second time results in an exception. + Tasks executed by calling the method are instantiated by calling a or class constructor. The task to be run synchronously must be in the state. A task may be started and run only once. Any attempts to schedule a task a second time results in an exception. - If the target scheduler does not support running this task on the current thread, the task will be scheduled for execution on the scheduler, and the current thread will block until the task has completed execution. Because of this, the calling thread does not need to call a method such as to ensure that the task has completed execution. For more information on exception handling for task operations, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). + If the target scheduler does not support running this task on the current thread, the task will be scheduled for execution on the scheduler, and the current thread will block until the task has completed execution. Because of this, the calling thread does not need to call a method such as to ensure that the task has completed execution. For more information on exception handling for task operations, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). ]]> @@ -4758,14 +4758,14 @@ This method is intended for compiler use rather than use directly in code. ## Remarks A task may be started and run only once. Any attempts to schedule a task a second time will result in an exception. - The is used to execute a task that has been created by calling one of the constructors. Typically, you do this when you need to separate the task's creation from its execution, such as when you conditionally execute tasks that you've created. For the more common case in which you don't need to separate task instantiation from execution, we recommend that you call an overload of the or method. + The is used to execute a task that has been created by calling one of the constructors. Typically, you do this when you need to separate the task's creation from its execution, such as when you conditionally execute tasks that you've created. For the more common case in which you don't need to separate task instantiation from execution, we recommend that you call an overload of the or method. For information on handling exceptions thrown by task operations, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). ## Examples - The following example calls the constructor to instantiate a new object that displays its task ID and managed thread ID and then executes a loop. It then calls the method to execute the task. Since this is a console app, the call to the method is necessary to prevent the app from terminating before the task finishes execution. + The following example calls the constructor to instantiate a new object that displays its task ID and managed thread ID and then executes a loop. It then calls the method to execute the task. Since this is a console app, the call to the method is necessary to prevent the app from terminating before the task finishes execution. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Start/Start1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Start/Start1.fs" id="Snippet1"::: @@ -4952,7 +4952,7 @@ This method is intended for compiler use rather than use directly in code. is preferable to using for similar functionality. For more information, see the "Waiting on Tasks" section in [Task-based Asynchronous Programming](/dotnet/standard/parallel-programming/task-based-asynchronous-programming) and [Using TPL with Other Asynchronous Patterns](/dotnet/standard/parallel-programming/using-tpl-with-other-asynchronous-patterns). + Using the wait functionality provided by is preferable to using for similar functionality. For more information, see the "Waiting on Tasks" section in [Task-based Asynchronous Programming](/dotnet/standard/parallel-programming/task-based-asynchronous-programming) and [Using TPL with Other Asynchronous Patterns](/dotnet/standard/parallel-programming/using-tpl-with-other-asynchronous-patterns). ]]> @@ -5072,10 +5072,10 @@ This member is an explicit interface member implementation. It can be used only is a synchronization method that causes the calling thread to wait until the current task has completed. If the current task has not started execution, the Wait method attempts to remove the task from the scheduler and execute it inline on the current thread. If it is unable to do that, or if the current task has already started execution, it blocks the calling thread until the task completes. For more information, see [Task.Wait and "Inlining"](https://devblogs.microsoft.com/pfxteam/task-wait-and-inlining/) in the Parallel Programming with .NET blog. + is a synchronization method that causes the calling thread to wait until the current task has completed. If the current task has not started execution, the Wait method attempts to remove the task from the scheduler and execute it inline on the current thread. If it is unable to do that, or if the current task has already started execution, it blocks the calling thread until the task completes. For more information, see [Task.Wait and "Inlining"](https://devblogs.microsoft.com/pfxteam/task-wait-and-inlining/) in the Parallel Programming with .NET blog. ## Examples - The following example starts a task that generates one million random integers between 0 and 100 and computes their mean. The example uses the method to ensure that the task completes before the application terminates. Otherwise, because this is a console application, the example would terminate before the task can compute and display the mean. + The following example starts a task that generates one million random integers between 0 and 100 and computes their mean. The example uses the method to ensure that the task completes before the application terminates. Otherwise, because this is a console application, the example would terminate before the task can compute and display the mean. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Wait/wait1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Wait/wait1.fs" id="Snippet1"::: @@ -5143,7 +5143,7 @@ This member is an explicit interface member implementation. It can be used only is a synchronization method that causes the calling thread to wait for the current task instance to complete until one of the following occurs: + is a synchronization method that causes the calling thread to wait for the current task instance to complete until one of the following occurs: - The task completes successfully. @@ -5154,7 +5154,7 @@ This member is an explicit interface member implementation. It can be used only ## Examples - The following example starts a task that generates five million random integers between 0 and 100 and computes their mean. The example uses the method to wait for the application to complete within 150 milliseconds. If the application completes normally, the task displays the sum and mean of the random numbers that it has generated. If the timeout interval has elapsed, the example displays a message before it terminates. + The following example starts a task that generates five million random integers between 0 and 100 and computes their mean. The example uses the method to wait for the application to complete within 150 milliseconds. If the application completes normally, the task displays the sum and mean of the random numbers that it has generated. If the timeout interval has elapsed, the example displays a message before it terminates. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Wait/Wait5.cs" id="Snippet5"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Wait/Wait5.fs" id="Snippet5"::: @@ -5221,17 +5221,17 @@ This member is an explicit interface member implementation. It can be used only method creates a cancelable wait; that is, it causes the current thread to wait until one of the following occurs: + The method creates a cancelable wait; that is, it causes the current thread to wait until one of the following occurs: - The task completes. -- The cancellation token is canceled. In this case, the call to the method throws an . +- The cancellation token is canceled. In this case, the call to the method throws an . > [!NOTE] > Canceling the `cancellationToken` cancellation token has no effect on the running task unless it has also been passed the cancellation token and is prepared to handle cancellation. Passing the `cancellationToken` object to this method simply allows the wait to be canceled. ## Examples - The following example illustrates the simple use of a cancellation token to cancel waiting for a task's completion. A task is launched, calls the method to cancel any of the token source's cancellation tokens, and then delays for five seconds. Note that the task itself has not been passed the cancellation token and is not cancelable. The application thread calls the task's method to wait for the task to complete, but the wait is canceled once the cancellation token is cancelled and an is thrown. The exception handler reports the exception and then sleeps for six seconds. As the output from the example shows, that delay allows the task to complete in the state. + The following example illustrates the simple use of a cancellation token to cancel waiting for a task's completion. A task is launched, calls the method to cancel any of the token source's cancellation tokens, and then delays for five seconds. Note that the task itself has not been passed the cancellation token and is not cancelable. The application thread calls the task's method to wait for the task to complete, but the wait is canceled once the cancellation token is cancelled and an is thrown. The exception handler reports the exception and then sleeps for six seconds. As the output from the example shows, that delay allows the task to complete in the state. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Wait/wait3.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Wait/wait3.fs" id="Snippet3"::: @@ -5299,7 +5299,7 @@ This member is an explicit interface member implementation. It can be used only is a synchronization method that causes the calling thread to wait for the current task instance to complete until one of the following occurs: + is a synchronization method that causes the calling thread to wait for the current task instance to complete until one of the following occurs: - The task completes successfully. @@ -5310,7 +5310,7 @@ This member is an explicit interface member implementation. It can be used only ## Examples - The following example starts a task that generates five million random integers between 0 and 100 and computes their mean. The example uses the method to wait for the application to complete within 150 milliseconds. If the application completes normally, the task displays the sum and mean of the random numbers that it has generated. If the timeout interval has elapsed, the example displays a message before it terminates. + The following example starts a task that generates five million random integers between 0 and 100 and computes their mean. The example uses the method to wait for the application to complete within 150 milliseconds. If the application completes normally, the task displays the sum and mean of the random numbers that it has generated. If the timeout interval has elapsed, the example displays a message before it terminates. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Wait/Wait6.cs" id="Snippet6"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Wait/Wait6.fs" id="Snippet6"::: @@ -5385,13 +5385,13 @@ This member is an explicit interface member implementation. It can be used only is a synchronization method that causes the calling thread to wait for the current task instance to complete until one of the following occurs: + is a synchronization method that causes the calling thread to wait for the current task instance to complete until one of the following occurs: - The task completes successfully. - The task itself is canceled or throws an exception. In this case, you handle an exception. The property contains details about the exception or exceptions. -- The `cancellationToken` cancellation token is canceled. In this case, the call to the method throws an . +- The `cancellationToken` cancellation token is canceled. In this case, the call to the method throws an . - The interval defined by `millisecondsTimeout` elapses. In this case, the current thread resumes execution and the method returns `false`. @@ -5401,7 +5401,7 @@ This member is an explicit interface member implementation. It can be used only ## Examples - The following example calls the method to provide both a timeout value and a cancellation token that can end the wait for a task's completion. A new thread is started and executes the `CancelToken` method, which pauses and then calls the method to cancel the cancellation tokens. A task is then launched and delays for 5 seconds. The method is then called to wait for the task's completion and is provided both a brief timeout value and a cancellation token. + The following example calls the method to provide both a timeout value and a cancellation token that can end the wait for a task's completion. A new thread is started and executes the `CancelToken` method, which pauses and then calls the method to cancel the cancellation tokens. A task is then launched and delays for 5 seconds. The method is then called to wait for the task's completion and is provided both a brief timeout value and a cancellation token. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Wait/wait4.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Wait/wait4.fs" id="Snippet4"::: @@ -5612,7 +5612,7 @@ An exception was thrown during method wraps all exceptions in an object and propagates it to the calling thread. + The following example starts 10 tasks, each of which is passed an index as a state object. Tasks with an index from two to five throw exceptions. The call to the method wraps all exceptions in an object and propagates it to the calling thread. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Overview/waitall.cs" id="Snippet02"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Overview/waitall.fs" id="Snippet02"::: @@ -6035,7 +6035,7 @@ An exception was thrown during method then waits for any of the tasks to complete. The example displays the task ID of the task that ended the wait, as well as the current status of all the tasks. + The following example launches five tasks, each of which sleeps for a minimum of 50 milliseconds or a maximum of 1,050 milliseconds. The method then waits for any of the tasks to complete. The example displays the task ID of the task that ended the wait, as well as the current status of all the tasks. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/WaitAny/WaitAny1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/WaitAny/WaitAny1.fs" id="Snippet1"::: @@ -6542,10 +6542,10 @@ An exception was thrown during method that return a object are typically called when you are interested in the status of a set of tasks or in the exceptions thrown by a set of tasks. + The overloads of the method that return a object are typically called when you are interested in the status of a set of tasks or in the exceptions thrown by a set of tasks. > [!NOTE] -> The call to method does not block the calling thread. +> The call to method does not block the calling thread. If any of the supplied tasks completes in a faulted state, the returned task will also complete in a state, where its exceptions will contain the aggregation of the set of unwrapped exceptions from each of the supplied tasks. @@ -6558,7 +6558,7 @@ An exception was thrown during ## Examples - The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. + The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/WhenAll/WhenAll4.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/WhenAll/WhenAll4.fs" id="Snippet4"::: @@ -6688,10 +6688,10 @@ An exception was thrown during method that return a object are typically called when you are interested in the status of a set of tasks or in the exceptions thrown by a set of tasks. + The overloads of the method that return a object are typically called when you are interested in the status of a set of tasks or in the exceptions thrown by a set of tasks. > [!NOTE] -> The call to method does not block the calling thread. +> The call to method does not block the calling thread. If any of the supplied tasks completes in a faulted state, the returned task will also complete in a state, where its exceptions will contain the aggregation of the set of unwrapped exceptions from each of the supplied tasks. @@ -6704,7 +6704,7 @@ An exception was thrown during ## Examples - The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is converted to an array and passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. + The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is converted to an array and passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/WhenAll/WhenAll3.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/WhenAll/WhenAll3.fs" id="Snippet3"::: @@ -6777,26 +6777,26 @@ An exception was thrown during method does not block the calling thread. However, a call to the returned property does block the calling thread. + The call to method does not block the calling thread. However, a call to the returned property does block the calling thread. If any of the supplied tasks completes in a faulted state, the returned task will also complete in a state, where its exceptions will contain the aggregation of the set of unwrapped exceptions from each of the supplied tasks. If none of the supplied tasks faulted but at least one of them was canceled, the returned task will end in the state. - If none of the tasks faulted and none of the tasks were canceled, the resulting task will end in the state. The property of the returned task will be set to an array containing all of the results of the supplied tasks in the same order as they were provided (e.g. if the input tasks array contained t1, t2, t3, the output task's property will return an `TResult[]` where `arr[0] == t1.Result, arr[1] == t2.Result, and arr[2] == t3.Result)`. + If none of the tasks faulted and none of the tasks were canceled, the resulting task will end in the state. The property of the returned task will be set to an array containing all of the results of the supplied tasks in the same order as they were provided (e.g. if the input tasks array contained t1, t2, t3, the output task's property will return an `TResult[]` where `arr[0] == t1.Result, arr[1] == t2.Result, and arr[2] == t3.Result)`. If the `tasks` argument contains no tasks, the returned task will immediately transition to a state before it's returned to the caller. The returned `TResult[]` will be an array of 0 elements. ## Examples - The following example creates ten tasks, each of which instantiates a random number generator that creates 1,000 random numbers between 1 and 1,000 and computes their mean. The method is used to delay instantiation of the random number generators so that they are not created with identical seed values. The call to the method then returns an array that contains the mean computed by each task. These are then used to calculate the overall mean. + The following example creates ten tasks, each of which instantiates a random number generator that creates 1,000 random numbers between 1 and 1,000 and computes their mean. The method is used to delay instantiation of the random number generators so that they are not created with identical seed values. The call to the method then returns an array that contains the mean computed by each task. These are then used to calculate the overall mean. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/WhenAll/whenall1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/WhenAll/whenall1.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Task/WhenAll/whenall1.vb" id="Snippet1"::: - In this case, the ten individual tasks are stored in a object. implements the interface. + In this case, the ten individual tasks are stored in a object. implements the interface. ]]> @@ -6945,20 +6945,20 @@ An exception was thrown during method does not block the calling thread. However, a call to the returned property does block the calling thread. + The call to method does not block the calling thread. However, a call to the returned property does block the calling thread. If any of the supplied tasks completes in a faulted state, the returned task will also complete in a state, where its exceptions will contain the aggregation of the set of unwrapped exceptions from each of the supplied tasks. If none of the supplied tasks faulted but at least one of them was canceled, the returned task will end in the state. - If none of the tasks faulted and none of the tasks were canceled, the resulting task will end in the state. The of the returned task will be set to an array containing all of the results of the supplied tasks in the same order as they were provided (e.g. if the input tasks array contained t1, t2, t3, the output task's will return an `TResult[]` where `arr[0] == t1.Result, arr[1] == t2.Result, and arr[2] == t3.Result)`. + If none of the tasks faulted and none of the tasks were canceled, the resulting task will end in the state. The of the returned task will be set to an array containing all of the results of the supplied tasks in the same order as they were provided (e.g. if the input tasks array contained t1, t2, t3, the output task's will return an `TResult[]` where `arr[0] == t1.Result, arr[1] == t2.Result, and arr[2] == t3.Result)`. If the supplied array/enumerable contains no tasks, the returned task will immediately transition to a state before it's returned to the caller. The returned `TResult[]` will be an array of 0 elements. ## Examples - The following example creates ten tasks, each of which instantiates a random number generator that creates 1,000 random numbers between 1 and 1,000 and computes their mean. In this case, the ten individual tasks are stored in a `Task` array. The method is used to delay instantiation of the random number generators so that they are not created with identical seed values. The call to the method then returns an array that contains the mean computed by each task. These are then used to calculate the overall mean. + The following example creates ten tasks, each of which instantiates a random number generator that creates 1,000 random numbers between 1 and 1,000 and computes their mean. In this case, the ten individual tasks are stored in a `Task` array. The method is used to delay instantiation of the random number generators so that they are not created with identical seed values. The call to the method then returns an array that contains the mean computed by each task. These are then used to calculate the overall mean. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/WhenAll/whenall2.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/WhenAll/whenall2.fs" id="Snippet2"::: diff --git a/xml/System.Threading.Tasks/TaskCanceledException.xml b/xml/System.Threading.Tasks/TaskCanceledException.xml index 51d0668e4c6..24d7e19e6f3 100644 --- a/xml/System.Threading.Tasks/TaskCanceledException.xml +++ b/xml/System.Threading.Tasks/TaskCanceledException.xml @@ -133,8 +133,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The localized error message string.| +||`null`.| +||The localized error message string.| ]]> @@ -195,8 +195,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| ]]> @@ -378,8 +378,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| ]]> diff --git a/xml/System.Threading.Tasks/TaskCompletionSource`1.xml b/xml/System.Threading.Tasks/TaskCompletionSource`1.xml index 6d263d57094..04c9d41c1ad 100644 --- a/xml/System.Threading.Tasks/TaskCompletionSource`1.xml +++ b/xml/System.Threading.Tasks/TaskCompletionSource`1.xml @@ -78,11 +78,11 @@ ## Remarks - In many scenarios, it's useful to enable a to represent an external asynchronous operation. is provided for this purpose. It enables the creation of a task that can be handed out to consumers. The consumers can use the members of the task the same way as they would in any other scenario handling task member variables. However, unlike most tasks, the state of a task created by a TaskCompletionSource is controlled explicitly by the methods on TaskCompletionSource. This enables the completion of the external asynchronous operation to be propagated to the underlying Task. The separation also ensures that consumers are not able to transition the state without access to the corresponding TaskCompletionSource. For more information, see the entry [The Nature of TaskCompletionSource\](https://devblogs.microsoft.com/pfxteam/the-nature-of-taskcompletionsourcetresult/) in the Parallel Programming with .NET blog. + In many scenarios, it's useful to enable a to represent an external asynchronous operation. is provided for this purpose. It enables the creation of a task that can be handed out to consumers. The consumers can use the members of the task the same way as they would in any other scenario handling task member variables. However, unlike most tasks, the state of a task created by a TaskCompletionSource is controlled explicitly by the methods on TaskCompletionSource. This enables the completion of the external asynchronous operation to be propagated to the underlying Task. The separation also ensures that consumers are not able to transition the state without access to the corresponding TaskCompletionSource. For more information, see the entry [The Nature of TaskCompletionSource\](https://devblogs.microsoft.com/pfxteam/the-nature-of-taskcompletionsourcetresult/) in the Parallel Programming with .NET blog. ## Examples - The following example shows how to use a : + The following example shows how to use a : :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskCompletionSourceTResult/Overview/taskcompletionsource.cs" id="Snippet01"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/TaskCompletionSourceTResult/Overview/taskcompletionsource.vb" id="Snippet01"::: @@ -242,7 +242,7 @@ created by this instance and accessible through its property will be instantiated using the specified `creationOptions`. + The created by this instance and accessible through its property will be instantiated using the specified `creationOptions`. ]]> @@ -651,9 +651,9 @@ that is controlled by this instance. When you create a object, the property of this object returns + This property enables a consumer to access the that is controlled by this instance. When you create a object, the property of this object returns - The , , , and methods (and their "Try" variants) on this instance all result in the relevant state transitions on this underlying Task. + The , , , and methods (and their "Try" variants) on this instance all result in the relevant state transitions on this underlying Task. ]]> @@ -721,9 +721,9 @@ is already in one of the three final states: , , or . + This operation will return false if the is already in one of the three final states: , , or . - This method also returns false if the underlying has already been disposed. + This method also returns false if the underlying has already been disposed. ]]> @@ -782,7 +782,7 @@ object is already in one of the following three final states. + The method returns false if the underlying object is already in one of the following three final states. - @@ -790,7 +790,7 @@ - - This method also returns `false` if the underlying object has already been disposed. + This method also returns `false` if the underlying object has already been disposed. ]]> @@ -858,7 +858,7 @@ is already in one of the three final states: , , or . + This operation will return false if the is already in one of the three final states: , , or . ]]> @@ -924,7 +924,7 @@ is already in one of the three final states: , , or . + This operation will return false if the is already in one of the three final states: , , or . ]]> @@ -1027,9 +1027,9 @@ is already in one of the three final states: , , or . + This operation will return false if the is already in one of the three final states: , , or . - This method also returns false if the underlying has already been disposed. + This method also returns false if the underlying has already been disposed. ]]> diff --git a/xml/System.Threading.Tasks/TaskCreationOptions.xml b/xml/System.Threading.Tasks/TaskCreationOptions.xml index e30399c1ada..42f68a52d00 100644 --- a/xml/System.Threading.Tasks/TaskCreationOptions.xml +++ b/xml/System.Threading.Tasks/TaskCreationOptions.xml @@ -75,15 +75,15 @@ ## Remarks The enumeration is used with the following methods: -- The and constructors with a `creationOptions` parameter, to specify the default options for tasks created by the task factory. +- The and constructors with a `creationOptions` parameter, to specify the default options for tasks created by the task factory. -- The and constructors with a `creationOptions` parameter, to specify the options used to customize the task's behavior. +- The and constructors with a `creationOptions` parameter, to specify the options used to customize the task's behavior. -- The and methods with a `creationOptions` parameter, to specify the options used to customize the task's behavior. +- The and methods with a `creationOptions` parameter, to specify the options used to customize the task's behavior. -- The and methods with a `creationOptions` parameter, to specify the options used to customize the behavior of the task that executes an end method when a specified completes. +- The and methods with a `creationOptions` parameter, to specify the options used to customize the behavior of the task that executes an end method when a specified completes. -- The constructors with a `creationOptions` parameter, to specify the options used to customize the behavior of the underlying task. +- The constructors with a `creationOptions` parameter, to specify the options used to customize the behavior of the underlying task. ]]> diff --git a/xml/System.Threading.Tasks/TaskExtensions.xml b/xml/System.Threading.Tasks/TaskExtensions.xml index 6682b36dcf9..a875aa8d2c1 100644 --- a/xml/System.Threading.Tasks/TaskExtensions.xml +++ b/xml/System.Threading.Tasks/TaskExtensions.xml @@ -117,19 +117,19 @@ Creates a proxy that represents the asynchronous operation of a (C#) or (Visual Basic). A Task that represents the asynchronous operation of the provided . - , where the inner Task represents work done as part of the outer . However, doing so results in a `Task` (C#) or `Task (Of Task)` (Visual Basic), which, if not dealt with carefully, could produce unexpected behavior. Unwrap solves this problem by creating a proxy Task that represents the entire asynchronous operation of such a task. - - - -## Examples - The following example shows how to unwrap a task: - + , where the inner Task represents work done as part of the outer . However, doing so results in a `Task` (C#) or `Task (Of Task)` (Visual Basic), which, if not dealt with carefully, could produce unexpected behavior. Unwrap solves this problem by creating a proxy Task that represents the entire asynchronous operation of such a task. + + + +## Examples + The following example shows how to unwrap a task: + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskExtensions/Unwrap/unwrap.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/TaskExtensions/Unwrap/unwrap.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/TaskExtensions/Unwrap/unwrap.vb" id="Snippet01"::: + ]]> The exception that is thrown if the argument is null. @@ -196,11 +196,11 @@ Creates a proxy that represents the asynchronous operation of a (C#) or (Visual Basic). A that represents the asynchronous operation of the provided (C#) or (Visual Basic). - from a , where the inner represents work done as part of the outer . However, doing so results in a `Task>` (C#) or `Task (Of Task(Of T))` (Visual Basic), which, if not dealt with carefully, could produce unexpected behavior. Unwrap solves this problem by creating a proxy that represents the entire asynchronous operation of such a `Task>` (C#) or `Task (Of Task(Of T))` (Visual Basic). - + from a , where the inner represents work done as part of the outer . However, doing so results in a `Task>` (C#) or `Task (Of Task(Of T))` (Visual Basic), which, if not dealt with carefully, could produce unexpected behavior. Unwrap solves this problem by creating a proxy that represents the entire asynchronous operation of such a `Task>` (C#) or `Task (Of Task(Of T))` (Visual Basic). + ]]> The exception that is thrown if the argument is null. diff --git a/xml/System.Threading.Tasks/TaskFactory.xml b/xml/System.Threading.Tasks/TaskFactory.xml index d9edc18fb8f..ee1c50fd607 100644 --- a/xml/System.Threading.Tasks/TaskFactory.xml +++ b/xml/System.Threading.Tasks/TaskFactory.xml @@ -72,25 +72,25 @@ .NET provides two factories for creating and scheduling tasks: -- The class, which creates and objects. You can call the overloads of this method to create and execute a task that requires non-default arguments. +- The class, which creates and objects. You can call the overloads of this method to create and execute a task that requires non-default arguments. > [!WARNING] - > Starting with .NET Framework 4.5, the method provides the easiest way to create a task with default configuration values and start it immediately. + > Starting with .NET Framework 4.5, the method provides the easiest way to create a task with default configuration values and start it immediately. -- The class, which creates objects. +- The class, which creates objects. The class allows you to do the following: -- Create a task and start it immediately by calling the method. +- Create a task and start it immediately by calling the method. > [!WARNING] - > Starting with .NET Framework 4.5, the method provides the easiest way to create a task with default configuration values and start it immediately. + > Starting with .NET Framework 4.5, the method provides the easiest way to create a task with default configuration values and start it immediately. -- Create a task that starts when any one of the tasks in an array has completed by calling the method. +- Create a task that starts when any one of the tasks in an array has completed by calling the method. -- Create a task that starts when all the tasks in an array have completed by calling the method. +- Create a task that starts when all the tasks in an array have completed by calling the method. - The static property returns a default object. You can also call one of the class constructors to configure the objects that the class creates. The following example configures a new object to create tasks that have a specified cancellation token, task creation options, continuation options, and a customized task scheduler. + The static property returns a default object. You can also call one of the class constructors to configure the objects that the class creates. The following example configures a new object to create tasks that have a specified cancellation token, task creation options, continuation options, and a customized task scheduler. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskFactory/Overview/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl_factories/vb/factories_vb.vb" id="Snippet1"::: @@ -98,7 +98,7 @@ In most cases, you do not have to instantiate a new instance. Instead, you can use the property, which returns a factory object that uses default values. You can then call its methods to start new tasks or define task continuations. For an illustration, see the example. ## Examples - The following example uses the static property to make two calls to the method. The first populates an array with the names of files in the user's MyDocuments directory, while the second populates an array with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the two arrays after the first two tasks have completed execution. + The following example uses the static property to make two calls to the method. The first populates an array with the names of files in the user's MyDocuments directory, while the second populates an array with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the two arrays after the first two tasks have completed execution. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Factory/factory1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Task/Factory/factory1.vb" id="Snippet1"::: @@ -163,7 +163,7 @@ instance with a default configuration. The property is initialized to , the property is initialized to , and the property is initialized to the current scheduler (see ). + This constructor creates a instance with a default configuration. The property is initialized to , the property is initialized to , and the property is initialized to the current scheduler (see ). ]]> @@ -216,7 +216,7 @@ instance with a default configuration. The property is initialized to , the property is initialized to , and the property is initialized to the current scheduler (see ). + This constructor creates a instance with a default configuration. The property is initialized to , the property is initialized to , and the property is initialized to the current scheduler (see ). ]]> @@ -271,7 +271,7 @@ property is initialized to , the property is initialized to , and the property is initialized to `scheduler`, unless it's null, in which case the property is initialized to the current scheduler (see ). + With this constructor, the property is initialized to , the property is initialized to , and the property is initialized to `scheduler`, unless it's null, in which case the property is initialized to the current scheduler (see ). ]]> @@ -328,7 +328,7 @@ property is initialized to `creationOptions`, the property is initialized to `continuationOptions`, and the property is initialized to the current scheduler (see ). + With this constructor, the property is initialized to `creationOptions`, the property is initialized to `continuationOptions`, and the property is initialized to the current scheduler (see ). ]]> @@ -394,7 +394,7 @@ property is initialized to `creationOptions`, the property is initialized to `continuationOptions`, and the property is initialized to `scheduler`, unless it's null, in which case the property is initialized to the current scheduler (see ). + With this constructor, the property is initialized to `creationOptions`, the property is initialized to `continuationOptions`, and the property is initialized to `scheduler`, unless it's null, in which case the property is initialized to the current scheduler (see ). ]]> @@ -579,19 +579,19 @@ method executes the `continuationAction` delegate when all tasks in the `tasks` array have completed, regardless of their completion status. + The method executes the `continuationAction` delegate when all tasks in the `tasks` array have completed, regardless of their completion status. - Exceptions thrown by tasks in the `tasks` array are not available to the continuation task through structured exception handling. You can determine which exceptions were thrown by examining the property of each task in the `tasks` array. To use structured exception handling to handle exceptions thrown by tasks in the `tasks` array, call the method. + Exceptions thrown by tasks in the `tasks` array are not available to the continuation task through structured exception handling. You can determine which exceptions were thrown by examining the property of each task in the `tasks` array. To use structured exception handling to handle exceptions thrown by tasks in the `tasks` array, call the method. ## Examples - The following example launches separate tasks that use a regular expression to count the number of words in a set of text files. The method is used to launch a task that displays the total word count when all the antecedent tasks have completed. + The following example launches separate tasks that use a regular expression to count the number of words in a set of text files. The method is used to launch a task that displays the total word count when all the antecedent tasks have completed. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskFactory/ContinueWhenAll/continuewhenall1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/TaskFactory/ContinueWhenAll/continuewhenall1.vb" id="Snippet1"::: - The call to the continuation task's method does not allow it to handle exceptions thrown by the antecedent tasks, so the example examines the property of each antecedent task to determine whether the task succeeded. + The call to the continuation task's method does not allow it to handle exceptions thrown by the antecedent tasks, so the example examines the property of each antecedent task to determine whether the task succeeded. ]]> @@ -3354,7 +3354,7 @@ The NotOn\* and OnlyOn\* , ## Remarks > [!TIP] -> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. +> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. ]]> @@ -3437,7 +3437,7 @@ The NotOn\* and OnlyOn\* , is running on. This method throws any exceptions thrown by the `beginMethod`. + The `beginMethod` delegate is started on the thread that is running on. This method throws any exceptions thrown by the `beginMethod`. ]]> @@ -3507,7 +3507,7 @@ The NotOn\* and OnlyOn\* , ## Remarks > [!TIP] -> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. +> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. ]]> @@ -3593,7 +3593,7 @@ The NotOn\* and OnlyOn\* , is running on. This method throws any exceptions thrown by the `beginMethod`. The values , and are all mutually exclusive. In the FromAsync methods, either `LongRunning` or `AttachedToParent` by themselves will cause an to be thrown. + The `beginMethod` delegate is started on the thread that is running on. This method throws any exceptions thrown by the `beginMethod`. The values , and are all mutually exclusive. In the FromAsync methods, either `LongRunning` or `AttachedToParent` by themselves will cause an to be thrown. ]]> @@ -3667,7 +3667,7 @@ The NotOn\* and OnlyOn\* , ## Remarks > [!TIP] -> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. +> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. ]]> @@ -3769,7 +3769,7 @@ The NotOn\* and OnlyOn\* , is running on. This method throws any exceptions thrown by the `beginMethod`. + The `beginMethod` delegate is started on the thread that is running on. This method throws any exceptions thrown by the `beginMethod`. ]]> @@ -3867,7 +3867,7 @@ The NotOn\* and OnlyOn\* , is running on. This method throws any exceptions thrown by the `beginMethod`. + The `beginMethod` delegate is started on the thread that is running on. This method throws any exceptions thrown by the `beginMethod`. ]]> @@ -3948,7 +3948,7 @@ The NotOn\* and OnlyOn\* , ## Remarks > [!TIP] -> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. +> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. ]]> @@ -4124,7 +4124,7 @@ The NotOn\* and OnlyOn\* , ## Remarks > [!TIP] -> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. +> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. ]]> @@ -4307,7 +4307,7 @@ The NotOn\* and OnlyOn\* , ## Remarks > [!TIP] -> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. +> The overloads that take an `asyncResult` parameter are not as efficient as the overloads that take a `beginMethod` parameter. If performance is an issue, use the overloads that provide the `beginMethod`/`endMethod` pattern. ]]> @@ -4420,7 +4420,7 @@ The NotOn\* and OnlyOn\* , is running on. This method throws any exceptions thrown by the `beginMethod`. + The `beginMethod` delegate is started on the thread that is running on. This method throws any exceptions thrown by the `beginMethod`. ]]> @@ -4529,7 +4529,7 @@ The NotOn\* and OnlyOn\* , is running on. This method throws any exceptions thrown by the `beginMethod`. + The `beginMethod` delegate is started on the thread that is running on. This method throws any exceptions thrown by the `beginMethod`. ]]> @@ -4636,7 +4636,7 @@ The NotOn\* and OnlyOn\* , is running on. This method throws any exceptions thrown by the `beginMethod`. + The `beginMethod` delegate is started on the thread that is running on. This method throws any exceptions thrown by the `beginMethod`. ]]> @@ -4743,7 +4743,7 @@ The NotOn\* and OnlyOn\* , is running on. This method throws any exceptions thrown by the `beginMethod`. + The `beginMethod` delegate is started on the thread that is running on. This method throws any exceptions thrown by the `beginMethod`. ]]> @@ -4863,7 +4863,7 @@ The NotOn\* and OnlyOn\* , is running on. This method throws any exceptions thrown by the `beginMethod`. + The `beginMethod` delegate is started on the thread that is running on. This method throws any exceptions thrown by the `beginMethod`. ]]> @@ -4983,7 +4983,7 @@ The NotOn\* and OnlyOn\* , is running on. This method throws any exceptions thrown by the `beginMethod`. + The `beginMethod` delegate is started on the thread that is running on. This method throws any exceptions thrown by the `beginMethod`. ]]> @@ -5101,7 +5101,7 @@ The NotOn\* and OnlyOn\* , is running on. This method throws any exceptions thrown by the `beginMethod`. + The `beginMethod` delegate is started on the thread that is running on. This method throws any exceptions thrown by the `beginMethod`. ]]> @@ -5219,7 +5219,7 @@ The NotOn\* and OnlyOn\* , is running on. This method throws any exceptions thrown by the `beginMethod`. + The `beginMethod` delegate is started on the thread that is running on. This method throws any exceptions thrown by the `beginMethod`. ]]> @@ -5348,7 +5348,7 @@ The NotOn\* and OnlyOn\* , is running on. This method throws any exceptions thrown by the `beginMethod`. + The `beginMethod` delegate is started on the thread that is running on. This method throws any exceptions thrown by the `beginMethod`. ]]> @@ -5477,7 +5477,7 @@ The NotOn\* and OnlyOn\* , is running on. This method throws any exceptions thrown by the `beginMethod`. + The `beginMethod` delegate is started on the thread that is running on. This method throws any exceptions thrown by the `beginMethod`. ]]> @@ -5568,13 +5568,13 @@ The NotOn\* and OnlyOn\* , method is the recommended way to launch a compute-bound task. Use the method only when you require fine-grained control for a long-running, compute-bound task. This includes scenarios in which you want to control the following: + Starting with the .NET Framework 4.5, the method is the recommended way to launch a compute-bound task. Use the method only when you require fine-grained control for a long-running, compute-bound task. This includes scenarios in which you want to control the following: -- Task creation options. Tasks created by the method by default are created with the option. To override this behavior, or to provide other options, call a overload. +- Task creation options. Tasks created by the method by default are created with the option. To override this behavior, or to provide other options, call a overload. -- Parameter passing. The overloads of the method do not allow you to pass a parameter to the task delegate. Overloads of the method do. +- Parameter passing. The overloads of the method do not allow you to pass a parameter to the task delegate. Overloads of the method do. -- The task scheduler. The overloads of the method use the default task scheduler. To control the task scheduler, call a overload with a `scheduler` parameter. For more information, see . +- The task scheduler. The overloads of the method use the default task scheduler. To control the task scheduler, call a overload with a `scheduler` parameter. For more information, see . ]]> @@ -5631,14 +5631,14 @@ The NotOn\* and OnlyOn\* , is functionally equivalent to creating a task by using one of its constructors, and then calling the method to schedule the task for execution. + Calling is functionally equivalent to creating a task by using one of its constructors, and then calling the method to schedule the task for execution. - Starting with the .NET Framework 4.5, you can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + Starting with the .NET Framework 4.5, you can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ## Examples - The following example uses the method to repeatedly invoke an delegate that generates a random number, interprets it as a Unicode code point, converts it to a UTF16-encoded code unit, and displays information about the resulting character or characters. + The following example uses the method to repeatedly invoke an delegate that generates a random number, interprets it as a Unicode code point, converts it to a UTF16-encoded code unit, and displays information about the resulting character or characters. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskFactory/StartNew/startnew1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/TaskFactory/StartNew/startnew1.vb" id="Snippet1"::: @@ -5703,14 +5703,14 @@ The NotOn\* and OnlyOn\* , to schedule it for execution. + Calling `StartNew` is functionally equivalent to creating a Task using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + Starting with the .NET Framework 4.5, you can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ## Examples - The following example calls the method to create a task that iterates the files in the C:\Windows\System32 directory. The lambda expression calls the method to add information about each file to a object. Each detached nested task invoked by the loop checks the state of the cancellation token and, if cancellation is requested, calls the method. The method throws an exception that is handled in a `catch` block when the calling thread calls the method. + The following example calls the method to create a task that iterates the files in the C:\Windows\System32 directory. The lambda expression calls the method to add information about each file to a object. Each detached nested task invoked by the loop checks the state of the cancellation token and, if cancellation is requested, calls the method. The method throws an exception that is handled in a `catch` block when the calling thread calls the method. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskFactory/StartNew/startnew2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/TaskFactory/StartNew/startnew2.vb" id="Snippet2"::: @@ -5777,9 +5777,9 @@ The NotOn\* and OnlyOn\* , to schedule it for execution. + Calling StartNew is functionally equivalent to creating a Task using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> @@ -5859,14 +5859,14 @@ The NotOn\* and OnlyOn\* , is functionally equivalent to creating a using one of its constructors and then calling the method to schedule it for execution. + Calling is functionally equivalent to creating a using one of its constructors and then calling the method to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ## Examples - The following example defines an array of 6-letter words. Each word is then passed to an delegate, which scrambles the word and displays the original word and its scrambled version. + The following example defines an array of 6-letter words. Each word is then passed to an delegate, which scrambles the word and displays the original word and its scrambled version. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskFactory/StartNew/startnew3.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/TaskFactory/StartNew/startnew3.vb" id="Snippet3"::: @@ -5950,19 +5950,19 @@ The NotOn\* and OnlyOn\* , to schedule it for execution. + Calling StartNew is functionally equivalent to creating a Task using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ## Examples - The following example defines an array of 6-letter words. Each word is then passed to an delegate, which scrambles the word and displays the original word and its scrambled version. + The following example defines an array of 6-letter words. Each word is then passed to an delegate, which scrambles the word and displays the original word and its scrambled version. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskFactory/StartNew/startnew4.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/TaskFactory/StartNew/startnew4.vb" id="Snippet4"::: - Note that the example initializes a single random number generator, which is protected by a lock. For the need of a lock, see "The System.Random class and thread safety" in the class topic. To handle the possibility of corruption of the random number generator, a cancellation token is passed to task. If two random numbers equal zero, the method assumes that the random number generator is corrupted and sets the cancellation token. Before sorting the `chars` array that contains the six characters in a word, the method calls the method to throw an if the token has been canceled. + Note that the example initializes a single random number generator, which is protected by a lock. For the need of a lock, see "The System.Random class and thread safety" in the class topic. To handle the possibility of corruption of the random number generator, a cancellation token is passed to task. If two random numbers equal zero, the method assumes that the random number generator is corrupted and sets the cancellation token. Before sorting the `chars` array that contains the six characters in a word, the method calls the method to throw an if the token has been canceled. ]]> @@ -6043,9 +6043,9 @@ The NotOn\* and OnlyOn\* , to schedule it for execution. + Calling StartNew is functionally equivalent to creating a Task using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> @@ -6114,9 +6114,9 @@ The NotOn\* and OnlyOn\* , to schedule it for execution. + Calling StartNew is functionally equivalent to creating a Task using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> @@ -6207,9 +6207,9 @@ The NotOn\* and OnlyOn\* , to schedule it for execution. + Calling StartNew is functionally equivalent to creating a Task using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> @@ -6288,14 +6288,14 @@ The NotOn\* and OnlyOn\* , is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. + Calling is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can call the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + Starting with the .NET Framework 4.5, you can call the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ## Examples - The following example is a simple addition app that generates two random numbers and prompts the user to enter their sum. It then indicates whether the answer is correct or, if the user's response is not a valid number, prompts the user to re-enter a valid number. The is used to create the objects that return the random numbers to add. + The following example is a simple addition app that generates two random numbers and prompts the user to enter their sum. It then indicates whether the answer is correct or, if the user's response is not a valid number, prompts the user to re-enter a valid number. The is used to create the objects that return the random numbers to add. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run5.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Task/.ctor/run5.vb" id="Snippet5"::: @@ -6372,9 +6372,9 @@ The NotOn\* and OnlyOn\* , using one of its constructors and then calling to schedule it for execution. + Calling StartNew is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> @@ -6448,9 +6448,9 @@ The NotOn\* and OnlyOn\* , is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. + Calling is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + Starting with the .NET Framework 4.5, you can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. @@ -6533,9 +6533,9 @@ The NotOn\* and OnlyOn\* , using one of its constructors and then calling to schedule it for execution. + Calling StartNew is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> @@ -6614,9 +6614,9 @@ The NotOn\* and OnlyOn\* , using one of its constructors and then calling to schedule it for execution. + Calling StartNew is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> @@ -6694,9 +6694,9 @@ The NotOn\* and OnlyOn\* , using one of its constructors and then calling to schedule it for execution. + Calling StartNew is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> @@ -6776,9 +6776,9 @@ The NotOn\* and OnlyOn\* , using one of its constructors and then calling to schedule it for execution. + Calling StartNew is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> @@ -6880,9 +6880,9 @@ The NotOn\* and OnlyOn\* , using one of its constructors and then calling to schedule it for execution. + Calling StartNew is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> diff --git a/xml/System.Threading.Tasks/TaskFactory`1.xml b/xml/System.Threading.Tasks/TaskFactory`1.xml index d0a5f6a2663..2660b7d3ac4 100644 --- a/xml/System.Threading.Tasks/TaskFactory`1.xml +++ b/xml/System.Threading.Tasks/TaskFactory`1.xml @@ -83,30 +83,30 @@ .NET provides two factories for creating and scheduling tasks: -- The class, which creates and objects. +- The class, which creates and objects. -- The class, which creates objects. +- The class, which creates objects. - The class allows you to do the following: + The class allows you to do the following: -- Create a task and start it immediately by calling the method. You can call the overloads of this method to create and execute a task that requires non-default arguments. +- Create a task and start it immediately by calling the method. You can call the overloads of this method to create and execute a task that requires non-default arguments. > [!WARNING] - > Starting with .NET Framework 4.5, the method provides the easiest way to create a task with default configuration values and start it immediately. + > Starting with .NET Framework 4.5, the method provides the easiest way to create a task with default configuration values and start it immediately. -- Create a task that starts when any one of the tasks in an array has completed by calling the or method. +- Create a task that starts when any one of the tasks in an array has completed by calling the or method. -- Create a task that starts when all the tasks in an array have completed by calling the or method. +- Create a task that starts when all the tasks in an array have completed by calling the or method. - The static property returns a default object. You can also call one of the class constructors to configure the objects that the class creates. The following example configures a new object to create tasks that have a specified cancellation token, task creation options, continuation options, and a customized task scheduler. + The static property returns a default object. You can also call one of the class constructors to configure the objects that the class creates. The following example configures a new object to create tasks that have a specified cancellation token, task creation options, continuation options, and a customized task scheduler. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskFactory`1/Overview/factoriestresult.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl_factories/vb/factoriestresult.vb" id="Snippet2"::: - In most cases, you do not have to instantiate a new instance. Instead, you can use the static property, which returns a factory object that uses default values. You can then call its methods to start new tasks or define task continuations. For an illustration, see the example. + In most cases, you do not have to instantiate a new instance. Instead, you can use the static property, which returns a factory object that uses default values. You can then call its methods to start new tasks or define task continuations. For an illustration, see the example. ## Examples - The following example uses the static property to make two calls to the method. The first task returns a string array that is populated with the names of files in the user's MyDocuments directory, while the second returns a string array that is populated with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the arrays returned by the two tasks after they have completed execution. + The following example uses the static property to make two calls to the method. The first task returns a string array that is populated with the names of files in the user's MyDocuments directory, while the second returns a string array that is populated with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the arrays returned by the two tasks after they have completed execution. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Factory/factory2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Task/Factory/factory2.vb" id="Snippet2"::: @@ -170,7 +170,7 @@ instance with a default configuration. The property is initialized to , the property is initialized to , and the property is initialized to the current scheduler (see ). + This constructor creates a instance with a default configuration. The property is initialized to , the property is initialized to , and the property is initialized to the current scheduler (see ). ]]> @@ -223,7 +223,7 @@ instance with a default configuration. The property is initialized to , the property is initialized to , and the property is initialized to the current scheduler (see ). + This constructor creates a instance with a default configuration. The property is initialized to , the property is initialized to , and the property is initialized to the current scheduler (see ). ]]> @@ -277,7 +277,7 @@ property is initialized to , the property is initialized to , and the property is initialized to `scheduler`, unless it's `null`, in which case the property is initialized to the current scheduler (see ). + With this constructor, the property is initialized to , the property is initialized to , and the property is initialized to `scheduler`, unless it's `null`, in which case the property is initialized to the current scheduler (see ). ]]> @@ -335,7 +335,7 @@ property is initialized to `creationOptions`, the property is initialized to `continuationOptions`, and the property is initialized to the current scheduler (see ). + With this constructor, the property is initialized to `creationOptions`, the property is initialized to `continuationOptions`, and the property is initialized to the current scheduler (see ). ]]> @@ -399,7 +399,7 @@ property is initialized to `creationOptions`, the property is initialized to `continuationOptions`, and the property is initialized to `scheduler`, unless it's `null`, in which case the property is initialized to the current scheduler (see ). + With this constructor, the property is initialized to `creationOptions`, the property is initialized to `continuationOptions`, and the property is initialized to `scheduler`, unless it's `null`, in which case the property is initialized to the current scheduler (see ). ]]> @@ -2966,7 +2966,7 @@ ## Remarks This property returns the default scheduler for this factory. It will be used to schedule all tasks unless another scheduler is explicitly specified during calls to this factory's methods. - If this property returns `null`, will be used. + If this property returns `null`, will be used. ]]> @@ -3036,7 +3036,7 @@ constructors, and then calling the method to schedule it for execution. + Calling `StartNew` is functionally equivalent to creating a task by using one of the constructors, and then calling the method to schedule it for execution. However, unless creation and scheduling must be separated, `StartNew` is the recommended approach for both simplicity and performance. @@ -3114,7 +3114,7 @@ constructors and then calling the method to schedule it for execution. + Calling `StartNew` is functionally equivalent to creating a task by using one of the constructors and then calling the method to schedule it for execution. However, unless creation and scheduling must be separated, `StartNew` is the recommended approach for both simplicity and performance. @@ -3177,7 +3177,7 @@ constructors and then calling the method to schedule it for execution. + Calling `StartNew` is functionally equivalent to creating a task by using one of the constructors and then calling the method to schedule it for execution. However, unless creation and scheduling must be separated, `StartNew` is the recommended approach for both simplicity and performance. @@ -3241,7 +3241,7 @@ constructors and then calling the method to schedule it for execution. + Calling `StartNew` is functionally equivalent to creating a task by using one of the constructors and then calling the method to schedule it for execution. However, unless creation and scheduling must be separated, `StartNew` is the recommended approach for both simplicity and performance. @@ -3322,7 +3322,7 @@ constructors and then calling the method to schedule it for execution. + Calling `StartNew` is functionally equivalent to creating a task by using one of the constructors and then calling the method to schedule it for execution. However, unless creation and scheduling must be separated, `StartNew` is the recommended approach for both simplicity and performance. @@ -3403,7 +3403,7 @@ constructors and then calling the method to schedule it for execution. + Calling `StartNew` is functionally equivalent to creating a task by using one of the constructors and then calling the method to schedule it for execution. However, unless creation and scheduling must be separated, `StartNew` is the recommended approach for both simplicity and performance. @@ -3471,7 +3471,7 @@ constructors and then calling the method to schedule it for execution. + Calling `StartNew` is functionally equivalent to creating a task by using one of the constructors and then calling the method to schedule it for execution. However, unless creation and scheduling must be separated, `StartNew` is the recommended approach for both simplicity and performance. @@ -3561,7 +3561,7 @@ constructors and then calling the method to schedule it for execution. + Calling `StartNew` is functionally equivalent to creating a task by using one of the constructors and then calling the method to schedule it for execution. However, unless creation and scheduling must be separated, `StartNew` is the recommended approach for both simplicity and performance. diff --git a/xml/System.Threading.Tasks/TaskScheduler.xml b/xml/System.Threading.Tasks/TaskScheduler.xml index 57d2fcd2b8f..b02c6e596f9 100644 --- a/xml/System.Threading.Tasks/TaskScheduler.xml +++ b/xml/System.Threading.Tasks/TaskScheduler.xml @@ -176,7 +176,7 @@ The following example creates a custom task scheduler that limits the number of will return the scheduler. + When not called from within a task, will return the scheduler. For more information, see . @@ -317,7 +317,7 @@ The following example creates a custom task scheduler that limits the number of instances queued to the returned scheduler will be executed through a call to the method on that context. + All instances queued to the returned scheduler will be executed through a call to the method on that context. For more information, see . @@ -716,9 +716,9 @@ protected override IEnumerable GetScheduledTasks() instances to be executed through either the method or the method. When the scheduler deems it appropriate to run the provided task, should be used to do so. TryExecuteTask handles all aspects of executing a task, including action invocation, exception handling, state management, and lifecycle control. + Scheduler implementations are provided with instances to be executed through either the method or the method. When the scheduler deems it appropriate to run the provided task, should be used to do so. TryExecuteTask handles all aspects of executing a task, including action invocation, exception handling, state management, and lifecycle control. - must only be used for tasks provided to this scheduler by the .NET Framework infrastructure. It should not be used to execute arbitrary tasks obtained through custom mechanisms. + must only be used for tasks provided to this scheduler by the .NET Framework infrastructure. It should not be used to execute arbitrary tasks obtained through custom mechanisms. ]]> @@ -787,7 +787,7 @@ protected override IEnumerable GetScheduledTasks() ## Remarks A class derived from implements this function to support inline execution of a task on a thread that initiates a wait on that task object. Inline execution is optional, and the request may be rejected by returning false. However, the more tasks that can be inlined, the better the scheduler will scale. In fact, a scheduler that inlines too little may be prone to deadlocks. A proper implementation should ensure that a request executing under the policies guaranteed by the scheduler can successfully inline. For example, if a scheduler uses a dedicated thread to execute tasks, any inlining requests from that thread should succeed. - If a scheduler decides to perform the inline execution, it should do so by calling to the base TaskScheduler's method with the provided task object, propagating the return value. It may also be appropriate for the scheduler to remove an inlined task from its internal data structures if it decides to honor the inlining request. Note, however, that under some circumstances a scheduler may be asked to inline a task that was not previously provided to it with the method. + If a scheduler decides to perform the inline execution, it should do so by calling to the base TaskScheduler's method with the provided task object, propagating the return value. It may also be appropriate for the scheduler to remove an inlined task from its internal data structures if it decides to honor the inlining request. Note, however, that under some circumstances a scheduler may be asked to inline a task that was not previously provided to it with the method. The derived scheduler is responsible for making sure that the calling thread is suitable for executing the given task as far as its own scheduling and execution policies are concerned. diff --git a/xml/System.Threading.Tasks/TaskSchedulerException.xml b/xml/System.Threading.Tasks/TaskSchedulerException.xml index f842b001d07..2c450b28d38 100644 --- a/xml/System.Threading.Tasks/TaskSchedulerException.xml +++ b/xml/System.Threading.Tasks/TaskSchedulerException.xml @@ -132,8 +132,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The localized error message string.| +||`null`.| +||The localized error message string.| ]]> @@ -242,8 +242,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| ]]> @@ -370,8 +370,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| ]]> diff --git a/xml/System.Threading.Tasks/Task`1.xml b/xml/System.Threading.Tasks/Task`1.xml index b5a287df83a..5067521dc9f 100644 --- a/xml/System.Threading.Tasks/Task`1.xml +++ b/xml/System.Threading.Tasks/Task`1.xml @@ -88,25 +88,25 @@ class represents a single operation that returns a value and that usually executes asynchronously. objects are one of the central components of the [task-based asynchronous pattern](https://learn.microsoft.com/dotnet/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap) first introduced in .NET Framework 4. Because the work performed by a object typically executes asynchronously on a thread pool thread rather than synchronously on the main application thread, you can use the property, as well as the , , and properties, to determine the state of a task. Most commonly, a lambda expression is used to specify the work that the task is to perform. + The class represents a single operation that returns a value and that usually executes asynchronously. objects are one of the central components of the [task-based asynchronous pattern](https://learn.microsoft.com/dotnet/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap) first introduced in .NET Framework 4. Because the work performed by a object typically executes asynchronously on a thread pool thread rather than synchronously on the main application thread, you can use the property, as well as the , , and properties, to determine the state of a task. Most commonly, a lambda expression is used to specify the work that the task is to perform. - instances may be created in a variety of ways. The most common approach, which is available starting with .NET Framework 4.5, is to call the static or method. These methods provide a simple way to start a task by using default values and without acquiring additional parameters. The following example uses the method to start a task that loops and then displays the number of loop iterations: + instances may be created in a variety of ways. The most common approach, which is available starting with .NET Framework 4.5, is to call the static or method. These methods provide a simple way to start a task by using default values and without acquiring additional parameters. The following example uses the method to start a task that loops and then displays the number of loop iterations: :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskTResult/Overview/run1.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/TaskTResult/Overview/run1.vb" id="Snippet6"::: - An alternative, and the most common way to start a task in .NET Framework 4, is to call the static or method. The property returns a object, and the property returns a object. Overloads of their `StartNew` method let you pass arguments, define task creation options, and specify a task scheduler. The following example uses the method to start a task. It is functionally equivalent to the code in the previous example. + An alternative, and the most common way to start a task in .NET Framework 4, is to call the static or method. The property returns a object, and the property returns a object. Overloads of their `StartNew` method let you pass arguments, define task creation options, and specify a task scheduler. The following example uses the method to start a task. It is functionally equivalent to the code in the previous example. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskTResult/Overview/startnew1.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/TaskTResult/Overview/startnew1.vb" id="Snippet7"::: For more complete examples, see [Task-based Asynchronous Programming](https://learn.microsoft.com/dotnet/standard/parallel-programming/task-based-asynchronous-programming). - The class also provides constructors that initialize the task but that do not schedule it for execution. For performance reasons, the and `Task.Factory.StartNew` methods are the preferred mechanisms for creating and scheduling computational tasks, but for scenarios where task creation and scheduling must be separated, the constructors may be used, and the task's method may then be used to schedule the task for execution at a later time. + The class also provides constructors that initialize the task but that do not schedule it for execution. For performance reasons, the and `Task.Factory.StartNew` methods are the preferred mechanisms for creating and scheduling computational tasks, but for scenarios where task creation and scheduling must be separated, the constructors may be used, and the task's method may then be used to schedule the task for execution at a later time. Starting with desktop apps that target .NET Framework 4.6, the culture of the thread that creates and invokes a task becomes part of the thread's context. That is, regardless of the current culture of the thread on which the task executes, the current culture of the task is the culture of the calling thread. For apps that target versions of .NET Framework prior to .NET Framework 4.6, the culture of the task is the culture of the thread on which the task executes. For more information, see the "Culture and task-based asynchronous operations" section in the topic. Note that Store apps follow the Windows Runtime in setting and getting the default culture. -For operations that do not return a value, you use the class. Starting with C# 7.0, for a more lightweight task that is a value type rather than a reference type, use the structure. +For operations that do not return a value, you use the class. Starting with C# 7.0, for a more lightweight task that is a value type rather than a reference type, use the structure. ]]> @@ -175,16 +175,16 @@ For operations that do not return a value, you use the object and launch a task is by calling the static and methods. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static and methods. - If a task with no action is needed just for the consumer of an API to have something to await, a should be used. + If a task with no action is needed just for the consumer of an API to have something to await, a should be used. ## Examples - The following example counts the approximate number of words in text files that represent published books. Each task is responsible for opening a file, reading its entire contents asynchronously, and calculating the word count by using a regular expression. The method is called to ensure that all tasks have completed before displaying the word count of each book to the console. + The following example counts the approximate number of words in text files that represent published books. Each task is responsible for opening a file, reading its entire contents asynchronously, and calculating the word count by using a regular expression. The method is called to ensure that all tasks have completed before displaying the word count of each book to the console. - Object instantiation is separated from object execution in this example so that the example can ensure that each file exists. If they do not, it displays the name of the missing file. Otherwise, it calls the method to launch each task. + Object instantiation is separated from object execution in this example so that the example can ensure that each file exists. If they do not, it displays the name of the missing file. Otherwise, it calls the method to launch each task. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run3.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Task/.ctor/run3.vb" id="Snippet2"::: @@ -255,7 +255,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -313,7 +313,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static and methods. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static and methods. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -372,7 +372,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -441,7 +441,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -510,7 +510,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -571,7 +571,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -643,7 +643,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -978,7 +978,7 @@ For operations that do not return a value, you use the object is used to define a timeout value of 100 milliseconds. If the event fires, the method is called, and the cancellation token is used to request cancellation of the tasks. + A cancellation token is passed to both the antecedent and the continuation task. A object is used to define a timeout value of 100 milliseconds. If the event fires, the method is called, and the cancellation token is used to request cancellation of the tasks. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskTResult/ContinueWith/continue1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/TaskTResult/ContinueWith/continue1.vb" id="Snippet1"::: @@ -1584,7 +1584,7 @@ For operations that do not return a value, you use the will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + The returned will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. ]]> @@ -1659,12 +1659,12 @@ For operations that do not return a value, you use the will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + The returned will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. ## Examples - The following example creates a chain of continuation tasks. Each task provides the current time, a object, for the state argument of the method. Each value represents the time at which the continue task is created. Each task produces as its result a second value that represents the time at which the task finishes. After all tasks finish, the example displays the date and times at which each continuation task starts and finishes. + The following example creates a chain of continuation tasks. Each task provides the current time, a object, for the state argument of the method. Each value represents the time at which the continue task is created. Each task produces as its result a second value that represents the time at which the task finishes. After all tasks finish, the example displays the date and times at which each continuation task starts and finishes. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task`1/ContinueWith/continuationstate.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl_continuationstate/vb/continuationstate.vb" id="Snippet1"::: @@ -1738,7 +1738,7 @@ For operations that do not return a value, you use the will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + The returned will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. ]]> @@ -1818,9 +1818,9 @@ For operations that do not return a value, you use the will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + The returned will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - The `continuationFunction`, when executed, should return a . + The `continuationFunction`, when executed, should return a . ]]> @@ -1895,7 +1895,7 @@ For operations that do not return a value, you use the will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + The returned will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. ]]> @@ -1977,7 +1977,7 @@ For operations that do not return a value, you use the will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + The returned will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. ]]> @@ -2052,9 +2052,9 @@ For operations that do not return a value, you use the will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + The returned will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - The `continuationFunction`, when executed, should return a . This task's completion state will be transferred to the task returned from the ContinueWith call. + The `continuationFunction`, when executed, should return a . This task's completion state will be transferred to the task returned from the ContinueWith call. ]]> @@ -2143,7 +2143,7 @@ For operations that do not return a value, you use the will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + The returned will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. ]]> @@ -2220,9 +2220,9 @@ For operations that do not return a value, you use the will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + The returned will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - The `continuationFunction`, when executed, should return a . + The `continuationFunction`, when executed, should return a . ]]> @@ -2326,9 +2326,9 @@ For operations that do not return a value, you use the will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + The returned will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - The `continuationFunction`, when executed, should return a . This task's completion state will be transferred to the task returned from the call. + The `continuationFunction`, when executed, should return a . This task's completion state will be transferred to the task returned from the call. ]]> @@ -2384,21 +2384,21 @@ For operations that do not return a value, you use the class that is identical to the one created by calling the parameterless constructor. It has the following property values: + This property returns a default instance of the class that is identical to the one created by calling the parameterless constructor. It has the following property values: |Property|Value| |--------------|-----------| -||| -||| -||| -||`null`, or | +||| +||| +||| +||`null`, or | - The most common use of this property is to create and start a new task in a single call to the method. + The most common use of this property is to create and start a new task in a single call to the method. > [!NOTE] -> Starting with .NET Framework 4.5, the method provides the easiest way to create a object with default configuration values. +> Starting with .NET Framework 4.5, the method provides the easiest way to create a object with default configuration values. - The following example uses the static property to make three calls to the method. The first starts a `Task` object, which executes a lambda expression that returns 1. The second starts a `Task` object, which executes a lambda expression that instantiates a new `Test` instance. The third starts a `Task` object, which enumerates the files in the C:\Users\Public\Pictures\Sample Pictures\ directory. (Note that successful execution of the example requires that the directory exist and that it contain files. + The following example uses the static property to make three calls to the method. The first starts a `Task` object, which executes a lambda expression that returns 1. The second starts a `Task` object, which executes a lambda expression that instantiates a new `Test` instance. The third starts a `Task` object, which enumerates the files in the C:\Users\Public\Pictures\Sample Pictures\ directory. (Note that successful execution of the example requires that the directory exist and that it contain files. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task`1/Factory/returnavalue10.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl/vb/10_returnavalue.vb" id="Snippet10"::: @@ -2525,14 +2525,14 @@ This method is intended for compiler use rather than use directly in code. method. + Accessing the property's get accessor blocks the calling thread until the asynchronous operation is complete; it is equivalent to calling the method. - Once the result of an operation is available, it is stored and is returned immediately on subsequent calls to the property. Note that, if an exception occurred during the operation of the task, or if the task has been cancelled, the property does not return a value. Instead, attempting to access the property value throws an exception. + Once the result of an operation is available, it is stored and is returned immediately on subsequent calls to the property. Note that, if an exception occurred during the operation of the task, or if the task has been cancelled, the property does not return a value. Instead, attempting to access the property value throws an exception. ## Examples - The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. If the directory contains files, it executes a lambda expression that instantiates a object for each file in the directory and retrieves the value of its property. If a directory contains no files, it simply calls the method to create a task whose property is zero (0). When the tasks finish, the total number of bytes in all a directory's files is available from the property. + The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. If the directory contains files, it executes a lambda expression that instantiates a object for each file in the directory and retrieves the value of its property. If a directory contains no files, it simply calls the method to create a task whose property is zero (0). When the tasks finish, the total number of bytes in all a directory's files is available from the property. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.vb" id="Snippet1"::: diff --git a/xml/System.Threading.Tasks/UnobservedTaskExceptionEventArgs.xml b/xml/System.Threading.Tasks/UnobservedTaskExceptionEventArgs.xml index 976b0c78da4..fe89a4673ec 100644 --- a/xml/System.Threading.Tasks/UnobservedTaskExceptionEventArgs.xml +++ b/xml/System.Threading.Tasks/UnobservedTaskExceptionEventArgs.xml @@ -69,7 +69,7 @@ method is used to mark the exception as observed. Marking the exception as observed prevents it from triggering exception escalation policy. For more information, see the [Remarks](/dotnet/api/system.threading.tasks.taskscheduler.unobservedtaskexception#remarks) of the event. + The Exception property is used to examine the exception without marking it as observed, whereas the method is used to mark the exception as observed. Marking the exception as observed prevents it from triggering exception escalation policy. For more information, see the [Remarks](/dotnet/api/system.threading.tasks.taskscheduler.unobservedtaskexception#remarks) of the event. ]]> diff --git a/xml/System.Threading.Tasks/ValueTask.xml b/xml/System.Threading.Tasks/ValueTask.xml index 24c60eeaf65..a44cd32ea16 100644 --- a/xml/System.Threading.Tasks/ValueTask.xml +++ b/xml/System.Threading.Tasks/ValueTask.xml @@ -71,15 +71,15 @@ Provides an awaitable result of an asynchronous operation. - using . A `ValueTask` instance may only be awaited once, and consumers may not call until the instance has completed. If these limitations are unacceptable, convert the `ValueTask` to a by calling . +## Remarks +A `ValueTask` instance may either be awaited or converted to a using . A `ValueTask` instance may only be awaited once, and consumers may not call until the instance has completed. If these limitations are unacceptable, convert the `ValueTask` to a by calling . The following operations should never be performed on a `ValueTask` instance: - Awaiting the instance multiple times. -- Calling multiple times. +- Calling multiple times. - Using more than one of these techniques to consume the instance. If you do any of the above, the results are undefined. @@ -354,9 +354,9 @@ This method either returns the wrapped task object, if one exists, or it manufac if the specified object is equal to the current object; otherwise, . - instances are equal when they wrap the same or the same pair of the object and the token. ]]> @@ -409,9 +409,9 @@ Two instances are equal when they wrap t if the specified object is equal to the current object; otherwise, . - instances are equal when they wrap the same or the same pair of the object and the token. ]]> @@ -942,9 +942,9 @@ If the is backed by a result or by a if the two values are equal; otherwise, . - instances are equal when they wrap the same or the same pair of the object and the token. ]]> @@ -996,9 +996,9 @@ Two instances are equal when they wrap t if the two values are not equal; otherwise, . - instances are equal when they wrap the same or the same pair of the object and the token. ]]> @@ -1044,7 +1044,7 @@ Two instances are equal when they wrap t Gets a that may be used at any point in the future. The preserved . - can be backed by a pooled , it is not safe to await an arbitrary multiple times. You can use the method to convert this into the instance backed by a regular that is safe to await multiple times. This method is similar to , but it returns the same instance when this represents a successful synchronously completed operation. After calling the original should never be used again. diff --git a/xml/System.Threading.Tasks/ValueTask`1.xml b/xml/System.Threading.Tasks/ValueTask`1.xml index e2ed44c4484..f9891ad5289 100644 --- a/xml/System.Threading.Tasks/ValueTask`1.xml +++ b/xml/System.Threading.Tasks/ValueTask`1.xml @@ -87,30 +87,30 @@ The result. Provides a value type that wraps a and a , only one of which is used. - instance may either be awaited or converted to a using . A instance may only be awaited once, and consumers may not read until the instance has completed. If these limitations are unacceptable, convert the to a by calling . +## Remarks +A instance may either be awaited or converted to a using . A instance may only be awaited once, and consumers may not read until the instance has completed. If these limitations are unacceptable, convert the to a by calling . -The following operations should never be performed on a instance: +The following operations should never be performed on a instance: - Awaiting the instance multiple times. - - Calling multiple times. + - Calling multiple times. - Using `.Result` or `.GetAwaiter().GetResult()` when the operation hasn't yet completed, or using them multiple times. - Using more than one of these techniques to consume the instance. If you do any of the above, the results are undefined. -A method may return an instance of this value type when it's likely that the result of its operation will be available synchronously, and when it's expected to be invoked so frequently that the cost of allocating a new for each call will be prohibitive. +A method may return an instance of this value type when it's likely that the result of its operation will be available synchronously, and when it's expected to be invoked so frequently that the cost of allocating a new for each call will be prohibitive. -There are tradeoffs to using a instead of a . For example, while a can help avoid an allocation in the case where the successful result is available synchronously, it also contains multiple fields, whereas a as a reference type is a single field. This means that returning a from a method results in copying more data. It also means, that if a method that returns a is awaited within an async method, the state machine for that async method will be larger, because it must store a struct containing multiple fields instead of a single reference. +There are tradeoffs to using a instead of a . For example, while a can help avoid an allocation in the case where the successful result is available synchronously, it also contains multiple fields, whereas a as a reference type is a single field. This means that returning a from a method results in copying more data. It also means, that if a method that returns a is awaited within an async method, the state machine for that async method will be larger, because it must store a struct containing multiple fields instead of a single reference. -For uses other than consuming the result of an asynchronous operation using await, can lead to a more convoluted programming model that requires more allocations. For example, consider a method that could return either a with a cached task as a common result or a . If the consumer of the result wants to use it as a in a method like or , the must first be converted to a using , leading to an allocation that would have been avoided if a cached had been used in the first place. +For uses other than consuming the result of an asynchronous operation using await, can lead to a more convoluted programming model that requires more allocations. For example, consider a method that could return either a with a cached task as a common result or a . If the consumer of the result wants to use it as a in a method like or , the must first be converted to a using , leading to an allocation that would have been avoided if a cached had been used in the first place. -As such, the default choice for any asynchronous method should be to return a or . Only if performance analysis proves it worthwhile should a be used instead of a . The non generic version of is not recommended for most scenarios. The property should be used to hand back a successfully completed singleton in the case where a method returning a completes synchronously and successfully. +As such, the default choice for any asynchronous method should be to return a or . Only if performance analysis proves it worthwhile should a be used instead of a . The non generic version of is not recommended for most scenarios. The property should be used to hand back a successfully completed singleton in the case where a method returning a completes synchronously and successfully. > [!NOTE] -> The use of the type is supported starting with C# 7.0, and is not supported by any version of Visual Basic. +> The use of the type is supported starting with C# 7.0, and is not supported by any version of Visual Basic. > [!NOTE] > An instance created with the parameterless constructor or by the `default(ValueTask)` syntax (a zero-initialized structure) represents a synchronously, successfully completed operation with a result of `default(TResult)`. @@ -960,10 +960,10 @@ If the is backed by a result or by a < Gets a that may be used at any point in the future. A task object for future use. - can be backed by a pooled , it is not safe to await an arbitrary multiple times. You can use the method to convert this into the instance backed by a regular that is safe to await multiple times. This method is similar to , but it returns the same instance when this represents a successful synchronously completed operation. After calling the original should never be used again. +Because a can be backed by a pooled , it is not safe to await an arbitrary multiple times. You can use the method to convert this into the instance backed by a regular that is safe to await multiple times. This method is similar to , but it returns the same instance when this represents a successful synchronously completed operation. After calling the original should never be used again. ]]> @@ -1009,11 +1009,11 @@ Because a can be backed by a pooled Gets the result. The result. - has completed. + has completed. -If this has completed successfully, this property returns the resulting value. If this has faulted, this property raises an exception. The thrown exception is not wrapped in an . +If this has completed successfully, this property returns the resulting value. If this has faulted, this property raises an exception. The thrown exception is not wrapped in an . ]]> diff --git a/xml/System.Threading/AbandonedMutexException.xml b/xml/System.Threading/AbandonedMutexException.xml index 073ca86e46e..815e115a118 100644 --- a/xml/System.Threading/AbandonedMutexException.xml +++ b/xml/System.Threading/AbandonedMutexException.xml @@ -81,10 +81,10 @@ ## Examples - The following code example executes a thread that abandons five mutexes, demonstrating their effects on the , , and methods. The value of the property is displayed for the call. + The following code example executes a thread that abandons five mutexes, demonstrating their effects on the , , and methods. The value of the property is displayed for the call. > [!NOTE] -> The call to the method is interrupted by one of the abandoned mutexes. The other abandoned mutex could still cause an to be thrown by subsequent wait methods. +> The call to the method is interrupted by one of the abandoned mutexes. The other abandoned mutex could still cause an to be thrown by subsequent wait methods. :::code language="csharp" source="~/snippets/csharp/System.Threading/AbandonedMutexException/Overview/koax.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/AbandonedMutexException/Overview/koax.vb" id="Snippet1"::: @@ -152,10 +152,10 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The system-supplied error message string.| -||`null`.| -||-1 (minus one).| +||`null`.| +||The system-supplied error message string.| +||`null`.| +||-1 (minus one).| ]]> @@ -214,10 +214,10 @@ |Property|Value| |--------------|-----------| -||`null`.| -||`message`.| -||`null`.| -||-1 (minus one).| +||`null`.| +||`message`.| +||`null`.| +||-1 (minus one).| ]]> @@ -278,10 +278,10 @@ |Property|Value| |--------------|-----------| -||`null`.| -||A system-supplied error message string.| -||`handle`.| -||`location`.| +||`null`.| +||A system-supplied error message string.| +||`handle`.| +||`location`.| ]]> @@ -410,10 +410,10 @@ |Property|Value| |--------------|-----------| -||`inner`.| -||`message`.| -||`null`.| -||-1 (minus one).| +||`inner`.| +||`message`.| +||`null`.| +||-1 (minus one).| ]]> @@ -476,10 +476,10 @@ |Property|Value| |--------------|-----------| -||`null`.| -||`message`.| -||`handle`.| -||`location`.| +||`null`.| +||`message`.| +||`handle`.| +||`location`.| ]]> @@ -546,10 +546,10 @@ |Property|Value| |--------------|-----------| -||`inner`.| -||`message`.| -||`handle`.| -||`location`.| +||`inner`.| +||`message`.| +||`handle`.| +||`location`.| ]]> @@ -602,7 +602,7 @@ method, the returned is the abandoned mutex with the lowest index in the array of objects that was passed to , or `null` if the abandoned mutex could not be identified. If the exception is thrown on a call to or , this property always returns `null`. + If the exception is thrown on a call to the method, the returned is the abandoned mutex with the lowest index in the array of objects that was passed to , or `null` if the abandoned mutex could not be identified. If the exception is thrown on a call to or , this property always returns `null`. ]]> @@ -654,15 +654,15 @@ method, this property returns the index of the abandoned mutex with the lowest index in the array of objects that was passed to , or -1 if the abandoned mutex could not be identified. If the exception is thrown on a call to or , this property always returns -1. + If the exception is thrown on a call to the method, this property returns the index of the abandoned mutex with the lowest index in the array of objects that was passed to , or -1 if the abandoned mutex could not be identified. If the exception is thrown on a call to or , this property always returns -1. ## Examples - The following code example executes a thread that abandons five mutexes. The abandoned mutexes are used to demonstrate the effects on the , , and method calls. The value of the property is displayed for the call. + The following code example executes a thread that abandons five mutexes. The abandoned mutexes are used to demonstrate the effects on the , , and method calls. The value of the property is displayed for the call. > [!NOTE] -> The call to is interrupted by one of the abandoned mutexes. The other abandoned mutex could still cause an to be thrown by subsequent wait methods. +> The call to is interrupted by one of the abandoned mutexes. The other abandoned mutex could still cause an to be thrown by subsequent wait methods. :::code language="csharp" source="~/snippets/csharp/System.Threading/AbandonedMutexException/Overview/koax.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/AbandonedMutexException/Overview/koax.vb" id="Snippet1"::: diff --git a/xml/System.Threading/AsyncFlowControl.xml b/xml/System.Threading/AsyncFlowControl.xml index b8285e50d1f..58b0d1766cc 100644 --- a/xml/System.Threading/AsyncFlowControl.xml +++ b/xml/System.Threading/AsyncFlowControl.xml @@ -56,11 +56,11 @@ Provides the functionality to restore the migration, or flow, of the execution context between threads. - method, which returns an structure. The method of the returned structure can be used to undo the flow suppression. The structure must be used on the same thread on which it was created. - + method, which returns an structure. The method of the returned structure can be used to undo the flow suppression. The structure must be used on the same thread on which it was created. + ]]> @@ -106,22 +106,22 @@ Releases all resources used by the current instance of the class. - . 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 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). - + . 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 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 `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. + ]]> - The structure is not used on the thread where it was created. - - -or- - + The structure is not used on the thread where it was created. + + -or- + The structure has already been used to call or . Cleaning Up Unmanaged Resources @@ -329,7 +329,7 @@ if the two structures are equal; otherwise, . - .]]> + .]]> @@ -379,7 +379,7 @@ if the structures are not equal; otherwise, . - .]]> + .]]> @@ -413,7 +413,7 @@ method to restore the associated to its previous state. ]]> @@ -466,19 +466,19 @@ This method calls the method to re Restores the flow of the execution context between threads. - method returns an structure that is used to restore the flow. - - The method must be called only on the structure returned by its associated method. - + method returns an structure that is used to restore the flow. + + The method must be called only on the structure returned by its associated method. + ]]> - The structure is not used on the thread where it was created. - - -or- - + The structure is not used on the thread where it was created. + + -or- + The structure has already been used to call or . diff --git a/xml/System.Threading/AsyncLocalValueChangedArgs`1.xml b/xml/System.Threading/AsyncLocalValueChangedArgs`1.xml index 8dd1fe7a4d2..5747f1c2e83 100644 --- a/xml/System.Threading/AsyncLocalValueChangedArgs`1.xml +++ b/xml/System.Threading/AsyncLocalValueChangedArgs`1.xml @@ -63,7 +63,7 @@ objects receives change notifications when it is instantiated by calling its constructor. + An objects receives change notifications when it is instantiated by calling its constructor. ]]> @@ -196,7 +196,7 @@ property is changed explicitly. + The property value is `false` if the property is changed explicitly. ]]> diff --git a/xml/System.Threading/AsyncLocal`1.xml b/xml/System.Threading/AsyncLocal`1.xml index 32f9479125b..210fe728458 100644 --- a/xml/System.Threading/AsyncLocal`1.xml +++ b/xml/System.Threading/AsyncLocal`1.xml @@ -65,14 +65,14 @@ instances can be used to persist data across threads. + Because the task-based asynchronous programming model tends to abstract the use of threads, instances can be used to persist data across threads. - The class also provides optional notifications when the value associated with the current thread changes, either because it was explicitly changed by setting the property, or implicitly changed when the thread encountered an `await` or other context transition. + The class also provides optional notifications when the value associated with the current thread changes, either because it was explicitly changed by setting the property, or implicitly changed when the thread encountered an `await` or other context transition. ## Examples - The following example uses the class to persist a string value across an asynchronous flow. It also contrasts the use of with . + The following example uses the class to persist a string value across an asynchronous flow. It also contrasts the use of with . :::code language="csharp" source="~/snippets/csharp/System.Threading/AsyncLocalT/Overview/Example1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/AsyncLocalT/Overview/Example1.vb" id="Snippet1"::: diff --git a/xml/System.Threading/AutoResetEvent.xml b/xml/System.Threading/AutoResetEvent.xml index 6f54c97e3a7..e652e0f4cfd 100644 --- a/xml/System.Threading/AutoResetEvent.xml +++ b/xml/System.Threading/AutoResetEvent.xml @@ -69,14 +69,14 @@ You use `AutoResetEvent`, , and ). That thread does not block: the releases the thread immediately and returns to the non-signaled state. +If no threads are waiting when the `AutoResetEvent` goes into a signaled state, the state remains signaled until a thread observes the signal (by calling ). That thread does not block: the releases the thread immediately and returns to the non-signaled state. > [!IMPORTANT] -> There's no guarantee that every call to the method will release a thread. If two calls are too close together, so that the second call occurs before a thread has been released, only one thread is released. It's as if the second call did not happen. Also, if is called when there are no threads waiting and the is already signaled, the call has no effect. +> There's no guarantee that every call to the method will release a thread. If two calls are too close together, so that the second call occurs before a thread has been released, only one thread is released. It's as if the second call did not happen. Also, if is called when there are no threads waiting and the is already signaled, the call has no effect. You can control the initial state of an `AutoResetEvent` by passing a Boolean value to the constructor: `true` if the initial state is signaled and `false` otherwise. -`AutoResetEvent` can also be used with the `static` and methods. +`AutoResetEvent` can also be used with the `static` and methods. derives from the class. An is functionally equivalent to an created with . @@ -84,13 +84,13 @@ 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 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. ## Examples -The following example shows how to use to release one thread at a time, by calling the method (on the base class) each time the user presses the **Enter** key. The example starts three threads, which wait on an that was created in the signaled state. The first thread is released immediately, because the is already in the signaled state. This resets the to the non-signaled state, so that subsequent threads block. The blocked threads are not released until the user releases them one at a time by pressing the **Enter** key. +The following example shows how to use to release one thread at a time, by calling the method (on the base class) each time the user presses the **Enter** key. The example starts three threads, which wait on an that was created in the signaled state. The first thread is released immediately, because the is already in the signaled state. This resets the to the non-signaled state, so that subsequent threads block. The blocked threads are not released until the user releases them one at a time by pressing the **Enter** key. -After the threads are released from the first , they wait on another that was created in the non-signaled state. All three threads block, so the method must be called three times to release them all. +After the threads are released from the first , they wait on another that was created in the non-signaled state. All three threads block, so the method must be called three times to release them all. :::code language="csharp" source="~/snippets/csharp/System.Threading/AutoResetEvent/Overview/simplerisbetter.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/AutoResetEvent/Overview/simplerisbetter.vb" id="Snippet3"::: @@ -157,11 +157,11 @@ After the threads are released from the first to synchronize the activities of two threads. The first thread, which is the application thread, executes `Main`. It writes values to the protected resource, which is a `static` (`Shared` in Visual Basic) field named `number`. The second thread executes the static `ThreadProc` method, which reads the values written by `Main`. - The `ThreadProc` method waits for the . When `Main` calls the method on the , the `ThreadProc` method reads one value. The immediately resets, so the `ThreadProc` method waits again. + The `ThreadProc` method waits for the . When `Main` calls the method on the , the `ThreadProc` method reads one value. The immediately resets, so the `ThreadProc` method waits again. The program logic guarantees that the `ThreadProc` method will never read the same value two times. It does not guarantee that the `ThreadProc` method will read every value written by `Main`. That guarantee would require a second lock. - After each write operation, `Main` yields by calling the method, to give the second thread a chance to execute. Otherwise, on a single-processor computer `Main` would write many values between any two read operations. + After each write operation, `Main` yields by calling the method, to give the second thread a chance to execute. Otherwise, on a single-processor computer `Main` would write many values between any two read operations. :::code language="csharp" source="~/snippets/csharp/System.Threading/AutoResetEvent/Overview/class1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/AutoResetEvent/Overview/class1.vb" id="Snippet1"::: diff --git a/xml/System.Threading/Barrier.xml b/xml/System.Threading/Barrier.xml index 3ba3fa7f0b8..58cc6c9be68 100644 --- a/xml/System.Threading/Barrier.xml +++ b/xml/System.Threading/Barrier.xml @@ -61,19 +61,19 @@ Enables multiple tasks to cooperatively work on an algorithm in parallel through multiple phases. - in a given phase and implicitly waits for all others to arrive. The same can be used for multiple phases. - - - -## Examples - The following example shows how to use a barrier: - + in a given phase and implicitly waits for all others to arrive. The same can be used for multiple phases. + + + +## Examples + The following example shows how to use a barrier: + :::code language="csharp" source="~/snippets/csharp/System.Threading/Barrier/Overview/barrier.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/System.Threading/Barrier/Overview/barrier.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Threading/Barrier/Overview/barrier.vb" id="Snippet01"::: + ]]> All public and protected members of are thread-safe and may be used concurrently from multiple threads, with the exception of Dispose, which must only be used when all other operations on the have completed. @@ -196,11 +196,11 @@ The to be executed after each phase. null (Nothing in Visual Basic) may be passed to indicate no action is taken. Initializes a new instance of the class. - @@ -256,18 +256,18 @@ Notifies the that there will be an additional participant. The phase number of the barrier in which the new participants will first participate. - The current instance has already been disposed. - Adding a participant would cause the barrier's participant count to exceed 32,767. - - -or- - + Adding a participant would cause the barrier's participant count to exceed 32,767. + + -or- + The method was invoked from within a post-phase action. Barrier How to: Synchronize Concurrent Operations with a Barrier @@ -323,19 +323,19 @@ Notifies the that there will be additional participants. The phase number of the barrier in which the new participants will first participate. - The current instance has already been disposed. - is less than 0. - - -or- - + is less than 0. + + -or- + Adding participants would cause the barrier's participant count to exceed 32,767. The method was invoked from within a post-phase action. Barrier @@ -448,16 +448,16 @@ Releases all resources used by the current instance of the class. - . 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 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). - + . 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 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 `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. + ]]> The method was invoked from within a post-phase action. @@ -508,11 +508,11 @@ true to release both managed and unmanaged resources; false to release only unmanaged resources. Releases the unmanaged resources used by the , and optionally releases the managed resources. - , Dispose is not thread-safe and may not be used concurrently with other members of this instance. - + , Dispose is not thread-safe and may not be used concurrently with other members of this instance. + ]]> Barrier @@ -603,11 +603,11 @@ Gets the number of participants in the barrier that haven't yet signaled in the current phase. Returns the number of participants in the barrier that haven't yet signaled in the current phase. - Barrier @@ -661,10 +661,10 @@ Notifies the that there will be one less participant. To be added. The current instance has already been disposed. - The barrier already has 0 participants. - - -or- - + The barrier already has 0 participants. + + -or- + The method was invoked from within a post-phase action. Barrier How to: Synchronize Concurrent Operations with a Barrier @@ -713,23 +713,23 @@ The number of additional participants to remove from the barrier. Notifies the that there will be fewer participants. - The current instance has already been disposed. The total participant count is less than the specified - The barrier already has 0 participants. - - -or- - - The method was invoked from within a post-phase action. - - -or- - + The barrier already has 0 participants. + + -or- + + The method was invoked from within a post-phase action. + + -or- + The current participant count is less than the specified participantCount. Barrier How to: Synchronize Concurrent Operations with a Barrier @@ -1030,11 +1030,11 @@ if all participants reached the barrier within the specified time; otherwise, . - is thrown and the value is not decreased. If the `cancellationToken` is not canceled or is canceled after the signal takes effect then is decreased and no is thrown. - + is thrown and the value is not decreased. If the `cancellationToken` is not canceled or is canceled after the signal takes effect then is decreased and no is thrown. + ]]> diff --git a/xml/System.Threading/BarrierPostPhaseException.xml b/xml/System.Threading/BarrierPostPhaseException.xml index 4ddf6420fd2..c4570b2edd3 100644 --- a/xml/System.Threading/BarrierPostPhaseException.xml +++ b/xml/System.Threading/BarrierPostPhaseException.xml @@ -126,8 +126,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The localized error message string.| +||`null`.| +||The localized error message string.| ]]> @@ -242,8 +242,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| ]]> @@ -372,8 +372,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| ]]> diff --git a/xml/System.Threading/CancellationToken.xml b/xml/System.Threading/CancellationToken.xml index 2b458fedc2b..9711db34f6b 100644 --- a/xml/System.Threading/CancellationToken.xml +++ b/xml/System.Threading/CancellationToken.xml @@ -90,7 +90,7 @@ enables cooperative cancellation between threads, thread pool work items, or objects. You create a cancellation token by instantiating a object, which manages cancellation tokens retrieved from its property. You then pass the cancellation token to any number of threads, tasks, or operations that should receive notice of cancellation. The token cannot be used to initiate cancellation. When the owning object calls , the property on every copy of the cancellation token is set to `true`. The objects that receive the notification can respond in whatever manner is appropriate. + A enables cooperative cancellation between threads, thread pool work items, or objects. You create a cancellation token by instantiating a object, which manages cancellation tokens retrieved from its property. You then pass the cancellation token to any number of threads, tasks, or operations that should receive notice of cancellation. The token cannot be used to initiate cancellation. When the owning object calls , the property on every copy of the cancellation token is set to `true`. The objects that receive the notification can respond in whatever manner is appropriate. For more information and code examples see [Cancellation in Managed Threads](/dotnet/standard/threading/cancellation-in-managed-threads). @@ -99,7 +99,7 @@ ## Examples The following example uses a random number generator to emulate a data collection application that reads 10 integral values from eleven different instruments. A value of zero indicates that the measurement has failed for one instrument, in which case the operation should be cancelled and no overall mean should be computed. -To handle the possible cancellation of the operation, the example instantiates a object that generates a cancellation token that's passed to a object. In turn, the object passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not completed because it was cancelled, the method throws an exception. +To handle the possible cancellation of the operation, the example instantiates a object that generates a cancellation token that's passed to a object. In turn, the object passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not completed because it was cancelled, the method throws an exception. :::code language="csharp" source="~/snippets/csharp/System.Threading/CancellationToken/Overview/cancel1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/CancellationToken/Overview/cancel1.vb" id="Snippet1"::: @@ -157,9 +157,9 @@ To handle the possible cancellation of the operation, the example instantiates a and will be `false`. + Tokens created with this constructor will remain in the canceled state specified by the `canceled` parameter. If `canceled` is `false`, both and will be `false`. - If `canceled` is `true`, both and will be `true`. + If `canceled` is `true`, both and will be `true`. ]]> @@ -220,7 +220,7 @@ To handle the possible cancellation of the operation, the example instantiates a returns `false`, it is guaranteed that the token will never transition into a canceled state, meaning that will never return `true`. A cancellation token that cannot be canceled is returned by the static property. + If returns `false`, it is guaranteed that the token will never transition into a canceled state, meaning that will never return `true`. A cancellation token that cannot be canceled is returned by the static property. You can optionally use this property to determine whether a cancellation token can be canceled before examining the value of the property to determine whether it has been canceled. @@ -483,7 +483,7 @@ Two cancellation tokens are equal if any one of the following conditions is true on the token's associated . + This property indicates whether cancellation has been requested for this token, either through the token initially being constructed in a canceled state, or through calling on the token's associated . If this property is `true`, it only guarantees that cancellation has been requested. It does not guarantee that every registered handler has finished executing, nor that cancellation requests have finished propagating to all registered handlers. Additional synchronization may be required, particularly in situations where related objects are being canceled concurrently. @@ -495,7 +495,7 @@ Two cancellation tokens are equal if any one of the following conditions is true :::code language="csharp" source="~/snippets/csharp/System.Threading/CancellationToken/IsCancellationRequested/cancellation.cs" id="Snippet12"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/CancellationToken/IsCancellationRequested/cancelthreads.vb" id="Snippet12"::: - The example instantiates a object, which controls access to the cancellation token. It then defines two thread procedures. The first is defined as a lambda expression that pools the keyboard and, when the "C" key is pressed, calls to set the cancellation token to the cancelled state. The second is a parameterized method, `ServerClass.StaticMethod`, that executes a loop until the property is `true`. + The example instantiates a object, which controls access to the cancellation token. It then defines two thread procedures. The first is defined as a lambda expression that pools the keyboard and, when the "C" key is pressed, calls to set the cancellation token to the cancelled state. The second is a parameterized method, `ServerClass.StaticMethod`, that executes a loop until the property is `true`. The main thread then starts the two threads and blocks until the thread that executes the `ServerClass.StaticMethod` method terminates. @@ -689,7 +689,7 @@ Two cancellation tokens are equal if any one of the following conditions is true method. +For the definition of equality, see the method. ]]> An associated has been disposed. diff --git a/xml/System.Threading/CancellationTokenSource.xml b/xml/System.Threading/CancellationTokenSource.xml index 83e936e3058..840ad8bb1e0 100644 --- a/xml/System.Threading/CancellationTokenSource.xml +++ b/xml/System.Threading/CancellationTokenSource.xml @@ -80,7 +80,7 @@ ## Remarks Starting with the .NET Framework 4, the .NET Framework uses a unified model for cooperative cancellation of asynchronous or long-running synchronous operations that involves two objects: -- A object, which provides a cancellation token through its property and sends a cancellation message by calling its or method. +- A object, which provides a cancellation token through its property and sends a cancellation message by calling its or method. - A object, which indicates whether cancellation is requested. @@ -90,23 +90,23 @@ - Pass the token returned by the property to each task or thread that listens for cancellation. -- Call the method from operations that receive the cancellation token. Provide a mechanism for each task or thread to respond to a cancellation request. Whether you choose to cancel an operation, and exactly how you do it, depends on your application logic. +- Call the method from operations that receive the cancellation token. Provide a mechanism for each task or thread to respond to a cancellation request. Whether you choose to cancel an operation, and exactly how you do it, depends on your application logic. -- Call the method to provide notification of cancellation. This sets the property on every copy of the cancellation token to `true`. +- Call the method to provide notification of cancellation. This sets the property on every copy of the cancellation token to `true`. -- Call the method when you are finished with the object. +- Call the method when you are finished with the object. 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#) 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 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#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. ## Examples The following example uses a random number generator to emulate a data collection application that reads 10 integral values from eleven different instruments. A value of zero indicates that the measurement has failed for one instrument, in which case the operation should be cancelled and no overall mean should be computed. - To handle the possible cancellation of the operation, the example instantiates a object that generates a cancellation token which is passed to a object. The object in turn passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not completed because it has been cancelled, the call to the method throws an exception. + To handle the possible cancellation of the operation, the example instantiates a object that generates a cancellation token which is passed to a object. The object in turn passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not completed because it has been cancelled, the call to the method throws an exception. :::code language="csharp" source="~/snippets/csharp/System.Threading/CancellationToken/Overview/cancel1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/CancellationToken/Overview/cancel1.vb" id="Snippet1"::: @@ -226,7 +226,7 @@ ## Remarks The countdown for the `millisecondsDelay` starts during the call to the constructor. When the `millisecondsDelay` expires, the constructed is canceled (if it has not been canceled already). - Subsequent calls to will reset the `millisecondsDelay` for the constructed , if it has not been canceled already. + Subsequent calls to will reset the `millisecondsDelay` for the constructed , if it has not been canceled already. ]]> @@ -282,7 +282,7 @@ ## Remarks The countdown for the delay starts during the call to the constructor. When the delay expires, the constructed is canceled, if it has not been canceled already. - Subsequent calls to will reset the delay for the constructed , if it has not been canceled already. + Subsequent calls to will reset the delay for the constructed , if it has not been canceled already. ]]> @@ -390,7 +390,7 @@ ## Remarks -The associated is notified of the cancellation and transitions to a state where returns true. +The associated is notified of the cancellation and transitions to a state where returns true. Any callbacks or cancelable operations registered with the are executed, if they haven't already been executed by a previous call to . Subsequent calls to won't execute the same callback again unless reregistered. (Avoid multiple calls to , because the intent of such code is often unclear.) @@ -406,7 +406,7 @@ Calling this method has the same effect as calling [`Cancel(false)`](xref:System The following example uses a random number generator to emulate a data collection application that reads 10 integral values from eleven different instruments. A value of zero indicates that the measurement has failed for one instrument, in which case the operation should be cancelled and no overall mean should be computed. -To handle the possible cancellation of the operation, the example instantiates a object that generates a cancellation token which is passed to a object. The object in turn passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not because it has been cancelled, the call to the method throws an exception. +To handle the possible cancellation of the operation, the example instantiates a object that generates a cancellation token which is passed to a object. The object in turn passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not because it has been cancelled, the call to the method throws an exception. :::code language="csharp" source="~/snippets/csharp/System.Threading/CancellationToken/Overview/cancel1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/CancellationToken/Overview/cancel1.vb" id="Snippet1"::: @@ -470,7 +470,7 @@ To handle the possible cancellation of the operation, the example instantiates a ## Remarks -The associated is notified of the cancellation and transitions to a state where returns `true`. +The associated is notified of the cancellation and transitions to a state where returns `true`. Any callbacks or cancelable operations registered with the are executed, if they haven't already been executed by a previous call to . Subsequent calls to won't execute the same callback again unless reregistered. (Avoid multiple calls to , because the intent of such code is often unclear.) @@ -478,7 +478,7 @@ Callbacks are executed synchronously in LIFO order. We recommend that cancelable operations and callbacks registered with not throw exceptions. -If `throwOnFirstException` is `true`, an exception will immediately propagate out of the call to , preventing the remaining callbacks and cancelable operations from being processed. +If `throwOnFirstException` is `true`, an exception will immediately propagate out of the call to , preventing the remaining callbacks and cancelable operations from being processed. If `throwOnFirstException` is `false`, this overload aggregates any exceptions thrown into an , such that one callback throwing an exception will not prevent other registered callbacks from being executed. @@ -948,7 +948,7 @@ If `throwOnFirstException` is `false`, this overload aggregates any exceptions t ## Remarks 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 the was occupying. - Note that calling `Dispose` does not communicate a request for cancellation to consumers of the associated . You can communicate a request for cancellation by calling methods such as or . + Note that calling `Dispose` does not communicate a request for cancellation to consumers of the associated . You can communicate a request for cancellation by calling methods such as or . For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). @@ -1061,7 +1061,7 @@ If `throwOnFirstException` is `false`, this overload aggregates any exceptions t method. + This property indicates whether cancellation has been requested for this token source, such as due to a call to its method. If this property returns `true`, it only guarantees that cancellation has been requested. It does not guarantee that every handler registered with the corresponding token has finished executing, nor that cancellation requests have finished propagating to all registered handlers. Additional synchronization may be required, particularly in situations where related objects are being canceled concurrently. diff --git a/xml/System.Threading/CompressedStack.xml b/xml/System.Threading/CompressedStack.xml index 0ec35f7b389..5e32f6f9828 100644 --- a/xml/System.Threading/CompressedStack.xml +++ b/xml/System.Threading/CompressedStack.xml @@ -66,15 +66,15 @@ Provides methods for setting and capturing the compressed stack on the current thread. This class cannot be inherited. - and actions. For example, if a action is two stack frames up from the current frame and there are no other code access security annotations between there and the current frame, the compressed stack records only that information, without having to serialize the entire call stack. - - The class is used internally by the class. For example, the method captures the compressed stack for the current call stack, along with impersonation and culture information. The class is used in turn by the class to flow context across threads, for example when scheduling thread pool tasks. - - This class is not used in ordinary application programming. - + and actions. For example, if a action is two stack frames up from the current frame and there are no other code access security annotations between there and the current frame, the compressed stack records only that information, without having to serialize the entire call stack. + + The class is used internally by the class. For example, the method captures the compressed stack for the current call stack, along with impersonation and culture information. The class is used in turn by the class to flow context across threads, for example when scheduling thread pool tasks. + + This class is not used in ordinary application programming. + ]]> @@ -125,13 +125,13 @@ Captures the compressed stack from the current thread. A object. - and actions, in a compressed format. For example, if a action is two stack frames up from the current frame and there are no other code access security annotations between there and the current frame, the compressed stack records only that information, without having to serialize the entire call stack. - - The captured compressed stack can be applied to another thread. - + and actions, in a compressed format. For example, if a action is two stack frames up from the current frame and there are no other code access security annotations between there and the current frame, the compressed stack records only that information, without having to serialize the entire call stack. + + The captured compressed stack can be applied to another thread. + ]]> @@ -186,11 +186,11 @@ Creates a copy of the current compressed stack. A object representing the current compressed stack. - @@ -222,13 +222,13 @@ [!NOTE] > This member is removed in the .NET Framework version 2.0 and subsequent versions. -Application code does not call this method; it is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled. For more information, see and . This method overrides . +Application code does not call this method; it is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled. For more information, see and . This method overrides . ]]> @@ -281,17 +281,17 @@ Application code does not call this method; it is automatically invoked during g Gets the compressed stack for the current thread. A for the current thread. - returns an empty object. - + returns an empty object. + ]]> - A caller in the call chain does not have permission to access unmanaged code. - - -or- - + A caller in the call chain does not have permission to access unmanaged code. + + -or- + The request for failed. @@ -356,13 +356,13 @@ Application code does not call this method; it is automatically invoked during g The structure representing the destination context of the serialization. Sets the object with the logical context information needed to recreate an instance of this execution context. - sets a with the logical call context information. During deserialization, the execution context object is reconstituted from the transmitted over the stream. - - For more information, see . - + sets a with the logical call context information. During deserialization, the execution context object is reconstituted from the transmitted over the stream. + + For more information, see . + ]]> @@ -429,11 +429,11 @@ Application code does not call this method; it is automatically invoked during g The object to be passed to the callback method. Runs a method in the specified compressed stack on the current thread. - diff --git a/xml/System.Threading/ContextCallback.xml b/xml/System.Threading/ContextCallback.xml index 8b22761dae5..ec76c852fb7 100644 --- a/xml/System.Threading/ContextCallback.xml +++ b/xml/System.Threading/ContextCallback.xml @@ -59,13 +59,13 @@ An object containing information to be used by the callback method each time it executes. Represents a method to be called within a new context. - is used by the and the methods. represents the method to be run in the provided context. Upon completion of the method execution, the context is restored to its previous state. - - Create the delegate by passing your callback method to the constructor. Your method must have the signature shown here. - + is used by the and the methods. represents the method to be run in the provided context. Upon completion of the method execution, the context is restored to its previous state. + + Create the delegate by passing your callback method to the constructor. Your method must have the signature shown here. + ]]> diff --git a/xml/System.Threading/CountdownEvent.xml b/xml/System.Threading/CountdownEvent.xml index 9732118bccc..7190aa6b686 100644 --- a/xml/System.Threading/CountdownEvent.xml +++ b/xml/System.Threading/CountdownEvent.xml @@ -403,7 +403,7 @@ , is not thread-safe and may not be used concurrently with other members of this instance. + Unlike most of the members of , is not thread-safe and may not be used concurrently with other members of this instance. ]]> @@ -610,7 +610,7 @@ for all subsequent accesses of the property on the current instance. Unlike most of the members of , Reset is not thread-safe and may not be used concurrently with other members of this instance. + This method resets for all subsequent accesses of the property on the current instance. Unlike most of the members of , Reset is not thread-safe and may not be used concurrently with other members of this instance. ]]> @@ -1264,7 +1264,7 @@ The that created should only be used if it's needed for integration with code bases that rely on having a WaitHandle. If all that's needed is to wait for the to be set, the method should be preferred. + should only be used if it's needed for integration with code bases that rely on having a WaitHandle. If all that's needed is to wait for the to be set, the method should be preferred. ]]> diff --git a/xml/System.Threading/EventResetMode.xml b/xml/System.Threading/EventResetMode.xml index b10176c51dc..de62ade40e0 100644 --- a/xml/System.Threading/EventResetMode.xml +++ b/xml/System.Threading/EventResetMode.xml @@ -56,10 +56,10 @@ method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task. + The following code example uses the method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task. The example starts five threads and allows them to block on an created with the AutoReset flag, then releases one thread each time the user presses the ENTER key. The example then queues another five threads and releases them all using an created with the ManualReset flag. - + :::code language="csharp" source="~/snippets/csharp/System.Threading/EventResetMode/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/EventResetMode/Overview/source.vb" id="Snippet1"::: diff --git a/xml/System.Threading/EventWaitHandle.xml b/xml/System.Threading/EventWaitHandle.xml index fa4e1377dea..16f3e53ec1a 100644 --- a/xml/System.Threading/EventWaitHandle.xml +++ b/xml/System.Threading/EventWaitHandle.xml @@ -62,18 +62,18 @@ ## Remarks -The class allows threads to communicate with each other by signaling. Typically, one or more threads block on an until an unblocked thread calls the method, releasing one or more of the blocked threads. A thread can signal an and then block on it, by calling the `static` (`Shared` in Visual Basic) method. +The class allows threads to communicate with each other by signaling. Typically, one or more threads block on an until an unblocked thread calls the method, releasing one or more of the blocked threads. A thread can signal an and then block on it, by calling the `static` (`Shared` in Visual Basic) method. > [!NOTE] > The class provides access to named system synchronization events. - The behavior of an that has been signaled depends on its reset mode. An created with the flag resets automatically when signaled, after releasing a single waiting thread. An created with the flag remains signaled until its method is called. + The behavior of an that has been signaled depends on its reset mode. An created with the flag resets automatically when signaled, after releasing a single waiting thread. An created with the flag remains signaled until its method is called. Automatic reset events provide exclusive access to a resource. If an automatic reset event is signaled when no threads are waiting, it remains signaled until a thread attempts to wait on it. The event releases the thread and immediately resets, blocking subsequent threads. - Manual reset events are like gates. When the event is not signaled, threads that wait on it will block. When the event is signaled, all waiting threads are released, and the event remains signaled (that is, subsequent waits do not block) until its method is called. Manual reset events are useful when one thread must complete an activity before other threads can proceed. + Manual reset events are like gates. When the event is not signaled, threads that wait on it will block. When the event is signaled, all waiting threads are released, and the event remains signaled (that is, subsequent waits do not block) until its method is called. Manual reset events are useful when one thread must complete an activity before other threads can proceed. - objects can be used with the `static`(`Shared` in Visual Basic) and methods. + objects can be used with the `static`(`Shared` in Visual Basic) and methods. For more information, see the [Thread interaction, or signaling](/dotnet/standard/threading/overview-of-synchronization-primitives#thread-interaction-or-signaling) section of the [Overview of synchronization primitives](/dotnet/standard/threading/overview-of-synchronization-primitives) article. @@ -244,7 +244,7 @@ The `name` can be prefixed with `Global\` or `Local\` to specify a namespace. Wh > By default, a named event is not restricted to the user that created it. Other users might be able to open and use the event, including interfering with the event by setting or resetting it inappropriately. To restrict access to specific users, you can use a constructor overload or and pass in an when creating the named event. Avoid using named events without access restrictions on systems that might have untrusted users running code. > [!IMPORTANT] -> When using this constructor for named system events, specify `false` for `initialState`. This constructor provides no way to determine whether a named system event was created, so you cannot make any assumptions about the state of the named event. To determine whether a named event was created, use the constructor or the constructor. +> When using this constructor for named system events, specify `false` for `initialState`. This constructor provides no way to determine whether a named system event was created, so you cannot make any assumptions about the state of the named event. To determine whether a named event was created, use the constructor or the constructor. If the initial state of the event is nonsignaled, threads that wait on the event will block. If the initial state is signaled, and the flag is specified for `mode`, threads that wait on the event will not block. If the initial state is signaled and `mode` is , the first thread that waits on the event will be released immediately, after which the event will reset, and subsequent threads will block. @@ -399,7 +399,7 @@ If a `name` is provided and a synchronization object of the requested type alrea If a system event with the name specified for the `name` parameter already exists, the `initialState` parameter is ignored. > [!IMPORTANT] -> When using this constructor for named system events, specify `false` for `initialState`. This constructor provides no way to determine whether a named system event was created, so you can't make any assumptions about the state of the named event. To determine whether a named event was created, use the constructor or the constructor. +> When using this constructor for named system events, specify `false` for `initialState`. This constructor provides no way to determine whether a named system event was created, so you can't make any assumptions about the state of the named event. To determine whether a named event was created, use the constructor or the constructor. If the initial state of the event is nonsignaled, threads that wait on the event will block. If the initial state is signaled and the flag is specified for `mode`, threads that wait on the event will not block. If the initial state is signaled and `mode` is , the first thread that waits on the event will be released immediately, after which the event will reset and subsequent threads will block. @@ -479,7 +479,7 @@ An object with the specified exists, but the specified If the system event does not exist, it is created with the specified access control security. If the event exists, the specified access control security is ignored. > [!NOTE] -> The caller has full control over the newly created object even if `eventSecurity` denies or fails to grant some access rights to the current user. However, if the current user attempts to get another object to represent the same named event, using either a constructor or the method, Windows access control security is applied. +> The caller has full control over the newly created object even if `eventSecurity` denies or fails to grant some access rights to the current user. However, if the current user attempts to get another object to represent the same named event, using either a constructor or the method, Windows access control security is applied. The `name` can be prefixed with `Global\` or `Local\` to specify a namespace. When the `Global` namespace is specified, the synchronization object can be shared with any processes on the system. When the `Local` namespace is specified, which is also the default when no namespace is specified, the synchronization object can be shared with processes in the same session. On Windows, a session is a login session, and services typically run in a different non-interactive session. On Unix-like operating systems, each shell has its own session. Session-local synchronization objects might be appropriate for synchronizing between processes with a parent/child relationship where they all run in the same session. For more information about synchronization object names on Windows, see [Object Names](/windows/win32/sync/object-names). @@ -630,7 +630,7 @@ An object with the specified exists, but the specified method uses the following combination of flags (combined using the bitwise OR operation) to search for permissions: , , and . + The method uses the following combination of flags (combined using the bitwise OR operation) to search for permissions: , , and . The user must have rights to call this method, and the event must have been opened with the flag. @@ -641,7 +641,7 @@ An object with the specified exists, but the specified If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to wait on the event with the rights needed to read and change the permissions. - After the permissions have been read, using the method, and changed, the event is opened with the rights required to wait on it and signal it. If you run the compiled example from a third command window, the example runs using the new permissions. + After the permissions have been read, using the method, and changed, the event is opened with the rights required to wait on it and signal it. If you run the compiled example from a third command window, the example runs using the new permissions. :::code language="csharp" source="~/snippets/csharp/System.Threading/EventWaitHandle/.ctor/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/EventWaitHandle/.ctor/source.vb" id="Snippet1"::: @@ -731,13 +731,13 @@ An object with the specified exists, but the specified If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown. - The method tries to open the specified named system event. To create the system event when it does not already exist, use one of the constructors that has a `name` parameter. + The method tries to open the specified named system event. To create the system event when it does not already exist, use one of the constructors that has a `name` parameter. Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system event. In .NET Framework, this method overload is equivalent to calling the [System.Threading.EventWaitHandle.OpenExisting(System.String,System.Security.AccessControl.EventWaitHandleRights)](/dotnet/api/system.threading.eventwaithandle.openexisting?view=netframework-4.8&preserve-view=true#System_Threading_EventWaitHandle_OpenExisting_System_String_System_Security_AccessControl_EventWaitHandleRights_) method overload and specifying and rights, combined by using the bitwise `OR` operation. - Specifying the flag allows a thread to wait on the named system event, and specifying the flag allows a thread to call the and methods. + Specifying the flag allows a thread to wait on the named system event, and specifying the flag allows a thread to call the and methods. ]]> @@ -807,9 +807,9 @@ The `name` can be prefixed with `Global\` or `Local\` to specify a namespace. Wh If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown. - The `rights` parameter must include the flag to allow threads to wait on the event, and the flag to allow threads to call the and methods. + The `rights` parameter must include the flag to allow threads to wait on the event, and the flag to allow threads to call the and methods. - The method tries to open an existing named system event. To create the system event when it does not already exist, use one of the constructors that has a `name` parameter. + The method tries to open an existing named system event. To create the system event when it does not already exist, use one of the constructors that has a `name` parameter. Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system event. @@ -890,7 +890,7 @@ There was some other error. The `HResult` property might provide more informatio If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. However, if `options` specifies access limited to the current user and the synchronization object is not compatible with it, a `WaitHandleCannotBeOpenedException` is thrown. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown as well. -The method tries to open the specified named system event. To create the system event when it does not already exist, use one of the constructors that has a `name` parameter. +The method tries to open the specified named system event. To create the system event when it does not already exist, use one of the constructors that has a `name` parameter. Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system event. @@ -1022,12 +1022,12 @@ There was some other error. The `HResult` property might provide more informatio with (including ), the method releases a single thread. If there are no waiting threads, the wait handle remains signaled until a thread attempts to wait on it, or until its method is called. + For an with (including ), the method releases a single thread. If there are no waiting threads, the wait handle remains signaled until a thread attempts to wait on it, or until its method is called. > [!IMPORTANT] -> There is no guarantee that every call to the method will release a thread from an whose reset mode is . If two calls are too close together, so that the second call occurs before a thread has been released, only one thread is released. It is as if the second call did not happen. Also, if is called when there are no threads waiting and the is already signaled, the call has no effect. +> There is no guarantee that every call to the method will release a thread from an whose reset mode is . If two calls are too close together, so that the second call occurs before a thread has been released, only one thread is released. It is as if the second call did not happen. Also, if is called when there are no threads waiting and the is already signaled, the call has no effect. - For an with (including ), calling the method leaves the wait handle in a signaled state until its method is called. + For an with (including ), calling the method leaves the wait handle in a signaled state until its method is called. ## Examples The following code example uses the method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task. @@ -1090,7 +1090,7 @@ There was some other error. The `HResult` property might provide more informatio If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to wait on the event with the rights needed to read and change the permissions. - After the permissions are changed, using the method, the event is opened with the rights required to wait on it and signal it. If you run the compiled example from a third command window, the example runs using the new permissions. + After the permissions are changed, using the method, the event is opened with the rights required to wait on it and signal it. If you run the compiled example from a third command window, the example runs using the new permissions. :::code language="csharp" source="~/snippets/csharp/System.Threading/EventWaitHandle/.ctor/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/EventWaitHandle/.ctor/source.vb" id="Snippet1"::: @@ -1197,11 +1197,11 @@ The `name` can be prefixed with `Global\` or `Local\` to specify a namespace. Wh If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, `false` is returned. - To create the system event when it does not already exist, use one of the constructors that has a `name` parameter. + To create the system event when it does not already exist, use one of the constructors that has a `name` parameter. If you are uncertain whether a named synchronization event exists, use this method overload instead of the method overload, which throws an exception if the synchronization event does not exist. - This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. Specifying the flag allows a thread to wait on the named system event, and specifying the flag allows a thread to call the and methods. + This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. Specifying the flag allows a thread to wait on the named system event, and specifying the flag allows a thread to call the and methods. Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system event. @@ -1272,11 +1272,11 @@ The `name` can be prefixed with `Global\` or `Local\` to specify a namespace. Wh If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, `false` is returned. - To create the system event when it does not already exist, use one of the constructors that has a `name` parameter. + To create the system event when it does not already exist, use one of the constructors that has a `name` parameter. If you are uncertain whether a named synchronization event exists, use this method overload instead of the method overload, which throws an exception if the synchronization event does not exist. - The `rights` parameter must include the flag to allow threads to wait on the event, and the flag to allow threads to call the and methods. + The `rights` parameter must include the flag to allow threads to wait on the event, and the flag to allow threads to call the and methods. Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system event. @@ -1356,7 +1356,7 @@ There was some other error. The `HResult` property might provide more informatio If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. However, if `options` specifies access limited to the current user and the synchronization object is not compatible with it, `false` is returned. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, `false` is returned as well. -To create the system event when it does not already exist, use one of the constructors that has a `name` parameter. +To create the system event when it does not already exist, use one of the constructors that has a `name` parameter. If you are uncertain whether a named synchronization event exists, use this method overload instead of the method overload, which throws an exception if the synchronization event does not exist. diff --git a/xml/System.Threading/ExecutionContext.xml b/xml/System.Threading/ExecutionContext.xml index 536d759b508..5b483cdf3a6 100644 --- a/xml/System.Threading/ExecutionContext.xml +++ b/xml/System.Threading/ExecutionContext.xml @@ -83,7 +83,7 @@ - The following is applicable to .NET Framework only. - - An execution context is the managed equivalent of a COM apartment. Within an application domain, the entire execution context must be transferred whenever a thread is transferred. This situation occurs during transfers made by the method, most thread pool operations, and Windows Forms thread marshaling through the Windows message pump. It does not occur in unsafe thread pool operations (such as the method), which do not transfer the compressed stack. Wherever the compressed stack flows, the managed principal, synchronization, locale, and user context also flow. The class provides the and methods to get the execution context and the method to set the execution context for the current thread. + An execution context is the managed equivalent of a COM apartment. Within an application domain, the entire execution context must be transferred whenever a thread is transferred. This situation occurs during transfers made by the method, most thread pool operations, and Windows Forms thread marshaling through the Windows message pump. It does not occur in unsafe thread pool operations (such as the method), which do not transfer the compressed stack. Wherever the compressed stack flows, the managed principal, synchronization, locale, and user context also flow. The class provides the and methods to get the execution context and the method to set the execution context for the current thread. An that is associated with a thread cannot be set on another thread. Attempting to do so will result in an exception being thrown. To propagate the from one thread to another, make a copy of the . @@ -144,7 +144,7 @@ method. + The captured execution context can be used as the `executionContext` parameter for the method. ]]> @@ -332,7 +332,7 @@ sets a with the logical call context information. During deserialization, the execution context object is reconstituted from the transmitted over the stream. + .NET Framework only: sets a with the logical call context information. During deserialization, the execution context object is reconstituted from the transmitted over the stream. For more information, see . @@ -388,7 +388,7 @@ method is used by infrastructure components to determine whether to transfer the during asynchronous operations. + The method is used by infrastructure components to determine whether to transfer the during asynchronous operations. ]]> @@ -488,9 +488,9 @@ To revert to the current execution context; capture it before calling Restore, a reverses the effect of a prior method call. + reverses the effect of a prior method call. - This method is called by the method of the structure returned by the method. You should use the method to restore the flow of the execution context, not the method. + This method is called by the method of the structure returned by the method. You should use the method to restore the flow of the execution context, not the method. ]]> @@ -628,7 +628,7 @@ To revert to the current execution context; capture it before calling Restore, a ## Remarks Use this method to suppress the flow of the on the current thread. - You must use the method on the returned structure to restore the flow of the . + You must use the method on the returned structure to restore the flow of the . ]]> diff --git a/xml/System.Threading/HostExecutionContext.xml b/xml/System.Threading/HostExecutionContext.xml index 3830adbe977..bec7e599b5e 100644 --- a/xml/System.Threading/HostExecutionContext.xml +++ b/xml/System.Threading/HostExecutionContext.xml @@ -221,7 +221,7 @@ method call. + The copy can be used as the parameter to a method call. ]]> diff --git a/xml/System.Threading/HostExecutionContextManager.xml b/xml/System.Threading/HostExecutionContextManager.xml index adefb7bdf4d..dfb882a31dc 100644 --- a/xml/System.Threading/HostExecutionContextManager.xml +++ b/xml/System.Threading/HostExecutionContextManager.xml @@ -54,7 +54,7 @@ has a reference to a in its property, then the common language runtime calls the manager every time a call to the method occurs, to allow the host to participate in the flow of the execution context. + If the current has a reference to a in its property, then the common language runtime calls the manager every time a call to the method occurs, to allow the host to participate in the flow of the execution context. ]]> @@ -208,7 +208,7 @@ method. + `previousState` must be the object returned by the method. ]]> @@ -276,9 +276,9 @@ method sets the host execution context for the current . A that has been used as the argument to another method call cannot be passed in as the parameter for this method. Instead, use the method to create a copy of a object and then use the copy to set the host execution context. + The method sets the host execution context for the current . A that has been used as the argument to another method call cannot be passed in as the parameter for this method. Instead, use the method to create a copy of a object and then use the copy to set the host execution context. - Call the method using the object returned by this method to restore the to its previous state. + Call the method using the object returned by this method to restore the to its previous state. ]]> diff --git a/xml/System.Threading/Interlocked.xml b/xml/System.Threading/Interlocked.xml index 345cd194b9b..c4577649a29 100644 --- a/xml/System.Threading/Interlocked.xml +++ b/xml/System.Threading/Interlocked.xml @@ -68,17 +68,17 @@ ## Remarks The methods of this class help protect against errors that can occur when the scheduler switches contexts while a thread is updating a variable that can be accessed by other threads, or when two threads are executing concurrently on separate processors. The members of this class do not throw exceptions. - The and methods increment or decrement a variable and store the resulting value in a single operation. On most computers, incrementing a variable is not an atomic operation, requiring the following steps: + The and methods increment or decrement a variable and store the resulting value in a single operation. On most computers, incrementing a variable is not an atomic operation, requiring the following steps: 1. Load a value from an instance variable into a register. 2. Increment or decrement the value. 3. Store the value in the instance variable. - If you do not use and , a thread can be preempted after executing the first two steps. Another thread can then execute all three steps. When the first thread resumes execution, it overwrites the value in the instance variable, and the effect of the increment or decrement performed by the second thread is lost. + If you do not use and , a thread can be preempted after executing the first two steps. Another thread can then execute all three steps. When the first thread resumes execution, it overwrites the value in the instance variable, and the effect of the increment or decrement performed by the second thread is lost. - The method atomically adds an integer value to an integer variable and returns the new value of the variable. + The method atomically adds an integer value to an integer variable and returns the new value of the variable. - The method atomically exchanges the values of the specified variables. The method combines two operations: comparing two values and storing a third value in one of the variables, based on the outcome of the comparison. The compare and exchange operations are performed as an atomic operation. + The method atomically exchanges the values of the specified variables. The method combines two operations: comparing two values and storing a third value in one of the variables, based on the outcome of the comparison. The compare and exchange operations are performed as an atomic operation. Ensure that any write or read access to a shared variable is atomic. Otherwise, the data might be corrupted or the loaded value might be incorrect. @@ -661,12 +661,12 @@ is the original value in `location1`, whether or not the exchange takes place. + If `comparand` and the value in `location1` are equal, then `value` is stored in `location1`. Otherwise, no operation is performed. The compare and exchange operations are performed as an atomic operation. The return value of is the original value in `location1`, whether or not the exchange takes place. ## Examples The following code example demonstrates a thread-safe method that accumulates a running total of values. Two threads add a series of values using the thread-safe method and ordinary addition, and when the threads complete the totals are compared. On a dual-processor computer, there is a significant difference in the totals. - In the thread-safe method, the initial value of the running total is saved, and then the method is used to exchange the newly computed total with the old total. If the return value is not equal to the saved value of the running total, then another thread has updated the total in the meantime. In that case, the attempt to update the running total must be repeated. + In the thread-safe method, the initial value of the running total is saved, and then the method is used to exchange the newly computed total with the old total. If the return value is not equal to the saved value of the running total, then another thread has updated the total in the meantime. In that case, the attempt to update the running total must be repeated. :::code language="csharp" source="~/snippets/csharp/System.Threading/Interlocked/CompareExchange/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Interlocked/CompareExchange/source.vb" id="Snippet1"::: @@ -779,13 +779,13 @@ is the original value in `location1`, whether or not the exchange takes place. + If `comparand` and the value in `location1` are equal, then `value` is stored in `location1`. Otherwise, no operation is performed. The compare and exchange operations are performed as an atomic operation. The return value of is the original value in `location1`, whether or not the exchange takes place. ## Examples - The following code example demonstrates a thread-safe method that accumulates a running total. The initial value of the running total is saved, and then the method is used to exchange the newly computed total with the old total. If the return value is not equal to the saved value of the running total, then another thread has updated the total in the meantime. In that case, the attempt to update the running total must be repeated. + The following code example demonstrates a thread-safe method that accumulates a running total. The initial value of the running total is saved, and then the method is used to exchange the newly computed total with the old total. If the return value is not equal to the saved value of the running total, then another thread has updated the total in the meantime. In that case, the attempt to update the running total must be repeated. > [!NOTE] -> The method provides a more convenient way to accumulate thread-safe running totals for integers. +> The method provides a more convenient way to accumulate thread-safe running totals for integers. :::code language="csharp" source="~/snippets/csharp/System.Threading/Interlocked/CompareExchange/source2.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Interlocked/CompareExchange/source2.vb" id="Snippet1"::: @@ -855,7 +855,7 @@ is the original value in `location1`, whether or not the exchange takes place. + If `comparand` and the value in `location1` are equal, then `value` is stored in `location1`. Otherwise, no operation is performed. The compare and exchange operations are performed as an atomic operation. The return value of is the original value in `location1`, whether or not the exchange takes place. ]]> @@ -1004,9 +1004,9 @@ ## Remarks > [!IMPORTANT] -> The method overload provides a generic alternative that can be used for concrete reference types. +> The method overload provides a generic alternative that can be used for concrete reference types. -If `comparand` and the object in `location1` are equal by reference, then `value` is stored in `location1`. Otherwise, no operation is performed. The compare and exchange operations are performed as an atomic operation. The return value of is the original value in `location1`, whether or not the exchange takes place. +If `comparand` and the object in `location1` are equal by reference, then `value` is stored in `location1`. Otherwise, no operation is performed. The compare and exchange operations are performed as an atomic operation. The return value of is the original value in `location1`, whether or not the exchange takes place. > [!NOTE] > The objects are compared for reference equality rather than value equality. As a result, two boxed instances of the same value type (for example, the integer 3) always appear to be unequal and no operation is performed. Do not use this overload with value types. @@ -1121,14 +1121,14 @@ If `comparand` and the object in `location1` are equal by reference, then `value is the original value in `location1`, whether or not the exchange takes place. + If `comparand` and the value in `location1` are equal, then `value` is stored in `location1`. Otherwise, no operation is performed. The compare and exchange operations are performed as an atomic operation. The return value of is the original value in `location1`, whether or not the exchange takes place. ## Examples The following code example demonstrates a thread-safe method that accumulates a running total of values. Two threads add a series of values using the thread-safe method and ordinary addition, and when the threads complete the totals are compared. On a dual-processor computer, there is a significant difference in the totals. - In the thread-safe method, the initial value of the running total is saved, and then the method is used to exchange the newly computed total with the old total. If the return value is not equal to the saved value of the running total, then another thread has updated the total in the meantime. In that case, the attempt to update the running total must be repeated. + In the thread-safe method, the initial value of the running total is saved, and then the method is used to exchange the newly computed total with the old total. If the return value is not equal to the saved value of the running total, then another thread has updated the total in the meantime. In that case, the attempt to update the running total must be repeated. :::code language="csharp" source="~/snippets/csharp/System.Threading/Interlocked/CompareExchange/source1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Interlocked/CompareExchange/source1.vb" id="Snippet1"::: @@ -1495,12 +1495,12 @@ If `comparand` and the value in `location1` are equal by reference, then `value` ## Examples - The following example determines how many random numbers that range from 0 to 1,000 are required to generate 1,000 random numbers with a midpoint value. To keep track of the number of midpoint values, a variable, `midpointCount`, is set equal to 1,000 and decremented each time the random number generator returns a midpoint value. Because three threads generate the random numbers, the method is called to ensure that multiple threads don't update `midpointCount` concurrently. Note that a lock is also used to protect the random number generator, and that a object is used to ensure that the `Main` method doesn't finish execution before the three threads. + The following example determines how many random numbers that range from 0 to 1,000 are required to generate 1,000 random numbers with a midpoint value. To keep track of the number of midpoint values, a variable, `midpointCount`, is set equal to 1,000 and decremented each time the random number generator returns a midpoint value. Because three threads generate the random numbers, the method is called to ensure that multiple threads don't update `midpointCount` concurrently. Note that a lock is also used to protect the random number generator, and that a object is used to ensure that the `Main` method doesn't finish execution before the three threads. :::code language="csharp" source="~/snippets/csharp/System.Threading/Interlocked/Decrement/decrement1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Interlocked/Decrement/decrement1.vb" id="Snippet1"::: - The following example is similar to the previous one, except that it uses the class instead of a thread procedure to generate 50,000 random midpoint integers. In this example, a lambda expression replaces the `GenerateNumbers` thread procedure, and the call to the method eliminates the need for the object. + The following example is similar to the previous one, except that it uses the class instead of a thread procedure to generate 50,000 random midpoint integers. In this example, a lambda expression replaces the `GenerateNumbers` thread procedure, and the call to the method eliminates the need for the object. :::code language="csharp" source="~/snippets/csharp/System.Threading/Interlocked/Decrement/decrement2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Interlocked/Decrement/decrement2.vb" id="Snippet2"::: @@ -2075,7 +2075,7 @@ If `comparand` and the value in `location1` are equal by reference, then `value` ## Remarks > [!IMPORTANT] -> The method overload provides a generic alternative that can be used for concrete reference types. +> The method overload provides a generic alternative that can be used for concrete reference types. ]]> @@ -2530,12 +2530,12 @@ If `comparand` and the value in `location1` are equal by reference, then `value` ## Examples - The following example determines how many random numbers that range from 0 to 1,000 are required to generate 1,000 random numbers with a midpoint value. To keep track of the number of midpoint values, a variable, `midpointCount`, is set equal to 0 and incremented each time the random number generator returns a midpoint value until it reaches 10,000. Because three threads generate the random numbers, the method is called to ensure that multiple threads don't update `midpointCount` concurrently. Note that a lock is also used to protect the random number generator, and that a object is used to ensure that the `Main` method doesn't finish execution before the three threads. + The following example determines how many random numbers that range from 0 to 1,000 are required to generate 1,000 random numbers with a midpoint value. To keep track of the number of midpoint values, a variable, `midpointCount`, is set equal to 0 and incremented each time the random number generator returns a midpoint value until it reaches 10,000. Because three threads generate the random numbers, the method is called to ensure that multiple threads don't update `midpointCount` concurrently. Note that a lock is also used to protect the random number generator, and that a object is used to ensure that the `Main` method doesn't finish execution before the three threads. :::code language="csharp" source="~/snippets/csharp/System.Threading/Interlocked/Increment/increment3.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Interlocked/Increment/Increment3.vb" id="Snippet3"::: - The following example is similar to the previous one, except that it uses the class instead of a thread procedure to generate 50,000 random midpoint integers. In this example, a lambda expression replaces the `GenerateNumbers` thread procedure, and the call to the method eliminates the need for the object. + The following example is similar to the previous one, except that it uses the class instead of a thread procedure to generate 50,000 random midpoint integers. In this example, a lambda expression replaces the `GenerateNumbers` thread procedure, and the call to the method eliminates the need for the object. :::code language="csharp" source="~/snippets/csharp/System.Threading/Interlocked/Increment/increment4.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Interlocked/Increment/Increment4.vb" id="Snippet4"::: @@ -2755,7 +2755,7 @@ If `comparand` and the value in `location1` are equal by reference, then `value` class in the .NET Framework 4.5 as a convenience; it's a wrapper for the method. + This method was added to the class in the .NET Framework 4.5 as a convenience; it's a wrapper for the method. For most purposes, the C# `lock` statement, the Visual Basic `SyncLock` statement, or the class provide easier ways to synchronize data. @@ -2800,7 +2800,7 @@ If `comparand` and the value in `location1` are equal by reference, then `value` method as follows: +The `MemoryBarrierProcessWide` method differs from the "normal" method as follows: - The normal memory barrier ensures that the reads and writes from the current CPU can't move across the barrier. The process-wide memory barrier ensures that any read or write from any CPU being used in the process can't move across the barrier. @@ -3088,10 +3088,10 @@ This method wraps a call to [FlushProcessWriteBuffers](/windows/win32/api/proces method is unnecessary on 64-bit systems, because 64-bit read operations are already atomic. On 32-bit systems, 64-bit read operations are not atomic unless performed using . + The method is unnecessary on 64-bit systems, because 64-bit read operations are already atomic. On 32-bit systems, 64-bit read operations are not atomic unless performed using . > [!IMPORTANT] -> On 32-bit platforms, despite taking a readonly reference parameter, this method requires write access to the memory location because it uses internally to ensure atomicity. Attempting to read from read-only memory (such as memory-mapped files opened with read-only access) can result in an . +> On 32-bit platforms, despite taking a readonly reference parameter, this method requires write access to the memory location because it uses internally to ensure atomicity. Attempting to read from read-only memory (such as memory-mapped files opened with read-only access) can result in an . ]]> @@ -3155,10 +3155,10 @@ This method wraps a call to [FlushProcessWriteBuffers](/windows/win32/api/proces method is unnecessary on 64-bit systems, because 64-bit read operations are already atomic. On 32-bit systems, 64-bit read operations are not atomic unless performed using . + The method is unnecessary on 64-bit systems, because 64-bit read operations are already atomic. On 32-bit systems, 64-bit read operations are not atomic unless performed using . > [!IMPORTANT] -> On 32-bit platforms, despite taking a readonly reference parameter, this method requires write access to the memory location because it uses internally to ensure atomicity. Attempting to read from read-only memory (such as memory-mapped files opened with read-only access) can result in an . +> On 32-bit platforms, despite taking a readonly reference parameter, this method requires write access to the memory location because it uses internally to ensure atomicity. Attempting to read from read-only memory (such as memory-mapped files opened with read-only access) can result in an . ]]> diff --git a/xml/System.Threading/LazyThreadSafetyMode.xml b/xml/System.Threading/LazyThreadSafetyMode.xml index ab8e633287f..73ad4ae8432 100644 --- a/xml/System.Threading/LazyThreadSafetyMode.xml +++ b/xml/System.Threading/LazyThreadSafetyMode.xml @@ -56,11 +56,11 @@ constructors. The effects of all constructors on thread synchronization can be described in terms of this enumeration, whether or not they have `mode` parameters. + Use this enumeration to specify the `mode` parameter of constructors. The effects of all constructors on thread synchronization can be described in terms of this enumeration, whether or not they have `mode` parameters. - A instance is initialized either by a user-specified initialization method or by the parameterless constructor for `T`. The initialization method is specified by the `valueFactory` parameter of a constructor. The method returns an instance of `T`, which is the type that is lazily instantiated by the instance of . If a constructor does not have a `valueFactory` parameter, the parameterless constructor for `T` is used to initialize the instance. In either case, initialization occurs the first time you call the property. + A instance is initialized either by a user-specified initialization method or by the parameterless constructor for `T`. The initialization method is specified by the `valueFactory` parameter of a constructor. The method returns an instance of `T`, which is the type that is lazily instantiated by the instance of . If a constructor does not have a `valueFactory` parameter, the parameterless constructor for `T` is used to initialize the instance. In either case, initialization occurs the first time you call the property. - In addition to specifying the thread safety of a instance, this enumeration affects exception caching. When exceptions are cached for a instance, you get only one chance to initialize the instance. If an exception is thrown the first time you call the property, that exception is cached and rethrown on all subsequent calls to the property. The advantage of caching exceptions is that any two threads always get the same result, even when errors occur. + In addition to specifying the thread safety of a instance, this enumeration affects exception caching. When exceptions are cached for a instance, you get only one chance to initialize the instance. If an exception is thrown the first time you call the property, that exception is cached and rethrown on all subsequent calls to the property. The advantage of caching exceptions is that any two threads always get the same result, even when errors occur. When you specify the PublicationOnly mode, exceptions are never cached. When you specify None or ExecutionAndPublication, caching depends on whether you specify an initialization method or allow the parameterless constructor for `T` to be used. Specifying an initialization method enables exception caching for these two modes. The initialization method can be very simple. For example, it might call the parameterless constructor for `T`: `new Lazy(() => new Contents(), mode)` in C#, or `New Lazy(Of Contents)(Function() New Contents())` in Visual Basic. If you use a constructor that does not specify an initialization method, exceptions that are thrown by the parameterless constructor for `T` are not cached. The following table summarizes exception caching behavior. diff --git a/xml/System.Threading/Lock+Scope.xml b/xml/System.Threading/Lock+Scope.xml index 2c043839069..a3aa7569a3c 100644 --- a/xml/System.Threading/Lock+Scope.xml +++ b/xml/System.Threading/Lock+Scope.xml @@ -32,9 +32,9 @@ ## Remarks -This type is intended to be used with the method, which returns a representing the lock that was entered, and with a language construct that automatically disposes the , such as the C# `using` keyword. Disposing the `Scope` exits the lock. Ensure that is called even in case of exceptions. +This type is intended to be used with the method, which returns a representing the lock that was entered, and with a language construct that automatically disposes the , such as the C# `using` keyword. Disposing the `Scope` exits the lock. Ensure that is called even in case of exceptions. -For more information, see and the Remarks for . +For more information, see and the Remarks for . ]]> @@ -65,7 +65,7 @@ For more information, see and the Rem ## Remarks -If the current thread holds the lock multiple times, such as recursively, the lock is exited only once. The current thread should ensure that each is matched with a on the `Scope` returned by `EnterScope`. +If the current thread holds the lock multiple times, such as recursively, the lock is exited only once. The current thread should ensure that each is matched with a on the `Scope` returned by `EnterScope`. For more information, see the Remarks for . diff --git a/xml/System.Threading/Lock.xml b/xml/System.Threading/Lock.xml index e18f1451b17..4bd546efd2f 100644 --- a/xml/System.Threading/Lock.xml +++ b/xml/System.Threading/Lock.xml @@ -24,17 +24,17 @@ The class can be used to define regions of code that require mutually exclusive access between threads of a process, commonly called critical sections, to prevent concurrent accesses to a resource. A `Lock` can be entered and exited, where the region of code between the enter and exit is a critical section associated with the lock. A thread that enters a lock is said to hold or own the lock until it exits the lock. At most one thread can hold a lock at any given time. A thread can hold multiple locks. A thread can enter a lock multiple times before exiting it, such as recursively. A thread that can't enter a lock immediately can wait until the lock can be entered or until a specified timeout expires. -When using the or methods to enter a lock: -- Ensure that the thread exits the lock with even in case of exceptions, such as in C# by using a `try/finally` block. +When using the or methods to enter a lock: +- Ensure that the thread exits the lock with even in case of exceptions, such as in C# by using a `try/finally` block. - When the lock is being entered and exited in a C# `async` method, ensure that there is no `await` between the enter and exit. Locks are held by threads and the code following an `await` might run on a different thread. -It is recommended to use the method with a language construct that automatically disposes the returned such as the C# `using` keyword, or to use the C# `lock` keyword, as these ensure that the lock is exited in exceptional cases. These patterns might also have performance benefits over using `Enter/TryEnter` and `Exit`. The following code fragment illustrates various patterns for entering and exiting a lock. +It is recommended to use the method with a language construct that automatically disposes the returned such as the C# `using` keyword, or to use the C# `lock` keyword, as these ensure that the lock is exited in exceptional cases. These patterns might also have performance benefits over using `Enter/TryEnter` and `Exit`. The following code fragment illustrates various patterns for entering and exiting a lock. :::code language="csharp" source="~/snippets/csharp/System.Threading/Lock/Overview/UsagePatterns.cs" id="Snippet1"::: When using the C# `lock` keyword or similar to enter and exit a lock, the type of the expression must be precisely `System.Threading.Lock`. If the type of the expression is anything else, such as `Object` or a generic type like `T`, a different implementation that is not interchangeable can be used instead (such as ). For more information, see the relevant [compiler speclet](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/csharp-13.0/lock-object). - can interrupt threads that are waiting to enter a lock. On Windows STA threads, waits for locks allow message pumping that can run other code on the same thread during a wait. Some features of the waits can be overridden by a custom . + can interrupt threads that are waiting to enter a lock. On Windows STA threads, waits for locks allow message pumping that can run other code on the same thread during a wait. Some features of the waits can be overridden by a custom . > [!NOTE] > A thread that enters a lock, including multiple times such as recursively, must exit the lock the same number of times to fully exit the lock and allow other threads to enter the lock. If a thread exits while holding a `Lock`, the behavior of the `Lock` becomes undefined. diff --git a/xml/System.Threading/LockCookie.xml b/xml/System.Threading/LockCookie.xml index d4deb2dd9b8..85cd60ba3aa 100644 --- a/xml/System.Threading/LockCookie.xml +++ b/xml/System.Threading/LockCookie.xml @@ -71,7 +71,7 @@ The following example shows how to request a reader lock, upgrade the reader lock to a writer lock, and save the . It then uses the to downgrade to a reader lock again. This code is part of a larger example provided for the class. - + :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/LockCookie/Overview/source.vb" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet5"::: @@ -290,7 +290,7 @@ if is equal to ; otherwise, . - .]]> + .]]> @@ -340,7 +340,7 @@ if is not equal to ; otherwise, . - .]]> + .]]> diff --git a/xml/System.Threading/LockRecursionException.xml b/xml/System.Threading/LockRecursionException.xml index 135234acb6f..09cc96a89ff 100644 --- a/xml/System.Threading/LockRecursionException.xml +++ b/xml/System.Threading/LockRecursionException.xml @@ -152,8 +152,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The localized error message string.| +||`null`.| +||The localized error message string.| ]]> @@ -214,8 +214,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string.| +||`null`.| +||The error message string.| ]]> @@ -342,8 +342,8 @@ |Property|Value| |--------------|-----------| -||The exception specified in `innerException`.| -||The error message string specified in `message`.| +||The exception specified in `innerException`.| +||The error message string specified in `message`.| ]]> diff --git a/xml/System.Threading/ManualResetEvent.xml b/xml/System.Threading/ManualResetEvent.xml index 89a519f6991..bc87a85f3c5 100644 --- a/xml/System.Threading/ManualResetEvent.xml +++ b/xml/System.Threading/ManualResetEvent.xml @@ -69,11 +69,11 @@ When a thread begins an activity that must complete before other threads proceed, it calls [ManualResetEvent.Reset](xref:System.Threading.EventWaitHandle.Reset%2A) to put `ManualResetEvent` in the non-signaled state. This thread can be thought of as controlling the `ManualResetEvent`. Threads that call [ManualResetEvent.WaitOne](xref:System.Threading.WaitHandle.WaitOne%2A) block, awaiting the signal. When the controlling thread completes the activity, it calls [ManualResetEvent.Set](xref:System.Threading.EventWaitHandle.Set%2A) to signal that the waiting threads can proceed. All waiting threads are released. - Once it has been signaled, `ManualResetEvent` remains signaled until it is manually reset by calling the method. That is, calls to return immediately. + Once it has been signaled, `ManualResetEvent` remains signaled until it is manually reset by calling the method. That is, calls to return immediately. You can control the initial state of a `ManualResetEvent` by passing a Boolean value to the constructor: `true` if the initial state is signaled, and `false` otherwise. - `ManualResetEvent` can also be used with the `static` and methods. + `ManualResetEvent` can also be used with the `static` and methods. Beginning with the .NET Framework version 2.0, derives from the class. A is functionally equivalent to an created with . @@ -85,12 +85,12 @@ ## Examples - The following example demonstrates how works. The example starts with a in the unsignaled state (that is, `false` is passed to the constructor). The example creates three threads, each of which blocks on the by calling its method. When the user presses the **Enter** key, the example calls the method, which releases all three threads. Contrast this with the behavior of the class, which releases threads one at a time, resetting automatically after each release. + The following example demonstrates how works. The example starts with a in the unsignaled state (that is, `false` is passed to the constructor). The example creates three threads, each of which blocks on the by calling its method. When the user presses the **Enter** key, the example calls the method, which releases all three threads. Contrast this with the behavior of the class, which releases threads one at a time, resetting automatically after each release. - Pressing the **Enter** key again demonstrates that the remains in the signaled state until its method is called: The example starts two more threads. These threads do not block when they call the method, but instead run to completion. + Pressing the **Enter** key again demonstrates that the remains in the signaled state until its method is called: The example starts two more threads. These threads do not block when they call the method, but instead run to completion. + + Pressing the **Enter** key again causes the example to call the method and to start one more thread, which blocks when it calls . Pressing the **Enter** key one final time calls to release the last thread, and the program ends. - Pressing the **Enter** key again causes the example to call the method and to start one more thread, which blocks when it calls . Pressing the **Enter** key one final time calls to release the last thread, and the program ends. - :::code language="csharp" source="~/snippets/csharp/System.Threading/ManualResetEvent/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/ManualResetEvent/Overview/source.vb" id="Snippet1"::: @@ -154,7 +154,7 @@ is signaled (that is, if it is created by passing `true` for `initialState`), threads that wait on the do not block. If the initial state is nonsignaled, threads block until the method is called. + If the initial state of a is signaled (that is, if it is created by passing `true` for `initialState`), threads that wait on the do not block. If the initial state is nonsignaled, threads block until the method is called. ]]> diff --git a/xml/System.Threading/ManualResetEventSlim.xml b/xml/System.Threading/ManualResetEventSlim.xml index 55631d87ab7..db3d20a2b6d 100644 --- a/xml/System.Threading/ManualResetEventSlim.xml +++ b/xml/System.Threading/ManualResetEventSlim.xml @@ -61,21 +61,21 @@ Represents a thread synchronization event that, when signaled, must be reset manually. This class is a lightweight alternative to . - when wait times are expected to be very short, and when the event does not cross a process boundary. uses busy spinning for a short time while it waits for the event to become signaled. When wait times are short, spinning can be much less expensive than waiting by using wait handles. However, if the event does not become signaled within a certain period of time, resorts to a regular event handle wait. - + when wait times are expected to be very short, and when the event does not cross a process boundary. uses busy spinning for a short time while it waits for the event to become signaled. When wait times are short, spinning can be much less expensive than waiting by using wait handles. However, if the event does not become signaled within a certain period of time, resorts to a regular event handle wait. + > [!NOTE] -> In .NET Core and .NET 5+, the default spin-waiting duration is short: on the order of 10s of microseconds, depending on platform and processor. If you expect wait times to be much longer than that, you can still use this class instead of (perhaps configured with less or no spin-waiting). However, the performance benefit would likely be only marginal. - - -## Examples +> In .NET Core and .NET 5+, the default spin-waiting duration is short: on the order of 10s of microseconds, depending on platform and processor. If you expect wait times to be much longer than that, you can still use this class instead of (perhaps configured with less or no spin-waiting). However, the performance benefit would likely be only marginal. + + +## Examples The following example shows how to use a . - + :::code language="csharp" source="~/snippets/csharp/System.Threading/ManualResetEventSlim/Overview/mres.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/System.Threading/ManualResetEventSlim/Overview/mres.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Threading/ManualResetEventSlim/Overview/mres.vb" id="Snippet01"::: + ]]> All public and protected members of are thread-safe and may be used concurrently from multiple threads, with the exception of Dispose, which must only be used when all other operations on the have completed, and Reset, which should only be used when no other threads are accessing the event. @@ -278,16 +278,16 @@ Releases all resources used by the current instance of the class. - . 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 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). - + . 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 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 `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. + ]]> Overview of synchronization primitives @@ -336,11 +336,11 @@ true to release both managed and unmanaged resources; false to release only unmanaged resources. Releases the unmanaged resources used by the , and optionally releases the managed resources. - , is not thread-safe and may not be used concurrently with other members of this instance. - + , is not thread-safe and may not be used concurrently with other members of this instance. + ]]> Overview of synchronization primitives @@ -429,11 +429,11 @@ Sets the state of the event to nonsignaled, which causes threads to block. - can be called concurrently with all members except . - + can be called concurrently with all members except . + ]]> The object has already been disposed. @@ -584,11 +584,11 @@ Blocks the current thread until the current is set. - The maximum number of waiters has been exceeded. @@ -703,11 +703,11 @@ The to observe. Blocks the current thread until the current receives a signal, while observing a . - The maximum number of waiters has been exceeded. @@ -772,10 +772,10 @@ if the was set; otherwise, . To be added. - is a negative number other than -1 milliseconds, which represents an infinite time-out. - - -or- - + is a negative number other than -1 milliseconds, which represents an infinite time-out. + + -or- + The number of milliseconds in is greater than Int32.MaxValue. The maximum number of waiters has been exceeded. The object has already been disposed. @@ -898,10 +898,10 @@ if the was set; otherwise, . To be added. - is a negative number other than -1 milliseconds, which represents an infinite time-out. - - -or- - + is a negative number other than -1 milliseconds, which represents an infinite time-out. + + -or- + The number of milliseconds in is greater than Int32.MaxValue. The maximum number of waiters has been exceeded. The object has already been disposed or the that created has been disposed. @@ -956,11 +956,11 @@ Gets the underlying object for this . The underlying event object for this . - , the public Wait methods should be preferred. It is recommended to dispose the instance after accessing this property, in order to prevent a resource leak. - + , the public Wait methods should be preferred. It is recommended to dispose the instance after accessing this property, in order to prevent a resource leak. + ]]> Overview of synchronization primitives diff --git a/xml/System.Threading/Monitor.xml b/xml/System.Threading/Monitor.xml index 9b67fba4e66..113289971f3 100644 --- a/xml/System.Threading/Monitor.xml +++ b/xml/System.Threading/Monitor.xml @@ -134,13 +134,13 @@ on the object passed as the parameter. If another thread has executed an `Enter` on the object but has not yet executed the corresponding , the current thread will block until the other thread releases the object. It is legal for the same thread to invoke `Enter` more than once without it blocking; however, an equal number of `Exit` calls must be invoked before other threads waiting on the object will unblock. + Use `Enter` to acquire the on the object passed as the parameter. If another thread has executed an `Enter` on the object but has not yet executed the corresponding , the current thread will block until the other thread releases the object. It is legal for the same thread to invoke `Enter` more than once without it blocking; however, an equal number of `Exit` calls must be invoked before other threads waiting on the object will unblock. Use to lock objects (that is, reference types), not value types. When you pass a value type variable to `Enter`, it is boxed as an object. If you pass the same variable to `Enter` again, it is boxed as a separate object, and the thread does not block. In this case, the code that `Monitor` is supposedly protecting is not protected. Furthermore, when you pass the variable to `Exit`, still another separate object is created. Because the object passed to `Exit` is different from the object passed to `Enter`, `Monitor` throws . For more information, see the conceptual topic [Monitors](xref:System.Threading.Monitor). - can interrupt threads that are waiting to enter a `Monitor` on an object. A will be thrown. + can interrupt threads that are waiting to enter a `Monitor` on an object. A will be thrown. - Use a C# `try`…`finally` block (`Try`…`Finally` in Visual Basic) to ensure that you release the monitor, or use the C# `lock` statement (`SyncLock` statement in Visual Basic), which wraps the and methods in a `try`…`finally` block. + Use a C# `try`…`finally` block (`Try`…`Finally` in Visual Basic) to ensure that you release the monitor, or use the C# `lock` statement (`SyncLock` statement in Visual Basic), which wraps the and methods in a `try`…`finally` block. @@ -218,18 +218,18 @@ on the object passed as the `obj` parameter. If another thread has executed an `Enter` on the object but has not yet executed the corresponding , the current thread will block until the other thread releases the object. It is legal for the same thread to invoke `Enter` more than once without it blocking; however, an equal number of `Exit` calls must be invoked before other threads waiting on the object will unblock. + Use `Enter` to acquire the on the object passed as the `obj` parameter. If another thread has executed an `Enter` on the object but has not yet executed the corresponding , the current thread will block until the other thread releases the object. It is legal for the same thread to invoke `Enter` more than once without it blocking; however, an equal number of `Exit` calls must be invoked before other threads waiting on the object will unblock. If the lock was not taken because an exception was thrown, the variable specified for the `lockTaken` parameter is `false` after this method ends. This allows the program to determine, in all cases, whether it is necessary to release the lock. If this method returns without throwing an exception, the variable specified for the `lockTaken` parameter is always `true`, and there is no need to test it. Use to lock objects (that is, reference types), not value types. When you pass a value type variable to `Enter`, it is boxed as an object. If you pass the same variable to `Enter` again, it is boxed as a separate object, and the thread does not block. In this case, the code that `Monitor` is supposedly protecting is not protected. Furthermore, when you pass the variable to `Exit`, another separate object is created. Because the object passed to `Exit` is different from the object passed to `Enter`, `Monitor` throws . For more information, see the conceptual topic [Monitors](xref:System.Threading.Monitor). - can interrupt threads that are waiting to enter a `Monitor` on an object. A will be thrown. + can interrupt threads that are waiting to enter a `Monitor` on an object. A will be thrown. ## Examples - The following code shows the basic pattern for using the method overload. This overload always sets the value of the variable that is passed to the `ref` parameter (`ByRef` in Visual Basic) `lockTaken`, even if the method throws an exception, so the value of the variable is a reliable way to test whether the lock has to be released. + The following code shows the basic pattern for using the method overload. This overload always sets the value of the variable that is passed to the `ref` parameter (`ByRef` in Visual Basic) `lockTaken`, even if the method throws an exception, so the value of the variable is a reliable way to test whether the lock has to be released. :::code language="csharp" source="~/snippets/csharp/System.Threading/Monitor/Enter/example.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Monitor/Enter/example.vb" id="Snippet2"::: @@ -298,9 +298,9 @@ calls for the object, then the lock is released. If the calling thread has not invoked `Exit` as many times as `Enter`, the lock is not released. + The calling thread must own the lock on the `obj` parameter. If the calling thread owns the lock on the specified object, and has made an equal number of `Exit` and calls for the object, then the lock is released. If the calling thread has not invoked `Exit` as many times as `Enter`, the lock is not released. - If the lock is released and other threads are in the ready queue for the object, one of the threads acquires the lock. If other threads are in the waiting queue waiting to acquire the lock, they are not automatically moved to the ready queue when the owner of the lock calls `Exit`. To move one or more waiting threads into the ready queue, call or before invoking `Exit`. + If the lock is released and other threads are in the ready queue for the object, one of the threads acquires the lock. If other threads are in the waiting queue waiting to acquire the lock, they are not automatically moved to the ready queue when the owner of the lock calls `Exit`. To move one or more waiting threads into the ready queue, call or before invoking `Exit`. @@ -375,7 +375,7 @@ ## Remarks This method works only for locks that are acquired by using the methods of the class, or by using the C# `lock` statement or the Visual Basic `SyncLock` statement, which are implemented with . - Use this method with diagnostic tools, such as the method and the class, to debug locking issues that involve the class. + Use this method with diagnostic tools, such as the method and the class, to debug locking issues that involve the class. ]]> @@ -477,13 +477,13 @@ The thread that currently owns the lock on the specified object invokes this method to signal the next thread in line for the lock. Upon receiving the pulse, the waiting thread is moved to the ready queue. When the thread that invoked `Pulse` releases the lock, the next thread in the ready queue (which is not necessarily the thread that was pulsed) acquires the lock. > [!IMPORTANT] -> The class does not maintain state indicating that the method has been called. Thus, if you call when no threads are waiting, the next thread that calls blocks as if had never been called. If two threads are using and to interact, this could result in a deadlock. Contrast this with the behavior of the class: If you signal an by calling its method, and there are no threads waiting, the remains in a signaled state until a thread calls , , or . The releases that thread and returns to the unsignaled state. +> The class does not maintain state indicating that the method has been called. Thus, if you call when no threads are waiting, the next thread that calls blocks as if had never been called. If two threads are using and to interact, this could result in a deadlock. Contrast this with the behavior of the class: If you signal an by calling its method, and there are no threads waiting, the remains in a signaled state until a thread calls , , or . The releases that thread and returns to the unsignaled state. Note that a synchronized object holds several references, including a reference to the thread that currently holds the lock, a reference to the ready queue, which contains the threads that are ready to obtain the lock, and a reference to the waiting queue, which contains the threads that are waiting for notification of a change in the object's state. - The `Pulse`, , and methods must be invoked from within a synchronized block of code. + The `Pulse`, , and methods must be invoked from within a synchronized block of code. - To signal multiple threads, use the method. + To signal multiple threads, use the method. ]]> @@ -552,9 +552,9 @@ Note that a synchronized object holds several references, including a reference to the thread that currently holds the lock, a reference to the ready queue, which contains the threads that are ready to obtain the lock, and a reference to the waiting queue, which contains the threads that are waiting for notification of a change in the object's state. - The , `PulseAll`, and methods must be invoked from within a synchronized block of code. + The , `PulseAll`, and methods must be invoked from within a synchronized block of code. - The remarks for the method explain what happens if is called when no threads are waiting. + The remarks for the method explain what happens if is called when no threads are waiting. To signal a single thread, use the `Pulse` method. @@ -630,12 +630,12 @@ ## Remarks If successful, this method acquires an exclusive lock on the `obj` parameter. This method returns immediately, whether or not the lock is available. - This method is similar to , but it will never block the current thread. If the thread cannot enter without blocking, the method returns `false,`. + This method is similar to , but it will never block the current thread. If the thread cannot enter without blocking, the method returns `false,`. > [!NOTE] > Use to lock objects (that is, reference types), not value types. For details, see the article. - To ensure that the thread does not enter the critical section, you should examine the method's return value and execute code in the critical section only if its return value is `true`. The following code fragment shows the pattern used to call this method. Note that you should call in a `finally` block to ensure that the calling thread releases its lock on the critical section if an exception occurs. + To ensure that the thread does not enter the critical section, you should examine the method's return value and execute code in the critical section only if its return value is `true`. The following code fragment shows the pattern used to call this method. Note that you should call in a `finally` block to ensure that the calling thread releases its lock on the critical section if an exception occurs. :::code language="csharp" source="~/snippets/csharp/System.Threading/Monitor/TryEnter/pattern1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Monitor/TryEnter/pattern1.vb" id="Snippet1"::: @@ -717,12 +717,12 @@ If the lock was not taken because an exception was thrown, the variable specified for the `lockTaken` parameter is `false` after this method ends. This allows the program to determine, in all cases, whether it is necessary to release the lock. - This method is similar to , but it will never block the current thread. If the thread cannot enter without blocking, the `lockTaken` argument is set to `false` when the method returns. + This method is similar to , but it will never block the current thread. If the thread cannot enter without blocking, the `lockTaken` argument is set to `false` when the method returns. > [!NOTE] > Use to lock objects (that is, reference types), not value types. For more information, see the article. - To ensure that the thread does not enter the critical section, you should examine the value of `lockTaken` and execute code in the critical section only if its value is `true`. The following code fragment shows the pattern used to call this method. Note that you should call in a `finally` block to ensure that the calling thread releases its lock on the critical section if an exception occurs. + To ensure that the thread does not enter the critical section, you should examine the value of `lockTaken` and execute code in the critical section only if its value is `true`. The following code fragment shows the pattern used to call this method. Note that you should call in a `finally` block to ensure that the calling thread releases its lock on the critical section if an exception occurs. :::code language="csharp" source="~/snippets/csharp/System.Threading/Monitor/TryEnter/pattern1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Monitor/TryEnter/pattern1.vb" id="Snippet2"::: @@ -730,7 +730,7 @@ ## Examples - The following code shows the basic pattern for using the method overload. This overload always sets the value of the variable that is passed to the `ref` parameter (`ByRef` in Visual Basic) `lockTaken`, even if the method throws an exception, so the value of the variable is a reliable way to test whether the lock has to be released. + The following code shows the basic pattern for using the method overload. This overload always sets the value of the variable that is passed to the `ref` parameter (`ByRef` in Visual Basic) `lockTaken`, even if the method throws an exception, so the value of the variable is a reliable way to test whether the lock has to be released. :::code language="csharp" source="~/snippets/csharp/System.Threading/Monitor/Enter/example.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Monitor/Enter/example.vb" id="Snippet3"::: @@ -799,12 +799,12 @@ , this method is equivalent to . If `millisecondsTimeout` equals 0, this method is equivalent to . + If the `millisecondsTimeout` parameter equals , this method is equivalent to . If `millisecondsTimeout` equals 0, this method is equivalent to . > [!NOTE] > Use to lock objects (that is, reference types), not value types. For details, see the article. - To ensure that the thread does not enter the critical section, you should examine the method's return value and execute code in the critical section only if its return value is `true`. The following code fragment shows the pattern used to call this method. Note that you should call in a `finally` block to ensure that the calling thread releases its lock on the critical section if an exception occurs. + To ensure that the thread does not enter the critical section, you should examine the method's return value and execute code in the critical section only if its return value is `true`. The following code fragment shows the pattern used to call this method. Note that you should call in a `finally` block to ensure that the calling thread releases its lock on the critical section if an exception occurs. :::code language="csharp" source="~/snippets/csharp/System.Threading/Monitor/TryEnter/pattern1.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Monitor/TryEnter/pattern1.vb" id="Snippet3"::: @@ -870,12 +870,12 @@ . If the value of `timeout` equals 0, this method is equivalent to . + If the value of the `timeout` parameter converted to milliseconds equals -1, this method is equivalent to . If the value of `timeout` equals 0, this method is equivalent to . > [!NOTE] > Use to lock objects (that is, reference types), not value types. For details, see the class topic. - To ensure that the thread does not enter the critical section, you should examine the method's return value and execute code in the critical section only if its return value is `true`. The following code fragment shows the pattern used to call this method. Note that you should call in a `finally` block to ensure that the calling thread releases its lock on the critical section if an exception occurs. + To ensure that the thread does not enter the critical section, you should examine the method's return value and execute code in the critical section only if its return value is `true`. The following code fragment shows the pattern used to call this method. Note that you should call in a `finally` block to ensure that the calling thread releases its lock on the critical section if an exception occurs. :::code language="csharp" source="~/snippets/csharp/System.Threading/Monitor/TryEnter/pattern1.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Monitor/TryEnter/pattern1.vb" id="Snippet5"::: @@ -948,14 +948,14 @@ , this method is equivalent to . If `millisecondsTimeout` equals 0, this method is equivalent to . + If the `millisecondsTimeout` parameter equals , this method is equivalent to . If `millisecondsTimeout` equals 0, this method is equivalent to . If the lock was not taken because an exception was thrown, the variable specified for the `lockTaken` parameter is `false` after this method ends. This allows the program to determine, in all cases, whether it is necessary to release the lock. > [!NOTE] > Use to lock objects (that is, reference types), not value types. For more information, see the class topic. - To ensure that the thread does not enter the critical section, you should examine the value of `lockTaken` and execute code in the critical section only if its value is `true`. The following code fragment shows the pattern used to call this method. Note that you should call in a `finally` block to ensure that the calling thread releases its lock on the critical section if an exception occurs. + To ensure that the thread does not enter the critical section, you should examine the value of `lockTaken` and execute code in the critical section only if its value is `true`. The following code fragment shows the pattern used to call this method. Note that you should call in a `finally` block to ensure that the calling thread releases its lock on the critical section if an exception occurs. :::code language="csharp" source="~/snippets/csharp/System.Threading/Monitor/TryEnter/pattern1.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Monitor/TryEnter/pattern1.vb" id="Snippet4"::: @@ -963,7 +963,7 @@ ## Examples - The following code shows the basic pattern for using the method overload. This overload always sets the value of the variable that is passed to the `ref` parameter (`ByRef` in Visual Basic) `lockTaken`, even if the method throws an exception, so the value of the variable is a reliable way to test whether the lock has to be released. + The following code shows the basic pattern for using the method overload. This overload always sets the value of the variable that is passed to the `ref` parameter (`ByRef` in Visual Basic) `lockTaken`, even if the method throws an exception, so the value of the variable is a reliable way to test whether the lock has to be released. :::code language="csharp" source="~/snippets/csharp/System.Threading/Monitor/Enter/example.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Monitor/Enter/example.vb" id="Snippet4"::: @@ -1032,14 +1032,14 @@ . If the value of `timeout` equals 0, this method is equivalent to . + If the value of the `timeout` parameter converted to milliseconds equals -1, this method is equivalent to . If the value of `timeout` equals 0, this method is equivalent to . If the lock was not taken because an exception was thrown, the variable specified for the `lockTaken` parameter is `false` after this method ends. This allows the program to determine, in all cases, whether it is necessary to release the lock. > [!NOTE] > Use to lock objects (that is, reference types), not value types. For more information, see the class topic. - To ensure that the thread does not enter the critical section, you should examine the value of `lockTaken` and execute code in the critical section only if its value is `true`. The following code fragment shows the pattern used to call this method. Note that you should call in a `finally` block to ensure that the calling thread releases its lock on the critical section if an exception occurs. + To ensure that the thread does not enter the critical section, you should examine the value of `lockTaken` and execute code in the critical section only if its value is `true`. The following code fragment shows the pattern used to call this method. Note that you should call in a `finally` block to ensure that the calling thread releases its lock on the critical section if an exception occurs. :::code language="csharp" source="~/snippets/csharp/System.Threading/Monitor/TryEnter/pattern1.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Monitor/TryEnter/pattern1.vb" id="Snippet6"::: @@ -1126,17 +1126,17 @@ ## Remarks The thread that currently owns the lock on the specified object invokes this method in order to release the object so that another thread can access it. The caller is blocked while waiting to reacquire the lock. This method is called when the caller needs to wait for a state change that will occur as a result of another thread's operations. - When a thread calls `Wait`, it releases the lock on the object and enters the object's waiting queue. The next thread in the object's ready queue (if there is one) acquires the lock and has exclusive use of the object. All threads that call `Wait` remain in the waiting queue until they receive a signal from or , sent by the owner of the lock. If `Pulse` is sent, only the thread at the head of the waiting queue is affected. If `PulseAll` is sent, all threads that are waiting for the object are affected. When the signal is received, one or more threads leave the waiting queue and enter the ready queue. A thread in the ready queue is permitted to reacquire the lock. + When a thread calls `Wait`, it releases the lock on the object and enters the object's waiting queue. The next thread in the object's ready queue (if there is one) acquires the lock and has exclusive use of the object. All threads that call `Wait` remain in the waiting queue until they receive a signal from or , sent by the owner of the lock. If `Pulse` is sent, only the thread at the head of the waiting queue is affected. If `PulseAll` is sent, all threads that are waiting for the object are affected. When the signal is received, one or more threads leave the waiting queue and enter the ready queue. A thread in the ready queue is permitted to reacquire the lock. This method returns when the calling thread reacquires the lock on the object. Note that this method blocks indefinitely if the holder of the lock does not call `Pulse` or `PulseAll`. - The caller executes `Wait` once, regardless of the number of times has been invoked for the specified object. Conceptually, the `Wait` method stores the number of times the caller invoked `Enter` on the object and invokes `Exit` as many times as necessary to fully release the locked object. The caller then blocks while waiting to reacquire the object. When the caller reacquires the lock, the system calls `Enter` as many times as necessary to restore the saved `Enter` count for the caller. Calling `Wait` releases the lock for the specified object only; if the caller is the owner of locks on other objects, these locks are not released. + The caller executes `Wait` once, regardless of the number of times has been invoked for the specified object. Conceptually, the `Wait` method stores the number of times the caller invoked `Enter` on the object and invokes `Exit` as many times as necessary to fully release the locked object. The caller then blocks while waiting to reacquire the object. When the caller reacquires the lock, the system calls `Enter` as many times as necessary to restore the saved `Enter` count for the caller. Calling `Wait` releases the lock for the specified object only; if the caller is the owner of locks on other objects, these locks are not released. Note that a synchronized object holds several references, including a reference to the thread that currently holds the lock, a reference to the ready queue, which contains the threads that are ready to obtain the lock, and a reference to the waiting queue, which contains the threads that are waiting for notification of a change in the object's state. - The , , and `Wait` methods must be invoked from within a synchronized block of code. + The , , and `Wait` methods must be invoked from within a synchronized block of code. - The remarks for the method explain what happens if is called when no threads are waiting. + The remarks for the method explain what happens if is called when no threads are waiting. ]]> @@ -1214,21 +1214,21 @@ The thread that currently owns the lock on the specified object invokes this method in order to release the object so that another thread can access it. The caller is blocked while waiting to reacquire the lock. This method is called when the caller needs to wait for a state change that will occur as a result of another thread's operations. - The time-out ensures that the current thread does not block indefinitely if another thread releases the lock without first calling the or method. It also moves the thread to the ready queue, bypassing other threads ahead of it in the wait queue, so that it can reacquire the lock sooner. The thread can test the return value of the method to determine whether it reacquired the lock prior to the time-out. The thread can evaluate the conditions that caused it to enter the wait, and if necessary call the method again. + The time-out ensures that the current thread does not block indefinitely if another thread releases the lock without first calling the or method. It also moves the thread to the ready queue, bypassing other threads ahead of it in the wait queue, so that it can reacquire the lock sooner. The thread can test the return value of the method to determine whether it reacquired the lock prior to the time-out. The thread can evaluate the conditions that caused it to enter the wait, and if necessary call the method again. - When a thread calls `Wait`, it releases the lock on the object and enters the object's waiting queue. The next thread in the object's ready queue (if there is one) acquires the lock and has exclusive use of the object. The thread that invoked `Wait` remains in the waiting queue until either a thread that holds the lock invokes , or it is the next in the queue and a thread that holds the lock invokes . However, if `millisecondsTimeout` elapses before another thread invokes this object's or method, the original thread is moved to the ready queue in order to regain the lock. + When a thread calls `Wait`, it releases the lock on the object and enters the object's waiting queue. The next thread in the object's ready queue (if there is one) acquires the lock and has exclusive use of the object. The thread that invoked `Wait` remains in the waiting queue until either a thread that holds the lock invokes , or it is the next in the queue and a thread that holds the lock invokes . However, if `millisecondsTimeout` elapses before another thread invokes this object's or method, the original thread is moved to the ready queue in order to regain the lock. > [!NOTE] -> If is specified for the `millisecondsTimeout` parameter, this method blocks indefinitely unless the holder of the lock calls or . If `millisecondsTimeout` equals 0, the thread that calls `Wait` releases the lock and then immediately enters the ready queue in order to regain the lock. +> If is specified for the `millisecondsTimeout` parameter, this method blocks indefinitely unless the holder of the lock calls or . If `millisecondsTimeout` equals 0, the thread that calls `Wait` releases the lock and then immediately enters the ready queue in order to regain the lock. - The caller executes `Wait` once, regardless of the number of times has been invoked for the specified object. Conceptually, the `Wait` method stores the number of times the caller invoked on the object and invokes as many times as necessary to fully release the locked object. The caller then blocks while waiting to reacquire the object. When the caller reacquires the lock, the system calls as many times as necessary to restore the saved count for the caller. Calling `Wait` releases the lock for the specified object only; if the caller is the owner of locks on other objects, these locks are not released. + The caller executes `Wait` once, regardless of the number of times has been invoked for the specified object. Conceptually, the `Wait` method stores the number of times the caller invoked on the object and invokes as many times as necessary to fully release the locked object. The caller then blocks while waiting to reacquire the object. When the caller reacquires the lock, the system calls as many times as necessary to restore the saved count for the caller. Calling `Wait` releases the lock for the specified object only; if the caller is the owner of locks on other objects, these locks are not released. > [!NOTE] > A synchronized object holds several references, including a reference to the thread that currently holds the lock, a reference to the ready queue, which contains the threads that are ready to obtain the lock, and a reference to the waiting queue, which contains the threads that are waiting for notification of a change in the object's state. - The , , and `Wait` methods must be invoked from within a synchronized block of code. + The , , and `Wait` methods must be invoked from within a synchronized block of code. - The remarks for the method explain what happens if is called when no threads are waiting. + The remarks for the method explain what happens if is called when no threads are waiting. ]]> @@ -1307,21 +1307,21 @@ The thread that currently owns the lock on the specified object invokes this method in order to release the object so that another thread can access it. The caller is blocked while waiting to reacquire the lock. This method is called when the caller needs to wait for a state change that will occur as a result of another thread's operations. - The time-out ensures that the current thread does not block indefinitely if another thread releases the lock without first calling the or method. It also moves the thread to the ready queue, bypassing other threads ahead of it in the wait queue, so that it can reacquire the lock sooner. The thread can test the return value of the method to determine whether it reacquired the lock prior to the time-out. The thread can evaluate the conditions that caused it to enter the wait, and if necessary call the method again. + The time-out ensures that the current thread does not block indefinitely if another thread releases the lock without first calling the or method. It also moves the thread to the ready queue, bypassing other threads ahead of it in the wait queue, so that it can reacquire the lock sooner. The thread can test the return value of the method to determine whether it reacquired the lock prior to the time-out. The thread can evaluate the conditions that caused it to enter the wait, and if necessary call the method again. - When a thread calls `Wait`, it releases the lock on the object and enters the object's waiting queue. The next thread in the object's ready queue (if there is one) acquires the lock and has exclusive use of the object. The thread that invoked `Wait` remains in the waiting queue until either a thread that holds the lock invokes , or it is the next in the queue and a thread that holds the lock invokes . However, if `timeout` elapses before another thread invokes this object's or method, the original thread is moved to the ready queue in order to regain the lock. + When a thread calls `Wait`, it releases the lock on the object and enters the object's waiting queue. The next thread in the object's ready queue (if there is one) acquires the lock and has exclusive use of the object. The thread that invoked `Wait` remains in the waiting queue until either a thread that holds the lock invokes , or it is the next in the queue and a thread that holds the lock invokes . However, if `timeout` elapses before another thread invokes this object's or method, the original thread is moved to the ready queue in order to regain the lock. > [!NOTE] -> If a representing -1 millisecond is specified for the `timeout` parameter, this method blocks indefinitely unless the holder of the lock calls or . If `timeout` is 0 milliseconds, the thread that calls `Wait` releases the lock and then immediately enters the ready queue in order to regain the lock. +> If a representing -1 millisecond is specified for the `timeout` parameter, this method blocks indefinitely unless the holder of the lock calls or . If `timeout` is 0 milliseconds, the thread that calls `Wait` releases the lock and then immediately enters the ready queue in order to regain the lock. - The caller executes `Wait` once, regardless of the number of times has been invoked for the specified object. Conceptually, the `Wait` method stores the number of times the caller invoked on the object and invokes as many times as necessary to fully release the locked object. The caller then blocks while waiting to reacquire the object. When the caller reacquires the lock, the system calls as many times as necessary to restore the saved count for the caller. Calling `Wait` releases the lock for the specified object only; if the caller is the owner of locks on other objects, these locks are not released. + The caller executes `Wait` once, regardless of the number of times has been invoked for the specified object. Conceptually, the `Wait` method stores the number of times the caller invoked on the object and invokes as many times as necessary to fully release the locked object. The caller then blocks while waiting to reacquire the object. When the caller reacquires the lock, the system calls as many times as necessary to restore the saved count for the caller. Calling `Wait` releases the lock for the specified object only; if the caller is the owner of locks on other objects, these locks are not released. > [!NOTE] > A synchronized object holds several references, including a reference to the thread that currently holds the lock, a reference to the ready queue, which contains the threads that are ready to obtain the lock, and a reference to the waiting queue, which contains the threads that are waiting for notification of a change in the object's state. - The , , and `Wait` methods must be invoked from within a synchronized block of code. + The , , and `Wait` methods must be invoked from within a synchronized block of code. - The remarks for the method explain what happens if is called when no threads are waiting. + The remarks for the method explain what happens if is called when no threads are waiting. ]]> diff --git a/xml/System.Threading/Mutex.xml b/xml/System.Threading/Mutex.xml index e92902ba3a3..ef1b956106d 100644 --- a/xml/System.Threading/Mutex.xml +++ b/xml/System.Threading/Mutex.xml @@ -65,19 +65,19 @@ 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 have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - You can use the method to request ownership of a mutex. The calling thread blocks until one of the following occurs: + You can use the method to request ownership of a mutex. The calling thread blocks until one of the following occurs: -- The mutex is signaled to indicate that it is not owned. When this happens, the method returns `true`, and the calling thread assumes ownership of the mutex and accesses the resource protected by the mutex. When it has finished accessing the resource, the thread must call the method to release ownership of the mutex. The first example in the Examples section illustrates this pattern. +- 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 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. A mutex can also be passed across application domain boundaries. - The thread that owns a mutex can request the same mutex in repeated calls to without blocking its execution. However, the thread must call the method the same number of times to release ownership of the mutex. + The thread that owns a mutex can request the same mutex in repeated calls to without blocking its execution. However, the thread must call the method the same number of times to release ownership of the mutex. - Because the class inherits from , you can also call the static and methods to synchronize access to a protected resource. + Because the class inherits from , you can also call the static and methods to synchronize access to a protected resource. If a thread terminates while owning a mutex, the mutex is said to be abandoned. The state of the mutex is set to signaled, and the next waiting thread gets ownership. Beginning in version 2.0 of the .NET Framework, an is thrown in the next thread that acquires the abandoned mutex. Before version 2.0 of the .NET Framework, no exception was thrown. @@ -88,7 +88,7 @@ Mutexes are of two types: local mutexes, which are unnamed, and named system mutexes. A local mutex exists only within your process. It can be used by any thread in your process that has a reference to the object that represents the mutex. Each unnamed object represents a separate local mutex. - Named system mutexes are visible throughout the operating system, and can be used to synchronize the activities of processes. You can create a object that represents a named system mutex by using a constructor that accepts a name. The operating-system object can be created at the same time, or it can exist before the creation of the object. You can create multiple objects that represent the same named system mutex, and you can use the method to open an existing named system mutex. + Named system mutexes are visible throughout the operating system, and can be used to synchronize the activities of processes. You can create a object that represents a named system mutex by using a constructor that accepts a name. The operating-system object can be created at the same time, or it can exist before the creation of the object. You can create multiple objects that represent the same named system mutex, and you can use the method to open an existing named system mutex. > [!NOTE] > On a server that is running Terminal Services, a named system mutex can have two levels of visibility. If its name begins with the prefix `Global\`, the mutex is visible in all terminal server sessions. If its name begins with the prefix `Local\`, the mutex is visible only in the terminal server session where it was created. In that case, a separate mutex with the same name can exist in each of the other terminal server sessions on the server. If you do not specify a prefix when you create a named mutex, it takes the prefix `Local\`. Within a terminal server session, two mutexes whose names differ only by their prefixes are separate mutexes, and both are visible to all processes in the terminal server session. That is, the prefix names `Global\` and `Local\` describe the scope of the mutex name relative to terminal server sessions, not relative to processes. @@ -100,12 +100,12 @@ ## Examples - This example shows how a local object is used to synchronize access to a protected resource. Because each calling thread is blocked until it acquires ownership of the mutex, it must call the method to release ownership of the mutex. + This example shows how a local object is used to synchronize access to a protected resource. Because each calling thread is blocked until it acquires ownership of the mutex, it must call the method to release ownership of the mutex. :::code language="csharp" source="~/snippets/csharp/System.Threading/Mutex/Overview/example1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Mutex/Overview/example1.vb" id="Snippet1"::: - In the following example, each thread calls the method to acquire the mutex. If the time-out interval elapses, the method returns `false`, and the thread neither acquires the mutex nor gains access to the resource the mutex protects. The method is called only by the thread that acquires the mutex. + In the following example, each thread calls the method to acquire the mutex. If the time-out interval elapses, the method returns `false`, and the thread neither acquires the mutex nor gains access to the resource the mutex protects. The method is called only by the thread that acquires the mutex. :::code language="csharp" source="~/snippets/csharp/System.Threading/Mutex/Overview/example2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Mutex/Overview/example2.vb" id="Snippet2"::: @@ -181,7 +181,7 @@ constructor overload and specifying `false` for initial ownership of the mutex. That is, the calling thread does not own the mutex. + Calling this constructor overload is the same as calling the constructor overload and specifying `false` for initial ownership of the mutex. That is, the calling thread does not own the mutex. @@ -327,13 +327,13 @@ If a `name` is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is used. If a synchronization object of a different type already exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown. Otherwise, a new synchronization object is created. - If `name` is not `null` and `initiallyOwned` is `true`, the calling thread owns the mutex only if the named system mutex was created as a result of this call. Since there is no mechanism for determining whether the named system mutex was created, it is better to specify `false` for `initiallyOwned` when calling this constructor overload. You can use the constructor if you need to determine initial ownership. + If `name` is not `null` and `initiallyOwned` is `true`, the calling thread owns the mutex only if the named system mutex was created as a result of this call. Since there is no mechanism for determining whether the named system mutex was created, it is better to specify `false` for `initiallyOwned` when calling this constructor overload. You can use the constructor if you need to determine initial ownership. This constructor initializes a object that represents a named system mutex. You can create multiple objects that represent the same named system mutex. - If the named mutex has already been created with access control security and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. + If the named mutex has already been created with access control security and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. - If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. + If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. Because they are system-wide, named mutexes can be used to coordinate resource use across process boundaries. @@ -407,9 +407,9 @@ If a `name` is provided and a synchronization object of the requested type alrea This constructor initializes a object that represents a named system mutex. You can create multiple objects that represent the same named system mutex. -If the named mutex has already been created with access control security and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. +If the named mutex has already been created with access control security and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. -If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. +If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. Because they are system-wide, named mutexes can be used to coordinate resource use across process boundaries. @@ -501,13 +501,13 @@ An object with the specified exists, but the specified If a `name` is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is used. If a synchronization object of a different type already exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown. Otherwise, a new synchronization object is created. - If `name` is not `null` and `initiallyOwned` is `true`, the calling thread owns the named mutex only if `createdNew` is `true` after the call. Otherwise the thread can request the mutex by calling the method. + If `name` is not `null` and `initiallyOwned` is `true`, the calling thread owns the named mutex only if `createdNew` is `true` after the call. Otherwise the thread can request the mutex by calling the method. This constructor initializes a object that represents a named system mutex. You can create multiple objects that represent the same named system mutex. - If the named mutex has already been created with access control security and the caller does not have rights, an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. + If the named mutex has already been created with access control security and the caller does not have rights, an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. - If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. In this case, `createdNew` is always `true`. + If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. In this case, `createdNew` is always `true`. Because they are system-wide, named mutexes can be used to coordinate resource use across process boundaries. @@ -578,13 +578,13 @@ There was some other error. The `HResult` property might provide more informatio If a `name` is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is used, However, if `options` specifies access limited to the current user and the synchronization object is not compatible with it, a `WaitHandleCannotBeOpenedException` is thrown. If a synchronization object of a different type already exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown as well. Otherwise, a new synchronization object is created. -If `name` is not `null` and `initiallyOwned` is `true`, the calling thread owns the mutex only if the named system mutex was created as a result of this call. Since there is no mechanism for determining whether the named system mutex was created, it is better to specify `false` for `initiallyOwned` when calling this constructor overload. You can use the constructor if you need to determine initial ownership. +If `name` is not `null` and `initiallyOwned` is `true`, the calling thread owns the mutex only if the named system mutex was created as a result of this call. Since there is no mechanism for determining whether the named system mutex was created, it is better to specify `false` for `initiallyOwned` when calling this constructor overload. You can use the constructor if you need to determine initial ownership. This constructor initializes a object that represents a named system mutex. You can create multiple objects that represent the same named system mutex. -If the named mutex has already been created with access control security and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. +If the named mutex has already been created with access control security and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. -If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. +If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. Because they are system-wide, named mutexes can be used to coordinate resource use across process boundaries. @@ -659,7 +659,7 @@ An object with the specified exists, but the specified If a `name` is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is used. If a synchronization object of a different type already exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown. Otherwise, a new synchronization object is created. - If `name` is not `null` and `initiallyOwned` is `true`, the calling thread owns the named mutex only if `createdNew` is `true` after the call. Otherwise the thread can request the mutex by calling the method. + If `name` is not `null` and `initiallyOwned` is `true`, the calling thread owns the named mutex only if `createdNew` is `true` after the call. Otherwise the thread can request the mutex by calling the method. Use this constructor to apply access control security to a named system mutex when it is created, preventing other code from taking control of the mutex. @@ -668,11 +668,11 @@ An object with the specified exists, but the specified If the named system mutex does not exist, it is created with the specified access control security. If the named mutex exists, the specified access control security is ignored. > [!NOTE] -> The caller has full control over the newly created object even if `mutexSecurity` denies or fails to grant some access rights to the current user. However, if the current user attempts to get another object to represent the same named mutex, using either a constructor or the method, Windows access control security is applied. +> The caller has full control over the newly created object even if `mutexSecurity` denies or fails to grant some access rights to the current user. However, if the current user attempts to get another object to represent the same named mutex, using either a constructor or the method, Windows access control security is applied. - If the named mutex has already been created with access control security and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. + If the named mutex has already been created with access control security and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. - If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. In this case, `createdNew` is always `true`. + If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. In this case, `createdNew` is always `true`. Because they are system-wide, named mutexes can be used to coordinate resource use across process boundaries. @@ -686,11 +686,11 @@ An object with the specified exists, but the specified ## Examples - The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. + The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. If the mutex does not exist, it is created with initial ownership and access control security that denies the current user the right to use the mutex, but grants the right to read and change permissions on the mutex. - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions. + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions. After the permissions are changed, the mutex is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. @@ -750,13 +750,13 @@ There was some other error. The `HResult` property might provide more informatio If a `name` is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is used, However, if `options` specifies access limited to the current user and the synchronization object is not compatible with it, a `WaitHandleCannotBeOpenedException` is thrown. If a synchronization object of a different type already exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown as well. Otherwise, a new synchronization object is created. -If `name` is not `null` and `initiallyOwned` is `true`, the calling thread owns the named mutex only if `createdNew` is `true` after the call. Otherwise the thread can request the mutex by calling the method. +If `name` is not `null` and `initiallyOwned` is `true`, the calling thread owns the named mutex only if `createdNew` is `true` after the call. Otherwise the thread can request the mutex by calling the method. This constructor initializes a object that represents a named system mutex. You can create multiple objects that represent the same named system mutex. -If the named mutex has already been created with access control security and the caller does not have rights, an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. +If the named mutex has already been created with access control security and the caller does not have rights, an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. -If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. In this case, `createdNew` is always `true`. +If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. In this case, `createdNew` is always `true`. Because they are system-wide, named mutexes can be used to coordinate resource use across process boundaries. @@ -817,19 +817,19 @@ An object with the specified exists, but the specified method uses the following combination of flags (combined using the bitwise OR operation) to search for permissions: , , and . + The method uses the following combination of flags (combined using the bitwise OR operation) to search for permissions: , , and . The user must have to call this method, and the mutex must have been opened with . > [!NOTE] -> In .NET Core and .NET 5+, the equivalent method is . +> In .NET Core and .NET 5+, the equivalent method is . ## Examples - The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. + The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. If the mutex does not exist, it is created with initial ownership and access control security that denies the current user the right to use the mutex, but grants the right to read and change permissions on the mutex. - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions, using the and methods. + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions, using the and methods. After the permissions are changed, the mutex is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. @@ -914,24 +914,24 @@ An object with the specified exists, but the specified If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown. - The method tries to open the specified named system mutex. To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. + The method tries to open the specified named system mutex. To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system mutex. - This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. + This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. - Specifying the flag allows a thread to wait on the mutex, and specifying the flag allows a thread to call the method. + Specifying the flag allows a thread to wait on the mutex, and specifying the flag allows a thread to call the method. This method does not request ownership of the mutex. ## Examples - The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. + The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. If the mutex does not exist, it is created with initial ownership and access control security that denies the current user the right to use the mutex, but grants the right to read and change permissions on the mutex. - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions. + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions. After the permissions are changed, the mutex is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. @@ -1005,9 +1005,9 @@ There was some other error. The `HResult` property might provide more informatio If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown. - The `rights` parameter must include the flag to allow threads to wait on the mutex, and the flag to allow threads to call the method. + The `rights` parameter must include the flag to allow threads to wait on the mutex, and the flag to allow threads to call the method. - The method tries to open an existing named mutex. To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. + The method tries to open an existing named mutex. To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system mutex. @@ -1016,11 +1016,11 @@ There was some other error. The `HResult` property might provide more informatio ## Examples - The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. + The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. If the mutex does not exist, it is created with initial ownership and access control security that denies the current user the right to use the mutex, but grants the right to read and change permissions on the mutex. - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions. + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions. After the permissions are changed, the mutex is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. @@ -1085,7 +1085,7 @@ There was some other error. The `HResult` property might provide more informatio If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. However, if `options` specifies access limited to the current user and the synchronization object is not compatible with it, a `WaitHandleCannotBeOpenedException` is thrown. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown as well. -The method tries to open the specified named system mutex. To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. +The method tries to open the specified named system mutex. To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system mutex. @@ -1168,12 +1168,12 @@ There was some other error. The `HResult` property might provide more informatio method), it must subsequently call to relinquish ownership of the mutex and unblock other threads that are trying to gain ownership of the mutex. If the attempt to get ownership of the mutex fails (for example, when a call to the method with a `millisecondsTimeout` or a `timeout` parameter returns `false` because the request times out), the thread shouldn't call , In this case, the thread should also not be allowed to access the resource protected by the mutex, as the following example shows. + Whenever a thread acquires a mutex (for example, by calling its method), it must subsequently call to relinquish ownership of the mutex and unblock other threads that are trying to gain ownership of the mutex. If the attempt to get ownership of the mutex fails (for example, when a call to the method with a `millisecondsTimeout` or a `timeout` parameter returns `false` because the request times out), the thread shouldn't call , In this case, the thread should also not be allowed to access the resource protected by the mutex, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Threading/Mutex/Overview/example2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Mutex/Overview/example2.vb" id="Snippet2"::: - A thread that owns a mutex can specify the same mutex in repeated wait function calls without blocking its execution. The number of calls is kept by the common language runtime. The thread must call the same number of times to release ownership of the mutex. + A thread that owns a mutex can specify the same mutex in repeated wait function calls without blocking its execution. The number of calls is kept by the common language runtime. The thread must call the same number of times to release ownership of the mutex. 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. Beginning in version 2.0 of the .NET Framework, an is thrown in the next thread that acquires the mutex. Prior to version 2.0 of the .NET Framework, no exception was thrown. @@ -1185,7 +1185,7 @@ There was some other error. The `HResult` property might provide more informatio ## Examples - The following example shows how a local object is used to synchronize access to a protected resource. The thread that creates the mutex does not own it initially. The method is used to release the mutex when it is no longer needed. + The following example shows how a local object is used to synchronize access to a protected resource. The thread that creates the mutex does not own it initially. The method is used to release the mutex when it is no longer needed. :::code language="csharp" source="~/snippets/csharp/System.Threading/Mutex/.ctor/class13.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Mutex/.ctor/class13.vb" id="Snippet1"::: @@ -1239,14 +1239,14 @@ There was some other error. The `HResult` property might provide more informatio The user must have rights to call this method, and the mutex must have been opened with . > [!NOTE] -> In .NET Core and .NET 5+, the equivalent method is . +> In .NET Core and .NET 5+, the equivalent method is . ## Examples - The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. + The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. If the mutex does not exist, it is created with initial ownership and access control security that denies the current user the right to use the mutex, but grants the right to read and change permissions on the mutex. - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions, using the and methods. + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions, using the and methods. After the permissions are changed, the mutex is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. @@ -1348,13 +1348,13 @@ There was some other error. The `HResult` property might provide more informatio If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, `false` is returned. - To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. + To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. - If you are uncertain whether a named mutex exists, use this method overload instead of the method overload, which throws an exception if the mutex does not exist. + If you are uncertain whether a named mutex exists, use this method overload instead of the method overload, which throws an exception if the mutex does not exist. Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system mutex. - This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. Specifying the flag allows a thread to wait on the mutex, and specifying the flag allows a thread to call the method. + This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. Specifying the flag allows a thread to wait on the mutex, and specifying the flag allows a thread to call the method. This method does not request ownership of the mutex. @@ -1425,11 +1425,11 @@ There was some other error. The `HResult` property might provide more informatio If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, `false` is returned. - To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. + To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. - If you are uncertain whether a named mutex exists, use this method overload instead of the method overload, which throws an exception if the mutex does not exist. + If you are uncertain whether a named mutex exists, use this method overload instead of the method overload, which throws an exception if the mutex does not exist. - The `rights` parameter must include the flag to allow threads to wait on the mutex, and the flag to allow threads to call the method. + The `rights` parameter must include the flag to allow threads to wait on the mutex, and the flag to allow threads to call the method. Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system mutex. @@ -1505,9 +1505,9 @@ There was some other error. The `HResult` property might provide more informatio If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. However, if `options` specifies access limited to the current user and the synchronization object is not compatible with it, `false` is returned. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, `false` is returned as well. -To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. +To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. -If you are uncertain whether a named mutex exists, use this method overload instead of the method overload, which throws an exception if the mutex does not exist. +If you are uncertain whether a named mutex exists, use this method overload instead of the method overload, which throws an exception if the mutex does not exist. Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system mutex. diff --git a/xml/System.Threading/Overlapped.xml b/xml/System.Threading/Overlapped.xml index 0917cb58c9c..db52f3e1f64 100644 --- a/xml/System.Threading/Overlapped.xml +++ b/xml/System.Threading/Overlapped.xml @@ -59,7 +59,7 @@ and methods transfer information from an object to a structure that can be passed to Windows API functions for asynchronous file I/O. The method transfers information from a structure to an instance of the class. + The and methods transfer information from an object to a structure that can be passed to Windows API functions for asynchronous file I/O. The method transfers information from a structure to an instance of the class. Changes to the properties of an object affect its associated structure, and vice versa. @@ -187,7 +187,7 @@ ## Remarks Use the property to get the handle of any managed synchronization event that derives from the class. - Your implementation of provides status information on the I/O operation. Pass it to the constructor in the `ar` parameter, and retrieve it later with the property. If a callback method is specified for the or method, the callback can retrieve your by unpacking the structure it receives. + Your implementation of provides status information on the I/O operation. Pass it to the constructor in the `ar` parameter, and retrieve it later with the property. If a callback method is specified for the or method, the callback can retrieve your by unpacking the structure it receives. ]]> @@ -242,9 +242,9 @@ class, use the property to get a object, and then call the method. + To get the handle of a managed synchronization object that derives from the class, use the property to get a object, and then call the method. - Your implementation of provides status information on the I/O operation. Pass it to the constructor in the `ar` parameter, and retrieve it later with the property. If a callback method is specified for the or method, the callback can retrieve your by unpacking the structure it receives. + Your implementation of provides status information on the I/O operation. Pass it to the constructor in the `ar` parameter, and retrieve it later with the property. If a callback method is specified for the or method, the callback can retrieve your by unpacking the structure it receives. ]]> @@ -406,7 +406,7 @@ class, use the property to get a object, and then call the method. + To get the handle of a managed synchronization object that derives from the class, use the property to get a object, and then call the method. ]]> @@ -467,7 +467,7 @@ method exactly once on every pointer you receive from the method. If you don't call the method, you will leak memory. If you call the method more than once, memory will be corrupted. + You must call the method exactly once on every pointer you receive from the method. If you don't call the method, you will leak memory. If you call the method more than once, memory will be corrupted. ]]> @@ -645,10 +645,10 @@ structure is fixed in physical memory until is called. + The unmanaged pointer returned by this method can be passed to the operating system in overlapped I/O operations. The structure is fixed in physical memory until is called. > [!IMPORTANT] -> The caller is responsible for pinning the buffer. If the application domain is unloaded, however, the handle to the pinned buffer is destroyed and the buffer is released, leaving the I/O operation to write to the freed address. For this reason, it is better to use the method overload, in which the runtime pins the buffer. +> The caller is responsible for pinning the buffer. If the application domain is unloaded, however, the handle to the pinned buffer is destroyed and the buffer is released, leaving the I/O operation to write to the freed address. For this reason, it is better to use the method overload, in which the runtime pins the buffer. ]]> @@ -723,7 +723,7 @@ structure is fixed in physical memory until is called. + The unmanaged pointer returned by this method can be passed to the operating system in overlapped I/O operations. The structure is fixed in physical memory until is called. The buffer or buffers specified in `userData` must be the same as those passed to the unmanaged operating system function that performs the asynchronous I/O. @@ -797,7 +797,7 @@ structure is not freed from physical memory until you call the method. + The structure is not freed from physical memory until you call the method. ]]> @@ -891,12 +891,12 @@ structure is fixed in physical memory until is called. + The unmanaged pointer returned by this method can be passed to the operating system in overlapped I/O operations. The structure is fixed in physical memory until is called. - The caller is responsible for pinning the buffer. If the application domain is unloaded, however, the handle to the pinned buffer is destroyed and the buffer is released, leaving the I/O operation to write to the freed address. For this reason, it is better to use the method overload, in which the runtime pins the buffer. + The caller is responsible for pinning the buffer. If the application domain is unloaded, however, the handle to the pinned buffer is destroyed and the buffer is released, leaving the I/O operation to write to the freed address. For this reason, it is better to use the method overload, in which the runtime pins the buffer. > [!CAUTION] -> Using the method could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. The method does not propagate the calling stack. Malicious code might be able to exploit this to avoid permission checks. +> Using the method could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. The method does not propagate the calling stack. Malicious code might be able to exploit this to avoid permission checks. ]]> @@ -971,14 +971,14 @@ structure is fixed in physical memory until is called. + The unmanaged pointer returned by this method can be passed to the operating system in overlapped I/O operations. The structure is fixed in physical memory until is called. The buffer or buffers specified in `userData` must be the same as those passed to the unmanaged operating system function that performs the asynchronous I/O. The runtime pins the buffer or buffers specified in`userData` for the duration of the I/O operation. If the application domain is unloaded, the runtime keeps the memory pinned until the I/O operation completes. > [!CAUTION] -> Using the method could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. The method does not propagate the calling stack. Malicious code might be able to exploit this to avoid permission checks. +> Using the method could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. The method does not propagate the calling stack. Malicious code might be able to exploit this to avoid permission checks. ]]> diff --git a/xml/System.Threading/ParameterizedThreadStart.xml b/xml/System.Threading/ParameterizedThreadStart.xml index 145746dcefc..d8be04738f1 100644 --- a/xml/System.Threading/ParameterizedThreadStart.xml +++ b/xml/System.Threading/ParameterizedThreadStart.xml @@ -64,25 +64,25 @@ ## Remarks When a managed thread is created, the method that executes on the thread is represented by: -- A delegate that is passed to the constructor. Any method that has no parameters and that returns `void` in C# or is a `Sub` procedure in Visual Basic can represent the delegate. +- A delegate that is passed to the constructor. Any method that has no parameters and that returns `void` in C# or is a `Sub` procedure in Visual Basic can represent the delegate. -- A delegate that is passed to the constructor. Any method that has a single parameter of type and that returns void in C# or is a Sub procedure in Visual Basic can represent the delegate. +- A delegate that is passed to the constructor. Any method that has a single parameter of type and that returns void in C# or is a Sub procedure in Visual Basic can represent the delegate. - The thread does not begin executing until the method is called. The or delegate is invoked on the thread, and execution begins at the first line of the method represented by the delegate. In the case of the delegate, the object that is passed to the method is passed to the delegate. + The thread does not begin executing until the method is called. The or delegate is invoked on the thread, and execution begins at the first line of the method represented by the delegate. In the case of the delegate, the object that is passed to the method is passed to the delegate. > [!NOTE] -> Visual Basic and C# users can omit the or delegate constructor when creating a thread. In Visual Basic, use the `AddressOf` operator when passing your method to the constructor; for example, `Dim t As New Thread(AddressOf ThreadProc)`. In C#, simply specify the name of the thread procedure. The compiler selects the correct delegate constructor. +> Visual Basic and C# users can omit the or delegate constructor when creating a thread. In Visual Basic, use the `AddressOf` operator when passing your method to the constructor; for example, `Dim t As New Thread(AddressOf ThreadProc)`. In C#, simply specify the name of the thread procedure. The compiler selects the correct delegate constructor. > [!NOTE] > When you create a delegate for an instance method in C++, the first parameter of the constructor is the instance variable. For a static method, the first parameter of the constructor is zero. For a static method, the delegate constructor requires only one parameter: the address of the callback method, qualified by the class name. - The delegate and the method overload make it easy to pass data to a thread procedure, but this technique is not type safe because any object can be passed to . A more robust way to pass data to a thread procedure is to put both the thread procedure and the data fields into a worker object. For more information, see [Creating Threads and Passing Data at Start Time](/dotnet/standard/threading/creating-threads-and-passing-data-at-start-time). + The delegate and the method overload make it easy to pass data to a thread procedure, but this technique is not type safe because any object can be passed to . A more robust way to pass data to a thread procedure is to put both the thread procedure and the data fields into a worker object. For more information, see [Creating Threads and Passing Data at Start Time](/dotnet/standard/threading/creating-threads-and-passing-data-at-start-time). The delegate supports only a single parameter. You can pass multiple data items to the by making that parameter one of the following: - An array. - A collection type, if all of the data items are of the same type. -- A tuple type, such as or . +- A tuple type, such as or . ## Examples The following code example uses a delegate to execute a static method and an instance method. The first delegate is represented by the static `DoWork` method and the second is represented by the instance `DoMoreWork` method. Both methods match the delegate signature; that is, they have a single parameter of type and don't return a value. diff --git a/xml/System.Threading/PeriodicTimer.xml b/xml/System.Threading/PeriodicTimer.xml index 6c8438a9d7a..ac64b5a7e72 100644 --- a/xml/System.Threading/PeriodicTimer.xml +++ b/xml/System.Threading/PeriodicTimer.xml @@ -25,14 +25,14 @@ Provides a periodic timer that enables waiting asynchronously for timer ticks. - may be in flight at any given moment. - - may be used concurrently with an active to interrupt it and cause it to return `false`. - + may be in flight at any given moment. + + may be used concurrently with an active to interrupt it and cause it to return `false`. + ]]> @@ -122,12 +122,12 @@ This timer is intended to be used only by a single consumer at a time: only one Stops the timer and releases the associated managed resources. - will cause an active wait with to complete with a value of `false`. All subsequent invocations will produce a value of `false`. - + will cause an active wait with to complete with a value of `false`. All subsequent invocations will produce a value of `false`. + ]]> @@ -214,11 +214,11 @@ This timer is intended to be used only by a single consumer at a time: only one ## Remarks -The result of the returned is `true` when it's completed due to the timer firing, and `false` when the timer is disposed. The returned enters the Canceled state when cancellation is requested. If the was already canceled when was called, the returned is created in the Canceled state. +The result of the returned is `true` when it's completed due to the timer firing, and `false` when the timer is disposed. The returned enters the Canceled state when cancellation is requested. If the was already canceled when was called, the returned is created in the Canceled state. + +The behaves like an auto-reset event, in that multiple ticks are coalesced into a single tick if they occur between calls to . Similarly, a call to will void any tick not yet consumed. may only be used by one consumer at a time, and may be used concurrently with a single call to . + -The behaves like an auto-reset event, in that multiple ticks are coalesced into a single tick if they occur between calls to . Similarly, a call to will void any tick not yet consumed. may only be used by one consumer at a time, and may be used concurrently with a single call to . - - ]]> The cancellation token was canceled. This exception is stored into the returned task. diff --git a/xml/System.Threading/PreAllocatedOverlapped.xml b/xml/System.Threading/PreAllocatedOverlapped.xml index 8dce876b442..e5630f80f88 100644 --- a/xml/System.Threading/PreAllocatedOverlapped.xml +++ b/xml/System.Threading/PreAllocatedOverlapped.xml @@ -119,14 +119,14 @@ An object or array of objects that represent the input or output buffer for the operations. Each object represents a buffer, such as an array of bytes. Its value can be . Initializes a new instance of the class and specifies a delegate to invoke when each asynchronous I/O operation is complete, a user-provided object that provides context, and managed objects that serve as buffers. - instance can be passed to the method to produce a instance that can be passed to the operating system in overlapped I/O operations. A single instance can only be used for a single native I/O operation at a time. However, the state stored in the instance can be reused for subsequent native operations. - + instance can be passed to the method to produce a instance that can be passed to the operating system in overlapped I/O operations. A single instance can only be used for a single native I/O operation at a time. However, the state stored in the instance can be reused for subsequent native operations. + > [!NOTE] -> The buffers specified in `pinData` are pinned until the method is called. - +> The buffers specified in `pinData` are pinned until the method is called. + ]]> @@ -288,7 +288,7 @@ The new instance can be passed to > [!NOTE] > The buffers specified in `pinData` are pinned until is called. - + ]]> diff --git a/xml/System.Threading/ReaderWriterLock.xml b/xml/System.Threading/ReaderWriterLock.xml index c35adee1d05..ea2c574c06c 100644 --- a/xml/System.Threading/ReaderWriterLock.xml +++ b/xml/System.Threading/ReaderWriterLock.xml @@ -72,7 +72,7 @@ > [!NOTE] > Holding reader locks or writer locks for long periods will starve other threads. For best performance, consider restructuring your application to minimize the duration of writes. - A thread can hold a reader lock or a writer lock, but not both at the same time. Instead of releasing a reader lock in order to acquire the writer lock, you can use and . + A thread can hold a reader lock or a writer lock, but not both at the same time. Instead of releasing a reader lock in order to acquire the writer lock, you can use and . Recursive lock requests increase the lock count on a lock. @@ -235,12 +235,12 @@ blocks if a different thread has the writer lock, or if at least one thread is waiting for the writer lock. + blocks if a different thread has the writer lock, or if at least one thread is waiting for the writer lock. > [!NOTE] -> If the current thread already has the writer lock, no reader lock is acquired. Instead, the lock count on the writer lock is incremented. This prevents a thread from blocking on its own writer lock. The result is exactly the same as calling , and an additional call to is required when releasing the writer lock. +> If the current thread already has the writer lock, no reader lock is acquired. Instead, the lock count on the writer lock is incremented. This prevents a thread from blocking on its own writer lock. The result is exactly the same as calling , and an additional call to is required when releasing the writer lock. - `AcquireReaderLock` supports recursive reader-lock requests. That is, a thread can call AcquireReaderLock multiple times, which increments the lock count each time. You must call once for each time you call `AcquireReaderLock`. Alternatively, you can call to reduce the lock count to zero immediately. + `AcquireReaderLock` supports recursive reader-lock requests. That is, a thread can call AcquireReaderLock multiple times, which increments the lock count each time. You must call once for each time you call `AcquireReaderLock`. Alternatively, you can call to reduce the lock count to zero immediately. Recursive lock requests are always granted immediately, without placing the requesting thread in the reader queue. Use recursive locks with caution, to avoid blocking writer-lock requests for long periods. @@ -324,12 +324,12 @@ blocks if a different thread has the writer lock, or if at least one thread is waiting for the writer lock. + blocks if a different thread has the writer lock, or if at least one thread is waiting for the writer lock. > [!NOTE] -> If the current thread already has the writer lock, no reader lock is acquired. Instead, the lock count on the writer lock is incremented. This prevents a thread from blocking on its own writer lock. The result is exactly the same as calling , and an additional call to is required when releasing the writer lock. +> If the current thread already has the writer lock, no reader lock is acquired. Instead, the lock count on the writer lock is incremented. This prevents a thread from blocking on its own writer lock. The result is exactly the same as calling , and an additional call to is required when releasing the writer lock. - `AcquireReaderLock` supports recursive reader-lock requests. That is, a thread can call AcquireReaderLock multiple times, which increments the lock count each time. You must call once for each time you call `AcquireReaderLock`. Alternatively, you can call to reduce the lock count to zero immediately. + `AcquireReaderLock` supports recursive reader-lock requests. That is, a thread can call AcquireReaderLock multiple times, which increments the lock count each time. You must call once for each time you call `AcquireReaderLock`. Alternatively, you can call to reduce the lock count to zero immediately. Recursive lock requests are always granted immediately, without placing the requesting thread in the reader queue. Use recursive locks with caution, to avoid blocking writer-lock requests for long periods. @@ -409,12 +409,12 @@ ## Remarks This method blocks if another thread has a reader lock or writer lock. For a description of the way the writer lock alternates with multiple concurrent reader locks, see the class. - A thread that already has a reader lock can acquire the writer lock in one of two ways: by releasing the reader lock before calling , or by calling . + A thread that already has a reader lock can acquire the writer lock in one of two ways: by releasing the reader lock before calling , or by calling . > [!CAUTION] -> If a thread calls `AcquireWriterLock` while it still has a reader lock, it will block on its own reader lock; if an infinite time-out is specified, the thread will deadlock. To avoid such deadlocks, use to determine whether the current thread already has a reader lock. +> If a thread calls `AcquireWriterLock` while it still has a reader lock, it will block on its own reader lock; if an infinite time-out is specified, the thread will deadlock. To avoid such deadlocks, use to determine whether the current thread already has a reader lock. - `AcquireWriterLock` supports recursive writer-lock requests. That is, a thread can call `AcquireWriterLock` multiple times, which increments the lock count each time. You must call once for each time you call `AcquireWriterLock`. Alternatively, you can call to reduce the lock count to zero immediately. + `AcquireWriterLock` supports recursive writer-lock requests. That is, a thread can call `AcquireWriterLock` multiple times, which increments the lock count each time. You must call once for each time you call `AcquireWriterLock`. Alternatively, you can call to reduce the lock count to zero immediately. Recursive lock requests are always granted immediately, without placing the requesting thread in the writer queue. @@ -494,12 +494,12 @@ ## Remarks This method blocks if another thread has a reader lock or writer lock. For a description of the way the writer lock alternates with multiple concurrent reader locks, see the class. - A thread that already has a reader lock can acquire the writer lock in one of two ways: by releasing the reader lock before calling , or by calling . + A thread that already has a reader lock can acquire the writer lock in one of two ways: by releasing the reader lock before calling , or by calling . > [!CAUTION] -> If a thread calls `AcquireWriterLock` while it still has a reader lock, it will block on its own reader lock; if an infinite time-out is specified, the thread will deadlock. To avoid such deadlocks, use to determine whether the current thread already has a reader lock. +> If a thread calls `AcquireWriterLock` while it still has a reader lock, it will block on its own reader lock; if an infinite time-out is specified, the thread will deadlock. To avoid such deadlocks, use to determine whether the current thread already has a reader lock. - `AcquireWriterLock` supports recursive writer-lock requests. That is, a thread can call `AcquireWriterLock` multiple times, which increments the lock count each time. You must call once for each time you call `AcquireWriterLock`. Alternatively, you can call to reduce the lock count to zero immediately. + `AcquireWriterLock` supports recursive writer-lock requests. That is, a thread can call `AcquireWriterLock` multiple times, which increments the lock count each time. You must call once for each time you call `AcquireWriterLock`. Alternatively, you can call to reduce the lock count to zero immediately. Recursive lock requests are always granted immediately, without placing the requesting thread in the writer queue. @@ -569,14 +569,14 @@ and `AnyWritersSince` to improve application performance. For example, a thread might cache the information it obtains while holding a reader lock. After releasing and later reacquiring the lock, the thread can use `AnyWritersSince` to determine whether other threads have written to the resource in the interim; if not, the cached information can be used. This technique is useful where reading the information protected by the lock is expensive; for example, running a database query. + You can use and `AnyWritersSince` to improve application performance. For example, a thread might cache the information it obtains while holding a reader lock. After releasing and later reacquiring the lock, the thread can use `AnyWritersSince` to determine whether other threads have written to the resource in the interim; if not, the cached information can be used. This technique is useful where reading the information protected by the lock is expensive; for example, running a database query. The caller must be holding a reader lock or a writer lock in order for the sequence number to be useful. ## Examples - The following code example shows how to use the method and the property to determine whether another thread acquired the writer lock on the protected resource since the current thread last held the writer lock. + The following code example shows how to use the method and the property to determine whether another thread acquired the writer lock on the protected resource since the current thread last held the writer lock. This code is part of a larger example provided for the class. @@ -645,10 +645,10 @@ releases the writer lock, regardless of the recursive lock count, and restores the reader lock that was held by the thread before upgrading to the writer lock. The lock count on the reader lock is restored. + releases the writer lock, regardless of the recursive lock count, and restores the reader lock that was held by the thread before upgrading to the writer lock. The lock count on the reader lock is restored. > [!NOTE] -> `DowngradeFromWriterLock` accepts a obtained by calling . Do not use a `LockCookie` returned by . +> `DowngradeFromWriterLock` accepts a obtained by calling . Do not use a `LockCookie` returned by . A thread does not block when downgrading from the writer lock, even if other threads are waiting for the writer lock, because all reader-lock requests are granted when the writer lock is released. @@ -712,7 +712,7 @@ when the current object is ready to be finalized. + The garbage collector calls when the current object is ready to be finalized. ]]> @@ -898,12 +898,12 @@ releases the reader lock or writer lock, regardless of the recursive lock count. To restore the state of the lock, including the lock count, pass the to . + releases the reader lock or writer lock, regardless of the recursive lock count. To restore the state of the lock, including the lock count, pass the to . ## Examples - The following code example shows how to use the method to release the lock, regardless of how many times it has been acquired by the thread, and how to restore the state of the lock later. + The following code example shows how to use the method to release the lock, regardless of how many times it has been acquired by the thread, and how to restore the state of the lock later. This code is part of a larger example provided for the class. @@ -973,10 +973,10 @@ decrements the lock count. When the count reaches zero, the lock is released. + decrements the lock count. When the count reaches zero, the lock is released. > [!NOTE] -> If a thread has the writer lock, calling `ReleaseReaderLock` has the same effect as calling . If a thread has no locks, calling `ReleaseReaderLock` throws an . +> If a thread has the writer lock, calling `ReleaseReaderLock` has the same effect as calling . If a thread has no locks, calling `ReleaseReaderLock` throws an . @@ -1052,7 +1052,7 @@ decrements the writer lock count. When the count reaches zero, the writer lock is released. + decrements the writer lock count. When the count reaches zero, the writer lock is released. > [!NOTE] > If a thread has a reader lock, or no locks, calling `ReleaseWriterLock` throws an . @@ -1139,14 +1139,14 @@ A thread blocks if it tries to restore a reader lock after another thread has acquired the writer lock, or if it tries to restore the writer lock after another thread has acquired a reader lock or writer lock. Because `RestoreLock` does not accept a time-out, you should take care to avoid possible deadlocks. > [!CAUTION] -> Before calling `RestoreLock`, make sure you have released all locks acquired since the call to . For example, a thread deadlocks if it acquires a reader lock, and then attempts to restore an earlier writer lock. Use and to detect such additional locks. +> Before calling `RestoreLock`, make sure you have released all locks acquired since the call to . For example, a thread deadlocks if it acquires a reader lock, and then attempts to restore an earlier writer lock. Use and to detect such additional locks. - Do not use a returned from . + Do not use a returned from . ## Examples - The following code example shows how to use the method to release the lock, regardless of how many times it has been acquired by the thread, and how to restore the state of the lock later. + The following code example shows how to use the method to release the lock, regardless of how many times it has been acquired by the thread, and how to restore the state of the lock later. This code is part of a larger example provided for the class. @@ -1234,11 +1234,11 @@ When a thread calls `UpgradeToWriterLock` the reader lock is released, regardless of the lock count, and the thread goes to the end of the queue for the writer lock. Thus, other threads might write to the resource before the thread that requested the upgrade is granted the writer lock. > [!IMPORTANT] -> The time-out exception is not thrown until the thread that called the method can reacquire the reader lock. If there are no other threads waiting for the writer lock, this happens immediately. However, if another thread is queued for the writer lock, the thread that called the method cannot reacquire the reader lock until all current readers have released their locks, and one thread has acquired and released the writer lock. This is true even if the other thread that requested the writer lock requested it after the current thread called the method. +> The time-out exception is not thrown until the thread that called the method can reacquire the reader lock. If there are no other threads waiting for the writer lock, this happens immediately. However, if another thread is queued for the writer lock, the thread that called the method cannot reacquire the reader lock until all current readers have released their locks, and one thread has acquired and released the writer lock. This is true even if the other thread that requested the writer lock requested it after the current thread called the method. - To restore the lock state, call using the returned by `UpgradeToWriterLock`. Do not use this `LockCookie` with . + To restore the lock state, call using the returned by `UpgradeToWriterLock`. Do not use this `LockCookie` with . - When a thread has no reader lock, do not use `UpgradeToWriterLock`. Use instead. + When a thread has no reader lock, do not use `UpgradeToWriterLock`. Use instead. For valid time-out values, see . @@ -1320,11 +1320,11 @@ When a thread calls `UpgradeToWriterLock` the reader lock is released, regardless of the lock count, and the thread goes to the end of the queue for the writer lock. Thus, other threads might write to the resource before the thread that requested the upgrade is granted the writer lock. > [!IMPORTANT] -> The time-out exception is not thrown until the thread that called the method can reacquire the reader lock. If there are no other threads waiting for the writer lock, this happens immediately. However, if another thread is queued for the writer lock, the thread that called the method cannot reacquire the reader lock until all current readers have released their locks, and one thread has acquired and released the writer lock. This is true even if the other thread that requested the writer lock requested it after the current thread called the method. +> The time-out exception is not thrown until the thread that called the method can reacquire the reader lock. If there are no other threads waiting for the writer lock, this happens immediately. However, if another thread is queued for the writer lock, the thread that called the method cannot reacquire the reader lock until all current readers have released their locks, and one thread has acquired and released the writer lock. This is true even if the other thread that requested the writer lock requested it after the current thread called the method. - To restore the lock state, call using the returned by `UpgradeToWriterLock`. Do not use this `LockCookie` with . + To restore the lock state, call using the returned by `UpgradeToWriterLock`. Do not use this `LockCookie` with . - When a thread has no reader lock, do not use `UpgradeToWriterLock`. Use instead. + When a thread has no reader lock, do not use `UpgradeToWriterLock`. Use instead. For valid time-out values, see . @@ -1387,7 +1387,7 @@ at a later time, if you want to determine whether other threads have acquired the writer lock in the meantime. + The sequence number increases whenever a thread acquires the writer lock. You can save the sequence number and pass it to at a later time, if you want to determine whether other threads have acquired the writer lock in the meantime. You can use `WriterSeqNum` to improve application performance. For example, a thread might cache the information it obtains while holding a reader lock. After releasing and later reacquiring the lock, the thread can determine whether other threads have written to the resource by calling `AnyWritersSince`; if not, the cached information can be used. This technique is useful when reading the information protected by the lock is expensive; for example, running a database query. @@ -1396,7 +1396,7 @@ ## Examples - The following code example shows how to use the property and the method to determine whether another thread acquired the writer lock on the protected resource since the current thread last held the writer lock. + The following code example shows how to use the property and the method to determine whether another thread acquired the writer lock on the protected resource since the current thread last held the writer lock. This code is part of a larger example provided for the class. diff --git a/xml/System.Threading/ReaderWriterLockSlim.xml b/xml/System.Threading/ReaderWriterLockSlim.xml index 5a2253f9acf..c947aba3cb0 100644 --- a/xml/System.Threading/ReaderWriterLockSlim.xml +++ b/xml/System.Threading/ReaderWriterLockSlim.xml @@ -119,7 +119,7 @@ ## Examples - The following example shows a simple synchronized cache that holds strings with integer keys. An instance of is used to synchronize access to the that serves as the inner cache. The parameterless constructor is used to create the lock. + The following example shows a simple synchronized cache that holds strings with integer keys. An instance of is used to synchronize access to the that serves as the inner cache. The parameterless constructor is used to create the lock. The example includes simple methods to add to the cache, delete from the cache, and read from the cache. To demonstrate time-outs, the example includes a method that adds to the cache only if it can do so within a specified time-out. @@ -134,7 +134,7 @@ :::code language="csharp" source="~/snippets/csharp/System.Threading/ReaderWriterLockSlim/Overview/classexample1.cs" id="Snippet12"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/ReaderWriterLockSlim/.ctor/classexample1.vb" id="Snippet12"::: - The following code then uses the `SynchronizedCache` object to store a dictionary of vegetable names. It creates three tasks. The first writes the names of vegetables stored in an array to a `SynchronizedCache` instance. The second and third task display the names of the vegetables, the first in ascending order (from low index to high index), the second in descending order. The final task searches for the string "cucumber" and, when it finds it, calls the method to substitute the string "green bean". + The following code then uses the `SynchronizedCache` object to store a dictionary of vegetable names. It creates three tasks. The first writes the names of vegetables stored in an array to a `SynchronizedCache` instance. The second and third task display the names of the vegetables, the first in ascending order (from low index to high index), the second in descending order. The final task searches for the string "cucumber" and, when it finds it, calls the method to substitute the string "green bean". :::code language="csharp" source="~/snippets/csharp/System.Threading/ReaderWriterLockSlim/Overview/classexample1.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/ReaderWriterLockSlim/.ctor/classexample1.vb" id="Snippet11"::: @@ -213,7 +213,7 @@ :::code language="csharp" source="~/snippets/csharp/System.Threading/LockRecursionPolicy/Overview/ClassExample1.cs" id="Snippet12"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/LockRecursionPolicy/Overview/ClassExample1.vb" id="Snippet12"::: - The following code then uses the `SynchronizedCache` object to store a dictionary of vegetable names. It creates three tasks. The first writes the names of vegetables stored in an array to a `SynchronizedCache` instance. The second and third task display the names of the vegetables, the first in ascending order (from low index to high index), the second in descending order. The final task searches for the string "cucumber" and, when it finds it, calls the method to substitute the string "green bean". + The following code then uses the `SynchronizedCache` object to store a dictionary of vegetable names. It creates three tasks. The first writes the names of vegetables stored in an array to a `SynchronizedCache` instance. The second and third task display the names of the vegetables, the first in ascending order (from low index to high index), the second in descending order. The final task searches for the string "cucumber" and, when it finds it, calls the method to substitute the string "green bean". :::code language="csharp" source="~/snippets/csharp/System.Threading/LockRecursionPolicy/Overview/ClassExample1.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/LockRecursionPolicy/Overview/ClassExample1.vb" id="Snippet11"::: @@ -343,10 +343,10 @@ 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). + 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. ]]> @@ -406,21 +406,21 @@ method to block for a specified interval, and then return if the calling thread has not entered read mode during that interval. + This method blocks until the calling thread enters the lock, and therefore might never return. Use the method to block for a specified interval, and then return if the calling thread has not entered read mode during that interval. Multiple threads can enter read mode at the same time. - 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. + 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. - 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. + 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. ## Examples - The following example shows how to use the method to enter the lock in read mode. The method shown in the example retrieves the value associated with a key. If the key is not found, the exception thrown by the inner is allowed to terminate the method. A `finally` block is used to execute the method, ensuring that the caller exits read mode. + The following example shows how to use the method to enter the lock in read mode. The method shown in the example retrieves the value associated with a key. If the key is not found, the exception thrown by the inner is allowed to terminate the method. A `finally` block is used to execute the method, ensuring that the caller exits read mode. This code is part of a larger example provided for the class. @@ -487,13 +487,13 @@ method to block for a specified interval, and then return if the calling thread has not entered upgradeable mode during that interval. + This method blocks until the calling thread enters the lock, and therefore might never return. Use the method to block for a specified interval, and then return if the calling thread has not entered upgradeable mode during that interval. Use upgradeable mode when a thread usually accesses the resource that is protected by the in read mode, but may need to enter write mode if certain conditions are met. A thread in upgradeable mode can downgrade to read mode or upgrade to write mode. Only one thread can enter upgradeable mode at any given time. If a thread is in upgradeable mode, and there are no threads waiting to enter write mode, any number of other threads can enter read mode, even if there are threads waiting to enter upgradeable mode. - 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. + 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. @@ -501,7 +501,7 @@ ## Examples - The following example shows how to use the method to enter the lock in upgradeable mode. A `finally` block is used to execute the method, ensuring that the caller exits upgradeable mode. + The following example shows how to use the method to enter the lock in upgradeable mode. A `finally` block is used to execute the method, ensuring that the caller exits upgradeable mode. The method shown in the example retrieves the value associated with a key and compares it with a new value. If the value is unchanged, the method returns a status indicating no change. If no value is found for the key, the key/value pair is inserted. If the value has changed, it is updated. Upgradeable mode allows the thread to upgrade the read lock as needed, without risk of deadlocks. @@ -574,9 +574,9 @@ method to block for a specified interval, and then return if the calling thread has not entered write mode during that interval. + This method blocks until the calling thread enters the lock, and therefore might never return. Use the method to block for a specified interval, and then return if the calling thread has not entered write mode during that interval. - 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. + 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. @@ -584,7 +584,7 @@ ## Examples - The following example shows how to use the method to enter the lock in write mode. The method shown in the example adds a new key/value pair to the synchronized cache. If the key is already in the cache, the exception thrown by the inner is allowed to terminate the method. A `finally` block is used to execute the method, ensuring that the caller exits write mode. + The following example shows how to use the method to enter the lock in write mode. The method shown in the example adds a new key/value pair to the synchronized cache. If the key is already in the cache, the exception thrown by the inner is allowed to terminate the method. A `finally` block is used to execute the method, ensuring that the caller exits write mode. This code is part of a larger example provided for the class. @@ -658,7 +658,7 @@ ## Examples - The following example shows how to use a `finally` block to execute the method, ensuring that the caller exits read mode. The method shown in the example retrieves the value associated with a key. If the key is not found, the exception thrown by the inner is allowed to terminate the method. The method is used to enter read mode. + The following example shows how to use a `finally` block to execute the method, ensuring that the caller exits read mode. The method shown in the example retrieves the value associated with a key. If the key is not found, the exception thrown by the inner is allowed to terminate the method. The method is used to enter read mode. This code is part of a larger example provided for the class. @@ -723,7 +723,7 @@ ## Examples - The following example shows how to use a `finally` block to execute the method, ensuring that the caller exits upgradeable mode. + The following example shows how to use a `finally` block to execute the method, ensuring that the caller exits upgradeable mode. The method shown in the example retrieves the value associated with a key and compares it with a new value. If the value is unchanged, the method returns a status indicating no change. If no value is found for the key, the key/value pair is inserted. If the value has changed, it is updated. Upgradeable mode allows the thread to upgrade the read lock as needed, without risk of deadlocks. @@ -794,7 +794,7 @@ ## Examples - The following example shows how to use a `finally` block to execute the method, ensuring that the caller exits write mode. The method shown in the example adds a new key/value pair to the synchronized cache. If the key is already in the cache, the exception thrown by the inner is allowed to terminate the method. The method is used to enter the lock in write mode. + The following example shows how to use a `finally` block to execute the method, ensuring that the caller exits write mode. The method shown in the example adds a new key/value pair to the synchronized cache. If the key is already in the cache, the exception thrown by the inner is allowed to terminate the method. The method is used to enter the lock in write mode. This code is part of a larger example provided for the class. @@ -1263,12 +1263,12 @@ Multiple threads can enter read mode at the same time. - 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. + 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. - 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. + 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. ]]> @@ -1334,12 +1334,12 @@ Multiple threads can enter the lock in read mode at the same time. - 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. + 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. - 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. + 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. ]]> @@ -1422,7 +1422,7 @@ Only one thread can enter a lock in upgradeable mode at any given time. If a thread is in upgradeable mode, and there are no threads waiting to enter write mode, any number of other threads can enter read mode, even if there are threads waiting to enter upgradeable mode. - 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. + 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. @@ -1497,7 +1497,7 @@ Only one thread can enter a lock in upgradeable mode at any given time. If a thread is in upgradeable mode, and there are no threads waiting to enter write mode, any number of other threads can enter read mode, even if there are threads waiting to enter upgradeable mode. - 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. + 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. @@ -1583,7 +1583,7 @@ ## Remarks If `millisecondsTimeout` is 0 (zero), this method checks the lock state and returns `false` immediately if the desired state is unavailable. - 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. + 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. @@ -1591,9 +1591,9 @@ ## Examples - The following example shows how to use the method to enter the lock in write mode, with a time-out. The method shown in the example adds a new key/value pair to the synchronized cache. If the specified time-out interval elapses before the thread enters the lock, the method returns `false`. The method returns `true` if the key/value pair is added. + The following example shows how to use the method to enter the lock in write mode, with a time-out. The method shown in the example adds a new key/value pair to the synchronized cache. If the specified time-out interval elapses before the thread enters the lock, the method returns `false`. The method returns `true` if the key/value pair is added. - If the key is already in the cache, the exception thrown by the inner is allowed to terminate the method. A `finally` block is used to execute the method, ensuring that the caller exits the lock. + If the key is already in the cache, the exception thrown by the inner is allowed to terminate the method. A `finally` block is used to execute the method, ensuring that the caller exits the lock. This code is part of a larger example provided for the class. @@ -1668,7 +1668,7 @@ ## Remarks If `timeout` is 0 (zero), this method checks the lock state and returns `false` immediately if the desired state is unavailable. - 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. + 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. diff --git a/xml/System.Threading/RegisteredWaitHandle.xml b/xml/System.Threading/RegisteredWaitHandle.xml index 00a0ec06b42..3badff549ab 100644 --- a/xml/System.Threading/RegisteredWaitHandle.xml +++ b/xml/System.Threading/RegisteredWaitHandle.xml @@ -68,14 +68,14 @@ ## Examples The following example shows how to use a to determine why a callback method is called, and how to unregister a task if the callback occurred because the wait handle was signaled. - The example also shows how to use the method to execute a specified callback method when a specified wait handle is signaled. In this example, the callback method is `WaitProc`, and the wait handle is an . + The example also shows how to use the method to execute a specified callback method when a specified wait handle is signaled. In this example, the callback method is `WaitProc`, and the wait handle is an . - The example defines a `TaskInfo` class to hold the information that is passed to the callback when it executes. The example creates a `TaskInfo` object and assigns it some string data. The that is returned by the method is assigned to the `Handle` field of the `TaskInfo` object so that the callback method has access to the . + The example defines a `TaskInfo` class to hold the information that is passed to the callback when it executes. The example creates a `TaskInfo` object and assigns it some string data. The that is returned by the method is assigned to the `Handle` field of the `TaskInfo` object so that the callback method has access to the . - In addition to specifying `TaskInfo` as the object to pass to the callback method, the call to the method specifies the that the task will wait for, a delegate that represents the `WaitProc` callback method, a one second time-out interval, and multiple callbacks. + In addition to specifying `TaskInfo` as the object to pass to the callback method, the call to the method specifies the that the task will wait for, a delegate that represents the `WaitProc` callback method, a one second time-out interval, and multiple callbacks. + + When the main thread signals the by calling its method, the delegate is invoked. The `WaitProc` method tests to determine whether a time-out occurred. If the callback was invoked because the wait handle was signaled, the `WaitProc` method unregisters the , stopping additional callbacks. In the case of a time-out, the task continues to wait. The `WaitProc` method ends by printing a message to the console. - When the main thread signals the by calling its method, the delegate is invoked. The `WaitProc` method tests to determine whether a time-out occurred. If the callback was invoked because the wait handle was signaled, the `WaitProc` method unregisters the , stopping additional callbacks. In the case of a time-out, the task continues to wait. The `WaitProc` method ends by printing a message to the console. - :::code language="csharp" source="~/snippets/csharp/System.Threading/RegisteredWaitHandle/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/RegisteredWaitHandle/Overview/source.vb" id="Snippet1"::: @@ -172,20 +172,20 @@ is successfully unregistered. If a callback method is in progress when executes, `waitObject` is not signaled until the callback method completes. In particular, if a callback method executes , `waitObject` is not signaled until that callback method completes. + If `waitObject` is specified, it is signaled only if the is successfully unregistered. If a callback method is in progress when executes, `waitObject` is not signaled until the callback method completes. In particular, if a callback method executes , `waitObject` is not signaled until that callback method completes. ## Examples - The following example shows how to use the method to unregister a task if a callback occurred because the wait handle was signaled. + The following example shows how to use the method to unregister a task if a callback occurred because the wait handle was signaled. - The example also shows how to use the method to execute a specified callback method when a specified wait handle is signaled. In this example, the callback method is `WaitProc`, and the wait handle is an . + The example also shows how to use the method to execute a specified callback method when a specified wait handle is signaled. In this example, the callback method is `WaitProc`, and the wait handle is an . - The example defines a `TaskInfo` class to hold the information that is passed to the callback when it executes. The example creates a `TaskInfo` object and assigns it some string data. The that is returned by the method is assigned to the `Handle` field of the `TaskInfo` object so that the callback method has access to the . + The example defines a `TaskInfo` class to hold the information that is passed to the callback when it executes. The example creates a `TaskInfo` object and assigns it some string data. The that is returned by the method is assigned to the `Handle` field of the `TaskInfo` object so that the callback method has access to the . - In addition to specifying `TaskInfo` as the object to pass to the callback method, the call to the method specifies the that the task will wait for, a delegate that represents the `WaitProc` callback method, a one second time-out interval, and multiple callbacks. + In addition to specifying `TaskInfo` as the object to pass to the callback method, the call to the method specifies the that the task will wait for, a delegate that represents the `WaitProc` callback method, a one second time-out interval, and multiple callbacks. - When the main thread signals the by calling its method, the delegate is invoked. The `WaitProc` method tests to determine whether a time-out occurred. If the callback was invoked because the wait handle was signaled, the `WaitProc` method unregisters the , stopping additional callbacks. In the case of a time-out, the task continues to wait. The `WaitProc` method ends by printing a message to the console. + When the main thread signals the by calling its method, the delegate is invoked. The `WaitProc` method tests to determine whether a time-out occurred. If the callback was invoked because the wait handle was signaled, the `WaitProc` method unregisters the , stopping additional callbacks. In the case of a time-out, the task continues to wait. The `WaitProc` method ends by printing a message to the console. :::code language="csharp" source="~/snippets/csharp/System.Threading/RegisteredWaitHandle/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/RegisteredWaitHandle/Overview/source.vb" id="Snippet1"::: diff --git a/xml/System.Threading/Semaphore.xml b/xml/System.Threading/Semaphore.xml index fdcf4132836..c2eea74bd26 100644 --- a/xml/System.Threading/Semaphore.xml +++ b/xml/System.Threading/Semaphore.xml @@ -61,17 +61,17 @@ class to control access to a pool of resources. Threads enter the semaphore by calling the method, which is inherited from the class, and release the semaphore by calling the method. + Use the class to control access to a pool of resources. Threads enter the semaphore by calling the method, which is inherited from the class, and release the semaphore by calling the method. The count on a semaphore is decremented each time a thread enters the semaphore, and incremented when a thread releases the semaphore. When the count is zero, subsequent requests block until other threads release the semaphore. When all threads have released the semaphore, the count is at the maximum value specified when the semaphore was created. There is no guaranteed order, such as FIFO or LIFO, in which blocked threads enter the semaphore. - A thread can enter the semaphore multiple times, by calling the method repeatedly. To release some or all of these entries, the thread can call the parameterless method overload multiple times, or it can call the method overload that specifies the number of entries to be released. + A thread can enter the semaphore multiple times, by calling the method repeatedly. To release some or all of these entries, the thread can call the parameterless method overload multiple times, or it can call the method overload that specifies the number of entries to be released. - The class does not enforce thread identity on calls to or . It is the programmer's responsibility to ensure that threads do not release the semaphore too many times. For example, suppose a semaphore has a maximum count of two, and that thread A and thread B both enter the semaphore. If a programming error in thread B causes it to call twice, both calls succeed. The count on the semaphore is full, and when thread A eventually calls , a is thrown. + The class does not enforce thread identity on calls to or . It is the programmer's responsibility to ensure that threads do not release the semaphore too many times. For example, suppose a semaphore has a maximum count of two, and that thread A and thread B both enter the semaphore. If a programming error in thread B causes it to call twice, both calls succeed. The count on the semaphore is full, and when thread A eventually calls , a is thrown. - Semaphores are of two types: local semaphores and named system semaphores. If you create a object using a constructor that accepts a name, it is associated with an operating-system semaphore of that name. Named system semaphores are visible throughout the operating system, and can be used to synchronize the activities of processes. You can create multiple objects that represent the same named system semaphore, and you can use the method to open an existing named system semaphore. + Semaphores are of two types: local semaphores and named system semaphores. If you create a object using a constructor that accepts a name, it is associated with an operating-system semaphore of that name. Named system semaphores are visible throughout the operating system, and can be used to synchronize the activities of processes. You can create multiple objects that represent the same named system semaphore, and you can use the method to open an existing named system semaphore. A local semaphore exists only within your process. It can be used by any thread in your process that has a reference to the local object. Each object is a separate local semaphore. @@ -81,7 +81,7 @@ ## Examples - The following code example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. + The following code example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. :::code language="csharp" source="~/snippets/csharp/System.Threading/Semaphore/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Semaphore/Overview/source.vb" id="Snippet1"::: @@ -162,12 +162,12 @@ ## Remarks This constructor initializes an unnamed semaphore. All threads that use an instance of such a semaphore must have references to the instance. - If `initialCount` is less than `maximumCount`, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. If you do not want to reserve any entries for the thread that creates the semaphore, use the same number for `maximumCount` and `initialCount`. + If `initialCount` is less than `maximumCount`, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. If you do not want to reserve any entries for the thread that creates the semaphore, use the same number for `maximumCount` and `initialCount`. ## Examples - The following example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. + The following example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. :::code language="csharp" source="~/snippets/csharp/System.Threading/Semaphore/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Semaphore/Overview/source.vb" id="Snippet1"::: @@ -241,16 +241,16 @@ If a `name` is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is used. If a synchronization object of a different type already exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown. Otherwise, a new synchronization object is created. - If the named system semaphore does not exist, it is created with the initial count and maximum count specified by `initialCount` and `maximumCount`. If the named system semaphore already exists, `initialCount` and `maximumCount` are not used, although invalid values still cause exceptions. If you need to determine whether or not a named system semaphore was created, use the constructor overload instead. + If the named system semaphore does not exist, it is created with the initial count and maximum count specified by `initialCount` and `maximumCount`. If the named system semaphore already exists, `initialCount` and `maximumCount` are not used, although invalid values still cause exceptions. If you need to determine whether or not a named system semaphore was created, use the constructor overload instead. > [!IMPORTANT] -> When you use this constructor overload, the recommended practice is to specify the same number for `initialCount` and `maximumCount`. If `initialCount` is less than `maximumCount`, and a named system semaphore is created, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. However, with this constructor overload there is no way to determine whether a named system semaphore was created. +> When you use this constructor overload, the recommended practice is to specify the same number for `initialCount` and `maximumCount`. If `initialCount` is less than `maximumCount`, and a named system semaphore is created, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. However, with this constructor overload there is no way to determine whether a named system semaphore was created. - If you specify `null` or an empty string for `name`, a local semaphore is created, as if you had called the constructor overload. + If you specify `null` or an empty string for `name`, a local semaphore is created, as if you had called the constructor overload. Because named semaphores are visible throughout the operating system, they can be used to coordinate resource use across process boundaries. - If you want to find out whether a named system semaphore exists, use the method. The method attempts to open an existing named semaphore, and throws an exception if the system semaphore does not exist. + If you want to find out whether a named system semaphore exists, use the method. The method attempts to open an existing named semaphore, and throws an exception if the system semaphore does not exist. > [!CAUTION] > By default, a named semaphore is not restricted to the user that created it. Other users may be able to open and use the semaphore, including interfering with the semaphore by acquiring the semaphore multiple times and not releasing it. To restrict access to specific users, you can use a constructor overload or and pass in a when creating the named semaphore. Avoid using named semaphores without access restrictions on systems that might have untrusted users running code. @@ -258,7 +258,7 @@ ## Examples - The following code example demonstrates the cross-process behavior of a named semaphore. The example creates a named semaphore with a maximum count of five and an initial count of five. The program makes three calls to the method. Thus, if you run the compiled example from two command windows, the second copy will block on the third call to . Release one or more entries in the first copy of the program to unblock the second. + The following code example demonstrates the cross-process behavior of a named semaphore. The example creates a named semaphore with a maximum count of five and an initial count of five. The program makes three calls to the method. Thus, if you run the compiled example from two command windows, the second copy will block on the third call to . Release one or more entries in the first copy of the program to unblock the second. :::code language="csharp" source="~/snippets/csharp/System.Threading/Semaphore/.ctor/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Semaphore/.ctor/source.vb" id="Snippet1"::: @@ -356,9 +356,9 @@ There was some other error. The `HResult` property might provide more informatio If the named system semaphore does not exist, it is created with the initial count and maximum count specified by `initialCount` and `maximumCount`. If the named system semaphore already exists, `initialCount` and `maximumCount` are not used, although invalid values still cause exceptions. Use `createdNew` to determine whether the system semaphore was created. - If `initialCount` is less than `maximumCount`, and `createdNew` is `true`, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. + If `initialCount` is less than `maximumCount`, and `createdNew` is `true`, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. - If you specify `null` or an empty string for `name`, a local semaphore is created, as if you had called the constructor overload. In this case, `createdNew` is always `true`. + If you specify `null` or an empty string for `name`, a local semaphore is created, as if you had called the constructor overload. In this case, `createdNew` is always `true`. Because named semaphores are visible throughout the operating system, they can be used to coordinate resource use across process boundaries. @@ -368,7 +368,7 @@ There was some other error. The `HResult` property might provide more informatio ## Examples - The following code example demonstrates the cross-process behavior of a named semaphore. The example creates a named semaphore with a maximum count of five and an initial count of two. That is, it reserves three entries for the thread that calls the constructor. If `createNew` is `false`, the program makes three calls to the method. Thus, if you run the compiled example from two command windows, the second copy will block on the third call to . Release one or more entries in the first copy of the program to unblock the second. + The following code example demonstrates the cross-process behavior of a named semaphore. The example creates a named semaphore with a maximum count of five and an initial count of two. That is, it reserves three entries for the thread that calls the constructor. If `createNew` is `false`, the program makes three calls to the method. Thus, if you run the compiled example from two command windows, the second copy will block on the third call to . Release one or more entries in the first copy of the program to unblock the second. :::code language="csharp" source="~/snippets/csharp/System.Threading/Semaphore/.ctor/source1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Semaphore/.ctor/source1.vb" id="Snippet1"::: @@ -439,16 +439,16 @@ This constructor initializes a object that rep If a `name` is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is used unless `options` specifies access limited to the current user and the synchronization object is not compatible with it, in which case a `WaitHandleCannotBeOpenedException` is thrown. If a synchronization object of a different type already exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown as well. Otherwise, a new synchronization object is created. -If the named system semaphore does not exist, it is created with the initial count and maximum count specified by `initialCount` and `maximumCount`. If the named system semaphore already exists, `initialCount` and `maximumCount` are not used, although invalid values still cause exceptions. If you need to determine whether or not a named system semaphore was created, use the constructor overload instead. +If the named system semaphore does not exist, it is created with the initial count and maximum count specified by `initialCount` and `maximumCount`. If the named system semaphore already exists, `initialCount` and `maximumCount` are not used, although invalid values still cause exceptions. If you need to determine whether or not a named system semaphore was created, use the constructor overload instead. > [!IMPORTANT] -> When you use this constructor overload, the recommended practice is to specify the same number for `initialCount` and `maximumCount`. If `initialCount` is less than `maximumCount`, and a named system semaphore is created, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. However, with this constructor overload, there's no way to determine whether a named system semaphore was created. +> When you use this constructor overload, the recommended practice is to specify the same number for `initialCount` and `maximumCount`. If `initialCount` is less than `maximumCount`, and a named system semaphore is created, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. However, with this constructor overload, there's no way to determine whether a named system semaphore was created. -If you specify `null` or an empty string for `name`, a local semaphore is created, as if you had called the constructor overload. +If you specify `null` or an empty string for `name`, a local semaphore is created, as if you had called the constructor overload. Because named semaphores are visible throughout the operating system, they can be used to coordinate resource use across process boundaries. -If you want to find out whether a named system semaphore exists, use the method. The method attempts to open an existing named semaphore, and throws an exception if the system semaphore does not exist. +If you want to find out whether a named system semaphore exists, use the method. The method attempts to open an existing named semaphore, and throws an exception if the system semaphore does not exist. On Windows, `options` can be provided to specify whether the named semaphore is accessible to the current user only or to all users. It also allows you to specify whether the named semaphore is accessible to processes in the current session only or to all sessions. For more information, see . @@ -529,13 +529,13 @@ An object with the specified exists, but the specified If the named system semaphore does not exist, it is created with the specified access control security. If the named semaphore exists, the specified access control security is ignored. > [!NOTE] -> The caller has full control over the newly created object even if `semaphoreSecurity` denies or fails to grant some access rights to the current user. However, if the current user attempts to get another object to represent the same named semaphore, using either a constructor or the method, Windows access control security is applied. +> The caller has full control over the newly created object even if `semaphoreSecurity` denies or fails to grant some access rights to the current user. However, if the current user attempts to get another object to represent the same named semaphore, using either a constructor or the method, Windows access control security is applied. If the named system semaphore does not exist, it is created with the initial count and maximum count specified by `initialCount` and `maximumCount`. If the named system semaphore already exists, `initialCount` and `maximumCount` are not used, although invalid values still cause exceptions. Use the `createdNew` parameter to determine whether the system semaphore was created by this constructor. - If `initialCount` is less than `maximumCount`, and `createdNew` is `true`, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. + If `initialCount` is less than `maximumCount`, and `createdNew` is `true`, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. - If you specify `null` or an empty string for `name`, a local semaphore is created, as if you had called the constructor overload. In this case, `createdNew` is always `true`. + If you specify `null` or an empty string for `name`, a local semaphore is created, as if you had called the constructor overload. In this case, `createdNew` is always `true`. Because named semaphores are visible throughout the operating system, they can be used to coordinate resource use across process boundaries. @@ -545,7 +545,7 @@ An object with the specified exists, but the specified ## Examples - The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. If the semaphore does not exist, it is created with a maximum count of two and with access control security that denies the current user the right to use the semaphore but grants the right to read and change permissions on the semaphore. If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. + The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. If the semaphore does not exist, it is created with a maximum count of two and with access control security that denies the current user the right to use the semaphore but grants the right to read and change permissions on the semaphore. If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. After the permissions are changed, the semaphore is opened with the rights required to enter and release. If you run the compiled example from a third command window, it runs using the new permissions. @@ -622,9 +622,9 @@ This constructor initializes a object that rep If the named system semaphore does not exist, it is created with the initial count and maximum count specified by `initialCount` and `maximumCount`. If the named system semaphore already exists, `initialCount` and `maximumCount` are not used, although invalid values still cause exceptions. Use the `createdNew` parameter to determine whether the system semaphore was created by this constructor. -If `initialCount` is less than `maximumCount`, and `createdNew` is `true`, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. +If `initialCount` is less than `maximumCount`, and `createdNew` is `true`, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. -If you specify `null` or an empty string for `name`, a local semaphore is created, as if you had called the constructor overload. In this case, `createdNew` is always `true`. +If you specify `null` or an empty string for `name`, a local semaphore is created, as if you had called the constructor overload. In this case, `createdNew` is always `true`. Because named semaphores are visible throughout the operating system, they can be used to coordinate resource use across process boundaries. @@ -689,7 +689,7 @@ An object with the specified exists, but the specified method uses the following combination of flags (combined using the bitwise OR operation) to search for permissions: , , and . + The method uses the following combination of flags (combined using the bitwise OR operation) to search for permissions: , , and . The user must have rights to call this method, and the semaphore must have been opened with rights. @@ -698,11 +698,11 @@ An object with the specified exists, but the specified ## Examples - The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. + The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. If the semaphore does not exist, it is created with a maximum count of two and with access control security that denies the current user the right to use the semaphore, but grants the right to read and change permissions on the semaphore. - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. The access control security for the system semaphore is obtained using the method. + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. The access control security for the system semaphore is obtained using the method. After the permissions are changed, the semaphore is opened with the rights required to enter and release. If you run the compiled example from a third command window, it runs using the new permissions. @@ -793,22 +793,22 @@ An object with the specified exists, but the specified If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown. - The method tries to open the specified named semaphore. To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. + The method tries to open the specified named semaphore. To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system semaphore. - This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. + This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. - Specifying the flag allows a thread to enter the semaphore, and specifying the flag allows a thread to call the method. + Specifying the flag allows a thread to enter the semaphore, and specifying the flag allows a thread to call the method. ## Examples - The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. + The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. If the semaphore does not exist, it is created with a maximum count of two and with access control security that denies the current user the right to use the semaphore, but which grants the right to read and change permissions on the semaphore. - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method overload. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method overload. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. After the permissions are changed, the semaphore is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. @@ -877,20 +877,20 @@ There was some other error. The `HResult` property might provide more informatio If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown. - The `rights` parameter must include the flag to allow threads to enter the semaphore, and the flag to allow threads to call the method. + The `rights` parameter must include the flag to allow threads to enter the semaphore, and the flag to allow threads to call the method. - The method tries to open an existing named semaphore. To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. + The method tries to open an existing named semaphore. To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system semaphore. ## Examples - The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. + The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. If the semaphore does not exist, it is created with a maximum count of two and with access control security that denies the current user the right to use the semaphore, but grants the right to read and change permissions on the semaphore. - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. After the permissions are changed, the semaphore is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. @@ -962,7 +962,7 @@ There was some other error. The `HResult` property might provide more informatio If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. However, if `options` specifies access limited to the current user and the synchronization object is not compatible with it, a `WaitHandleCannotBeOpenedException` is thrown. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown as well. -The method tries to open the specified named semaphore. To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. +The method tries to open the specified named semaphore. To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system semaphore. @@ -1059,16 +1059,16 @@ There was some other error. The `HResult` property might provide more informatio method to enter the semaphore, and they typically use this method overload to exit. + Threads typically use the method to enter the semaphore, and they typically use this method overload to exit. - If a is thrown by the method, it does not necessarily indicate a problem with the calling thread. A programming error in another thread might have caused that thread to exit the semaphore more times than it entered. + If a is thrown by the method, it does not necessarily indicate a problem with the calling thread. A programming error in another thread might have caused that thread to exit the semaphore more times than it entered. If the current object represents a named system semaphore, the user must have rights and the semaphore must have been opened with rights. ## Examples - The following code example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. + The following code example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. @@ -1144,14 +1144,14 @@ There was some other error. The `HResult` property might provide more informatio ## Remarks If a thread has entered the semaphore multiple times, this method overload allows the entire semaphore count to be restored with one call. - If a is thrown by the method, it does not necessarily indicate a problem with the calling thread. A programming error in another thread might have caused that thread to exit the semaphore more times than it entered. + If a is thrown by the method, it does not necessarily indicate a problem with the calling thread. A programming error in another thread might have caused that thread to exit the semaphore more times than it entered. If the current object represents a named system semaphore, the user must have rights and the semaphore must have been opened with rights. ## Examples - The following code example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. + The following code example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. @@ -1212,13 +1212,13 @@ There was some other error. The `HResult` property might provide more informatio ## Examples - The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. + The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. If the semaphore does not exist, it is created with a maximum count of two and with access control security that denies the current user the right to use the semaphore but grants the right to read and change permissions on the semaphore. - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. - After the permissions are changed, using the method, the semaphore is opened with the rights required to enter and release. If you run the compiled example from a third command window, it runs using the new permissions. + After the permissions are changed, using the method, the semaphore is opened with the rights required to enter and release. If you run the compiled example from a third command window, it runs using the new permissions. :::code language="csharp" source="~/snippets/csharp/System.Threading/Semaphore/.ctor/source2.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Semaphore/.ctor/source2.vb" id="Snippet1"::: @@ -1320,11 +1320,11 @@ There was some other error. The `HResult` property might provide more informatio If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, `false` is returned. - To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. + To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. - If you are uncertain whether a named semaphore exists, use this method overload instead of the method overload, which throws an exception if the semaphore does not exist. + If you are uncertain whether a named semaphore exists, use this method overload instead of the method overload, which throws an exception if the semaphore does not exist. - This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. Specifying the flag allows a thread to enter the semaphore, and specifying the flag allows a thread to call the method. + This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. Specifying the flag allows a thread to enter the semaphore, and specifying the flag allows a thread to call the method. ]]> @@ -1387,11 +1387,11 @@ There was some other error. The `HResult` property might provide more informatio If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, `false` is returned. - To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. + To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. - If you are uncertain whether a named semaphore exists, use this method overload instead of the method overload, which throws an exception if the semaphore does not exist. + If you are uncertain whether a named semaphore exists, use this method overload instead of the method overload, which throws an exception if the semaphore does not exist. - The `rights` parameter must include the flag to allow threads to enter the semaphore, and the flag to allow threads to call the method. + The `rights` parameter must include the flag to allow threads to enter the semaphore, and the flag to allow threads to call the method. Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system semaphore. @@ -1471,9 +1471,9 @@ There was some other error. The `HResult` property might provide more informatio If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. However, if `options` specifies access limited to the current user and the synchronization object is not compatible with it, `false` is returned. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, `false` is returned as well. -To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. +To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. -If you are uncertain whether a named semaphore exists, use this method overload instead of the method overload, which throws an exception if the semaphore does not exist. +If you are uncertain whether a named semaphore exists, use this method overload instead of the method overload, which throws an exception if the semaphore does not exist. ]]> diff --git a/xml/System.Threading/SemaphoreFullException.xml b/xml/System.Threading/SemaphoreFullException.xml index 0ca48b24608..cfc8354291c 100644 --- a/xml/System.Threading/SemaphoreFullException.xml +++ b/xml/System.Threading/SemaphoreFullException.xml @@ -81,12 +81,12 @@ method at this point, a is thrown. + The count on a semaphore is decremented each time a thread enters the semaphore, and incremented when a thread releases the semaphore. When the count is zero, subsequent requests block until other threads release the semaphore. When all threads have released the semaphore, the count is at the maximum value specified when the semaphore was created. If a programming error causes a thread to call the method at this point, a is thrown. > [!NOTE] -> The class does not enforce thread identity on calls to the and methods. It is not necessary for the same thread that called to call . +> The class does not enforce thread identity on calls to the and methods. It is not necessary for the same thread that called to call . - does not necessarily indicate a problem with the code where the exception occurred. Consider the following scenario: Thread A and thread B enter a semaphore that has a maximum count of two. A programming error in thread B causes it to call twice, so that the count on the semaphore is full. As a result, when thread A eventually calls , a is thrown. + does not necessarily indicate a problem with the code where the exception occurred. Consider the following scenario: Thread A and thread B enter a semaphore that has a maximum count of two. A programming error in thread B causes it to call twice, so that the count on the semaphore is full. As a result, when thread A eventually calls , a is thrown. For a list of initial property values for an instance of the class, see the constructor. @@ -164,8 +164,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The system-supplied error message string.| +||`null`.| +||The system-supplied error message string.| ]]> @@ -227,8 +227,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||`message`.| +||`null`.| +||`message`.| ]]> diff --git a/xml/System.Threading/SemaphoreSlim.xml b/xml/System.Threading/SemaphoreSlim.xml index 4413088c053..2777c21efaa 100644 --- a/xml/System.Threading/SemaphoreSlim.xml +++ b/xml/System.Threading/SemaphoreSlim.xml @@ -72,7 +72,7 @@ A lightweight semaphore controls access to a pool of resources that is local to your application. When you instantiate a semaphore, you can specify the maximum number of threads that can enter the semaphore concurrently. You also specify the initial number of threads that can enter the semaphore concurrently. This defines the semaphore's count. - The count is decremented each time a thread enters the semaphore, and incremented each time a thread releases the semaphore. To enter the semaphore, a thread calls one of the or overloads. To release the semaphore, it calls one of the overloads. When the count reaches zero, subsequent calls to one of the `Wait` methods block until other threads release the semaphore. If multiple threads are blocked, there is no guaranteed order, such as FIFO or LIFO, that controls when threads enter the semaphore. + The count is decremented each time a thread enters the semaphore, and incremented each time a thread releases the semaphore. To enter the semaphore, a thread calls one of the or overloads. To release the semaphore, it calls one of the overloads. When the count reaches zero, subsequent calls to one of the `Wait` methods block until other threads release the semaphore. If multiple threads are blocked, there is no guaranteed order, such as FIFO or LIFO, that controls when threads enter the semaphore. The basic structure for code that uses a semaphore to protect resources is: @@ -88,10 +88,10 @@ SemaphoreSlim.Release() When all threads have released the semaphore, the count is at the maximum value specified when the semaphore was created. The semaphore's count is available from the property. > [!IMPORTANT] -> The class doesn't enforce thread or task identity on calls to the , , and methods. In addition, if the constructor is used to instantiate the object, the property can increase beyond the value set by the constructor. It is the programmer's responsibility to ensure that calls to or methods are appropriately paired with calls to methods. +> The class doesn't enforce thread or task identity on calls to the , , and methods. In addition, if the constructor is used to instantiate the object, the property can increase beyond the value set by the constructor. It is the programmer's responsibility to ensure that calls to or methods are appropriately paired with calls to methods. ## Examples - The following example creates a semaphore with a maximum count of three threads and an initial count of zero threads. The example starts five tasks, all of which block waiting for the semaphore. The main thread calls the overload to increase the semaphore count to its maximum, which allows three tasks to enter the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread to make the output easier to read. + The following example creates a semaphore with a maximum count of three threads and an initial count of zero threads. The example starts five tasks, all of which block waiting for the semaphore. The main thread calls the overload to increase the semaphore count to its maximum, which allows three tasks to enter the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread to make the output easier to read. :::code language="csharp" source="~/snippets/csharp/System.Threading/SemaphoreSlim/Overview/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/SemaphoreSlim/Overview/example.vb" id="Snippet1"::: @@ -156,7 +156,7 @@ SemaphoreSlim.Release() object instantiated by calling this constructor doesn't throw a exception if a call to the method increases the value of the property beyond `initialCount`. This occurs if there are more calls to methods than there are to or methods. To set the maximum number of concurrent requests to enter the semaphore that can be granted, call the constructor. + The `initialCount` parameter defines the number of concurrent requests to enter the semaphore that can be granted. However, it doesn't define the maximum number of requests that can be granted concurrently. A object instantiated by calling this constructor doesn't throw a exception if a call to the method increases the value of the property beyond `initialCount`. This occurs if there are more calls to methods than there are to or methods. To set the maximum number of concurrent requests to enter the semaphore that can be granted, call the constructor. ]]> @@ -255,7 +255,7 @@ SemaphoreSlim.Release() does not imply a successful wait on the itself, nor does it decrement the semaphore's count. After the available wait handle is signaled, you should wait on the specifically. + Use this property only when you must wait on a SemaphoreSlim together with other kernel-based synchronization objects with the same wait handle. A successful wait on the does not imply a successful wait on the itself, nor does it decrement the semaphore's count. After the available wait handle is signaled, you should wait on the specifically. ]]> @@ -306,7 +306,7 @@ SemaphoreSlim.Release() property is set by the call to the class constructor. It is decremented by each call to the or method, and incremented by each call to the method. + The initial value of the property is set by the call to the class constructor. It is decremented by each call to the or method, and incremented by each call to the method. ]]> @@ -429,7 +429,7 @@ SemaphoreSlim.Release() , is not thread-safe and may not be used concurrently with other members of this instance. + Unlike most of the members of , is not thread-safe and may not be used concurrently with other members of this instance. ]]> @@ -491,7 +491,7 @@ SemaphoreSlim.Release() method increments the property by one. If the value of the property is zero before this method is called, the method also allows one thread or task blocked by a call to the or method to enter the semaphore. + A call to the method increments the property by one. If the value of the property is zero before this method is called, the method also allows one thread or task blocked by a call to the or method to enter the semaphore. ]]> @@ -547,7 +547,7 @@ SemaphoreSlim.Release() method increments the property by `releaseCount`. If the value of the property is zero before this method is called, the method also allows `releaseCount` threads or tasks blocked by a call to the or method to enter the semaphore. + A call to the method increments the property by `releaseCount`. If the value of the property is zero before this method is called, the method also allows `releaseCount` threads or tasks blocked by a call to the or method to enter the semaphore. ]]> @@ -686,7 +686,7 @@ If the timeout is set to zero milliseconds, the method doesn't block. It tests t If a thread or task is able to enter the semaphore, it decrements the property by one. -If a thread or task is blocked when calling and the timeout interval specified by `millisecondsTimeout` expires: +If a thread or task is blocked when calling and the timeout interval specified by `millisecondsTimeout` expires: - The thread or task doesn't enter the semaphore. - The property isn't decremented. @@ -828,7 +828,7 @@ If the timeout is set to zero milliseconds, the method doesn't block. It tests t If a thread or task is able to enter the semaphore, it decrements the property by one. -If a thread or task is blocked when calling and the timeout interval specified by `millisecondsTimeout` expires: +If a thread or task is blocked when calling and the timeout interval specified by `millisecondsTimeout` expires: - The thread or task doesn't enter the semaphore. - The property isn't decremented. @@ -907,7 +907,7 @@ If the timeout is set to zero milliseconds, the method doesn't block. It tests t If a thread or task is able to enter the semaphore, it decrements the property by one. -If `cancellationToken` is cancelled, or if a thread or task is blocked when calling and the timeout interval specified by `millisecondsTimeout` expires: +If `cancellationToken` is cancelled, or if a thread or task is blocked when calling and the timeout interval specified by `millisecondsTimeout` expires: - The thread or task doesn't enter the semaphore. - The property isn't decremented. @@ -990,7 +990,7 @@ If the timeout is set to zero milliseconds, the method doesn't block. It tests t If a thread or task is able to enter the semaphore, it decrements the property by one. -If `cancellationToken` is cancelled, or if a thread or task is blocked when calling and the timeout interval specified by `millisecondsTimeout` expires: +If `cancellationToken` is cancelled, or if a thread or task is blocked when calling and the timeout interval specified by `millisecondsTimeout` expires: - The thread or task doesn't enter the semaphore. - The property isn't decremented. diff --git a/xml/System.Threading/SpinLock.xml b/xml/System.Threading/SpinLock.xml index e9e9ab00dc1..c2331a47dca 100644 --- a/xml/System.Threading/SpinLock.xml +++ b/xml/System.Threading/SpinLock.xml @@ -243,9 +243,9 @@ End Class is a non-reentrant lock, meaning that if a thread holds the lock, it is not allowed to enter the lock again. If thread ownership tracking is enabled (whether it's enabled is available through ), an exception will be thrown when a thread tries to re-enter a lock it already holds. However, if thread ownership tracking is disabled, attempting to enter a lock already held will result in deadlock. + is a non-reentrant lock, meaning that if a thread holds the lock, it is not allowed to enter the lock again. If thread ownership tracking is enabled (whether it's enabled is available through ), an exception will be thrown when a thread tries to re-enter a lock it already holds. However, if thread ownership tracking is disabled, attempting to enter a lock already held will result in deadlock. - If you call without having first called the internal state of the can become corrupted. + If you call without having first called the internal state of the can become corrupted. ]]> @@ -316,9 +316,9 @@ End Class provides the same behavior as if calling using true as the argument. + The default overload of provides the same behavior as if calling using true as the argument. - If you call without having first called the internal state of the can become corrupted. + If you call without having first called the internal state of the can become corrupted. ]]> @@ -380,9 +380,9 @@ End Class with the `useMemoryBarrier` argument set to true will improve the fairness of the lock at the expense of some performance. The default overload behaves as if specifying true for `useMemoryBarrier`. + Calling with the `useMemoryBarrier` argument set to true will improve the fairness of the lock at the expense of some performance. The default overload behaves as if specifying true for `useMemoryBarrier`. - If you call without having first called the internal state of the can become corrupted. + If you call without having first called the internal state of the can become corrupted. ]]> @@ -613,7 +613,7 @@ End Class , TryEnter will not block waiting for the lock to be available. If the lock is not available when TryEnter is called, it will return immediately without any further spinning. + Unlike , TryEnter will not block waiting for the lock to be available. If the lock is not available when TryEnter is called, it will return immediately without any further spinning. ]]> @@ -672,7 +672,7 @@ End Class , TryEnter will not block indefinitely waiting for the lock to be available. It will block until either the lock is available or until the `millisecondsTimeout` has expired. + Unlike , TryEnter will not block indefinitely waiting for the lock to be available. It will block until either the lock is available or until the `millisecondsTimeout` has expired. ]]> @@ -733,7 +733,7 @@ End Class , TryEnter will not block indefinitely waiting for the lock to be available. It will block until either the lock is available or until the `timeout` has expired. + Unlike , TryEnter will not block indefinitely waiting for the lock to be available. It will block until either the lock is available or until the `timeout` has expired. ]]> diff --git a/xml/System.Threading/SpinWait.xml b/xml/System.Threading/SpinWait.xml index 257ab3b8a7b..f17dbc6e581 100644 --- a/xml/System.Threading/SpinWait.xml +++ b/xml/System.Threading/SpinWait.xml @@ -53,21 +53,21 @@ Provides support for spin-based waiting. - encapsulates common spinning logic. On single-processor machines, yields are always used instead of busy waits, and on computers with Intel processors employing Hyper-Threading technology, it helps to prevent hardware thread starvation. SpinWait encapsulates a good mixture of spinning and true yielding. - - is a value type, which means that low-level code can utilize SpinWait without fear of unnecessary allocation overheads. SpinWait is not generally useful for ordinary applications. In most cases, you should use the synchronization classes provided by the .NET Framework, such as . For most purposes where spin waiting is required, however, the type should be preferred over the method. - - - -## Examples - The following example shows how to use a : - + encapsulates common spinning logic. On single-processor machines, yields are always used instead of busy waits, and on computers with Intel processors employing Hyper-Threading technology, it helps to prevent hardware thread starvation. SpinWait encapsulates a good mixture of spinning and true yielding. + + is a value type, which means that low-level code can utilize SpinWait without fear of unnecessary allocation overheads. SpinWait is not generally useful for ordinary applications. In most cases, you should use the synchronization classes provided by the .NET Framework, such as . For most purposes where spin waiting is required, however, the type should be preferred over the method. + + + +## Examples + The following example shows how to use a : + :::code language="csharp" source="~/snippets/csharp/System.Threading/SpinWait/Overview/spinwait.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/System.Threading/SpinWait/Overview/spinwait.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Threading/SpinWait/Overview/spinwait.vb" id="Snippet01"::: + ]]> While is designed to be used in concurrent applications, it is not designed to be used from multiple threads concurrently. members are not thread-safe. If multiple threads must spin, each should use its own instance of . @@ -159,11 +159,11 @@ Gets whether the next call to will yield the processor, triggering a forced context switch. Whether the next call to will yield the processor, triggering a forced context switch. - always yields the processor. On machines with multiple CPUs, may yield after an unspecified number of calls. - + always yields the processor. On machines with multiple CPUs, may yield after an unspecified number of calls. + ]]> SpinWait @@ -210,16 +210,16 @@ Resets the spin counter. - and behave as though no calls to had been issued on this instance. If a instance is reused many times, it may be useful to reset it to avoid yielding too soon. - - - -## Examples - The following is an example of using SpinWait in a simple lock-free stack implementation. (This is just an example. If an efficient, thread-safe stack is needed, consider using ConcurrentStack.) - + and behave as though no calls to had been issued on this instance. If a instance is reused many times, it may be useful to reset it to avoid yielding too soon. + + + +## Examples + The following is an example of using SpinWait in a simple lock-free stack implementation. (This is just an example. If an efficient, thread-safe stack is needed, consider using ConcurrentStack.) + :::code language="csharp" source="~/snippets/csharp/System.Threading/SpinWait/Overview/reset.cs" id="Snippet01"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/SpinWait/Overview/reset.vb" id="Snippet01"::: @@ -269,11 +269,11 @@ Performs a single spin. - has been called so far on this instance. Each spin results in the method being called. A count is kept of the number of times is called, and after a threshold count is reached, the method is called. - + has been called so far on this instance. Each spin results in the method being called. A count is kept of the number of times is called, and after a threshold count is reached, the method is called. + ]]> SpinWait diff --git a/xml/System.Threading/SynchronizationContext.xml b/xml/System.Threading/SynchronizationContext.xml index dea070c889b..3510be3cdea 100644 --- a/xml/System.Threading/SynchronizationContext.xml +++ b/xml/System.Threading/SynchronizationContext.xml @@ -427,7 +427,7 @@ method starts an asynchronous request to post a message. + The method starts an asynchronous request to post a message. ]]> @@ -490,7 +490,7 @@ method starts a synchronous request to send a message. + The method starts a synchronous request to send a message. ]]> @@ -666,7 +666,7 @@ method calls the external declaration to perform the wait activity. Override the method to change the wait behavior for the synchronization context. + The method calls the external declaration to perform the wait activity. Override the method to change the wait behavior for the synchronization context. ]]> @@ -744,7 +744,7 @@ is a declaration for an unmanaged external helper function. is called by the method to wait for a signal for the specified operating system handles. + is a declaration for an unmanaged external helper function. is called by the method to wait for a signal for the specified operating system handles. ]]> diff --git a/xml/System.Threading/SynchronizationLockException.xml b/xml/System.Threading/SynchronizationLockException.xml index 5a6f08499a8..a3f79fbfbe7 100644 --- a/xml/System.Threading/SynchronizationLockException.xml +++ b/xml/System.Threading/SynchronizationLockException.xml @@ -73,11 +73,11 @@ is thrown by calling the , , , and methods of the class from an unsynchronized block of code. + is thrown by calling the , , , and methods of the class from an unsynchronized block of code. uses the HRESULT COR_E_SYNCHRONIZATIONLOCK, which has the value 0x80131518. - For a list of initial property values for an instance of , see the constructors. + For a list of initial property values for an instance of , see the constructors. ]]> @@ -142,8 +142,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The localized error message string.| +||`null`.| +||The localized error message string.| ]]> @@ -199,8 +199,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string.| +||`null`.| +||The error message string.| ]]> @@ -326,8 +326,8 @@ |Property|Value| |--------------|-----------| -||The inner exception reference.| -||The error message string.| +||The inner exception reference.| +||The error message string.| ]]> diff --git a/xml/System.Threading/Thread.xml b/xml/System.Threading/Thread.xml index a0e90c17016..ce348343f00 100644 --- a/xml/System.Threading/Thread.xml +++ b/xml/System.Threading/Thread.xml @@ -150,7 +150,7 @@ method. To pass a data object to the thread, use the method overload. + A thread does not begin executing when it is created. To schedule the thread for execution, call the method. To pass a data object to the thread, use the method overload. > [!NOTE] > Visual Basic users can omit the constructor when creating a thread. Use the `AddressOf` operator when passing your method, for example, `Dim t As New Thread(AddressOf ThreadProc)`. Visual Basic automatically calls the constructor. @@ -222,7 +222,7 @@ method. + A thread does not begin executing when it is created. To schedule the thread for execution, call the method. > [!NOTE] > Visual Basic users can omit the constructor when creating a thread. Use the `AddressOf` operator when passing your method, for example, `Dim t As New Thread(AddressOf ThreadProc)`. Visual Basic automatically calls the constructor. @@ -300,7 +300,7 @@ constructor overload is the recommended stack size for threads. If a thread has memory problems, the most likely cause is programming error, such as infinite recursion. + Avoid using this constructor overload. The default stack size used by the constructor overload is the recommended stack size for threads. If a thread has memory problems, the most likely cause is programming error, such as infinite recursion. > [!IMPORTANT] > Beginning with the .NET Framework 4, only fully trusted code can set `maxStackSize` to a value that is greater than the default stack size (1 megabyte). If a larger value is specified for `maxStackSize` when code is running with partial trust, `maxStackSize` is ignored and the default stack size is used. No exception is thrown. Code at any trust level can set `maxStackSize` to a value that is less than the default stack size. @@ -383,7 +383,7 @@ constructor overload is the recommended stack size for threads. If a thread has memory problems, the most likely cause is programming error, such as infinite recursion. + Avoid using this constructor overload. The default stack size used by the constructor overload is the recommended stack size for threads. If a thread has memory problems, the most likely cause is programming error, such as infinite recursion. > [!IMPORTANT] > Beginning with the .NET Framework 4, only fully trusted code can set `maxStackSize` to a value that is greater than the default stack size (1 megabyte). If a larger value is specified for `maxStackSize` when code is running with partial trust, `maxStackSize` is ignored and the default stack size is used. No exception is thrown. Code at any trust level can set `maxStackSize` to a value that is less than the default stack size. @@ -490,19 +490,19 @@ This method is obsolete. On .NET 5 and later versions, calling this method produces a compile-time warning. This method throws a at run time on .NET 5 and later and .NET Core. - When this method is invoked on a thread, the system throws a in the thread to abort it. `ThreadAbortException` is a special exception that can be caught by application code, but is re-thrown at the end of the `catch` block unless is called. `ResetAbort` cancels the request to abort, and prevents the `ThreadAbortException` from terminating the thread. Unexecuted `finally` blocks are executed before the thread is aborted. + When this method is invoked on a thread, the system throws a in the thread to abort it. `ThreadAbortException` is a special exception that can be caught by application code, but is re-thrown at the end of the `catch` block unless is called. `ResetAbort` cancels the request to abort, and prevents the `ThreadAbortException` from terminating the thread. Unexecuted `finally` blocks are executed before the thread is aborted. > [!NOTE] > When a thread calls `Abort` on itself, the effect is similar to throwing an exception; the happens immediately, and the result is predictable. However, if one thread calls `Abort` on another thread, the abort interrupts whatever code is running. There is also a chance that a static constructor could be aborted. In rare cases, this might prevent instances of that class from being created in that application domain. - The thread is not guaranteed to abort immediately, or at all. This situation can occur if a thread does an unbounded amount of computation in the `finally` blocks that are called as part of the abort procedure, thereby indefinitely delaying the abort. To wait until a thread has aborted, you can call the method on the thread after calling the method, but there is no guarantee the wait will end. + The thread is not guaranteed to abort immediately, or at all. This situation can occur if a thread does an unbounded amount of computation in the `finally` blocks that are called as part of the abort procedure, thereby indefinitely delaying the abort. To wait until a thread has aborted, you can call the method on the thread after calling the method, but there is no guarantee the wait will end. > [!NOTE] -> The thread that calls might block if the thread that is being aborted is in a protected region of code, such as a `catch` block, `finally` block, or constrained execution region. If the thread that calls holds a lock that the aborted thread requires, a deadlock can occur. +> The thread that calls might block if the thread that is being aborted is in a protected region of code, such as a `catch` block, `finally` block, or constrained execution region. If the thread that calls holds a lock that the aborted thread requires, a deadlock can occur. - If `Abort` is called on a thread that has not been started, the thread will abort when is called. If `Abort` is called on a thread that is blocked or is sleeping, the thread is interrupted and then aborted. + If `Abort` is called on a thread that has not been started, the thread will abort when is called. If `Abort` is called on a thread that is blocked or is sleeping, the thread is interrupted and then aborted. - If `Abort` is called on a thread that has been suspended, a is thrown in the thread that called , and is added to the property of the thread being aborted. A is not thrown in the suspended thread until is called. + If `Abort` is called on a thread that has been suspended, a is thrown in the thread that called , and is added to the property of the thread being aborted. A is not thrown in the suspended thread until is called. If `Abort` is called on a managed thread while it is executing unmanaged code, a `ThreadAbortException` is not thrown until the thread returns to managed code. @@ -583,19 +583,19 @@ This method is obsolete. On .NET 5 and later versions, calling this method produ This method is obsolete. On .NET 5 and later versions, calling this method produces a compile-time warning. This method throws a at run time on .NET 5 and later and .NET Core. - When this method is invoked on a thread, the system throws a in the thread to abort it. `ThreadAbortException` is a special exception that can be caught by application code, but is re-thrown at the end of the `catch` block unless is called. `ResetAbort` cancels the request to abort, and prevents the `ThreadAbortException` from terminating the thread. Unexecuted `finally` blocks are executed before the thread is aborted. + When this method is invoked on a thread, the system throws a in the thread to abort it. `ThreadAbortException` is a special exception that can be caught by application code, but is re-thrown at the end of the `catch` block unless is called. `ResetAbort` cancels the request to abort, and prevents the `ThreadAbortException` from terminating the thread. Unexecuted `finally` blocks are executed before the thread is aborted. > [!NOTE] > When a thread calls `Abort` on itself, the effect is similar to throwing an exception; the happens immediately, and the result is predictable. However, if one thread calls `Abort` on another thread, the abort interrupts whatever code is running. There is a chance that a static constructor could be aborted. In rare cases, this might prevent instances of that class from being created in that application domain. - The thread is not guaranteed to abort immediately, or at all. This situation can occur if a thread does an unbounded amount of computation in the `finally` blocks that are called as part of the abort procedure, thereby indefinitely delaying the abort. To wait until a thread has aborted, you can call the method on the thread after calling the method, but there is no guarantee that the wait will end. + The thread is not guaranteed to abort immediately, or at all. This situation can occur if a thread does an unbounded amount of computation in the `finally` blocks that are called as part of the abort procedure, thereby indefinitely delaying the abort. To wait until a thread has aborted, you can call the method on the thread after calling the method, but there is no guarantee that the wait will end. > [!NOTE] -> The thread that calls might block if the thread that is being aborted is in a protected region of code, such as a `catch` block, `finally` block, or constrained execution region. If the thread that calls holds a lock that the aborted thread requires, a deadlock can occur. +> The thread that calls might block if the thread that is being aborted is in a protected region of code, such as a `catch` block, `finally` block, or constrained execution region. If the thread that calls holds a lock that the aborted thread requires, a deadlock can occur. - If `Abort` is called on a thread that has not been started, the thread will abort when is called. If `Abort` is called on a thread that is blocked or is sleeping, the thread is interrupted and then aborted. + If `Abort` is called on a thread that has not been started, the thread will abort when is called. If `Abort` is called on a thread that is blocked or is sleeping, the thread is interrupted and then aborted. - If `Abort` is called on a thread that has been suspended, a is thrown in the thread that called , and is added to the property of the thread being aborted. A is not thrown in the suspended thread until is called. + If `Abort` is called on a thread that has been suspended, a is thrown in the thread that called , and is added to the property of the thread being aborted. A is not thrown in the suspended thread until is called. If `Abort` is called on a managed thread while it is executing unmanaged code, a `ThreadAbortException` is not thrown until the thread returns to managed code. @@ -753,12 +753,12 @@ This method is obsolete. On .NET 5 and later versions, calling this method produ Threads use a local store memory mechanism to store thread-specific data. The common language runtime allocates a multi-slot data store array to each process when it is created. The thread can allocate a data slot in the data store, store and retrieve a data value in the slot, and free the slot for reuse after the thread expires. Data slots are unique per thread. No other thread (not even a child thread) can get that data. - It is not necessary to use the method to allocate a named data slot, because the method allocates the slot if it has not already been allocated. + It is not necessary to use the method to allocate a named data slot, because the method allocates the slot if it has not already been allocated. > [!NOTE] -> If the method is used, it should be called in the main thread at program startup, because it throws an exception if a slot with the specified name has already been allocated. There is no way to test whether a slot has already been allocated. +> If the method is used, it should be called in the main thread at program startup, because it throws an exception if a slot with the specified name has already been allocated. There is no way to test whether a slot has already been allocated. - Slots allocated with this method must be freed with . + Slots allocated with this method must be freed with . ## Examples This section contains two code examples. The first example shows how to use a field that is marked with the attribute to hold thread-specific information. The second example shows how to use a data slot to do the same thing. @@ -776,7 +776,7 @@ This method is obsolete. On .NET 5 and later versions, calling this method produ The following example demonstrates how to use a named data slot to store thread-specific information. > [!NOTE] -> The example code does not use the method, because the method allocates the slot if it has not already been allocated. If the method is used, it should be called in the main thread at program startup. +> The example code does not use the method, because the method allocates the slot if it has not already been allocated. If the method is used, it should be called in the main thread at program startup. :::code language="csharp" source="~/snippets/csharp/System.Threading/Thread/AllocateNamedDataSlot/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading/Thread/AllocateNamedDataSlot/source.fs" id="Snippet1"::: @@ -849,7 +849,7 @@ This method is obsolete. On .NET 5 and later versions, calling this method produ property is obsolete.** The non-obsolete alternatives are the method to retrieve the apartment state and the method to set the apartment state. +**The property is obsolete.** The non-obsolete alternatives are the method to retrieve the apartment state and the method to set the apartment state. > [!IMPORTANT] > New threads are initialized as if their apartment state has not been set before they're started. The main application thread is initialized to by default. @@ -920,12 +920,12 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR For example, consider a task that attempts to allocate memory while holding a lock. If the memory allocation fails, aborting the current task is not sufficient to ensure stability of the , because there can be other tasks in the domain waiting for the same lock. If the current task is terminated, other tasks could be deadlocked. - When a failure occurs in a critical region, the host might decide to unload the entire rather than take the risk of continuing execution in a potentially unstable state. To inform the host that your code is entering a critical region, call . Call when execution returns to a non-critical region of code. + When a failure occurs in a critical region, the host might decide to unload the entire rather than take the risk of continuing execution in a potentially unstable state. To inform the host that your code is entering a critical region, call . Call when execution returns to a non-critical region of code. Using this method in code that runs under SQL Server 2005 requires the code to be run at the highest host protection level. ## Examples - The following example demonstrates the use of the and methods to divide a block of code into critical and non-critical regions. + The following example demonstrates the use of the and methods to divide a block of code into critical and non-critical regions. :::code language="csharp" source="~/snippets/csharp/System.Threading/Thread/BeginCriticalRegion/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading/Thread/BeginCriticalRegion/source.fs" id="Snippet1"::: @@ -990,12 +990,12 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR ## Remarks Some hosts of the common language runtime, such as Microsoft SQL Server 2005, provide their own thread management. A host that provides its own thread management can move an executing task from one physical operating system thread to another at any time. Most tasks are not affected by this switching. However, some tasks have thread affinity - that is, they depend on the identity of a physical operating system thread. These tasks must inform the host when they execute code that should not be switched. - For example, if your application calls a system API to acquire an operating system lock that has thread affinity, such as a Win32 CRITICAL_SECTION, you must call before acquiring the lock, and after releasing the lock. + For example, if your application calls a system API to acquire an operating system lock that has thread affinity, such as a Win32 CRITICAL_SECTION, you must call before acquiring the lock, and after releasing the lock. Using this method in code that runs under SQL Server 2005 requires the code to be run at the highest host protection level. ## Examples - The following example demonstrates the use of the and methods to notify a host that a block of code depends on the identity of a physical operating system thread. + The following example demonstrates the use of the and methods to notify a host that a block of code depends on the identity of a physical operating system thread. :::code language="csharp" source="~/snippets/csharp/System.Threading/Thread/BeginThreadAffinity/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading/Thread/BeginThreadAffinity/source.fs" id="Snippet1"::: @@ -1102,7 +1102,7 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR > The property doesn't work reliably when used with any thread other than the current thread. In .NET Framework, reading the property is reliable, although setting it for a thread other than the current thread is not. On .NET Core, an is thrown if a thread attempts to read or write the property on a different thread. > We recommend that you use the property to retrieve and set the current culture. - Beginning with the .NET Framework 4, you can set the property to a neutral culture. This is because the behavior of the class has changed: When it represents a neutral culture, its property values (in particular, the , , , , and properties) now reflect the specific culture that is associated with the neutral culture. In earlier versions of the .NET Framework, the property threw a exception when a neutral culture was assigned. + Beginning with the .NET Framework 4, you can set the property to a neutral culture. This is because the behavior of the class has changed: When it represents a neutral culture, its property values (in particular, the , , , , and properties) now reflect the specific culture that is associated with the neutral culture. In earlier versions of the .NET Framework, the property threw a exception when a neutral culture was assigned. ## Examples The following example shows the threading statement that allows the user interface of a Windows Forms application to display in the culture that is set in Control Panel. Additional code is needed. @@ -1254,7 +1254,7 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR :::code language="fsharp" source="~/snippets/fsharp/System.Threading/Thread/CurrentThread/currentthread2.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Thread/CurrentThread/currentthread2.vb" id="Snippet1"::: - Each child task generates 1 million random numbers between 1 and 1 million and returns their mean. The parent task calls the method to ensure that the child tasks have completed before displaying the mean returned by each task and calculating the mean of means. + Each child task generates 1 million random numbers between 1 and 1 million and returns their mean. The parent task calls the method to ensure that the child tasks have completed before displaying the mean returned by each task and calculating the mean of means. Note that while the application runs on a foreground thread, each task runs on a thread pool thread. @@ -1321,7 +1321,7 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR > The property doesn't work reliably when used with any thread other than the current thread. In .NET Framework, reading the property is reliable, although setting it for a thread other than the current thread is not. On .NET Core, an is thrown if a thread attempts to read or write the property on a different thread. > We recommend that you use the property to retrieve and set the current culture. - The returned by this property can be a neutral culture. Neutral cultures should not be used with formatting methods such as , , and . Use the method to get a specific culture, or use the property. + The returned by this property can be a neutral culture. Neutral cultures should not be used with formatting methods such as , , and . Use the method to get a specific culture, or use the property. ## Examples The following example determines whether the language of the current thread's UI culture is French. If it is not, it sets the UI culture of the current thread to English (United States). @@ -1400,9 +1400,9 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR - The application needs to control precisely when message pumping occurs. - Such applications can use the method to prevent the CLR from doing automatic reclamation of runtime callable wrappers. + Such applications can use the method to prevent the CLR from doing automatic reclamation of runtime callable wrappers. - When this method has been called on a thread, automatic cleanup cannot be re-enabled for that thread. When your application is ready to clean up runtime callable wrappers, use the method to instruct the runtime to clean up all runtime callable wrappers in the current context. Message pumping occurs while the method executes. + When this method has been called on a thread, automatic cleanup cannot be re-enabled for that thread. When your application is ready to clean up runtime callable wrappers, use the method to instruct the runtime to clean up all runtime callable wrappers in the current context. Message pumping occurs while the method executes. ]]> @@ -1464,12 +1464,12 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR For example, consider a task that attempts to allocate memory while holding a lock. If the memory allocation fails, aborting the current task is not sufficient to ensure stability of the , because there can be other tasks in the domain waiting for the same lock. If the current task is terminated, other tasks could be deadlocked. - When a failure occurs in a critical region, the host might decide to unload the entire rather than take the risk of continuing execution in a potentially unstable state. To inform the host that your code is entering a critical region, call . Call when execution returns to a non-critical region of code. + When a failure occurs in a critical region, the host might decide to unload the entire rather than take the risk of continuing execution in a potentially unstable state. To inform the host that your code is entering a critical region, call . Call when execution returns to a non-critical region of code. Using this method in code that runs under SQL Server 2005 requires the code to be run at the highest host protection level. ## Examples - The following example demonstrates the use of the and methods to divide a block of code into critical and non-critical regions. + The following example demonstrates the use of the and methods to divide a block of code into critical and non-critical regions. :::code language="csharp" source="~/snippets/csharp/System.Threading/Thread/BeginCriticalRegion/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading/Thread/BeginCriticalRegion/source.fs" id="Snippet1"::: @@ -1534,12 +1534,12 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR ## Remarks Some hosts of the common language runtime, such as Microsoft SQL Server 2005, provide their own thread management. A host that provides its own thread management can move an executing task from one physical operating system thread to another at any time. Most tasks are not affected by this switching. However, some tasks have thread affinity - that is, they depend on the identity of a physical operating system thread. These tasks must inform the host when they execute code that should not be switched. - For example, if your application calls a system API to acquire an operating system lock that has thread affinity, such as a Win32 CRITICAL_SECTION, you must call before acquiring the lock, and after releasing the lock. + For example, if your application calls a system API to acquire an operating system lock that has thread affinity, such as a Win32 CRITICAL_SECTION, you must call before acquiring the lock, and after releasing the lock. Using this method in code that runs under SQL Server 2005 requires the code to be run at the highest host protection level. ## Examples - The following example demonstrates the use of the and methods to notify a host that a block of code depends on the identity of a physical operating system thread. + The following example demonstrates the use of the and methods to notify a host that a block of code depends on the identity of a physical operating system thread. :::code language="csharp" source="~/snippets/csharp/System.Threading/Thread/BeginThreadAffinity/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading/Thread/BeginThreadAffinity/source.fs" id="Snippet1"::: @@ -1665,7 +1665,7 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR when the current object is ready to be finalized. + The garbage collector calls when the current object is ready to be finalized. ]]> @@ -1721,7 +1721,7 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR > [!IMPORTANT] > .NET Framework provides two mechanisms for using thread local storage (TLS): thread-relative static fields (that is, fields that are marked with the attribute) and data slots. Thread-relative static fields provide much better performance than data slots, and enable compile-time type checking. For more information about using TLS, see [Thread Local Storage: Thread-Relative Static Fields and Data Slots](/dotnet/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots). - After any thread calls `FreeNamedDataSlot`, any other thread that calls with the same name will allocate a new slot associated with the name. Subsequent calls to `GetNamedDataSlot` by any thread will return the new slot. However, any thread that still has a returned by an earlier call to `GetNamedDataSlot` can continue to use the old slot. + After any thread calls `FreeNamedDataSlot`, any other thread that calls with the same name will allocate a new slot associated with the name. Subsequent calls to `GetNamedDataSlot` by any thread will return the new slot. However, any thread that still has a returned by an earlier call to `GetNamedDataSlot` can continue to use the old slot. A slot that has been associated with a name is released only when every `LocalDataStoreSlot` that was obtained prior to the call to `FreeNamedDataSlot` has been released and garbage-collected. @@ -1801,12 +1801,12 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR method and the method, replaces the property. + This method, along with the method and the method, replaces the property. ## Examples - The following code example demonstrates the , , and methods. The code example creates a thread. Before the thread is started, displays the initial state and changes the state to . The method then returns `false` when attempting to change the state to because the apartment state is already set. If the same operation had been attempted with , would have been thrown. + The following code example demonstrates the , , and methods. The code example creates a thread. Before the thread is started, displays the initial state and changes the state to . The method then returns `false` when attempting to change the state to because the apartment state is already set. If the same operation had been attempted with , would have been thrown. - After the thread is started, the method is used again. This time it throws because the thread has already been started. + After the thread is started, the method is used again. This time it throws because the thread has already been started. :::code language="csharp" source="~/snippets/csharp/System.Threading/Thread/GetApartmentState/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading/Thread/GetApartmentState/source.fs" id="Snippet1"::: @@ -1989,7 +1989,7 @@ The value is not guaranteed to be a zero-based processor number. Threads use a local store memory mechanism to store thread-specific data. The common language runtime allocates a multi-slot data store array to each process when it is created. The thread can allocate a data slot in the data store, store and retrieve a data value in the slot, and free the slot for reuse after the thread expires. Data slots are unique per thread. No other thread (not even a child thread) can get that data. > [!NOTE] -> is a `Shared` method that always applies to the currently executing thread, even if you call it using a variable that refers to another thread. To avoid confusion, use the class name when calling `Shared` methods: `Dim test As Object = Thread.GetData(testSlot)`. +> is a `Shared` method that always applies to the currently executing thread, even if you call it using a variable that refers to another thread. To avoid confusion, use the class name when calling `Shared` methods: `Dim test As Object = Thread.GetData(testSlot)`. ## Examples This section contains two code examples. The first example shows how to use a field that is marked with the attribute to hold thread-specific information. The second example shows how to use a data slot to do the same thing. @@ -2599,16 +2599,16 @@ The value is not guaranteed to be a zero-based processor number. is a synchronization method that blocks the calling thread (that is, the thread that calls the method) until the thread whose method is called has completed. Use this method to ensure that a thread has been terminated. The caller will block indefinitely if the thread does not terminate. In the following example, the `Thread1` thread calls the method of `Thread2`, which causes `Thread1` to block until `Thread2` has completed. + is a synchronization method that blocks the calling thread (that is, the thread that calls the method) until the thread whose method is called has completed. Use this method to ensure that a thread has been terminated. The caller will block indefinitely if the thread does not terminate. In the following example, the `Thread1` thread calls the method of `Thread2`, which causes `Thread1` to block until `Thread2` has completed. :::code language="csharp" source="~/snippets/csharp/System.Threading/Thread/Join/join1a.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading/Thread/Join/join1a.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Thread/Join/join1a.vb" id="Snippet1"::: - If the thread has already terminated when is called, the method returns immediately. + If the thread has already terminated when is called, the method returns immediately. > [!WARNING] -> You should never call the method of the object that represents the current thread from the current thread. This causes your app to become unresponsive because the current thread waits upon itself indefinitely, +> You should never call the method of the object that represents the current thread from the current thread. This causes your app to become unresponsive because the current thread waits upon itself indefinitely, This method changes the state of the calling thread to include . You cannot invoke `Join` on a thread that is in the state. @@ -2674,7 +2674,7 @@ The value is not guaranteed to be a zero-based processor number. is a synchronization method that blocks the calling thread (that is, the thread that calls the method) until either the thread whose method is called has completed or the time-out interval has elapsed. In the following example, the `Thread1` thread calls the method of `Thread2`, which causes `Thread1` to block either until `Thread2` has completed or 2 seconds have elapsed. + is a synchronization method that blocks the calling thread (that is, the thread that calls the method) until either the thread whose method is called has completed or the time-out interval has elapsed. In the following example, the `Thread1` thread calls the method of `Thread2`, which causes `Thread1` to block either until `Thread2` has completed or 2 seconds have elapsed. :::code language="csharp" source="~/snippets/csharp/System.Threading/Thread/Join/join1b.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading/Thread/Join/join1b.fs" id="Snippet2"::: @@ -2682,7 +2682,7 @@ The value is not guaranteed to be a zero-based processor number. If is specified for the `millisecondsTimeout` parameter, this method behaves identically to the method overload, except for the return value. - If the thread has already terminated when is called, the method returns immediately. + If the thread has already terminated when is called, the method returns immediately. This method changes the state of the calling thread to include . You cannot invoke `Join` on a thread that is in the state. @@ -2744,7 +2744,7 @@ The value is not guaranteed to be a zero-based processor number. is a synchronization method that blocks the calling thread (that is, the thread that calls the method) until either the thread whose method is called has completed or the time-out interval has elapsed. In the following example, the `Thread1` thread calls the method of `Thread2`, which causes `Thread1` to block either until `Thread2` has completed or 2 seconds have elapsed. + is a synchronization method that blocks the calling thread (that is, the thread that calls the method) until either the thread whose method is called has completed or the time-out interval has elapsed. In the following example, the `Thread1` thread calls the method of `Thread2`, which causes `Thread1` to block either until `Thread2` has completed or 2 seconds have elapsed. :::code language="csharp" source="~/snippets/csharp/System.Threading/Thread/Join/join1c.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading/Thread/Join/join1c.fs" id="Snippet3"::: @@ -2752,7 +2752,7 @@ The value is not guaranteed to be a zero-based processor number. If is specified for `timeout`, this method behaves identically to the method overload, except for the return value. - If the thread has already terminated when is called, the method returns immediately. + If the thread has already terminated when is called, the method returns immediately. This method changes the state of the current thread to include . You cannot invoke `Join` on a thread that is in the state. @@ -3164,7 +3164,7 @@ The value is not guaranteed to be a zero-based processor number. ## Remarks > [!CAUTION] -> Do not use the and methods to synchronize the activities of threads. You have no way of knowing what code a thread is executing when you suspend it. If you suspend a thread while it holds locks during a security permission evaluation, other threads in the might be blocked. If you suspend a thread while it is executing a class constructor, other threads in the that attempt to use that class are blocked. Deadlocks can occur very easily. +> Do not use the and methods to synchronize the activities of threads. You have no way of knowing what code a thread is executing when you suspend it. If you suspend a thread while it holds locks during a security permission evaluation, other threads in the might be blocked. If you suspend a thread while it is executing a class constructor, other threads in the that attempt to use that class are blocked. Deadlocks can occur very easily. ]]> @@ -3235,12 +3235,12 @@ The value is not guaranteed to be a zero-based processor number. > [!NOTE] > The main application thread is initialized to by default. The only way to set the apartment state of the main application thread to is to apply the attribute to the entry point method. - The method, along with the method and the method, replaces the property. + The method, along with the method and the method, replaces the property. ## Examples - The following code example demonstrates the , , and methods. The code example creates a thread. Before the thread is started, displays the initial state and changes the state to . The method then returns `false` when attempting to change the state to because the apartment state is already set. If the same operation had been attempted with , would have been thrown. + The following code example demonstrates the , , and methods. The code example creates a thread. Before the thread is started, displays the initial state and changes the state to . The method then returns `false` when attempting to change the state to because the apartment state is already set. If the same operation had been attempted with , would have been thrown. - After the thread is started, the method is used again. This time it throws because the thread has already been started. + After the thread is started, the method is used again. This time it throws because the thread has already been started. :::code language="csharp" source="~/snippets/csharp/System.Threading/Thread/GetApartmentState/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading/Thread/GetApartmentState/source.fs" id="Snippet1"::: @@ -3388,7 +3388,7 @@ The value is not guaranteed to be a zero-based processor number. Threads use a local store memory mechanism to store thread-specific data. The common language runtime allocates a multi-slot data store array to each process when it is created. The thread can allocate a data slot in the data store, store and retrieve a data value in the slot, and free the slot for reuse after the thread procedure ends and the object has been reclaimed by garbage collection. Data slots are unique per thread. No other thread (not even a child thread) can get that data. > [!NOTE] -> is a `Shared` method that always applies to the currently executing thread, even if you call it using a variable that refers to another thread. To avoid confusion, use the class name when calling `Shared` methods: `Thread.SetData(testSlot, "test data")`. +> is a `Shared` method that always applies to the currently executing thread, even if you call it using a variable that refers to another thread. To avoid confusion, use the class name when calling `Shared` methods: `Thread.SetData(testSlot, "test data")`. ## Examples This section contains two code examples. The first example shows how to use a field that is marked with the attribute to hold thread-specific information. The second example shows how to use a data slot to do the same thing. @@ -3488,10 +3488,10 @@ The value is not guaranteed to be a zero-based processor number. This method does not perform standard COM and SendMessage pumping. > [!NOTE] -> If you need to sleep on a thread that has , but you want to perform standard COM and SendMessage pumping, consider using one of the overloads of the method that specifies a timeout interval. +> If you need to sleep on a thread that has , but you want to perform standard COM and SendMessage pumping, consider using one of the overloads of the method that specifies a timeout interval. ## Examples - The following example uses the method to block the application's main thread. + The following example uses the method to block the application's main thread. :::code language="csharp" source="~/snippets/csharp/System.Threading/Thread/Sleep/example.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading/Thread/Sleep/example.fs" id="Snippet1"::: @@ -3553,15 +3553,15 @@ The value is not guaranteed to be a zero-based processor number. You can specify for the `timeout` parameter to suspend the thread indefinitely. However, we recommend that you use other classes such as , , , or instead to synchronize threads or manage resources. - This overload of uses the total number of whole milliseconds in `timeout`. Fractional milliseconds are discarded. + This overload of uses the total number of whole milliseconds in `timeout`. Fractional milliseconds are discarded. This method does not perform standard COM and SendMessage pumping. > [!NOTE] -> If you need to sleep on a thread that has , but you want to perform standard COM and SendMessage pumping, consider using one of the overloads of the method that specifies a timeout interval. +> If you need to sleep on a thread that has , but you want to perform standard COM and SendMessage pumping, consider using one of the overloads of the method that specifies a timeout interval. ## Examples - The following example uses the method overload to block the application's main thread five times, for two seconds each time. + The following example uses the method overload to block the application's main thread five times, for two seconds each time. :::code language="csharp" source="~/snippets/csharp/System.Threading/Thread/Sleep/example1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading/Thread/Sleep/example1.fs" id="Snippet1"::: @@ -3628,14 +3628,14 @@ The value is not guaranteed to be a zero-based processor number. method is useful for implementing locks. Classes in the .NET Framework, such as and , use this method internally. essentially puts the processor into a very tight loop, with the loop count specified by the `iterations` parameter. The duration of the wait therefore depends on the speed of the processor. + The method is useful for implementing locks. Classes in the .NET Framework, such as and , use this method internally. essentially puts the processor into a very tight loop, with the loop count specified by the `iterations` parameter. The duration of the wait therefore depends on the speed of the processor. - Contrast this with the method. A thread that calls yields the rest of its current slice of processor time, even if the specified interval is zero. Specifying a non-zero interval for removes the thread from consideration by the thread scheduler until the time interval has elapsed. + Contrast this with the method. A thread that calls yields the rest of its current slice of processor time, even if the specified interval is zero. Specifying a non-zero interval for removes the thread from consideration by the thread scheduler until the time interval has elapsed. - is not generally useful for ordinary applications. In most cases, you should use the synchronization classes provided by the .NET Framework; for example, call or a statement that wraps (`lock` in C# or `SyncLock` in Visual Basic). + is not generally useful for ordinary applications. In most cases, you should use the synchronization classes provided by the .NET Framework; for example, call or a statement that wraps (`lock` in C# or `SyncLock` in Visual Basic). > [!CAUTION] -> In the rare case where it is advantageous to avoid a context switch, such as when you know that a state change is imminent, make a call to the method in your loop. The code executes is designed to prevent problems that can occur on computers with multiple processors. For example, on computers with multiple Intel processors employing Hyper-Threading technology, prevents processor starvation in certain situations. +> In the rare case where it is advantageous to avoid a context switch, such as when you know that a state change is imminent, make a call to the method in your loop. The code executes is designed to prevent problems that can occur on computers with multiple processors. For example, on computers with multiple Intel processors employing Hyper-Threading technology, prevents processor starvation in certain situations. ]]> @@ -3705,7 +3705,7 @@ The value is not guaranteed to be a zero-based processor number. state, the operating system can schedule it for execution. The thread begins executing at the first line of the method represented by the or delegate supplied to the thread constructor. Note that the call to does not block the calling thread. + Once a thread is in the state, the operating system can schedule it for execution. The thread begins executing at the first line of the method represented by the or delegate supplied to the thread constructor. Note that the call to does not block the calling thread. > [!NOTE] > If this overload is used with a thread created using a delegate, `null` is passed to the method executed by the thread. @@ -3784,7 +3784,7 @@ The value is not guaranteed to be a zero-based processor number. state, the operating system can schedule it for execution. The thread begins executing at the first line of the method represented by the or delegate supplied to the thread constructor. Note that the call to does not block the calling thread. + Once a thread is in the state, the operating system can schedule it for execution. The thread begins executing at the first line of the method represented by the or delegate supplied to the thread constructor. Note that the call to does not block the calling thread. Once the thread terminates, it cannot be restarted with another call to `Start`. @@ -3871,7 +3871,7 @@ The value is not guaranteed to be a zero-based processor number. If the thread is already suspended, this method has no effect. > [!CAUTION] -> Do not use the and methods to synchronize the activities of threads. You have no way of knowing what code a thread is executing when you suspend it. If you suspend a thread while it holds locks during a security permission evaluation, other threads in the might be blocked. If you suspend a thread while it is executing a class constructor, other threads in the that attempt to use that class are blocked. Deadlocks can occur very easily. +> Do not use the and methods to synchronize the activities of threads. You have no way of knowing what code a thread is executing when you suspend it. If you suspend a thread while it holds locks during a security permission evaluation, other threads in the might be blocked. If you suspend a thread while it is executing a class constructor, other threads in the that attempt to use that class are blocked. Deadlocks can occur very easily. When you call the `Suspend` method on a thread, the system notes that a thread suspension has been requested and allows the thread to execute until it reaches a safe point before actually suspending the thread. A safe point for a thread is a point in its execution at which garbage collection can be performed. Once a safe point is reached, the runtime guarantees that the suspended thread will not make any further progress in managed code. A thread executing outside managed code is always safe for garbage collection, and its execution continues until it attempts to resume execution of managed code. @@ -4206,12 +4206,12 @@ When you call the `Suspend` method on a thread, the system notes that a thread s > [!NOTE] > The main application thread is initialized to by default. The only way to set the apartment state of the main application thread to is to apply the attribute to the entry point method. - The method, along with the method and the method, replaces the property. + The method, along with the method and the method, replaces the property. ## Examples - The following code example demonstrates the , , and methods. The code example creates a thread. Before the thread is started, displays the initial state and changes the state to . The method then returns `false` when attempting to change the state to because the apartment state is already set. If the same operation had been attempted with , would have been thrown. + The following code example demonstrates the , , and methods. The code example creates a thread. Before the thread is started, displays the initial state and changes the state to . The method then returns `false` when attempting to change the state to because the apartment state is already set. If the same operation had been attempted with , would have been thrown. - After the thread is started, the method is used again. This time it throws because the thread has already been started. + After the thread is started, the method is used again. This time it throws because the thread has already been started. :::code language="csharp" source="~/snippets/csharp/System.Threading/Thread/GetApartmentState/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading/Thread/GetApartmentState/source.fs" id="Snippet1"::: @@ -4388,7 +4388,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -4451,7 +4451,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -4514,7 +4514,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -4577,7 +4577,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -4640,7 +4640,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -4703,7 +4703,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -4780,7 +4780,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -4847,7 +4847,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -4910,7 +4910,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -4977,7 +4977,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -5044,7 +5044,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -5111,7 +5111,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -5178,7 +5178,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -5252,7 +5252,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -5316,7 +5316,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -5380,7 +5380,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -5444,7 +5444,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -5508,7 +5508,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -5572,7 +5572,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -5644,7 +5644,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -5712,7 +5712,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -5776,7 +5776,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -5844,7 +5844,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -5912,7 +5912,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -5980,7 +5980,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -6048,7 +6048,7 @@ Unlike , which captures the c and are legacy APIs and have been replaced by and . See the class for more information. + and are legacy APIs and have been replaced by and . See the class for more information. ]]> @@ -6111,7 +6111,7 @@ Unlike , which captures the c Yielding is limited to the processor that is executing the calling thread. The operating system will not switch execution to another processor, even if that processor is idle or is running a thread of lower priority. If there are no other threads that are ready to execute on the current processor, the operating system does not yield execution, and this method returns `false`. - This method is equivalent to using platform invoke to call the native Win32 `SwitchToThread` function. You should call the method instead of using platform invoke, because platform invoke bypasses any custom threading behavior the host has requested. + This method is equivalent to using platform invoke to call the native Win32 `SwitchToThread` function. You should call the method instead of using platform invoke, because platform invoke bypasses any custom threading behavior the host has requested. ]]> diff --git a/xml/System.Threading/ThreadAbortException.xml b/xml/System.Threading/ThreadAbortException.xml index b64b03857aa..fdcaa7aad70 100644 --- a/xml/System.Threading/ThreadAbortException.xml +++ b/xml/System.Threading/ThreadAbortException.xml @@ -64,13 +64,13 @@ method to destroy a thread, the common language runtime throws a on .NET Framework. is a special exception that can be caught, but it will automatically be raised again at the end of the `catch` block. When this exception is raised, the runtime executes all the `finally` blocks before ending the thread. Because the thread can do an unbounded computation in the `finally` blocks or call to cancel the abort, there is no guarantee that the thread will ever end. If you want to wait until the aborted thread has ended, you can call the method. is a blocking call that does not return until the thread actually stops executing. + When a call is made to the method to destroy a thread, the common language runtime throws a on .NET Framework. is a special exception that can be caught, but it will automatically be raised again at the end of the `catch` block. When this exception is raised, the runtime executes all the `finally` blocks before ending the thread. Because the thread can do an unbounded computation in the `finally` blocks or call to cancel the abort, there is no guarantee that the thread will ever end. If you want to wait until the aborted thread has ended, you can call the method. is a blocking call that does not return until the thread actually stops executing. > [!NOTE] -> **.NET Core and .NET 5+ only:** Even though this type exists in .NET Core and .NET 5+, since is not supported, the common language runtime won't ever throw . +> **.NET Core and .NET 5+ only:** Even though this type exists in .NET Core and .NET 5+, since is not supported, the common language runtime won't ever throw . > [!NOTE] -> When the common language runtime (CLR) stops background threads after all foreground threads in a managed executable have ended, it does not use . Therefore, you cannot use to detect when background threads are being terminated by the CLR. +> When the common language runtime (CLR) stops background threads after all foreground threads in a managed executable have ended, it does not use . Therefore, you cannot use to detect when background threads are being terminated by the CLR. uses `HRESULT COR_E_THREADABORTED`, which has the value `0x80131530`. @@ -78,7 +78,7 @@ > The value of the inherited property is always `null`. ## Examples - The following example demonstrates aborting a thread. The thread that receives the `ThreadAbortException` uses the method to cancel the abort request and continue executing. + The following example demonstrates aborting a thread. The thread that receives the `ThreadAbortException` uses the method to cancel the abort request and continue executing. :::code language="csharp" source="~/snippets/csharp/System.Threading/ThreadAbortException/Overview/threadabex.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/ThreadAbortException/Overview/threadabex.vb" id="Snippet1"::: @@ -152,7 +152,7 @@ Main ending. method. The exact content and usage of this object is application defined; it is typically used to convey information that is meaningful to the thread being aborted. + The object returned by this property is specified through the `stateInfo` parameter of the method. The exact content and usage of this object is application defined; it is typically used to convey information that is meaningful to the thread being aborted. diff --git a/xml/System.Threading/ThreadInterruptedException.xml b/xml/System.Threading/ThreadInterruptedException.xml index 391942a2ea5..8e38a150e5d 100644 --- a/xml/System.Threading/ThreadInterruptedException.xml +++ b/xml/System.Threading/ThreadInterruptedException.xml @@ -64,11 +64,11 @@ states until it is destroyed. Calling when a thread is in the state will cause a to be thrown in the target thread. If the thread is not in the state, the exception is not thrown until the thread enters that state. If the thread never blocks, it could complete without ever being interrupted. + After a thread is created, it is in one or more states until it is destroyed. Calling when a thread is in the state will cause a to be thrown in the target thread. If the thread is not in the state, the exception is not thrown until the thread enters that state. If the thread never blocks, it could complete without ever being interrupted. uses the HRESULT COR_E_THREADINTERRUPTED, which has the value 0x80131519. - For a list of initial property values for an instance of , see the constructors. + For a list of initial property values for an instance of , see the constructors. @@ -138,8 +138,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The localized error message string.| +||`null`.| +||The localized error message string.| ]]> @@ -194,8 +194,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string.| +||`null`.| +||The error message string.| ]]> @@ -320,8 +320,8 @@ |Property|Value| |--------------|-----------| -||The inner exception reference.| -||The error message string.| +||The inner exception reference.| +||The error message string.| ]]> diff --git a/xml/System.Threading/ThreadLocal`1.xml b/xml/System.Threading/ThreadLocal`1.xml index 9a19d8f5d8c..c107d5d310f 100644 --- a/xml/System.Threading/ThreadLocal`1.xml +++ b/xml/System.Threading/ThreadLocal`1.xml @@ -83,7 +83,7 @@ : + The following example shows how to use : :::code language="csharp" source="~/snippets/csharp/System.Threading/ThreadLocalT/Overview/threadlocal.cs" id="Snippet01"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/ThreadLocalT/Overview/threadlocal.vb" id="Snippet01"::: @@ -153,9 +153,9 @@ is accessed for the first time. + The default value of `T` is used to initialize the instance when is accessed for the first time. - This constructor is equivalent to calling the constructor with a value of `false` for the `trackAllValues` argument. + This constructor is equivalent to calling the constructor with a value of `false` for the `trackAllValues` argument. ]]> @@ -208,7 +208,7 @@ property to retrieve all values throws an exception. + If `trackAllValues` is `false`, only the value of this instance for the current thread is accessible. Attempting to use the property to retrieve all values throws an exception. ]]> @@ -307,7 +307,7 @@ property to retrieve all values throws an exception. + If `trackAllValues` is `false`, only the value of this instance for the current thread is accessible. Attempting to use the property to retrieve all values throws an exception. ]]> @@ -372,12 +372,12 @@ . 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 the was occupying. + 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 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 `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. ]]> @@ -432,7 +432,7 @@ , this method is not thread-safe. + Unlike most of the members of , this method is not thread-safe. ]]> @@ -577,7 +577,7 @@ directly. + Calling this method forces initialization for the current thread, as is the case with accessing directly. ]]> @@ -639,10 +639,10 @@ will initialize it. - If a value factory was supplied during the construction, initialization will happen by invoking the function to retrieve the initial value for . + If this instance was not previously initialized for the current thread, accessing will initialize it. + If a value factory was supplied during the construction, initialization will happen by invoking the function to retrieve the initial value for . Otherwise, the default value of `T` will be used. - Regardless of the initialization method, will be set to `true`. + Regardless of the initialization method, will be set to `true`. ]]> diff --git a/xml/System.Threading/ThreadPool.xml b/xml/System.Threading/ThreadPool.xml index 31f599ebbb0..6ed54a33339 100644 --- a/xml/System.Threading/ThreadPool.xml +++ b/xml/System.Threading/ThreadPool.xml @@ -62,13 +62,13 @@ ## Remarks Many applications create threads that spend a great deal of time in the sleeping state, waiting for an event to occur. Other threads might enter a sleeping state only to be awakened periodically to poll for a change or update status information. The thread pool enables you to use threads more efficiently by providing your application with a pool of worker threads that are managed by the system. Examples of operations that use thread pool threads include the following: -- When you create a or object to perform some task asynchronously, by default the task is scheduled to run on a thread pool thread. +- When you create a or object to perform some task asynchronously, by default the task is scheduled to run on a thread pool thread. - Asynchronous timers use the thread pool. Thread pool threads execute callbacks from the class and raise events from the class. - 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 +- 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) @@ -78,19 +78,19 @@ 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. + 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. - 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. + 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. Timer-queue timers and registered wait operations also use the thread pool. Their callback functions are queued to the thread pool. - There is one thread pool per process. Beginning with the .NET Framework 4, the default size of the thread pool for a process depends on several factors, such as the size of the virtual address space. A process can call the method to determine the number of threads. The number of threads in the thread pool can be changed by using the method. Each thread uses the default stack size and runs at the default priority. + There is one thread pool per process. Beginning with the .NET Framework 4, the default size of the thread pool for a process depends on several factors, such as the size of the virtual address space. A process can call the method to determine the number of threads. The number of threads in the thread pool can be changed by using the method. Each thread uses the default stack size and runs at the default priority. > [!NOTE] > Unmanaged code that hosts the .NET Framework can change the size of the thread pool by using the `CorSetMaxThreads` function, defined in the mscoree.h file. @@ -100,10 +100,10 @@ > [!NOTE] > 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. + 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. @@ -113,7 +113,7 @@ :::code language="csharp" source="~/snippets/csharp/System.Threading/ThreadPool/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/ThreadPool/Overview/source.vb" id="Snippet1"::: - If you comment out the call to the method, the main thread exits before method runs on the thread pool thread. The thread pool uses background threads, which do not keep the application running if all foreground threads have terminated. (This is a simple example of a race condition.) + If you comment out the call to the method, the main thread exits before method runs on the thread pool thread. The thread pool uses background threads, which do not keep the application running if all foreground threads have terminated. (This is a simple example of a race condition.) ]]> @@ -369,7 +369,7 @@ If a thread pool implementation may have different types of work items, the coun returns, the variable specified by `workerThreads` contains the number of additional worker threads that can be started, and the variable specified by `completionPortThreads` contains the number of additional asynchronous I/O threads that can be started. + When returns, the variable specified by `workerThreads` contains the number of additional worker threads that can be started, and the variable specified by `completionPortThreads` contains the number of additional asynchronous I/O threads that can be started. If there are no available threads, additional thread pool requests remain queued until thread pool threads become available. @@ -443,11 +443,11 @@ If a thread pool implementation may have different types of work items, the coun returns, the variable specified by `workerThreads` contains the maximum number of worker threads allowed in the thread pool, and the variable specified by `completionPortThreads` contains the maximum number of asynchronous I/O threads allowed in the thread pool. + When returns, the variable specified by `workerThreads` contains the maximum number of worker threads allowed in the thread pool, and the variable specified by `completionPortThreads` contains the maximum number of asynchronous I/O threads allowed in the thread pool. - You can use the method to determine the actual number of threads in the thread pool at any given time. + You can use the method to determine the actual number of threads in the thread pool at any given time. - You can use the to set the maximum number of worker threads and asynchronous I/O threads in the thread pool. + You can use the to set the maximum number of worker threads and asynchronous I/O threads in the thread pool. You can queue as many thread pool requests as system memory allows. If there are more requests than thread pool threads, the additional requests remain queued until thread pool threads become available. @@ -642,17 +642,17 @@ If a thread pool implementation may have different types of work items, the coun if the method is successfully queued; is thrown if the work item could not be queued. overload that accepts an object containing the necessary data. +You can place data required by the queued method in the instance fields of the class in which the method is defined, or you can use the overload that accepts an object containing the necessary data. > [!NOTE] -> Visual Basic users can omit the constructor, and simply use the `AddressOf` operator when passing the callback method to . Visual Basic automatically calls the correct delegate constructor. +> Visual Basic users can omit the constructor, and simply use the `AddressOf` operator when passing the callback method to . Visual Basic automatically calls the correct delegate constructor. -The property value is propagated to worker threads queued using the method. +The property value is propagated to worker threads queued using the method. ]]> method overload to queue a task, which is represented by the `ThreadProc` method, to execute when a thread becomes available. No task information is supplied with this overload. Therefore, the information that is available to the `ThreadProc` method is limited to the object the method belongs to. +The following example uses the method overload to queue a task, which is represented by the `ThreadProc` method, to execute when a thread becomes available. No task information is supplied with this overload. Therefore, the information that is available to the `ThreadProc` method is limited to the object the method belongs to. :::code language="csharp" source="~/snippets/csharp/System.Threading/ThreadPool/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/ThreadPool/Overview/source.vb" id="Snippet1"::: @@ -732,12 +732,12 @@ The following example uses the [!NOTE] -> Visual Basic users can omit the constructor, and simply use the `AddressOf` operator when passing the callback method to . Visual Basic automatically calls the correct delegate constructor. +> Visual Basic users can omit the constructor, and simply use the `AddressOf` operator when passing the callback method to . Visual Basic automatically calls the correct delegate constructor. ## Examples - The following example uses the .NET thread pool to calculate the `Fibonacci` result for five numbers between 20 and 40. Each `Fibonacci` result is represented by the `Fibonacci` class, which provides a method named `ThreadPoolCallback` that performs the calculation. An object that represents each `Fibonacci` value is created, and the `ThreadPoolCallback` method is passed to , which assigns an available thread in the pool to execute the method. + The following example uses the .NET thread pool to calculate the `Fibonacci` result for five numbers between 20 and 40. Each `Fibonacci` result is represented by the `Fibonacci` class, which provides a method named `ThreadPoolCallback` that performs the calculation. An object that represents each `Fibonacci` value is created, and the `ThreadPoolCallback` method is passed to , which assigns an available thread in the pool to execute the method. - Because each `Fibonacci` object is given a semi-random value to compute, and because each thread will be competing for processor time, you cannot know in advance how long it will take for all five results to be calculated. That is why each `Fibonacci` object is passed an instance of the class during construction. Each object signals the provided event object when its calculation is complete, which allows the primary thread to block execution with until all five `Fibonacci` objects have calculated a result. The `Main` method then displays each `Fibonacci` result. + Because each `Fibonacci` object is given a semi-random value to compute, and because each thread will be competing for processor time, you cannot know in advance how long it will take for all five results to be calculated. That is why each `Fibonacci` object is passed an instance of the class during construction. Each object signals the provided event object when its calculation is complete, which allows the primary thread to block execution with until all five `Fibonacci` objects have calculated a result. The `Main` method then displays each `Fibonacci` result. :::code language="csharp" source="~/snippets/csharp/System.Threading/ThreadPool/QueueUserWorkItem/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/ThreadPool/QueueUserWorkItem/source.vb" id="Snippet1"::: @@ -890,21 +890,21 @@ The following example uses the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. - The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: + The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: - The specified object is in the signaled state. - The time-out interval elapses. - 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. + 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. - To cancel the wait operation, call the method. + To cancel the wait operation, call the method. - The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. + The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. Before returning, the function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the wait condition to be satisfied. For example, the count of a semaphore is decreased by one. @@ -989,21 +989,21 @@ The following example uses the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. - The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: + The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: - The specified object is in the signaled state. - The time-out interval elapses. - 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. + 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. - To cancel the wait operation, call the method. + To cancel the wait operation, call the method. - The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. + The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. Before returning, the function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the wait condition to be satisfied. For example, the count of a semaphore is decreased by one. @@ -1088,21 +1088,21 @@ The following example uses the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. - The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: + The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: - The specified object is in the signaled state. - The time-out interval elapses. - 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. + 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. - To cancel the wait operation, call the method. + To cancel the wait operation, call the method. - The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. + The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. Before returning, the function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the wait condition to be satisfied. For example, the count of a semaphore is decreased by one. @@ -1192,32 +1192,32 @@ The following example uses the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. - The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: + The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: - The specified object is in the signaled state. - The time-out interval elapses. - 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. + 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. - To cancel the wait operation, call the method. + To cancel the wait operation, call the method. - The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. + The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. Before returning, the function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the wait condition to be satisfied. For example, the count of a semaphore is decreased by one. ## Examples - The following example shows how to use the method to execute a specified callback method when a specified wait handle is signaled. In this example, the callback method is `WaitProc`, and the wait handle is an . + The following example shows how to use the method to execute a specified callback method when a specified wait handle is signaled. In this example, the callback method is `WaitProc`, and the wait handle is an . - The example defines a `TaskInfo` class to hold the information that is passed to the callback when it executes. The example creates a `TaskInfo` object and assigns it some string data. The that is returned by the method is assigned to the `Handle` field of the `TaskInfo` object so that the callback method has access to the . + The example defines a `TaskInfo` class to hold the information that is passed to the callback when it executes. The example creates a `TaskInfo` object and assigns it some string data. The that is returned by the method is assigned to the `Handle` field of the `TaskInfo` object so that the callback method has access to the . - In addition to specifying `TaskInfo` as the object to pass to the callback method, the call to the method specifies the that the task will wait for, a delegate that represents the `WaitProc` callback method, a one second time-out interval, and multiple callbacks. + In addition to specifying `TaskInfo` as the object to pass to the callback method, the call to the method specifies the that the task will wait for, a delegate that represents the `WaitProc` callback method, a one second time-out interval, and multiple callbacks. - When the main thread signals the by calling its method, the delegate is invoked. The `WaitProc` method tests to determine whether a time-out occurred. If the callback was invoked because the wait handle was signaled, the `WaitProc` method unregisters the , stopping additional callbacks. In the case of a time-out, the task continues to wait. The `WaitProc` method ends by printing a message to the console. + When the main thread signals the by calling its method, the delegate is invoked. The `WaitProc` method tests to determine whether a time-out occurred. If the callback was invoked because the wait handle was signaled, the `WaitProc` method unregisters the , stopping additional callbacks. In the case of a time-out, the task continues to wait. The `WaitProc` method ends by printing a message to the console. :::code language="csharp" source="~/snippets/csharp/System.Threading/RegisteredWaitHandle/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/RegisteredWaitHandle/Overview/source.vb" id="Snippet1"::: @@ -1285,7 +1285,7 @@ The following example uses the property. In addition, you cannot set the maximum number of worker threads or I/O completion threads to a number smaller than the corresponding minimum number of worker threads or I/O completion threads. To determine the minimum thread pool size, call the method. + You cannot set the maximum number of worker threads or I/O completion threads to a number smaller than the number of processors on the computer. To determine how many processors are present, retrieve the value of the property. In addition, you cannot set the maximum number of worker threads or I/O completion threads to a number smaller than the corresponding minimum number of worker threads or I/O completion threads. To determine the minimum thread pool size, call the method. If the common language runtime is hosted, for example by Internet Information Services (IIS) or SQL Server, the host can limit or prevent changes to the thread pool size. @@ -1366,9 +1366,9 @@ The following example uses the ), returns `false` and does not change either of the minimum values. + If you specify a negative number or a number larger than the maximum number of active thread pool threads (obtained using ), returns `false` and does not change either of the minimum values. - By default, the minimum number of threads is set to the processor count. You can use to increase the minimum number of threads, such as to temporarily work around issues where some queued work items or tasks block thread pool threads. Those blockages sometimes lead to a situation where all worker or I/O completion threads are blocked (starvation). However, increasing the minimum number of threads might degrade performance in other ways, such as: + By default, the minimum number of threads is set to the processor count. You can use to increase the minimum number of threads, such as to temporarily work around issues where some queued work items or tasks block thread pool threads. Those blockages sometimes lead to a situation where all worker or I/O completion threads are blocked (starvation). However, increasing the minimum number of threads might degrade performance in other ways, such as: - The thread pool may schedule more worker threads, even when the worker threads are not getting blocked. The oversubscription can cause threads that get scheduled-out to be significantly delayed as they wait in a long queue to get another time slice, delaying some work items or tasks. - Worker threads may take more CPU time in dequeuing work items due to having to scan more threads to steal work from. @@ -1377,7 +1377,7 @@ The following example uses the [!CAUTION] -> Using the method to increase the minimum number of threads can cause performance problems as described in the preceding text. In most cases, the thread pool will perform better with its own algorithm for allocating threads. Reducing the minimum to less than the number of processors can also hurt performance. +> Using the method to increase the minimum number of threads can cause performance problems as described in the preceding text. In most cases, the thread pool will perform better with its own algorithm for allocating threads. Reducing the minimum to less than the number of processors can also hurt performance. @@ -1495,7 +1495,7 @@ If a thread pool implementation may have different types of threads, the count i For information about using native Win32 overlapped I/O, see the class, the structure, and the `OVERLAPPED` structure in the Win32 Platform SDK. > [!CAUTION] -> Using the method could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread does not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. +> Using the method could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread does not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. ]]> @@ -1617,10 +1617,10 @@ The thread pool will invoke the work item's method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. + Unlike the method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. > [!CAUTION] -> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. +> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. ]]> @@ -1772,14 +1772,14 @@ The thread pool will invoke the work item's method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. + Unlike the method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. > [!CAUTION] -> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. +> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. 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. - When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. ]]> @@ -1862,14 +1862,14 @@ The thread pool will invoke the work item's method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. + Unlike the method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. > [!CAUTION] -> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. +> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. 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. - When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. ]]> @@ -1952,14 +1952,14 @@ The thread pool will invoke the work item's method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. + Unlike the method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. > [!CAUTION] -> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. +> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. 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. - When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. ]]> @@ -2047,14 +2047,14 @@ The thread pool will invoke the work item's method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. + Unlike the method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. > [!CAUTION] -> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. +> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. 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. - When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. ]]> diff --git a/xml/System.Threading/ThreadPoolBoundHandle.xml b/xml/System.Threading/ThreadPoolBoundHandle.xml index b4449eb326f..9cead8b544e 100644 --- a/xml/System.Threading/ThreadPoolBoundHandle.xml +++ b/xml/System.Threading/ThreadPoolBoundHandle.xml @@ -126,21 +126,21 @@ Returns an unmanaged pointer to a structure using the callback state and buffers associated with the specified object. An unmanaged pointer to a structure. - structure is fixed in physical memory until the method is called. - + structure is fixed in physical memory until the method is called. + ]]> is . is currently in use for another I/O operation. - This method was called after the was disposed. - - -or- - + This method was called after the was disposed. + + -or- + This method was called after was disposed. @@ -211,12 +211,12 @@ structure is fixed in physical memory until is called. +The unmanaged pointer returned by this method can be passed to the operating system in overlapped I/O operations. The structure is fixed in physical memory until is called. > [!NOTE] > The buffers specified in `pinData` are pinned for the duration of the I/O operation. -The buffer or buffers specified in `pinData` must be the same as those passed to the unmanaged operating system function that performs the asynchronous I/O. +The buffer or buffers specified in `pinData` must be the same as those passed to the unmanaged operating system function that performs the asynchronous I/O. ]]> @@ -274,30 +274,30 @@ The buffer or buffers specified in `pinData` must be the same as those passed to Returns a for the specified handle, which is bound to the system thread pool. A for , which is bound to the system thread pool. - object does not take ownership of `handle`; it remains the responsibility of the caller to call . - + object does not take ownership of `handle`; it remains the responsibility of the caller to call . + ]]> is . - has been disposed. - - -or- - - does not refer to a valid I/O handle. - - -or- - - refers to a handle that has not been opened for overlapped I/O. - - -or- - + has been disposed. + + -or- + + does not refer to a valid I/O handle. + + -or- + + refers to a handle that has not been opened for overlapped I/O. + + -or- + refers to a handle that has already been bound. @@ -396,13 +396,13 @@ The buffer or buffers specified in `pinData` must be the same as those passed to An unmanaged pointer to the structure to be freed. Frees the memory associated with a structure allocated by the method. - [!CAUTION] -> You must call the method exactly once on every unmanaged pointer allocated by using the method. If you do not call the method, you will leak memory. If you call the method more than once on the same unmanaged pointer, memory will be corrupted. - +> You must call the method exactly once on every unmanaged pointer allocated by using the method. If you do not call the method, you will leak memory. If you call the method more than once on the same unmanaged pointer, memory will be corrupted. + ]]> diff --git a/xml/System.Threading/ThreadStart.xml b/xml/System.Threading/ThreadStart.xml index bdadc7f0d9f..a50ccc996c2 100644 --- a/xml/System.Threading/ThreadStart.xml +++ b/xml/System.Threading/ThreadStart.xml @@ -59,10 +59,10 @@ delegate or a delegate that is passed to the constructor. The thread does not begin executing until the method is called. Execution begins at the first line of the method represented by the or delegate. + When a managed thread is created, the method that executes on the thread is represented by a delegate or a delegate that is passed to the constructor. The thread does not begin executing until the method is called. Execution begins at the first line of the method represented by the or delegate. > [!NOTE] -> Visual Basic and C# users can omit the or delegate constructor when creating a thread. In Visual Basic, use the `AddressOf` operator when passing your method to the constructor; for example, `Dim t As New Thread(AddressOf ThreadProc)`. In C#, simply specify the name of the thread procedure. The compiler selects the correct delegate constructor. +> Visual Basic and C# users can omit the or delegate constructor when creating a thread. In Visual Basic, use the `AddressOf` operator when passing your method to the constructor; for example, `Dim t As New Thread(AddressOf ThreadProc)`. In C#, simply specify the name of the thread procedure. The compiler selects the correct delegate constructor. ## Examples The following code example shows the syntax for creating and using a delegate with an instance method and with a static method. diff --git a/xml/System.Threading/ThreadState.xml b/xml/System.Threading/ThreadState.xml index eeeaea076c0..29ae4ea80ce 100644 --- a/xml/System.Threading/ThreadState.xml +++ b/xml/System.Threading/ThreadState.xml @@ -66,9 +66,9 @@ ## Remarks The `ThreadState` enumeration defines a set of all possible execution states for threads. It's of interest only in a few debugging scenarios. Your code should never use the thread state to synchronize the activities of threads. - Once a thread is created, it's in at least one of the states until it terminates. Threads created within the common language runtime are initially in the state, while external, or unmanaged, threads that come into the runtime are already in the state. A thread is transitioned from the state into the state by calling . Once a thread leaves the state as the result of a call to , it can never return to the state. + Once a thread is created, it's in at least one of the states until it terminates. Threads created within the common language runtime are initially in the state, while external, or unmanaged, threads that come into the runtime are already in the state. A thread is transitioned from the state into the state by calling . Once a thread leaves the state as the result of a call to , it can never return to the state. - A thread can be in more than one state at a given time. For example, if a thread is blocked on a call to , and another thread calls on the blocked thread, the blocked thread will be in both the and states at the same time. In this case, as soon as the thread returns from the call to or is interrupted, it will receive the to begin aborting. Not all combinations of `ThreadState` values are valid; for example, a thread cannot be in both the and states. + A thread can be in more than one state at a given time. For example, if a thread is blocked on a call to , and another thread calls on the blocked thread, the blocked thread will be in both the and states at the same time. In this case, as soon as the thread returns from the call to or is interrupted, it will receive the to begin aborting. Not all combinations of `ThreadState` values are valid; for example, a thread cannot be in both the and states. A thread can never leave the state. @@ -80,16 +80,16 @@ |Action|ThreadState| |------------|-----------------| |A thread is created within the common language runtime.|| -|Another thread calls the method on the new thread, and the call returns.

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

The method does not return until the new thread has started running. There is no way to know at what point the new thread will start running, during the call to .|| +|The thread calls || +|The thread calls on another object.|| +|The thread calls on another thread.|| +|Another thread calls || +|Another thread calls || +|The thread responds to a request.|| +|Another thread calls || +|Another thread calls || +|The thread responds to an request.|| |A thread is terminated.|| In addition to the states noted above, there is also the state, which indicates whether the thread is running in the background or foreground. For more information, see [Foreground and Background Threads](/dotnet/standard/threading/foreground-and-background-threads). diff --git a/xml/System.Threading/ThreadStateException.xml b/xml/System.Threading/ThreadStateException.xml index 6157fc0c15b..e961846b3ac 100644 --- a/xml/System.Threading/ThreadStateException.xml +++ b/xml/System.Threading/ThreadStateException.xml @@ -71,11 +71,11 @@ states until it terminates. `ThreadStateException` is thrown by methods that cannot perform the requested operation due to the current state of a thread. For example, trying to restart an aborted thread by calling on a thread that has terminated throws a . + Once a thread is created, it is in at least one of the states until it terminates. `ThreadStateException` is thrown by methods that cannot perform the requested operation due to the current state of a thread. For example, trying to restart an aborted thread by calling on a thread that has terminated throws a . uses the HRESULT COR_E_THREADSTATE, which has the value 0x80131520. - For a list of initial property values for an instance of , see the constructors. + For a list of initial property values for an instance of , see the constructors. @@ -157,8 +157,8 @@ In main. Attempting to restart myThread. |Property|Value| |--------------|-----------| -||`null`.| -||The localized error message string.| +||`null`.| +||The localized error message string.| ]]> @@ -215,8 +215,8 @@ In main. Attempting to restart myThread. |Property|Value| |--------------|-----------| -||`null`.| -||The error message string.| +||`null`.| +||The error message string.| ]]> @@ -341,8 +341,8 @@ In main. Attempting to restart myThread. |Property|Value| |--------------|-----------| -||The inner exception reference.| -||The error message string.| +||The inner exception reference.| +||The error message string.| ]]> diff --git a/xml/System.Threading/Timeout.xml b/xml/System.Threading/Timeout.xml index 963e8574992..65a7dc51139 100644 --- a/xml/System.Threading/Timeout.xml +++ b/xml/System.Threading/Timeout.xml @@ -64,13 +64,13 @@ is used by methods that accept an integer `millisecondsTimeout` parameter, such as , , and . is used by methods that accept a `timeout` parameter of type , such as , , and . + The members of this class are used to specify infinite time-out intervals in threading operations. is used by methods that accept an integer `millisecondsTimeout` parameter, such as , , and . is used by methods that accept a `timeout` parameter of type , such as , , and . ## Examples The following example shows a thread going to sleep for an infinite time and subsequently being woken up. - + :::code language="csharp" source="~/snippets/csharp/System.Threading/Thread/Interrupt/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Thread/Interrupt/source.vb" id="Snippet1"::: @@ -128,7 +128,7 @@ and , this value is used to suspend the thread indefinitely. However, in most cases, we recommend that you use other classes, such as , , , or instead, to synchronize threads or manage resources. + For threading methods that accept a `millisecondsTimeout` parameter, such as and , this value is used to suspend the thread indefinitely. However, in most cases, we recommend that you use other classes, such as , , , or instead, to synchronize threads or manage resources. The value of this field is -1 (0xFFFFFFFF). @@ -186,7 +186,7 @@ , such as and , this value is used to suspend the thread indefinitely. However, in most cases, we recommend that you use other classes, such as , , , or instead, to synchronize threads or manage resources. + For threading methods that accept a `timeout` parameter of type , such as and , this value is used to suspend the thread indefinitely. However, in most cases, we recommend that you use other classes, such as , , , or instead, to synchronize threads or manage resources. The value of this field is -00:00:00.0010000, or -1 millisecond. diff --git a/xml/System.Threading/Timer.xml b/xml/System.Threading/Timer.xml index fd48bee721d..d25420e5e22 100644 --- a/xml/System.Threading/Timer.xml +++ b/xml/System.Threading/Timer.xml @@ -119,7 +119,7 @@ The timer delegate is specified when the timer is constructed and cannot be chan > - (.NET Framework only), an ASP.NET component that performs asynchronous or synchronous web page postbacks at a regular interval. > - , a timer that's integrated into the `Dispatcher` queue. This timer is processed with a specified priority at a specified time interval. - When you create a timer, you can specify an amount of time to wait before the first execution of the method (due time), and an amount of time to wait between subsequent executions (period). The class has the same resolution as the system clock. This means that if the period is less than the resolution of the system clock, the delegate will execute at intervals defined by the resolution of the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems. You can change the due time and period, or disable the timer, by using the method. + When you create a timer, you can specify an amount of time to wait before the first execution of the method (due time), and an amount of time to wait between subsequent executions (period). The class has the same resolution as the system clock. This means that if the period is less than the resolution of the system clock, the delegate will execute at intervals defined by the resolution of the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems. You can change the due time and period, or disable the timer, by using the method. > [!NOTE] > As long as you are using a , you must keep a reference to it. As with any managed object, a is subject to garbage collection when there are no references to it. The fact that a is still active does not prevent it from being collected. @@ -127,7 +127,7 @@ The timer delegate is specified when the timer is constructed and cannot be chan > [!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). - When a timer is no longer needed, use the method to free the resources held by the timer. Note that callbacks can occur after the method overload has been called, because the timer queues callbacks for execution by thread pool threads. You can use the method overload to wait until all callbacks have completed. + When a timer is no longer needed, use the method to free the resources held by the timer. Note that callbacks can occur after the method overload has been called, because the timer queues callbacks for execution by thread pool threads. You can use the method overload to wait until all callbacks have completed. The callback method executed by the timer should be reentrant, because it is called on threads. The callback can be executed simultaneously on two thread pool threads if the timer interval is less than the time required to execute the callback, or if all thread pool threads are in use and the callback is queued multiple times. @@ -144,7 +144,7 @@ The following example defines a `StatusChecker` class that includes a `CheckStat `maxCount`\ Determines the maximum number of times the callback method should be invoked. - The application thread creates the timer, which waits one second and then executes the `CheckStatus` callback method every 250 milliseconds. The application thread then blocks until the object is signaled. When the `CheckStatus` callback method executes `maxCount` times, it calls the `AutoResetEvent.Set` method to set the state of the object to signaled. The first time this happens, the application thread calls the method so that the callback method now executes every half second. It once again blocks until the object is signaled. When this happens, the timer is destroyed by calling its method, and the application terminates. + The application thread creates the timer, which waits one second and then executes the `CheckStatus` callback method every 250 milliseconds. The application thread then blocks until the object is signaled. When the `CheckStatus` callback method executes `maxCount` times, it calls the `AutoResetEvent.Set` method to set the state of the object to signaled. The first time this happens, the application thread calls the method so that the callback method now executes every half second. It once again blocks until the object is signaled. When this happens, the timer is destroyed by calling its method, and the application terminates. :::code language="csharp" source="~/snippets/csharp/System.Threading/Timer/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Timer/Overview/source.vb" id="Snippet1"::: @@ -218,7 +218,7 @@ The following example defines a `StatusChecker` class that includes a `CheckStat object itself as the state object. After creating the timer, use the method to set the interval and due time. + Call this constructor when you want to use the object itself as the state object. After creating the timer, use the method to set the interval and due time. This constructor specifies an infinite due time before the first callback and an infinite interval between callbacks, in order to prevent the first callback from occurring before the object is assigned to the state object. @@ -227,7 +227,7 @@ The following example defines a `StatusChecker` class that includes a `CheckStat ## Examples - The following code example creates a new timer, using the timer itself as the state object. The method is used to start the timer. When the timer callback occurs, the state object is used to turn the timer off. + The following code example creates a new timer, using the timer itself as the state object. The method is used to start the timer. When the timer callback occurs, the state object is used to turn the timer off. :::code language="csharp" source="~/snippets/csharp/System.Threading/Timer/.ctor/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/timerSelfCtor/VB/source.vb" id="Snippet1"::: @@ -305,9 +305,9 @@ The following example defines a `StatusChecker` class that includes a `CheckStat ## Remarks The delegate specified by the `callback` parameter is invoked once after `dueTime` elapses, and thereafter each time the `period` time interval elapses. - If `dueTime` is zero (0), `callback` is invoked immediately. If `dueTime` is , `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. + If `dueTime` is zero (0), `callback` is invoked immediately. If `dueTime` is , `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. - Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or and `dueTime` is not , `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. + Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or and `dueTime` is not , `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. > [!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). @@ -397,11 +397,11 @@ The following example defines a `StatusChecker` class that includes a `CheckStat ## Remarks The delegate specified by the `callback` parameter is invoked once after `dueTime` elapses, and thereafter each time the `period` time interval elapses. - If `dueTime` is zero (0), `callback` is invoked immediately. If `dueTime` is , `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. + If `dueTime` is zero (0), `callback` is invoked immediately. If `dueTime` is , `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. - Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. - - If `period` is zero (0) or and `dueTime` is not , `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. + Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. + + If `period` is zero (0) or and `dueTime` is not , `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. > [!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). @@ -484,9 +484,9 @@ The following example defines a `StatusChecker` class that includes a `CheckStat ## Remarks The delegate specified by the `callback` parameter is invoked once after `dueTime` elapses, and thereafter each time the `period` time interval elapses. - If `dueTime` is zero (0), `callback` is invoked immediately. If `dueTime` is negative one (-1) milliseconds, `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. + If `dueTime` is zero (0), `callback` is invoked immediately. If `dueTime` is negative one (-1) milliseconds, `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. - Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or negative one (-1) milliseconds and `dueTime` is positive, `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. + Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or negative one (-1) milliseconds and `dueTime` is positive, `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. > [!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). @@ -580,9 +580,9 @@ The following example defines a `StatusChecker` class that includes a `CheckStat ## Remarks The delegate specified by the `callback` parameter is invoked once after `dueTime` elapses, and thereafter each time the `period` time interval elapses. - If `dueTime` is zero (0), `callback` is invoked immediately. If `dueTime` is , `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. + If `dueTime` is zero (0), `callback` is invoked immediately. If `dueTime` is , `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. - Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or and `dueTime` is not , `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. + Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or and `dueTime` is not , `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. > [!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). @@ -706,11 +706,11 @@ The following example defines a `StatusChecker` class that includes a `CheckStat ## Remarks The callback method is invoked once after `dueTime` elapses, and thereafter each time the time interval specified by `period` elapses. - If `dueTime` is zero (0), the callback method is invoked immediately. If `dueTime` is , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. + If `dueTime` is zero (0), the callback method is invoked immediately. If `dueTime` is , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. - If `period` is zero (0) or , and `dueTime` is not , the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a positive value for `period`. + If `period` is zero (0) or , and `dueTime` is not , the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a positive value for `period`. - The method can be called from the delegate. + The method can be called from the delegate. @@ -788,11 +788,11 @@ The following example defines a `StatusChecker` class that includes a `CheckStat ## Remarks The callback method is invoked once after `dueTime` elapses, and thereafter each time the time interval specified by `period` elapses. - If `dueTime` is zero (0), the callback method is invoked immediately. If `dueTime` is , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. + If `dueTime` is zero (0), the callback method is invoked immediately. If `dueTime` is , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. - If `period` is zero (0) or , and `dueTime` is not , the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a positive value for `period`. + If `period` is zero (0) or , and `dueTime` is not , the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a positive value for `period`. - The method can be called from the delegate. + The method can be called from the delegate. ]]> @@ -868,11 +868,11 @@ The following example defines a `StatusChecker` class that includes a `CheckStat ## Remarks The callback method is invoked once after `dueTime` elapses, and thereafter each time the time interval specified by `period` elapses. - If `dueTime` is , the callback method is invoked immediately. If `dueTime` is , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. + If `dueTime` is , the callback method is invoked immediately. If `dueTime` is , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. - If `period` is or , and `dueTime` is positive, the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a value greater than zero for `period`. + If `period` is or , and `dueTime` is positive, the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a value greater than zero for `period`. - The method can be called from the delegate. + The method can be called from the delegate. ## Examples The following code example demonstrates how to start a `Timer` and, after a set number of invocations, change its period. @@ -953,11 +953,11 @@ The following example defines a `StatusChecker` class that includes a `CheckStat ## Remarks The callback method is invoked once after `dueTime` elapses, and thereafter each time the time interval specified by `period` elapses. - If `dueTime` is zero (0), the callback method is invoked immediately. If `dueTime` is , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. + If `dueTime` is zero (0), the callback method is invoked immediately. If `dueTime` is , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. - If `period` is zero (0) or , and `dueTime` is not , the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a positive value for `period`. + If `period` is zero (0) or , and `dueTime` is not , the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a positive value for `period`. - The method can be called from the delegate. + The method can be called from the delegate. ]]> @@ -1028,7 +1028,7 @@ The following example defines a `StatusChecker` class that includes a `CheckStat Calling `Dispose` allows the resources used by the to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). > [!NOTE] -> Callbacks can occur after the method overload has been called, because the timer queues callbacks for execution by thread pool threads. You can use the method overload to wait until all callbacks have completed. +> Callbacks can occur after the method overload has been called, because the timer queues callbacks for execution by thread pool threads. You can use the method overload to wait until all callbacks have completed. @@ -1102,10 +1102,10 @@ The following example defines a `StatusChecker` class that includes a `CheckStat ## Remarks Calling `Dispose` allows the resources used by the to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - When this method completes, it signals the specified by the `notifyObject` parameter.Use this overload of the method if you want to be able to block until you are certain that the timer has been disposed. The timer is not disposed until all currently queued callbacks have completed. + When this method completes, it signals the specified by the `notifyObject` parameter.Use this overload of the method if you want to be able to block until you are certain that the timer has been disposed. The timer is not disposed until all currently queued callbacks have completed. > [!NOTE] -> If the callback uses the method to set the `dueTime` parameter to zero, a race condition can occur when the method overload is called: If the timer queues a new callback before the method overload detects that there are no callbacks queued, continues to block; otherwise, the timer is disposed while the new callback is being queued, and an is thrown when the new callback calls the method. +> If the callback uses the method to set the `dueTime` parameter to zero, a race condition can occur when the method overload is called: If the timer queues a new callback before the method overload detects that there are no callbacks queued, continues to block; otherwise, the timer is disposed while the new callback is being queued, and an is thrown when the new callback calls the method. ]]> diff --git a/xml/System.Threading/TimerCallback.xml b/xml/System.Threading/TimerCallback.xml index ae2134bcd11..b14c82dd2f6 100644 --- a/xml/System.Threading/TimerCallback.xml +++ b/xml/System.Threading/TimerCallback.xml @@ -74,10 +74,10 @@ . This method does not execute in the thread that created the timer; it executes in a separate thread pool thread that is provided by the system. The `TimerCallback` delegate invokes the method once after the start time elapses, and continues to invoke it once per timer interval until the method is called, or until the method is called with the interval value . + Use a `TimerCallback` delegate to specify the method that is called by a . This method does not execute in the thread that created the timer; it executes in a separate thread pool thread that is provided by the system. The `TimerCallback` delegate invokes the method once after the start time elapses, and continues to invoke it once per timer interval until the method is called, or until the method is called with the interval value . > [!NOTE] -> Callbacks can occur after the method overload has been called, because the timer queues callbacks for execution by thread pool threads. You can use the method overload to wait until all callbacks have completed. +> Callbacks can occur after the method overload has been called, because the timer queues callbacks for execution by thread pool threads. You can use the method overload to wait until all callbacks have completed. The timer delegate is specified when the timer is constructed, and cannot be changed. The start time for a `Timer` is passed in the `dueTime` parameter of the `Timer` constructors, and the period is passed in the `period` parameter. For an example that demonstrates creating and using a `TimerCallback` delegate, see . @@ -85,7 +85,7 @@ ## Examples The following code example shows how to create the delegate used with the `Timer` class. - + :::code language="csharp" source="~/snippets/csharp/System.Threading/Timer/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Timer/Overview/source.vb" id="Snippet1"::: diff --git a/xml/System.Threading/Volatile.xml b/xml/System.Threading/Volatile.xml index 34945d394aa..4d4ba8d827e 100644 --- a/xml/System.Threading/Volatile.xml +++ b/xml/System.Threading/Volatile.xml @@ -82,16 +82,16 @@ > - Volatile reads and writes ensure that a value is read or written to memory and not cached (for example, in a processor register). Thus, you can use these operations to synchronize access to a field that can be updated by another thread or by hardware. > - The class also provides read and write operations for some 64-bit types such as and . Volatile reads and writes on such 64-bit memory are atomic even on 32-bit processors, unlike regular reads and writes. - Volatile memory operations are for special cases of synchronization, where normal locking is not an acceptable alternative. Under normal circumstances, the C# `lock` statement, the Visual Basic `SyncLock` statement, and the class provide the easiest and least error-prone way of synchronizing access to data, and the class provides a simple way to write lazy initialization code without directly using double-checked locking. + Volatile memory operations are for special cases of synchronization, where normal locking is not an acceptable alternative. Under normal circumstances, the C# `lock` statement, the Visual Basic `SyncLock` statement, and the class provide the easiest and least error-prone way of synchronizing access to data, and the class provides a simple way to write lazy initialization code without directly using double-checked locking. - The and methods enable functionality that is not supported in languages. For example: + The and methods enable functionality that is not supported in languages. For example: - Some languages, such as Visual Basic, do not recognize the concept of volatile memory operations. The class provides that functionality in such languages. > [!NOTE] - > Calling one of these methods affects only a single memory access. To provide effective synchronization for a field, all access to the field must use and . + > Calling one of these methods affects only a single memory access. To provide effective synchronization for a field, all access to the field must use and . -- In C#, using the `volatile` modifier on a field guarantees that every access to that field is a volatile memory operation, but the `volatile` modifier cannot be applied to array elements. The and methods can be used on array elements. +- In C#, using the `volatile` modifier on a field guarantees that every access to that field is a volatile memory operation, but the `volatile` modifier cannot be applied to array elements. The and methods can be used on array elements. ]]> diff --git a/xml/System.Threading/WaitCallback.xml b/xml/System.Threading/WaitCallback.xml index 38185e39607..aa3f1846a35 100644 --- a/xml/System.Threading/WaitCallback.xml +++ b/xml/System.Threading/WaitCallback.xml @@ -60,22 +60,22 @@ An object containing information to be used by the callback method. Represents a callback method to be executed by a thread pool thread. - represents a callback method that you want to execute on a thread. Create the delegate by passing your callback method to the constructor. Your method must have the signature shown here. - - Queue the method for execution by passing the delegate to . The callback method executes when a thread pool thread becomes available. - + represents a callback method that you want to execute on a thread. Create the delegate by passing your callback method to the constructor. Your method must have the signature shown here. + + Queue the method for execution by passing the delegate to . The callback method executes when a thread pool thread becomes available. + > [!NOTE] -> Visual Basic users can omit the constructor, and simply use the `AddressOf` operator when passing the callback method to . Visual Basic automatically calls the correct delegate constructor. - - If you want to pass information to the callback method, create an object that contains the necessary information and pass it to the method as the second argument. Each time the callback method executes, the `state` parameter contains this object. +> Visual Basic users can omit the constructor, and simply use the `AddressOf` operator when passing the callback method to . Visual Basic automatically calls the correct delegate constructor. + + If you want to pass information to the callback method, create an object that contains the necessary information and pass it to the method as the second argument. Each time the callback method executes, the `state` parameter contains this object. + + For examples that use the `WaitCallback` delegate, see the method. + + For more information about the thread pool, see [The managed thread pool](/dotnet/standard/threading/the-managed-thread-pool). - For examples that use the `WaitCallback` delegate, see the method. - - For more information about the thread pool, see [The managed thread pool](/dotnet/standard/threading/the-managed-thread-pool). - ]]> diff --git a/xml/System.Threading/WaitHandle.xml b/xml/System.Threading/WaitHandle.xml index e703a7172f9..faade36f469 100644 --- a/xml/System.Threading/WaitHandle.xml +++ b/xml/System.Threading/WaitHandle.xml @@ -84,31 +84,31 @@ - The class. See [Semaphore and SemaphoreSlim](/dotnet/standard/threading/semaphore-and-semaphoreslim). - Threads can block on an individual wait handle by calling the instance method , which is inherited by classes derived from . + Threads can block on an individual wait handle by calling the instance method , which is inherited by classes derived from . - The derived classes of differ in their thread affinity. Event wait handles (, , and ) and semaphores do not have thread affinity; any thread can signal an event wait handle or semaphore. Mutexes, on the other hand, do have thread affinity; the thread that owns a mutex must release it, and an exception is thrown if a thread calls the method on a mutex that it does not own. + The derived classes of differ in their thread affinity. Event wait handles (, , and ) and semaphores do not have thread affinity; any thread can signal an event wait handle or semaphore. Mutexes, on the other hand, do have thread affinity; the thread that owns a mutex must release it, and an exception is thrown if a thread calls the method on a mutex that it does not own. Because the class derives from , these classes can be used to synchronize the activities of threads across application domain boundaries. In addition to its derived classes, the class has a number of static methods that block a thread until one or more synchronization objects receive a signal. These include: -- , which allows a thread to signal one wait handle and immediately wait on another. +- , which allows a thread to signal one wait handle and immediately wait on another. -- , which allows a thread to wait until all the wait handles in an array receive a signal. +- , which allows a thread to wait until all the wait handles in an array receive a signal. -- , which allows a thread to wait until any one of a specified set of wait handles has been signaled. +- , which allows a thread to wait until any one of a specified set of wait handles has been signaled. 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#) 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 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#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - implements the pattern. See [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). 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. + implements the pattern. See [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). 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. ## Examples - The following code example shows how two threads can do background tasks while the Main thread waits for the tasks to complete using the static and methods of the class. + The following code example shows how two threads can do background tasks while the Main thread waits for the tasks to complete using the static and methods of the class. :::code language="csharp" source="~/snippets/csharp/System.Threading/WaitHandle/Overview/WaitHandle.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/WaitHandle/Overview/WaitHandle.vb" id="Snippet1"::: @@ -212,12 +212,12 @@ method for the class and its derived classes. It provides a standard implementation that calls the `Dispose(Boolean)` overload with a `true` argument and then calls the method. Call this method to release all resources held by an instance of `WaitHandle` or a derived class. + This method is the public implementation of the method for the class and its derived classes. It provides a standard implementation that calls the `Dispose(Boolean)` overload with a `true` argument and then calls the method. Call this method to release all resources held by an instance of `WaitHandle` or a derived class. Once this method is called, references to the current instance cause undefined behavior. > [!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. ]]> @@ -288,10 +288,10 @@ method. + 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. ]]> @@ -355,7 +355,7 @@ and the methods with the `explicitDisposing` parameter set to `true`. When the `explicitDisposing` parameter is `true`, this method releases all resources held by any managed objects that this object references. + This method is called by the and the methods with the `explicitDisposing` parameter set to `true`. When the `explicitDisposing` parameter is `true`, this method releases all resources held by any managed objects that this object references. ]]> @@ -400,7 +400,7 @@ > This member has been removed from the .NET Framework version 2.0 and subsequent versions. This topic applies only to the versions listed in "Version Information" later in this topic. -Application code does not call this method; it is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled. For more information, see and . This method overrides . +Application code does not call this method; it is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled. For more information, see and . This method overrides . ]]> @@ -592,7 +592,7 @@ Application code does not call this method; it is automatically invoked during g ## Remarks When you assign a new value to the property, the previous handle will be closed when the previous object is collected. Do not manually close the handle, because this results in an when the attempts to close the handle. - implements the pattern. See [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). When you derive from , use the property to store your native handle operating system handle. You do not need to override the protected method unless you use additional unmanaged resources. + implements the pattern. See [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). When you derive from , use the property to store your native handle operating system handle. You do not need to override the protected method unless you use additional unmanaged resources. ]]> @@ -660,7 +660,7 @@ Application code does not call this method; it is automatically invoked during g This operation is not guaranteed to be atomic. After the current thread signals `toSignal` but before it waits on `toWaitOn`, a thread that is running on another processor might signal `toWaitOn` or wait on it. ## Examples - The following code example uses the method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task. + The following code example uses the method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task. The example starts five threads, allows them to block on an created with the flag, and then releases one thread each time the user presses the ENTER key. The example then queues another five threads and releases them all using an created with the flag. @@ -955,14 +955,14 @@ Calling `Dispose` allows the resources used by the is new in the .NET Framework version 2.0. In previous versions, the method returns `true` when a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. + is new in the .NET Framework version 2.0. In previous versions, the method returns `true` when a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. - 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 . + 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`. + Calling this method overload is equivalent to calling the method overload and specifying -1 (or ) for `millisecondsTimeout` and `true` for `exitContext`. @@ -1056,12 +1056,12 @@ Note: In the .NET for ## Remarks If `millisecondsTimeout` is zero, the method does not block. It tests the state of the wait handles and returns immediately. - 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 . + 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`. + Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. ]]> @@ -1149,14 +1149,14 @@ Note: In the .NET for ## Remarks If `timeout` is zero, the method does not block. It tests the state of the wait handles and returns immediately. - 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. + 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 . - Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. + Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. ]]> @@ -1251,10 +1251,10 @@ If `millisecondsTimeout` is zero, the method does not block. It tests the state If a mutex is abandoned, an is thrown. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. -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 . +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. [!INCLUDE [Exit the context](~/includes/remarks/System.Threading/WaitHandle/exit-context.md)] @@ -1347,10 +1347,10 @@ If `timeout` is zero, the method does not block. It tests the state of the wait If a mutex is abandoned, an is thrown. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. -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. +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 . @@ -1461,9 +1461,9 @@ The maximum value for `timeout` is is new in the .NET Framework version 2.0. In previous versions, the method returns `true` if the wait completes because a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. + is new in the .NET Framework version 2.0. In previous versions, the method returns `true` if the wait completes because a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. - The method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. + The method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. > [!NOTE] > In versions of the .NET Framework earlier than version 2.0, if a thread exits or aborts without explicitly releasing a , and that `Mutex` is at index 0 (zero) in a `WaitAny` array on another thread, the index returned by `WaitAny` is 128 instead of 0. @@ -1472,12 +1472,12 @@ The maximum value for `timeout` is state. - Calling this method overload is equivalent to calling the method overload and specifying -1 (or ) for `millisecondsTimeout` and `true` for `exitContext`. + Calling this method overload is equivalent to calling the method overload and specifying -1 (or ) for `millisecondsTimeout` and `true` for `exitContext`. ## Examples - The following code example demonstrates calling the method. + The following code example demonstrates calling the method. :::code language="csharp" source="~/snippets/csharp/System.Threading/WaitHandle/Overview/WaitHandle.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/WaitHandle/Overview/WaitHandle.vb" id="Snippet1"::: @@ -1558,13 +1558,13 @@ The maximum value for `timeout` is method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. + The method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. This method returns when the wait terminates, either when any of the handles are signaled or when a timeout occurs. If more than one object becomes signaled during the call, the return value is the array index of the signaled object with the smallest index value of all the signaled objects. The maximum number of the wait handles is 64, and 63 if the current thread is in state. - Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. + Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. ]]> @@ -1642,7 +1642,7 @@ The maximum value for `timeout` is method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. + The method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. This method returns when the wait terminates, either when any of the handles are signaled or when a time-out occurs. If more than one object becomes signaled during the call, the return value is the array index of the signaled object with the smallest index value of all the signaled objects. @@ -1650,7 +1650,7 @@ The maximum value for `timeout` is . - Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. + Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. ]]> @@ -1737,7 +1737,7 @@ The maximum value for `timeout` is method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. +The method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. This method returns when the wait terminates, either when any of the handles are signaled or when a timeout occurs. If more than one object becomes signaled during the call, the return value is the array index of the signaled object with the smallest index value of all the signaled objects. @@ -1830,7 +1830,7 @@ The maximum number of the wait handles is 64, and 63 if the current thread is in If `timeout` is zero, the method does not block. It tests the state of the wait handles and returns immediately. -The method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. +The method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. This method returns when the wait terminates, either when any of the handles are signaled or when a time-out occurs. If more than one object becomes signaled during the call, the return value is the array index of the signaled object with the smallest index value of all the signaled objects. @@ -1930,11 +1930,11 @@ The maximum value for `timeout` is is new in the .NET Framework version 2.0. In previous versions, the method returns `true` when a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. + is new in the .NET Framework version 2.0. In previous versions, the method returns `true` when a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. The caller of this method blocks indefinitely until the current instance receives a signal. Use this method to block until a receives a signal from another thread, such as is generated when an asynchronous operation completes. For more information, see the interface. - Calling this method overload is equivalent to calling the method overload and specifying -1 or for the first parameter and `false` for the second parameter. + Calling this method overload is equivalent to calling the method overload and specifying -1 or for the first parameter and `false` for the second parameter. Override this method to customize the behavior of derived classes. @@ -2010,7 +2010,7 @@ The maximum value for `timeout` is overload and specifying `false` for `exitContext`. + Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. @@ -2088,7 +2088,7 @@ The maximum value for `timeout` is . - Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. + Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. ]]> @@ -2166,7 +2166,7 @@ Override this method to customize the behavior of derived classes. [!INCLUDE [Exit the context](~/includes/remarks/System.Threading/WaitHandle/exit-context.md)] ## Examples - The following example shows how the method overload behaves when it is called within a synchronization domain. First, a thread waits with `exitContext` set to `false` and blocks until the wait timeout expires. A second thread executes after the first thread terminates and waits with `exitContext` set to `true`. The call to signal the wait handle for this second thread is not blocked, and the thread completes before the wait timeout. + The following example shows how the method overload behaves when it is called within a synchronization domain. First, a thread waits with `exitContext` set to `false` and blocks until the wait timeout expires. A second thread executes after the first thread terminates and waits with `exitContext` set to `true`. The call to signal the wait handle for this second thread is not blocked, and the thread completes before the wait timeout. :::code language="csharp" source="~/snippets/csharp/System.Threading/WaitHandle/WaitOne/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/WaitHandle/WaitOne/source.vb" id="Snippet1"::: diff --git a/xml/System.Threading/WaitHandleCannotBeOpenedException.xml b/xml/System.Threading/WaitHandleCannotBeOpenedException.xml index b282e55faa9..2726e12a5f0 100644 --- a/xml/System.Threading/WaitHandleCannotBeOpenedException.xml +++ b/xml/System.Threading/WaitHandleCannotBeOpenedException.xml @@ -72,7 +72,7 @@ , , and classes can represent named system synchronization objects. When you use the method, the method, or the method to open a named system object that does not exist, a exception is thrown. + Instances of the , , and classes can represent named system synchronization objects. When you use the method, the method, or the method to open a named system object that does not exist, a exception is thrown. ]]> @@ -137,8 +137,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The system-supplied error message string.| +||`null`.| +||The system-supplied error message string.| ]]> @@ -195,8 +195,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||`message`.| +||`null`.| +||`message`.| ]]> diff --git a/xml/System.Threading/WaitHandleExtensions.xml b/xml/System.Threading/WaitHandleExtensions.xml index dde7a2aea05..639c0390053 100644 --- a/xml/System.Threading/WaitHandleExtensions.xml +++ b/xml/System.Threading/WaitHandleExtensions.xml @@ -128,7 +128,7 @@ is an extension method that is equivalent to retrieving the value of the property. + is an extension method that is equivalent to retrieving the value of the property. ]]> @@ -200,7 +200,7 @@ is an extension method that is equivalent to assigning a value to the property. + is an extension method that is equivalent to assigning a value to the property. ]]> diff --git a/xml/System.Threading/WaitOrTimerCallback.xml b/xml/System.Threading/WaitOrTimerCallback.xml index 2a388bcb1a9..630848354d1 100644 --- a/xml/System.Threading/WaitOrTimerCallback.xml +++ b/xml/System.Threading/WaitOrTimerCallback.xml @@ -68,13 +68,13 @@ ## Remarks represents a callback method that you want to execute when a registered wait handle times out or is signaled. Create the delegate by passing your callback method to the constructor. Your method must have the signature shown here. - Create the registered wait handle by passing the delegate and a to . Your callback method executes each time the times out or is signaled. + Create the registered wait handle by passing the delegate and a to . Your callback method executes each time the times out or is signaled. > [!NOTE] -> Visual Basic users can omit the constructor, and simply use the `AddressOf` operator when passing the callback method to . Visual Basic automatically calls the correct delegate constructor. +> Visual Basic users can omit the constructor, and simply use the `AddressOf` operator when passing the callback method to . Visual Basic automatically calls the correct delegate constructor. - If you want to pass information to your callback method, create an object that contains the necessary information and pass it to when you create the registered wait handle. Each time your callback method executes, the `state` parameter contains this object. + If you want to pass information to your callback method, create an object that contains the necessary information and pass it to when you create the registered wait handle. Each time your callback method executes, the `state` parameter contains this object. For more information about using callback methods to synchronize thread pool threads, see [The managed thread pool](/dotnet/standard/threading/the-managed-thread-pool). @@ -83,14 +83,14 @@ ## Examples The following example shows how to use the delegate to represent a callback method that is executed when a wait handle is signaled. - The example also shows how to use the method to execute a specified callback method when a specified wait handle is signaled. In this example, the callback method is `WaitProc` and the wait handle is an . + The example also shows how to use the method to execute a specified callback method when a specified wait handle is signaled. In this example, the callback method is `WaitProc` and the wait handle is an . - The example defines a `TaskInfo` class to hold the information that is passed to the callback when it executes. The example creates a `TaskInfo` object and assigns it some string data. The that is returned by the method is assigned to the `Handle` field of the `TaskInfo` object, so that the callback method has access to the . + The example defines a `TaskInfo` class to hold the information that is passed to the callback when it executes. The example creates a `TaskInfo` object and assigns it some string data. The that is returned by the method is assigned to the `Handle` field of the `TaskInfo` object, so that the callback method has access to the . - In addition to the `TaskInfo` object, the call to the method specifies the the task waits on, a delegate that represents the `WaitProc` callback method, a one-second timeout interval, and multiple callbacks. + In addition to the `TaskInfo` object, the call to the method specifies the the task waits on, a delegate that represents the `WaitProc` callback method, a one-second timeout interval, and multiple callbacks. + + When the main thread signals the by calling its method, the delegate is invoked. The `WaitProc` method tests to determine whether a timeout occurred. If the callback was invoked because the wait handle was signaled, the `WaitProc` method unregisters the , stopping further callbacks. In the case of a timeout, the task continues waiting. The `WaitProc` method ends by printing a message to the console. - When the main thread signals the by calling its method, the delegate is invoked. The `WaitProc` method tests to determine whether a timeout occurred. If the callback was invoked because the wait handle was signaled, the `WaitProc` method unregisters the , stopping further callbacks. In the case of a timeout, the task continues waiting. The `WaitProc` method ends by printing a message to the console. - :::code language="csharp" source="~/snippets/csharp/System.Threading/RegisteredWaitHandle/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/RegisteredWaitHandle/Overview/source.vb" id="Snippet1"::: diff --git a/xml/System.Timers/ElapsedEventArgs.xml b/xml/System.Timers/ElapsedEventArgs.xml index 9a384042467..90f29641712 100644 --- a/xml/System.Timers/ElapsedEventArgs.xml +++ b/xml/System.Timers/ElapsedEventArgs.xml @@ -138,7 +138,7 @@ event is raised on a thread, so the event-handling method might run on one thread at the same time that a call to the method runs on another thread. This might result in the event being raised after the method is called. This race condition cannot be prevented simply by comparing the property with the time when the method is called, because the event-handling method might already be executing when the method is called, or might begin executing between the moment when the method is called and the moment when the stop time is saved. If it is critical to prevent the thread that calls the method from proceeding while the event-handling method is still executing, use a more robust synchronization mechanism such as the class or the method. Code that uses the method can be found in the example for the method. + The event is raised on a thread, so the event-handling method might run on one thread at the same time that a call to the method runs on another thread. This might result in the event being raised after the method is called. This race condition cannot be prevented simply by comparing the property with the time when the method is called, because the event-handling method might already be executing when the method is called, or might begin executing between the moment when the method is called and the moment when the stop time is saved. If it is critical to prevent the thread that calls the method from proceeding while the event-handling method is still executing, use a more robust synchronization mechanism such as the class or the method. Code that uses the method can be found in the example for the method. diff --git a/xml/System.Timers/Timer.xml b/xml/System.Timers/Timer.xml index 73ab6865daf..d5cf2aae707 100644 --- a/xml/System.Timers/Timer.xml +++ b/xml/System.Timers/Timer.xml @@ -73,7 +73,7 @@ > 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 have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. The server-based class is designed for use with worker threads in a multithreaded environment. Server timers can move among threads to handle the raised event, resulting in more accuracy than Windows timers in raising the event on time. @@ -85,7 +85,7 @@ > [!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). - When is set to `false`, a object raises the event only once, after the first has elapsed. To keep raising the event regularly at the interval defined by the , set to `true`, which is the default value. + When is set to `false`, a object raises the event only once, after the first has elapsed. To keep raising the event regularly at the interval defined by the , set to `true`, which is the default value. The component catches and suppresses all exceptions thrown by event handlers for the event. This behavior is subject to change in future releases of the .NET Framework. Note, however, that this is not true of event handlers that execute asynchronously and include the `await` operator (in C#) or the `Await` operator (in Visual Basic). Exceptions thrown in these event handlers are propagated back to the calling thread, as the following example illustrates. For more information on exceptions thrown in asynchronous methods, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). @@ -93,16 +93,16 @@ :::code language="fsharp" source="~/snippets/fsharp/System.Timers/ElapsedEventArgs/Overview/AsyncHandlerEx1.fs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Timers/ElapsedEventArgs/Overview/AsyncHandlerEx1.vb" id="Snippet3"::: - 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. + 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. + Even if is not `null`, events can occur after the or method has been called or after the property has been set to `false`, because the signal to raise the event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the event to ignore subsequent events. If you use the class with a user interface element, such as a form or control, without placing the timer on that user interface element, assign the form or control that contains the to the property, so that the event is marshaled to the user interface thread. - For a list of default property values for an instance of , see the constructor. + 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: @@ -182,10 +182,10 @@ |Property|Initial value| |--------------|-------------------| -||`true`| -||`false`| -||100 milliseconds| -||A null reference (`Nothing` in Visual Basic).| +||`true`| +||`false`| +||100 milliseconds| +||A null reference (`Nothing` in Visual Basic).| @@ -354,9 +354,9 @@ 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. - 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`. + 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`. @@ -421,7 +421,7 @@ method ends 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 start the initialization of a component that is used on a form or by another component. The method ends the initialization. Using the and methods prevents the control from being used before it is fully initialized. ]]> @@ -473,7 +473,7 @@ method in turn calls the `Dispose` method. + The method in turn calls the `Dispose` method. ]]> @@ -581,16 +581,16 @@ event is raised if the property is `true` and the time interval (in milliseconds) defined by the property elapses. If the property is `true`, the event is raised repeatedly at an interval defined by the property; otherwise, the event is raised only once, the first time the value elapses. + The event is raised if the property is `true` and the time interval (in milliseconds) defined by the property elapses. If the property is `true`, the event is raised repeatedly at an interval defined by the property; otherwise, the event is raised only once, the first time the value elapses. - If is set after the has started, the count is reset. For example, if you set the interval to 5 seconds and then set 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`. + If is set after the has started, the count is reset. For example, if you set the interval to 5 seconds and then set 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`. - 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. + 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. + 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. The component catches and suppresses all exceptions thrown by event handlers for the event. This behavior is subject to change in future releases of .NET Framework. @@ -673,14 +673,14 @@ to `true` is the same as calling , while setting to `false` is the same as calling . + 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 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`. + 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 . @@ -749,7 +749,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 is 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 is fully initialized. ]]> @@ -838,12 +838,12 @@ If your app requires greater resolution than that offered by the class or the system clock, use the high-resolution multimedia timers; see [How to: Use the High-Resolution Timer](https://msdn.microsoft.com/library/aa964692.aspx). - 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`. + 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`. - 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`. + 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`. @@ -965,14 +965,14 @@ is called and is set to `false`, the raises the event only once, the first time the interval elapses. If is called and is `true`, the raises the event the first time the interval elapses and continues to raise the event on the specified interval. + If is called and is set to `false`, the raises the event only once, the first time the interval elapses. If is called and is `true`, the raises the event the first time the interval elapses and continues to raise the event on the specified interval. - You can also start timing by setting to `true`. + 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. + A call to the method when the timer is enabled has no effect. ]]> @@ -1033,25 +1033,25 @@ to `false`. + You can also stop timing by setting to `false`. > [!NOTE] -> The signal to raise the event is always queued for execution on a thread, so the event-handling method might run on one thread at the same time that a call to the method runs on another thread. This might result in the event being raised after the method is called. The second code example in the Examples section shows one way to work around this race condition. +> The signal to raise the event is always queued for execution on a thread, so the event-handling method might run on one thread at the same time that a call to the method runs on another thread. This might result in the event being raised after the method is called. The second code example in the Examples section shows one way to work around this race condition. ## Examples - The following example instantiates a `System.Timers.Timer` object that fires its event every two seconds (2,000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. When the user presses the Enter key, the application calls the method before terminating the application. + The following example instantiates a `System.Timers.Timer` object that fires its event every two seconds (2,000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. When the user presses the Enter key, the application calls the method before terminating the application. :::code language="csharp" source="~/snippets/csharp/System.Timers/ElapsedEventArgs/Overview/timer2a.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.Timers/ElapsedEventArgs/Overview/timer2a.fs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Timers/ElapsedEventArgs/Overview/timer2a.vb" id="Snippet2"::: - The following code example shows one way to prevent the thread that calls the method from continuing until a currently executing event ends, and also to prevent two events from executing the event handler at the same time (often referred to as reentrancy). + The following code example shows one way to prevent the thread that calls the method from continuing until a currently executing event ends, and also to prevent two events from executing the event handler at the same time (often referred to as reentrancy). - The example executes 100 test runs. Each time the test is run, the timer is started with an interval of 150 milliseconds. The event handler uses the method to simulate a task that randomly varies in length from 50 to 200 milliseconds. The test method also starts a control thread that waits for a second and then stops the timer. If an event is being handled when the control thread stops the timer, the control thread must wait until the event is finished before proceeding. + The example executes 100 test runs. Each time the test is run, the timer is started with an interval of 150 milliseconds. The event handler uses the method to simulate a task that randomly varies in length from 50 to 200 milliseconds. The test method also starts a control thread that waits for a second and then stops the timer. If an event is being handled when the control thread stops the timer, the control thread must wait until the event is finished before proceeding. - The method overload is used to avoid reentrancy and to prevent the control thread from continuing until an executing event ends. The event handler uses the method to set a control variable to 1, but only if the value is currently zero. This is an atomic operation. If the return value is zero, the control variable has been set to 1 and the event handler proceeds. If the return value is non-zero, the event is simply discarded to avoid reentrancy. (If it were necessary to execute every event, the class would be a better way to synchronize the events.) When the event handler ends, it sets the control variable back to zero. The example records the total number of events that executed, that were discarded because of reentrancy, and that occurred after the method was called. + The method overload is used to avoid reentrancy and to prevent the control thread from continuing until an executing event ends. The event handler uses the method to set a control variable to 1, but only if the value is currently zero. This is an atomic operation. If the return value is zero, the control variable has been set to 1 and the event handler proceeds. If the return value is non-zero, the event is simply discarded to avoid reentrancy. (If it were necessary to execute every event, the class would be a better way to synchronize the events.) When the event handler ends, it sets the control variable back to zero. The example records the total number of events that executed, that were discarded because of reentrancy, and that occurred after the method was called. - The control thread uses the method to set the control variable to -1 (minus one), but only if the value is currently zero. If the atomic operation returns non-zero, an event is currently executing. The control thread waits and tries again. The example records the number of times the control thread had to wait for an event to finish. + The control thread uses the method to set the control variable to -1 (minus one), but only if the value is currently zero. If the atomic operation returns non-zero, an event is currently executing. The control thread waits and tries again. The example records the number of times the control thread had to wait for an event to finish. :::code language="csharp" source="~/snippets/csharp/System.Timers/Timer/Stop/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Timers/Timer/Stop/source.fs" id="Snippet1"::: @@ -1126,14 +1126,14 @@ is `null`, the method that handles the event is called on a thread from the system-thread pool. For more information on system-thread pools, see . + When is `null`, the method that handles the event is called on a thread from the system-thread pool. For more information on system-thread pools, see . - 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. + 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`. + 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`. ## Examples The following example is a Windows Forms app that serves as a very simple text file editor. When the text in the text box has not been saved, the app asks the user at one-minute intervals whether they want to save the contents of the text box. To do this, the property is set to one minute (60,000 milliseconds), and the property is set to the object. diff --git a/xml/System.Transactions.Configuration/DefaultSettingsSection.xml b/xml/System.Transactions.Configuration/DefaultSettingsSection.xml index 257e14ccc85..b00b8e96c29 100644 --- a/xml/System.Transactions.Configuration/DefaultSettingsSection.xml +++ b/xml/System.Transactions.Configuration/DefaultSettingsSection.xml @@ -17,25 +17,25 @@ Represents an XML section in a configuration file that contains default values of a transaction. This class cannot be inherited. - ` - - `` - - `` - - `` - - `` - - `` - - This example specifies the default values of a transaction. Specifically, it sets the computer name of the Distributed Transaction Coordinator (MSDTC) that is responsible for coordinating all distributed transactions started locally, and the default time after which a transaction times out. In addition, it specifies a setting that can only be modified at the machine level, which is the maximum amount of time allowed before a transaction times out. - + ` + + `` + + `` + + `` + + `` + + `` + + This example specifies the default values of a transaction. Specifically, it sets the computer name of the Distributed Transaction Coordinator (MSDTC) that is responsible for coordinating all distributed transactions started locally, and the default time after which a transaction times out. In addition, it specifies a setting that can only be modified at the machine level, which is the maximum amount of time allowed before a transaction times out. + ]]> @@ -84,17 +84,17 @@ Gets the name of the transaction manager. The name of the transaction manager. The default value is an empty string. - . If this property is `null` or contains an empty string, the local transaction manager is used as the remote transaction manager. If you set this property to a value other than the default empty string, you must install Windows Server 2003 Service Pack 1. Otherwise, any transactional operation fails with . A transaction that is escalated to be managed by the MSDTC will not use the local MSDTC, but instead use the one on the machine specified by this property. If that transaction manager is unavailable for any reason, an exception is thrown. - - This property is not case-sensitive, and should only contain the short name of the machine. It does not accept fully qualified domain names, localhost or IP addresses. If this property contains an invalid remote machine name, an "unable to read configuration information" exception is thrown. - - You should have the proper security permission to use a remote MSDTC. For more information on how to configure DTC security settings, please see the [Configuring MSDTC security properties](https://learn.microsoft.com/previous-versions/windows/desktop/ms679479(v=vs.85)) article. - + . If this property is `null` or contains an empty string, the local transaction manager is used as the remote transaction manager. If you set this property to a value other than the default empty string, you must install Windows Server 2003 Service Pack 1. Otherwise, any transactional operation fails with . A transaction that is escalated to be managed by the MSDTC will not use the local MSDTC, but instead use the one on the machine specified by this property. If that transaction manager is unavailable for any reason, an exception is thrown. + + This property is not case-sensitive, and should only contain the short name of the machine. It does not accept fully qualified domain names, localhost or IP addresses. If this property contains an invalid remote machine name, an "unable to read configuration information" exception is thrown. + + You should have the proper security permission to use a remote MSDTC. For more information on how to configure DTC security settings, please see the [Configuring MSDTC security properties](https://learn.microsoft.com/previous-versions/windows/desktop/ms679479(v=vs.85)) article. + ]]> An attempt to set this property to fully qualified domain names or IP addresses. @@ -153,13 +153,13 @@ Gets or sets a default time after which a transaction times out. A object. The default property is 00:01:00. - value at runtime. - - A value of 00:00:00 (or zero) is interpreted as infinity. - + value at runtime. + + A value of 00:00:00 (or zero) is interpreted as infinity. + ]]> An attempt to set this property to negative values. diff --git a/xml/System.Transactions/CommittableTransaction.xml b/xml/System.Transactions/CommittableTransaction.xml index ecc9760dd39..b5f5eee7419 100644 --- a/xml/System.Transactions/CommittableTransaction.xml +++ b/xml/System.Transactions/CommittableTransaction.xml @@ -63,7 +63,7 @@ class implicitly. Unlike the class, the application writer needs to specifically call the and methods in order to commit or abort the transaction. However, only the creator of a transaction can commit the transaction. Therefore, copies of a committable transaction obtained through the method are not committable. + The `CommittableTransaction` class provides an explicit way for applications to use a transaction, as opposed to using the class implicitly. Unlike the class, the application writer needs to specifically call the and methods in order to commit or abort the transaction. However, only the creator of a transaction can commit the transaction. Therefore, copies of a committable transaction obtained through the method are not committable. > [!NOTE] > We recommend that you create implicit transactions using the class, so that the ambient transaction context is automatically managed for you. You should also use the and classes for applications that require the use of the same transaction across multiple function calls or multiple thread calls. For more information on this model, see the [Implementing An Implicit Transaction Using Transaction Scope](/dotnet/framework/data/transactions/implementing-an-implicit-transaction-using-transaction-scope) topic. @@ -286,7 +286,7 @@ . + This method returns immediately, before the transaction has been completed. The transaction then commits on a different thread, and the `asyncCallback` delegate is invoked when it has completed. After this method is called, you do not receive the outcome of the transaction until you call . > [!NOTE] > The commit process may complete synchronously inside this method call. @@ -340,9 +340,9 @@ ## Remarks When this method is called, all objects that have registered to participate in the transaction are polled and can independently indicate their vote to either commit or roll back the transaction. If any participant votes to roll back the transaction, it is rolled back and this method throws a exception. This is a normal occurrence for a transaction and your code should catch and process such exceptions. - and block until the first phase of transaction processing is complete. The first phase ends after all resource managers and enlistments in the transaction have voted on the transaction outcome and the has durably decided to commit or abort the transaction. The second phase of processing is always asynchronous. Therefore, there is no guarantee that data just committed from within a given transaction will be immediately available afterwards when not using another transaction to view this data. + and block until the first phase of transaction processing is complete. The first phase ends after all resource managers and enlistments in the transaction have voted on the transaction outcome and the has durably decided to commit or abort the transaction. The second phase of processing is always asynchronous. Therefore, there is no guarantee that data just committed from within a given transaction will be immediately available afterwards when not using another transaction to view this data. - Because this method blocks until the first phase of transaction processing is complete, you should be extremely careful when using this method in a Windows Form (WinForm) application, or a deadlock can occur. If you call this method inside one WinForm Control event (for example, clicking a button), and use the synchronous method to direct the control to perform some UI tasks (for example, changing colors) in the middle of processing the transaction, a deadlock will happen. This is because the method is synchronous and blocks the worker thread until the UI thread finishes its job. However, in our scenario, the UI thread is also waiting for the worker thread to commit the transaction. The result is that none is able to proceed and the scope waits indefinitely for the Commit to finish. You should use rather than wherever possible, because it is asynchronous and thus less prone to deadlock. + Because this method blocks until the first phase of transaction processing is complete, you should be extremely careful when using this method in a Windows Form (WinForm) application, or a deadlock can occur. If you call this method inside one WinForm Control event (for example, clicking a button), and use the synchronous method to direct the control to perform some UI tasks (for example, changing colors) in the middle of processing the transaction, a deadlock will happen. This is because the method is synchronous and blocks the worker thread until the UI thread finishes its job. However, in our scenario, the UI thread is also waiting for the worker thread to commit the transaction. The result is that none is able to proceed and the scope waits indefinitely for the Commit to finish. You should use rather than wherever possible, because it is asynchronous and thus less prone to deadlock. ]]> @@ -397,12 +397,12 @@ method, when you have finished any cleanup work associated with the asynchronous commitment. You can also call this method early without waiting for the delegate. If, by the time you call this method, the transaction has not completed, this method waits for its completion. + You should call this method in the callback delegate specified as a parameter to the method, when you have finished any cleanup work associated with the asynchronous commitment. You can also call this method early without waiting for the delegate. If, by the time you call this method, the transaction has not completed, this method waits for its completion. > [!CAUTION] > The property returned by `asyncResult` is always `false`, even if the operation completed synchronously. - and block until the first phase of transaction processing is complete. The first phase ends after all resource managers and enlistments in the transaction have voted on the transaction outcome and the has durably decided to commit or abort the transaction. The second phase of processing is always asynchronous. Therefore, there is no guarantee that data just committed from within a given transaction will be immediately available afterwards when not using another transaction to view this data. + and block until the first phase of transaction processing is complete. The first phase ends after all resource managers and enlistments in the transaction have voted on the transaction outcome and the has durably decided to commit or abort the transaction. The second phase of processing is always asynchronous. Therefore, there is no guarantee that data just committed from within a given transaction will be immediately available afterwards when not using another transaction to view this data. ]]> diff --git a/xml/System.Transactions/DependentCloneOption.xml b/xml/System.Transactions/DependentCloneOption.xml index 89e9bf72ac5..3ef22734b2e 100644 --- a/xml/System.Transactions/DependentCloneOption.xml +++ b/xml/System.Transactions/DependentCloneOption.xml @@ -44,19 +44,19 @@ Controls what kind of dependent transaction to create. - method, with the parameter controlling what kind of dependent transaction to create. For more information on how this enumeration is used, see [Managing Concurrency with DependentTransaction](https://msdn.microsoft.com/library/bdad8468-2a90-4b81-8375-278067120cab). - - - -## Examples - The following example shows you how to create a dependent transaction. - + method, with the parameter controlling what kind of dependent transaction to create. For more information on how this enumeration is used, see [Managing Concurrency with DependentTransaction](https://msdn.microsoft.com/library/bdad8468-2a90-4b81-8375-278067120cab). + + + +## Examples + The following example shows you how to create a dependent transaction. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/tx_dependenttx/cs/dependenttx.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/tx_dependenttx/vb/dependenttx.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/tx_dependenttx/vb/dependenttx.vb" id="Snippet1"::: + ]]> Managing Concurrency with DependentTransaction diff --git a/xml/System.Transactions/DependentTransaction.xml b/xml/System.Transactions/DependentTransaction.xml index e1b502645eb..0db5565130a 100644 --- a/xml/System.Transactions/DependentTransaction.xml +++ b/xml/System.Transactions/DependentTransaction.xml @@ -53,23 +53,23 @@ Describes a clone of a transaction providing guarantee that the transaction cannot be committed until the application comes to rest regarding work on the transaction. This class cannot be inherited. - is a clone of a object created using the method. Its sole purpose is to allow the application to come to rest and guarantee that the transaction cannot commit while work is still being performed on the transaction (for example, on a worker thread). - - When the work done within the cloned transaction is finally complete and ready to be committed, it can inform the creator of the transaction using the method. Thus you can preserve the consistency and correctness of data. - - The enumeration is used to determine the behavior on commit. This behavior control allows an application to come to rest, as well as provides concurrency support. For more information on how this enumeration is used, see [Managing Concurrency with DependentTransaction](https://msdn.microsoft.com/library/bdad8468-2a90-4b81-8375-278067120cab). - - - -## Examples - The following example shows you how to create a dependent transaction. - + is a clone of a object created using the method. Its sole purpose is to allow the application to come to rest and guarantee that the transaction cannot commit while work is still being performed on the transaction (for example, on a worker thread). + + When the work done within the cloned transaction is finally complete and ready to be committed, it can inform the creator of the transaction using the method. Thus you can preserve the consistency and correctness of data. + + The enumeration is used to determine the behavior on commit. This behavior control allows an application to come to rest, as well as provides concurrency support. For more information on how this enumeration is used, see [Managing Concurrency with DependentTransaction](https://msdn.microsoft.com/library/bdad8468-2a90-4b81-8375-278067120cab). + + + +## Examples + The following example shows you how to create a dependent transaction. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/tx_dependenttx/cs/dependenttx.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/tx_dependenttx/vb/dependenttx.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/tx_dependenttx/vb/dependenttx.vb" id="Snippet1"::: + ]]> This type is thread safe. @@ -115,17 +115,17 @@ Attempts to complete the dependent transaction. - Any attempt for additional work on the transaction after this method is called. These include invoking methods such as , , , , or any serialization operations on the transaction. diff --git a/xml/System.Transactions/Enlistment.xml b/xml/System.Transactions/Enlistment.xml index b6e86a12951..4ff77a63b37 100644 --- a/xml/System.Transactions/Enlistment.xml +++ b/xml/System.Transactions/Enlistment.xml @@ -48,16 +48,16 @@ and methods of the object are invoked to enlist a participant in a transaction, they return this object describing the enlistment. + When the and methods of the object are invoked to enlist a participant in a transaction, they return this object describing the enlistment. - During the final phase of the transaction commit, the transaction manager passes this object to a resource manager implementing the interface that has enlisted in a transaction. Specifically, the transaction manager calls either the or the method of the participant, depending on whether the latter has decided to commit or roll back the transaction. The participant should call the method of this object to let the transaction manager know that it has completed its work. + During the final phase of the transaction commit, the transaction manager passes this object to a resource manager implementing the interface that has enlisted in a transaction. Specifically, the transaction manager calls either the or the method of the participant, depending on whether the latter has decided to commit or roll back the transaction. The participant should call the method of this object to let the transaction manager know that it has completed its work. - An enlistment can call the method at anytime before it has called in the prepare phase. By doing so, the enlistment is casting a read only vote, meaning that it votes commit on the transaction but does not need to receive the final outcome. Note that, after the method is called, the enlisted participant receives no further notifications from the transaction manager. + An enlistment can call the method at anytime before it has called in the prepare phase. By doing so, the enlistment is casting a read only vote, meaning that it votes commit on the transaction but does not need to receive the final outcome. Note that, after the method is called, the enlisted participant receives no further notifications from the transaction manager. ## Examples - The following example shows an implementation of the interface, and when the method should be called. + The following example shows an implementation of the interface, and when the method should be called. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/tx_enlist/cs/enlist.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/tx_enlist/vb/enlist.vb" id="Snippet2"::: @@ -112,11 +112,11 @@ , or method of the participant, depending on whether the transaction is to be committed or rolled back. The resource manager should perform any work necessary to finish the transaction and then inform the transaction manager that it has finished by calling the method on the `enlistment` parameter. + During the final phase of the transaction commit, the transaction manager calls either the , or method of the participant, depending on whether the transaction is to be committed or rolled back. The resource manager should perform any work necessary to finish the transaction and then inform the transaction manager that it has finished by calling the method on the `enlistment` parameter. - If the resource manager has enlisted durably, but does not respond by calling method, the transaction manager is unsure that the resource manager has received the respective notification call. As such, the transaction manager keeps waiting for a response, and maintains information relevant to this transaction. If is never called, this piece of information is kept around indefinitely in memory or in a system-wide resource. This results in resources not being able to be reclaimed. In the case of a distributed transaction, this could eventually fill the MSDTC log, which halts the MSDTC process. In the case of a transaction managed by , this results in a gradual and continual increase in the memory consumption of the resource manager's process. Therefore, it is crucial that you call the method once your resource manager is done with your prepare work. + If the resource manager has enlisted durably, but does not respond by calling method, the transaction manager is unsure that the resource manager has received the respective notification call. As such, the transaction manager keeps waiting for a response, and maintains information relevant to this transaction. If is never called, this piece of information is kept around indefinitely in memory or in a system-wide resource. This results in resources not being able to be reclaimed. In the case of a distributed transaction, this could eventually fill the MSDTC log, which halts the MSDTC process. In the case of a transaction managed by , this results in a gradual and continual increase in the memory consumption of the resource manager's process. Therefore, it is crucial that you call the method once your resource manager is done with your prepare work. - An enlistment can call the method at anytime before it has called in the prepare phase. By doing so, the enlistment is casting a read only vote, meaning that it votes commit on the transaction but does not need to receive the final outcome. Note that, after this method is called, the enlisted participant receives no further notifications from the transaction manager. + An enlistment can call the method at anytime before it has called in the prepare phase. By doing so, the enlistment is casting a read only vote, meaning that it votes commit on the transaction but does not need to receive the final outcome. Note that, after this method is called, the enlisted participant receives no further notifications from the transaction manager. ]]> diff --git a/xml/System.Transactions/EnlistmentOptions.xml b/xml/System.Transactions/EnlistmentOptions.xml index 0b7aee8850c..c4c188e706c 100644 --- a/xml/System.Transactions/EnlistmentOptions.xml +++ b/xml/System.Transactions/EnlistmentOptions.xml @@ -50,17 +50,17 @@ Determines whether the object should be enlisted during the prepare phase. - and and methods to notify the transaction manager whether the resource manager needs to create another enlistment during the Prepare phase. For more information on enlistment, see [Enlisting Resources as Participants in a Transaction](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/ee818750(v=vs.100)). - - If EnlistDuringPrepareRequired is specified during enlistment, the resource manager indicates that it wants to receive a Prepare notification while new enlistments are still allowed for the transaction. A resource manager who acts as a cache for another durable resource, such as a backend database, would probably use this option during enlistment. When the caching resource gets its Prepare notification, it transfers its content to the durable resource. By doing so, the durable resource enlists on the transaction to become a participant of the 2 Phase Commit (2PC) protocol. Before this happens, only the caching resource (not the durable resource) was enlisted. - - If None is specified, the enlistment indicates that it will not receive a Prepare notification until it is too late to create new enlistments in 2PC. In our preceding scenario, if a caching resource specifies this option during enlistment, and attempts to flush its cache during the Prepare notification, the durable resource gets an exception when it attempts on enlisting since it is too late. - - None should be used as a default. - + and and methods to notify the transaction manager whether the resource manager needs to create another enlistment during the Prepare phase. For more information on enlistment, see [Enlisting Resources as Participants in a Transaction](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/ee818750(v=vs.100)). + + If EnlistDuringPrepareRequired is specified during enlistment, the resource manager indicates that it wants to receive a Prepare notification while new enlistments are still allowed for the transaction. A resource manager who acts as a cache for another durable resource, such as a backend database, would probably use this option during enlistment. When the caching resource gets its Prepare notification, it transfers its content to the durable resource. By doing so, the durable resource enlists on the transaction to become a participant of the 2 Phase Commit (2PC) protocol. Before this happens, only the caching resource (not the durable resource) was enlisted. + + If None is specified, the enlistment indicates that it will not receive a Prepare notification until it is too late to create new enlistments in 2PC. In our preceding scenario, if a caching resource specifies this option during enlistment, and attempts to flush its cache during the Prepare notification, the durable resource gets an exception when it attempts on enlisting since it is too late. + + None should be used as a default. + ]]> diff --git a/xml/System.Transactions/HostCurrentTransactionCallback.xml b/xml/System.Transactions/HostCurrentTransactionCallback.xml index 04a9398886b..413646d2789 100644 --- a/xml/System.Transactions/HostCurrentTransactionCallback.xml +++ b/xml/System.Transactions/HostCurrentTransactionCallback.xml @@ -50,11 +50,11 @@ Provides a mechanism for the hosting environment to supply its own default notion of . A object. - . It is called when is `null`, and there is no current that indicates that the ambient transaction may have been suppressed. - + . It is called when is `null`, and there is no current that indicates that the ambient transaction may have been suppressed. + ]]> diff --git a/xml/System.Transactions/IEnlistmentNotification.xml b/xml/System.Transactions/IEnlistmentNotification.xml index ef1bcd15867..bcd413e376f 100644 --- a/xml/System.Transactions/IEnlistmentNotification.xml +++ b/xml/System.Transactions/IEnlistmentNotification.xml @@ -48,16 +48,16 @@ ## Remarks In order for a resource manager to participate in a transaction, it must enlist in the transaction through the transaction manager. The class defines a set of methods whose names begin with `Enlist` that provide this functionality. The different `Enlist` methods correspond to the different types of enlistment that a resource manager may have. - This class describes an interface that a resource manager should implement to provide two phase commit notification callbacks for the transaction manager upon enlisting for participation. For each resource manager's implementation of the interface, you should enlist it using the method or the method of the class, depending on whether your resource is volatile or durable. For more information on enlistment and 2PC, see [Enlisting Resources as Participants in a Transaction](/dotnet/framework/data/transactions/enlisting-resources-as-participants-in-a-transaction) and [Committing a Transaction in Single-Phase and Multi-Phase](/dotnet/framework/data/transactions/committing-a-transaction-in-single-phase-and-multi-phase) respectively. + This class describes an interface that a resource manager should implement to provide two phase commit notification callbacks for the transaction manager upon enlisting for participation. For each resource manager's implementation of the interface, you should enlist it using the method or the method of the class, depending on whether your resource is volatile or durable. For more information on enlistment and 2PC, see [Enlisting Resources as Participants in a Transaction](/dotnet/framework/data/transactions/enlisting-resources-as-participants-in-a-transaction) and [Committing a Transaction in Single-Phase and Multi-Phase](/dotnet/framework/data/transactions/committing-a-transaction-in-single-phase-and-multi-phase) respectively. The transaction manager notifies the enlisted object at different phases of the Two Phase Commit Protocol by the following methods. |Method|Description| |------------|-----------------| -||This method of an enlisted object is used as a callback by the Transaction Manager during the first phase of a transaction, when the transaction manager asks participants whether they can commit the transaction.| -||This method of an enlisted object is used as a callback by the Transaction Manager during the second phase of a transaction if the transaction is committed.| -||This method of an enlisted object is used as a callback by the Transaction Manager during the second phase of a transaction if the transaction is aborted (that is, rolled back).| -||This method of an enlisted object is used as a callback by the Transaction Manager during the second phase of a transaction if the transaction is in doubt.| +||This method of an enlisted object is used as a callback by the Transaction Manager during the first phase of a transaction, when the transaction manager asks participants whether they can commit the transaction.| +||This method of an enlisted object is used as a callback by the Transaction Manager during the second phase of a transaction if the transaction is committed.| +||This method of an enlisted object is used as a callback by the Transaction Manager during the second phase of a transaction if the transaction is aborted (that is, rolled back).| +||This method of an enlisted object is used as a callback by the Transaction Manager during the second phase of a transaction if the transaction is in doubt.| > [!NOTE] > You should be aware that notifications might not be sent sequentially, or in a particular order. @@ -65,7 +65,7 @@ ## Examples - The following example shows an implementation of this interface, as well as enlisting the object as a participant in a transaction using the method. + The following example shows an implementation of this interface, as well as enlisting the object as a participant in a transaction using the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/tx_enlist/cs/enlist.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/tx_enlist/vb/enlist.vb" id="Snippet1"::: @@ -124,9 +124,9 @@ ## Remarks The transaction manager calls this method of an enlisted object during the second phase of a commitment, when it instructs all participants to commit the transaction. - The resource manager should perform any work necessary to finish the transaction and then inform the TM that it has finished by calling the method on the `enlistment` parameter. + The resource manager should perform any work necessary to finish the transaction and then inform the TM that it has finished by calling the method on the `enlistment` parameter. - If the resource manager has enlisted durably, but does not respond by calling method, the transaction manager is unsure that the resource manager has received the call. As such, the transaction manager keeps waiting for a response, and maintains information relevant to this transaction. If is never called, this piece of information is kept around indefinitely in memory or in a system-wide resource. This results in resources not being able to be reclaimed. In the case of a distributed transaction, this could eventually fill the MSDTC log, which halts the MSDTC process. In the case of a transaction managed by , this results in a gradual and continual increase in the memory consumption of the resource manager's process. Therefore, it is crucial that you call the method once your resource manager is done with your prepare work. + If the resource manager has enlisted durably, but does not respond by calling method, the transaction manager is unsure that the resource manager has received the call. As such, the transaction manager keeps waiting for a response, and maintains information relevant to this transaction. If is never called, this piece of information is kept around indefinitely in memory or in a system-wide resource. This results in resources not being able to be reclaimed. In the case of a distributed transaction, this could eventually fill the MSDTC log, which halts the MSDTC process. In the case of a transaction managed by , this results in a gradual and continual increase in the memory consumption of the resource manager's process. Therefore, it is crucial that you call the method once your resource manager is done with your prepare work. ]]> @@ -179,12 +179,12 @@ ## Remarks This method is called for volatile resources when the transaction manager has invoked a single phase commit operation to a single durable resource, and then connection to the durable resource was lost prior to getting the transaction result. At that point, the transaction outcome cannot be safely determined. - As is considered to be a final state for a transaction, you should not call or after calling . + As is considered to be a final state for a transaction, you should not call or after calling . > [!NOTE] -> Your implementation of this method for the volatile resource should perform whatever recovery or containment operation it understands on the affected data. It must also call the method on the on the `enlistment` parameter when it has finished its work. +> Your implementation of this method for the volatile resource should perform whatever recovery or containment operation it understands on the affected data. It must also call the method on the on the `enlistment` parameter when it has finished its work. - If the resource manager has enlisted durably, but does not respond by calling method, the transaction manager is unsure that the resource manager has received the call. As such, the transaction manager keeps waiting for a response, and maintains information relevant to this transaction. If is never called, this piece of information is kept around indefinitely in memory or in a system-wide resource. This results in resources not being able to be reclaimed. In the case of a distributed transaction, this could eventually fill the MSDTC log, which halts the MSDTC process. In the case of a transaction managed by , this results in a gradual and continual increase in the memory consumption of the resource manager's process. Therefore, it is crucial that you call the method once your resource manager is done with your prepare work. + If the resource manager has enlisted durably, but does not respond by calling method, the transaction manager is unsure that the resource manager has received the call. As such, the transaction manager keeps waiting for a response, and maintains information relevant to this transaction. If is never called, this piece of information is kept around indefinitely in memory or in a system-wide resource. This results in resources not being able to be reclaimed. In the case of a distributed transaction, this could eventually fill the MSDTC log, which halts the MSDTC process. In the case of a transaction managed by , this results in a gradual and continual increase in the memory consumption of the resource manager's process. Therefore, it is crucial that you call the method once your resource manager is done with your prepare work. ]]> @@ -237,13 +237,13 @@ ## Remarks The transaction manager calls this method of an enlisted resource manager during the phase 1 of a commitment, when it asks participants whether they can commit the transaction. - When you are implementing a durable resource manager, you should log your prepare record during this phase. The record should contain all the necessary information to perform recovery. This includes the property, which is passed to the transaction manager in the method during recovery. For more information on recovery, see [Performing Recovery](https://msdn.microsoft.com/library/d342c5c7-da64-4a4c-8e63-b52f4fbf2691). + When you are implementing a durable resource manager, you should log your prepare record during this phase. The record should contain all the necessary information to perform recovery. This includes the property, which is passed to the transaction manager in the method during recovery. For more information on recovery, see [Performing Recovery](https://msdn.microsoft.com/library/d342c5c7-da64-4a4c-8e63-b52f4fbf2691). - Your resource manager should complete all work that must be finished before calling the method of the `preparingEnlistment` parameter to indicate its vote for commitment. You should make sure that this is accomplished before receiving any phase 2 notification such as commit, rollback or in doubt. This is because phase 2 notifications can happen inline on the same thread that called the method in phase 1. As such, you should not do any work after the call (for example, releasing locks) that you would expect to have completed before receiving the phase 2 notifications. + Your resource manager should complete all work that must be finished before calling the method of the `preparingEnlistment` parameter to indicate its vote for commitment. You should make sure that this is accomplished before receiving any phase 2 notification such as commit, rollback or in doubt. This is because phase 2 notifications can happen inline on the same thread that called the method in phase 1. As such, you should not do any work after the call (for example, releasing locks) that you would expect to have completed before receiving the phase 2 notifications. You can also call the method of the `preparingEnlistment` parameter to indicate a vote for rollback. - If you want the object to merely observe and react to the progress of the transaction, without participating in it, your implementation of this method should call the method of the `preparingEnlistment` parameter when it has finished its work. By doing so, your resource manager would not receive any phase 2 notification. + If you want the object to merely observe and react to the progress of the transaction, without participating in it, your implementation of this method should call the method of the `preparingEnlistment` parameter when it has finished its work. By doing so, your resource manager would not receive any phase 2 notification. ]]> @@ -296,9 +296,9 @@ ## Remarks The transaction manager calls this method of an enlisted object when the transaction is being rolled back (aborted) due to the inability of one or more transaction participants to commit the transaction. - The resource manager should perform any work necessary to finish the transaction and then inform the TM that it has finished by calling the method on the `enlistment` parameter. + The resource manager should perform any work necessary to finish the transaction and then inform the TM that it has finished by calling the method on the `enlistment` parameter. - If the resource manager has enlisted durably, but does not respond by calling method, the transaction manager is unsure that the resource manager has received the call. As such, the transaction manager keeps waiting for a response, and maintains information relevant to this transaction. If is never called, this piece of information is kept around indefinitely in memory or in a system-wide resource. This results in resources not being able to be reclaimed. In the case of a distributed transaction, this could eventually fill the MSDTC log, which halts the MSDTC process. In the case of a transaction managed by , this results in a gradual and continual increase in the memory consumption of the resource manager's process. Therefore, it is crucial that you call the method once your resource manager is done with your prepare work. + If the resource manager has enlisted durably, but does not respond by calling method, the transaction manager is unsure that the resource manager has received the call. As such, the transaction manager keeps waiting for a response, and maintains information relevant to this transaction. If is never called, this piece of information is kept around indefinitely in memory or in a system-wide resource. This results in resources not being able to be reclaimed. In the case of a distributed transaction, this could eventually fill the MSDTC log, which halts the MSDTC process. In the case of a transaction managed by , this results in a gradual and continual increase in the memory consumption of the resource manager's process. Therefore, it is crucial that you call the method once your resource manager is done with your prepare work. ]]> diff --git a/xml/System.Transactions/IPromotableSinglePhaseNotification.xml b/xml/System.Transactions/IPromotableSinglePhaseNotification.xml index 44420f7fa21..8a0de6dae88 100644 --- a/xml/System.Transactions/IPromotableSinglePhaseNotification.xml +++ b/xml/System.Transactions/IPromotableSinglePhaseNotification.xml @@ -52,11 +52,11 @@ ## Remarks Promotable Enlistments (PSPE) allow a resource, such as a database, to take ownership of the transaction if it is the only entity participating in the transaction. Later, if needed, the infrastructure can still escalate the transaction to MSDTC. For more information, see [Optimization Using Single Phase Commit and Promotable Single Phase Notification](https://learn.microsoft.com/previous-versions/dotnet/netframework-3.0/ms229980(v=vs.85)). - A resource manager that implements this interface delegates control of the commit of it's internal non-distributed transaction to an enlistment on a transaction through the method on the class. + A resource manager that implements this interface delegates control of the commit of it's internal non-distributed transaction to an enlistment on a transaction through the method on the class. - If the method is called, your implementation of this interface must produce a distributed transaction in the form of a propagation token, and return it to . + If the method is called, your implementation of this interface must produce a distributed transaction in the form of a propagation token, and return it to . - After you enlist an object that implements this interface as a participant of a transaction using the method, the transaction manager then notifies the participant when the transaction is promoted, committed, or rolled back by invoking the method, the method, or the method of the object. + After you enlist an object that implements this interface as a participant of a transaction using the method, the transaction manager then notifies the participant when the transaction is promoted, committed, or rolled back by invoking the method, the method, or the method of the object. For more information, see [Optimization Using Single Phase Commit and Promotable Single Phase Notification](https://learn.microsoft.com/previous-versions/dotnet/netframework-3.0/ms229980(v=vs.85)). @@ -160,7 +160,7 @@ callback method on the `singlePhaseEnlistment` parameter. If the PSPE replies with or , an is thrown from the callback. + On receiving this notification, the PSPE should always rollback it's internal transaction and then reply with the callback method on the `singlePhaseEnlistment` parameter. If the PSPE replies with or , an is thrown from the callback. ]]> diff --git a/xml/System.Transactions/ISinglePhaseNotification.xml b/xml/System.Transactions/ISinglePhaseNotification.xml index a743eb2dfe4..7c074d201fb 100644 --- a/xml/System.Transactions/ISinglePhaseNotification.xml +++ b/xml/System.Transactions/ISinglePhaseNotification.xml @@ -47,17 +47,17 @@ Describes a resource object that supports single phase commit optimization to participate in a transaction. - method or the method of the class. Specifically, the `EnlistmentOptions` parameter should equal to to ensure that a single phase commit is performed. If it is mistakenly set to , no single phase commit occurs. - - Since the interface derives from the interface, the resource manager must also implement all the methods of the latter for two phase commit notifications. It is the transaction manager's choice as to whether two phase commit or the single phase commit optimization is used with this resource manager. However, implementing this interface gives the resource manager the opportunity to take advantage of the optimization when it is available. - - If the optimization is used and the transaction manager calls the method of the enlisted resource, the resource manager should respond to this call by using various methods of the class to inform the transaction manager if the transaction is to be committed or rolled back. - + method or the method of the class. Specifically, the `EnlistmentOptions` parameter should equal to to ensure that a single phase commit is performed. If it is mistakenly set to , no single phase commit occurs. + + Since the interface derives from the interface, the resource manager must also implement all the methods of the latter for two phase commit notifications. It is the transaction manager's choice as to whether two phase commit or the single phase commit optimization is used with this resource manager. However, implementing this interface gives the resource manager the opportunity to take advantage of the optimization when it is available. + + If the optimization is used and the transaction manager calls the method of the enlisted resource, the resource manager should respond to this call by using various methods of the class to inform the transaction manager if the transaction is to be committed or rolled back. + ]]> @@ -105,17 +105,17 @@ A used to send a response to the transaction manager. Represents the resource manager's implementation of the callback for the single phase commit optimization. - method is called, or the two phase commit methods defined in the interface are called. - - Your implementation of this method should call either the method or the method of the `singlePhaseEnlistment` parameter to indicate whether the transaction should be committed or rolled back. - - The transaction manager calls this method when there is only one volatile enlistment that supports single phase commit, or when there are zero or more volatile enlistments and one durable enlistment. In the latter case, the volatile enlistments receive notifications for two-phase-commit, and the sole durable enlistment receives a single-phase commit notification. - + method is called, or the two phase commit methods defined in the interface are called. + + Your implementation of this method should call either the method or the method of the `singlePhaseEnlistment` parameter to indicate whether the transaction should be committed or rolled back. + + The transaction manager calls this method when there is only one volatile enlistment that supports single phase commit, or when there are zero or more volatile enlistments and one durable enlistment. In the latter case, the volatile enlistments receive notifications for two-phase-commit, and the sole durable enlistment receives a single-phase commit notification. + ]]> diff --git a/xml/System.Transactions/ITransactionPromoter.xml b/xml/System.Transactions/ITransactionPromoter.xml index 4fc13b1fd66..5d8c1071c2e 100644 --- a/xml/System.Transactions/ITransactionPromoter.xml +++ b/xml/System.Transactions/ITransactionPromoter.xml @@ -43,11 +43,11 @@ Describes a delegated transaction for an existing transaction that can be escalated to be managed by the MSDTC when needed. - interface directly. Instead, you should implement the interface, which inherits the single method of this interface. For more information on implementing a resource manager, see [Implementing A Resource Manager](/dotnet/framework/data/transactions/implementing-a-resource-manager). - + interface directly. Instead, you should implement the interface, which inherits the single method of this interface. For more information on implementing a resource manager, see [Implementing A Resource Manager](/dotnet/framework/data/transactions/implementing-a-resource-manager). + ]]> @@ -93,11 +93,11 @@ Notifies an enlisted object that an escalation of the delegated transaction has been requested. A transmitter/receiver propagation token that marshals a distributed transaction. For more information, see . - should be thrown by an implementation of interface to indicate that a call to has failed. - + should be thrown by an implementation of interface to indicate that a call to has failed. + ]]> diff --git a/xml/System.Transactions/PreparingEnlistment.xml b/xml/System.Transactions/PreparingEnlistment.xml index 68d85902952..4ea8c309738 100644 --- a/xml/System.Transactions/PreparingEnlistment.xml +++ b/xml/System.Transactions/PreparingEnlistment.xml @@ -48,9 +48,9 @@ method to obtain a resource's vote on the transaction. Depending on whether it votes to commit or roll back, your implementation of the resource manager should call the or methods of this type. + During the initial (prepare) phase of the transaction, the transaction manager passes this type to the resource manager by calling the method to obtain a resource's vote on the transaction. Depending on whether it votes to commit or roll back, your implementation of the resource manager should call the or methods of this type. - The resource manager can also call the method at anytime before it has called the method. By doing so, the enlistment is casting a read only vote, meaning that it votes commit on the transaction but does not need to receive the final outcome. + The resource manager can also call the method at anytime before it has called the method. By doing so, the enlistment is casting a read only vote, meaning that it votes commit on the transaction but does not need to receive the final outcome. Durable resource managers can retrieve the information that is be needed by the transaction manager for re-enlistment from the property. For more information on recovery, see [Performing Recovery](https://msdn.microsoft.com/library/d342c5c7-da64-4a4c-8e63-b52f4fbf2691). @@ -118,7 +118,7 @@ method of the interface calls this method to indicate that the transaction must be rolled back. + An implementation of the method of the interface calls this method to indicate that the transaction must be rolled back. @@ -217,11 +217,11 @@ method of the interface, calls this method to indicate that the transaction can be committed. + In the first (prepare) phase of a two phase commit, a resource manager implementing the method of the interface, calls this method to indicate that the transaction can be committed. - The resource manager can call the method at anytime before it has called this method. By doing so, the enlistment is casting a read only vote, meaning that it votes commit on the transaction but does not need to receive the final outcome. + The resource manager can call the method at anytime before it has called this method. By doing so, the enlistment is casting a read only vote, meaning that it votes commit on the transaction but does not need to receive the final outcome. - Once this method is called by an enlistment and before it returns, it is possible that another thread or this same thread could make a call into the same enlistment method such as to perform a rollback. This can result in a deadlock situation if the resource manager implementation does not release resource locks until after this method returns. + Once this method is called by an enlistment and before it returns, it is possible that another thread or this same thread could make a call into the same enlistment method such as to perform a rollback. This can result in a deadlock situation if the resource manager implementation does not release resource locks until after this method returns. diff --git a/xml/System.Transactions/SinglePhaseEnlistment.xml b/xml/System.Transactions/SinglePhaseEnlistment.xml index 8b8d13a7961..b7254ea6915 100644 --- a/xml/System.Transactions/SinglePhaseEnlistment.xml +++ b/xml/System.Transactions/SinglePhaseEnlistment.xml @@ -51,11 +51,11 @@ Provides a set of callbacks that facilitate communication between a participant enlisted for Single Phase Commit and the transaction manager when the notification is received. - is called, and an instance of this type is passed in, the participant then notifies the transaction manager via the method or the method to indicate whether the transaction should be committed or rolled back. - + is called, and an instance of this type is passed in, the participant then notifies the transaction manager via the method or the method to indicate whether the transaction should be committed or rolled back. + ]]> This type is thread safe. @@ -73,11 +73,11 @@ Represents a callback that is used to indicate to the transaction manager that the transaction should be rolled back. - @@ -121,11 +121,11 @@ Represents a callback that is used to indicate to the transaction manager that the transaction should be rolled back. - interface uses this method to notify the transaction manager that it cannot commit, and that the transaction should be rolled back. - + interface uses this method to notify the transaction manager that it cannot commit, and that the transaction should be rolled back. + ]]> @@ -214,11 +214,11 @@ Represents a callback that is used to indicate to the transaction manager that the SinglePhaseCommit was successful. - interface uses this method to notify the transaction manager that the transaction should be committed. - + interface uses this method to notify the transaction manager that the transaction should be committed. + ]]> @@ -272,11 +272,11 @@ Represents a callback that is used to indicate to the transaction manager that the status of the transaction is in doubt. - interface uses this method to notify the transaction manager that the transaction is in doubt. A transaction is in doubt when one or more of the enlisted resource managers cannot be contacted. - + interface uses this method to notify the transaction manager that the transaction is in doubt. A transaction is in doubt when one or more of the enlisted resource managers cannot be contacted. + ]]> diff --git a/xml/System.Transactions/Transaction.xml b/xml/System.Transactions/Transaction.xml index 9eaf9c5d108..13ed0003308 100644 --- a/xml/System.Transactions/Transaction.xml +++ b/xml/System.Transactions/Transaction.xml @@ -178,7 +178,7 @@ Although you can set the ambient transaction using this property, you should use the object to manipulate the ambient transaction whenever possible. - This property is thread static. If you change the ambient transaction using this property inside a an is thrown when is called, and the previous ambient transaction value is restored. + This property is thread static. If you change the ambient transaction using this property inside a an is thrown when is called, and the previous ambient transaction value is restored. ]]> @@ -232,7 +232,7 @@ ## Remarks A dependent transaction is a transaction whose outcome depends on the outcome of the transaction from which it was cloned. - The `cloneoption` parameter controls what kind of dependent transaction to create. If a dependent transaction is created with , it blocks the commit process of the transaction until the transaction times out, or is called on the . If it is created with , it automatically aborts the transaction if is called before is called on the . + The `cloneoption` parameter controls what kind of dependent transaction to create. If a dependent transaction is created with , it blocks the commit process of the transaction until the transaction times out, or is called on the . If it is created with , it automatically aborts the transaction if is called before is called on the . @@ -292,7 +292,7 @@ inside a an is thrown when is called, and the previous ambient transaction value is restored. + If you change the ambient transaction by setting inside a an is thrown when is called, and the previous ambient transaction value is restored. ]]> @@ -634,14 +634,14 @@ method. + Volatile resource managers cannot recovery from failure to complete a transaction in which they were participating. To obtain a durable enlistment in a transaction, use the method. Resource managers enlisted for participation in a transaction through this method receive two phase commit notifications that correspond to the methods defined on the interface. ## Examples - The following example shows an implementation of interface, as well as enlisting the object as a participant in a transaction using the method. + The following example shows an implementation of interface, as well as enlisting the object as a participant in a transaction using the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/tx_enlist/cs/enlist.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/tx_enlist/vb/enlist.vb" id="Snippet1"::: @@ -699,7 +699,7 @@ method. For more information on volatile and durable resources, as well as how to enlist a resource, see [Implementing A Resource Manager](/previous-versions/ms229975(v=vs.90)). For more information on how a resource manager responds to commit notification and prepare the commit, see [Committing A Transaction In Single-Phase and Multi-Phase](/previous-versions/ckawh9ct(v=vs.90)). + Volatile resource managers cannot recovery from failure to complete a transaction in which they were participating. To obtain a durable enlistment in a transaction, use the method. For more information on volatile and durable resources, as well as how to enlist a resource, see [Implementing A Resource Manager](/previous-versions/ms229975(v=vs.90)). For more information on how a resource manager responds to commit notification and prepare the commit, see [Committing A Transaction In Single-Phase and Multi-Phase](/previous-versions/ckawh9ct(v=vs.90)). You should note that even when your resource manager implementation enlists with this method, it is not guaranteed that it receives a single phase commit. The transaction manager can still send two phase commit notifications instead. For more information on the single phase commit optimization, see [Optimization Using Single Phase Commit and Promotable Single Phase Notification](/previous-versions/dotnet/netframework-3.0/ms229980(v=vs.85)). @@ -948,7 +948,7 @@ if and are equal; otherwise, . - .]]> + .]]> @@ -999,7 +999,7 @@ if and are not equal; otherwise, . - .]]> + .]]> diff --git a/xml/System.Transactions/TransactionAbortedException.xml b/xml/System.Transactions/TransactionAbortedException.xml index 981f7abd7e9..68d523412c6 100644 --- a/xml/System.Transactions/TransactionAbortedException.xml +++ b/xml/System.Transactions/TransactionAbortedException.xml @@ -56,13 +56,13 @@ The exception that is thrown when an operation is attempted on a transaction that has already been rolled back, or an attempt is made to commit the transaction and the transaction aborts. - method on a transaction that has already timed out. This exception is also thrown when an attempt is made to commit the transaction and the transaction aborts. - - This is a recoverable error. - + method on a transaction that has already timed out. This exception is also thrown when an attempt is made to commit the transaction and the transaction aborts. + + This is a recoverable error. + ]]> diff --git a/xml/System.Transactions/TransactionInterop.xml b/xml/System.Transactions/TransactionInterop.xml index 6596d85dd32..163cf778371 100644 --- a/xml/System.Transactions/TransactionInterop.xml +++ b/xml/System.Transactions/TransactionInterop.xml @@ -60,27 +60,27 @@ The Export/Import (push model) propagation involves the following steps: -1. On the remote machine, obtain the "whereabouts" of the transaction manager of that machine by calling the method. You can then cache this piece of information on the client machine for future usage. +1. On the remote machine, obtain the "whereabouts" of the transaction manager of that machine by calling the method. You can then cache this piece of information on the client machine for future usage. 2. Send the data containing the whereabouts to the client machine using any preferred method. -3. On the client machine, use the whereabouts to "export" the transaction to the remote machine and generate a transaction "cookie". This is done by calling and passing in the remote machine's whereabouts. +3. On the client machine, use the whereabouts to "export" the transaction to the remote machine and generate a transaction "cookie". This is done by calling and passing in the remote machine's whereabouts. 4. Send the data containing the transaction "cookie" to the remote machine using any preferred method. -5. On the remote machine, use the transaction "cookie" to obtain a clone of the client transaction by calling the method. +5. On the remote machine, use the transaction "cookie" to obtain a clone of the client transaction by calling the method. -6. On the remote machine, use the clone transaction to enlist the resource manager using the or methods of the class. +6. On the remote machine, use the clone transaction to enlist the resource manager using the or methods of the class. The Transmitter/Receiver (pull model) propagation involves the following steps: -- On the client machine, using the transaction generates a corresponding "propagation token" by calling . +- On the client machine, using the transaction generates a corresponding "propagation token" by calling . - Send the data containing the "propagation token" of the transaction to the remote machine using any preferred method. - On the remote machine, use the "propagation token" to obtain a clone of the client transaction by calling is called. Another advantage is that the propagation token can be sent to any remote machine, while the export cookie can be used only on the machine that provided the whereabouts. + The Transmitter/Receiver model provides better performance in scenarios where the transaction token is sent to a remote machine, but the remote machine may not use it to obtain the transaction. This is because the transaction is not propagated until is called. Another advantage is that the propagation token can be sent to any remote machine, while the export cookie can be used only on the machine that provided the whereabouts. However, you should also note that the whereabouts of remote transaction managers are encapsulated in all the propagation tokens, making them bigger than the corresponding transaction cookies from the Export/Import model. @@ -339,7 +339,7 @@ method, provide functionality for "pull" propagation, in which the transaction is "pulled" from the remote machine when this method is called to unmarshal the transaction. + This method, together with the method, provide functionality for "pull" propagation, in which the transaction is "pulled" from the remote machine when this method is called to unmarshal the transaction. For more information on different propagation models, see the Remarks section of the class. @@ -438,7 +438,7 @@ method. + The Whereabouts contains an address that describes the location of a transaction manager. This permits two transaction managers to communicate with one another and thereby propagate a transaction from one system to the other. The information returned by this method can be used to provide location information for push model transaction propagation with the method. For more information on different propagation models, see the Remarks section of the class. diff --git a/xml/System.Transactions/TransactionManager.xml b/xml/System.Transactions/TransactionManager.xml index c1a052d2c06..bd098524818 100644 --- a/xml/System.Transactions/TransactionManager.xml +++ b/xml/System.Transactions/TransactionManager.xml @@ -345,7 +345,7 @@ method for each outstanding transaction. Only when all of the reenlistments are done should the resource manager call . + All durable resource managers should do recovery when they first start up by calling the method for each outstanding transaction. Only when all of the reenlistments are done should the resource manager call . For more information on recovery, see [Performing Recovery](/previous-versions/ms229982(v=vs.90)). @@ -409,15 +409,15 @@ A resource manager facilitates resolution of durable enlistments in a transaction by reenlisting the transaction participant after resource failure. -The `resourceManagerIdentifier` parameter is used to consistently label the participant of a transaction in the event of a resource failure. When calling the method, the resource manager must provide the same `resourceManagerIdentifier` as it used when it originally called the method during enlistment, or a is thrown. +The `resourceManagerIdentifier` parameter is used to consistently label the participant of a transaction in the event of a resource failure. When calling the method, the resource manager must provide the same `resourceManagerIdentifier` as it used when it originally called the method during enlistment, or a is thrown. -When a participant is reenlisted using this method, the phase 2 methods of that correspond to the transaction's outcome (that is, , , or ) are called as appropriate. +When a participant is reenlisted using this method, the phase 2 methods of that correspond to the transaction's outcome (that is, , , or ) are called as appropriate. -After the participants are successfully reenlisted, you should then call to complete the recovery. +After the participants are successfully reenlisted, you should then call to complete the recovery. You should only call this method when a resource manager restarts from failure. In addition, you should only reenlist unresolved transactions logged by a resource manager during the initial Prepare phase of a two-phase commit. Any attempt to call this method at invalid times can produce erroneous results. -If the transaction manager fails, and your resource manager performs recovery only a short time after you called the method on an enlistment in phase 1 of the Two-Phase Commit protocol, your resource manager might either receive the or callback. +If the transaction manager fails, and your resource manager performs recovery only a short time after you called the method on an enlistment in phase 1 of the Two-Phase Commit protocol, your resource manager might either receive the or callback. For more information on recovery, see [Performing Recovery](/previous-versions/ms229982(v=vs.90)). diff --git a/xml/System.Transactions/TransactionOptions.xml b/xml/System.Transactions/TransactionOptions.xml index 7a8affae38d..2550c1a5bae 100644 --- a/xml/System.Transactions/TransactionOptions.xml +++ b/xml/System.Transactions/TransactionOptions.xml @@ -53,11 +53,11 @@ Contains additional information that specifies transaction behaviors. - and constructors to create a new transaction with the desired behaviors. - + and constructors to create a new transaction with the desired behaviors. + ]]> @@ -281,7 +281,7 @@ if and are equal; otherwise, . - .]]> + .]]> @@ -331,7 +331,7 @@ if and are not equal; otherwise, . - .]]> + .]]> @@ -374,11 +374,11 @@ Gets or sets the timeout period for the transaction. A value that specifies the timeout period for the transaction. - diff --git a/xml/System.Transactions/TransactionPromotionException.xml b/xml/System.Transactions/TransactionPromotionException.xml index b3af3216dc6..c69b1aed634 100644 --- a/xml/System.Transactions/TransactionPromotionException.xml +++ b/xml/System.Transactions/TransactionPromotionException.xml @@ -56,11 +56,11 @@ The exception that is thrown when a promotion fails. - interface to indicate that a call to has failed. If an implementation of fails a promotion due to an exception that is not fatal, it should catch that exception and create a with the original exception as the inner exception. - + interface to indicate that a call to has failed. If an implementation of fails a promotion due to an exception that is not fatal, it should catch that exception and create a with the original exception as the inner exception. + ]]> diff --git a/xml/System.Transactions/TransactionScope.xml b/xml/System.Transactions/TransactionScope.xml index aba5d12234a..3d2bea8f2c2 100644 --- a/xml/System.Transactions/TransactionScope.xml +++ b/xml/System.Transactions/TransactionScope.xml @@ -69,13 +69,13 @@ Upon instantiating a by the `new` statement, the transaction manager determines which transaction to participate in. Once determined, the scope always participates in that transaction. The decision is based on two factors: whether an ambient transaction is present and the value of the `TransactionScopeOption` parameter in the constructor. The ambient transaction is the transaction your code executes in. You can obtain a reference to the ambient transaction by calling the static property of the class. For more information on how this parameter is used, see the "Transaction Flow Management" section of the [Implementing An Implicit Transaction Using Transaction Scope](/dotnet/framework/data/transactions/implementing-an-implicit-transaction-using-transaction-scope) topic. - If no exception occurs within the transaction scope (that is, between the initialization of the object and the calling of its method), then the transaction in which the scope participates is allowed to proceed. If an exception does occur within the transaction scope, the transaction in which it participates will be rolled back. + If no exception occurs within the transaction scope (that is, between the initialization of the object and the calling of its method), then the transaction in which the scope participates is allowed to proceed. If an exception does occur within the transaction scope, the transaction in which it participates will be rolled back. - When your application completes all work it wants to perform in a transaction, you should call the method only once to inform that transaction manager that it is acceptable to commit the transaction. Failing to call this method aborts the transaction. + When your application completes all work it wants to perform in a transaction, you should call the method only once to inform that transaction manager that it is acceptable to commit the transaction. Failing to call this method aborts the transaction. - A call to the method marks the end of the transaction scope. Exceptions that occur after calling this method may not affect the transaction. + A call to the method marks the end of the transaction scope. Exceptions that occur after calling this method may not affect the transaction. - If you modify the value of inside a scope, an exception is thrown when is called. However, at the end of the scope, the previous value is restored. In addition, if you call on inside a transaction scope that created the transaction, the transaction aborts at the end of the scope. + If you modify the value of inside a scope, an exception is thrown when is called. However, at the end of the scope, the previous value is restored. In addition, if you call on inside a transaction scope that created the transaction, the transaction aborts at the end of the scope. @@ -779,7 +779,7 @@ When you use the `transactionOptions` parameter to specify an property, and trying to do so results in an exception being thrown. - The actual work of commit between the resources manager happens at the `End Using` statement if the object created the transaction. If it did not create the transaction, the commit occurs whenever is called by the owner of the object. At that point the Transaction Manager calls the resource managers and informs them to either commit or rollback, based on whether this method was called on the object. + The actual work of commit between the resources manager happens at the `End Using` statement if the object created the transaction. If it did not create the transaction, the commit occurs whenever is called by the owner of the object. At that point the Transaction Manager calls the resource managers and informs them to either commit or rollback, based on whether this method was called on the object. @@ -840,11 +840,11 @@ When you use the `transactionOptions` parameter to specify an object created the transaction and was called on the scope, the object attempts to commit the transaction when this method is called. In this case, this method blocks until the first phase of transaction processing is complete. The first phase ends after all resource managers and enlistments in the transaction have voted on the transaction outcome and the has durably decided to commit or abort the transaction. The second phase of processing is always asynchronous. Therefore, there is no guarantee that data just committed from within a given transaction will be immediately available afterwards when not using another transaction to view this data. + Calling this method marks the end of the transaction scope. If the object created the transaction and was called on the scope, the object attempts to commit the transaction when this method is called. In this case, this method blocks until the first phase of transaction processing is complete. The first phase ends after all resource managers and enlistments in the transaction have voted on the transaction outcome and the has durably decided to commit or abort the transaction. The second phase of processing is always asynchronous. Therefore, there is no guarantee that data just committed from within a given transaction will be immediately available afterwards when not using another transaction to view this data. The use of the C# `using` construction ensures that this method is called even if an exception occurs. Exceptions that occur after calling this method may not affect the transaction. This method also restores the ambient transaction to it original state. A is thrown if the transaction is not actually committed. - Because this method blocks until the first phase of transaction processing is complete, you should be extremely careful when using this method in a Windows Form (WinForm) application, or a deadlock can occur. If you call this method inside one WinForm Control event (for example, clicking a button), and use the synchronous method to direct the control to perform some UI tasks (for example, changing colors) in the middle of processing the transaction, a deadlock will happen. This is because the method is synchronous and blocks the worker thread until the UI thread finishes its job. However, in our scenario, the UI thread is also waiting for the worker thread to commit the transaction. The result is that none is able to proceed and the scope waits indefinitely for the Commit to finish. You should use rather than wherever possible, because it is asynchronous and thus less prone to deadlock. + Because this method blocks until the first phase of transaction processing is complete, you should be extremely careful when using this method in a Windows Form (WinForm) application, or a deadlock can occur. If you call this method inside one WinForm Control event (for example, clicking a button), and use the synchronous method to direct the control to perform some UI tasks (for example, changing colors) in the middle of processing the transaction, a deadlock will happen. This is because the method is synchronous and blocks the worker thread until the UI thread finishes its job. However, in our scenario, the UI thread is also waiting for the worker thread to commit the transaction. The result is that none is able to proceed and the scope waits indefinitely for the Commit to finish. You should use rather than wherever possible, because it is asynchronous and thus less prone to deadlock. For more information on how this method is used, see the [Implementing An Implicit Transaction Using Transaction Scope](/dotnet/framework/data/transactions/implementing-an-implicit-transaction-using-transaction-scope) topic. diff --git a/xml/System.Transactions/TransactionScopeAsyncFlowOption.xml b/xml/System.Transactions/TransactionScopeAsyncFlowOption.xml index 71d3b1cb7af..0b5f12be6fc 100644 --- a/xml/System.Transactions/TransactionScopeAsyncFlowOption.xml +++ b/xml/System.Transactions/TransactionScopeAsyncFlowOption.xml @@ -43,11 +43,11 @@ Specifies whether transaction flow across thread continuations is enabled for . - overloads that take a `TransactionScopeAsyncFlowOption` parameter. `Suppress` is the default setting if no `TransactionScopeAsyncFlowOption` is specified. - + overloads that take a `TransactionScopeAsyncFlowOption` parameter. `Suppress` is the default setting if no `TransactionScopeAsyncFlowOption` is specified. + ]]> From 7a83cd458990171110b0b5785e1211606a7fbe8a Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 30 Mar 2026 16:02:57 -0700 Subject: [PATCH 2/4] System.S* --- .../AceEnumerator.xml | 50 +- .../CommonAcl.xml | 2 +- .../CommonSecurityDescriptor.xml | 100 +-- .../DirectorySecurity.xml | 24 +- .../EventWaitHandleAccessRule.xml | 18 +- .../EventWaitHandleAuditRule.xml | 70 +- .../EventWaitHandleRights.xml | 22 +- .../EventWaitHandleSecurity.xml | 52 +- .../FileSecurity.xml | 28 +- .../FileSystemSecurity.xml | 34 +- .../GenericAce.xml | 4 +- .../MutexAccessRule.xml | 18 +- .../MutexAuditRule.xml | 70 +- .../MutexRights.xml | 22 +- .../MutexSecurity.xml | 52 +- .../NativeObjectSecurity.xml | 80 +- .../ObjectAce.xml | 4 +- .../ObjectSecurity.xml | 150 ++-- .../RegistryAccessRule.xml | 122 +-- .../RegistryAuditRule.xml | 80 +- .../RegistryRights.xml | 4 +- .../RegistrySecurity.xml | 64 +- .../SemaphoreAccessRule.xml | 18 +- .../SemaphoreAuditRule.xml | 70 +- .../SemaphoreRights.xml | 24 +- .../SemaphoreSecurity.xml | 52 +- .../ExtendedProtectionPolicyElement.xml | 4 +- .../ServiceNameElement.xml | 2 +- .../ServiceNameElementCollection.xml | 14 +- .../ChannelBinding.xml | 40 +- .../ExtendedProtectionPolicy.xml | 4 +- .../AuthorizationContext.xml | 4 +- xml/System.Security.Claims/Claim.xml | 8 +- .../ClaimsAuthenticationManager.xml | 86 +- .../ClaimsAuthorizationManager.xml | 16 +- xml/System.Security.Claims/ClaimsIdentity.xml | 218 ++--- .../ClaimsPrincipal.xml | 30 +- .../AlgorithmIdentifier.xml | 54 +- .../CmsRecipient.xml | 6 +- .../CmsSigner.xml | 36 +- .../ContentInfo.xml | 4 +- .../EnvelopedCms.xml | 28 +- .../Pkcs12Builder.xml | 10 +- .../Pkcs12Info.xml | 2 +- .../Pkcs12SafeBag.xml | 16 +- .../Pkcs12SafeContents.xml | 2 +- .../Pkcs9SigningTime.xml | 42 +- .../SignedCms.xml | 12 +- .../PublicKey.xml | 4 +- .../X500DistinguishedName.xml | 2 +- .../X509Certificate.xml | 52 +- .../X509Certificate2.xml | 12 +- .../X509Certificate2Collection.xml | 16 +- .../X509Certificate2Enumerator.xml | 6 +- .../X509Certificate2UI.xml | 12 +- ...teCollection+X509CertificateEnumerator.xml | 6 +- .../X509Chain.xml | 10 +- .../X509ChainElementCollection.xml | 2 +- .../X509ChainElementEnumerator.xml | 58 +- .../X509ChainStatus.xml | 2 +- .../X509ExtensionCollection.xml | 4 +- .../X509ExtensionEnumerator.xml | 58 +- .../X509FindType.xml | 4 +- .../X509KeyUsageExtension.xml | 2 +- .../X509NameType.xml | 4 +- .../X509SelectionFlag.xml | 6 +- .../X509Store.xml | 14 +- .../CipherData.xml | 8 +- .../CipherReference.xml | 2 +- .../DataObject.xml | 2 +- .../EncryptedReference.xml | 6 +- .../EncryptedXml.xml | 46 +- .../EncryptionMethod.xml | 4 +- .../EncryptionProperty.xml | 138 ++-- .../IRelDecryptor.xml | 4 +- .../KeyInfoName.xml | 2 +- .../KeyInfoX509Data.xml | 4 +- .../Reference.xml | 4 +- .../Signature.xml | 6 +- .../SignedInfo.xml | 2 +- .../SignedXml.xml | 24 +- .../Transform.xml | 6 +- .../TransformChain.xml | 2 +- .../X509IssuerSerial.xml | 2 +- .../XmlDsigBase64Transform.xml | 8 +- .../XmlDsigC14NTransform.xml | 10 +- .../XmlDsigEnvelopedSignatureTransform.xml | 10 +- .../XmlDsigExcC14NTransform.xml | 2 +- .../XmlDsigXPathTransform.xml | 22 +- .../XmlDsigXsltTransform.xml | 6 +- xml/System.Security.Cryptography/AesCng.xml | 8 +- .../AesCryptoServiceProvider.xml | 8 +- .../AesManaged.xml | 132 +-- .../AsnEncodedDataEnumerator.xml | 14 +- .../AsymmetricAlgorithm.xml | 30 +- .../AsymmetricKeyExchangeDeformatter.xml | 8 +- .../AsymmetricKeyExchangeFormatter.xml | 62 +- .../AsymmetricSignatureDeformatter.xml | 64 +- .../AsymmetricSignatureFormatter.xml | 64 +- xml/System.Security.Cryptography/CngKey.xml | 38 +- .../CngKeyCreationParameters.xml | 6 +- .../CngKeyHandleOpenOptions.xml | 10 +- .../CngProperty.xml | 88 +- .../CngPropertyOptions.xml | 14 +- .../CryptoAPITransform.xml | 10 +- .../CryptoConfig.xml | 8 +- .../CryptoStream.xml | 40 +- ...CryptographicAttributeObjectCollection.xml | 2 +- .../CryptographicException.xml | 22 +- ...ptographicUnexpectedOperationException.xml | 16 +- .../CspParameters.xml | 8 +- xml/System.Security.Cryptography/DES.xml | 8 +- .../DESCryptoServiceProvider.xml | 22 +- xml/System.Security.Cryptography/DSACng.xml | 6 +- .../DSACryptoServiceProvider.xml | 18 +- .../DSAOpenSsl.xml | 6 +- .../DSASignatureFormatter.xml | 2 +- .../DataProtectionScope.xml | 4 +- .../DataProtector.xml | 124 +-- .../DpapiDataProtector.xml | 8 +- xml/System.Security.Cryptography/ECCurve.xml | 2 +- .../ECDiffieHellman.xml | 764 +++++++++--------- .../ECDiffieHellmanCng.xml | 24 +- .../ECDiffieHellmanKeyDerivationFunction.xml | 2 +- .../ECDiffieHellmanOpenSsl.xml | 8 +- .../ECDiffieHellmanPublicKey.xml | 2 +- xml/System.Security.Cryptography/ECDsa.xml | 2 +- xml/System.Security.Cryptography/ECDsaCng.xml | 18 +- .../ECDsaOpenSsl.xml | 8 +- .../ECParameters.xml | 4 +- .../FromBase64Transform.xml | 2 +- .../FromBase64TransformMode.xml | 10 +- xml/System.Security.Cryptography/HMAC.xml | 4 +- .../HMACSHA384.xml | 2 +- .../HMACSHA512.xml | 2 +- .../HashAlgorithm.xml | 20 +- .../HashAlgorithmName.xml | 6 +- .../ICryptoTransform.xml | 30 +- .../ICspAsymmetricAlgorithm.xml | 40 +- xml/System.Security.Cryptography/KeySizes.xml | 2 +- .../KeyedHashAlgorithm.xml | 2 +- xml/System.Security.Cryptography/MD5.xml | 4 +- .../MD5CryptoServiceProvider.xml | 22 +- .../ManifestSignatureInformation.xml | 10 +- ...ManifestSignatureInformationCollection.xml | 14 +- .../MaskGenerationMethod.xml | 4 +- .../MemoryProtectionScope.xml | 24 +- .../OidCollection.xml | 2 +- .../OidEnumerator.xml | 14 +- xml/System.Security.Cryptography/OidGroup.xml | 10 +- .../PKCS1MaskGenerationMethod.xml | 2 +- .../ProtectedData.xml | 8 +- .../ProtectedMemory.xml | 100 +-- .../RC2CryptoServiceProvider.xml | 6 +- .../RNGCryptoServiceProvider.xml | 8 +- xml/System.Security.Cryptography/RSA.xml | 16 +- xml/System.Security.Cryptography/RSACng.xml | 12 +- .../RSACryptoServiceProvider.xml | 38 +- .../RSAEncryptionPadding.xml | 10 +- .../RSAOAEPKeyExchangeDeformatter.xml | 6 +- .../RSAOAEPKeyExchangeFormatter.xml | 8 +- .../RSAOpenSsl.xml | 8 +- .../RSAPKCS1KeyExchangeDeformatter.xml | 76 +- .../RSAPKCS1KeyExchangeFormatter.xml | 6 +- .../RSAPKCS1SignatureDeformatter.xml | 108 +-- .../RSAPKCS1SignatureFormatter.xml | 100 +-- .../RSASignaturePadding.xml | 6 +- .../Rfc2898DeriveBytes.xml | 8 +- .../RijndaelManaged.xml | 12 +- .../RijndaelManagedTransform.xml | 98 +-- .../SHA1CryptoServiceProvider.xml | 2 +- .../StrongNameSignatureInformation.xml | 2 +- .../SymmetricAlgorithm.xml | 32 +- .../ToBase64Transform.xml | 12 +- .../TripleDES.xml | 4 +- .../TripleDESCng.xml | 8 +- .../TripleDESCryptoServiceProvider.xml | 14 +- .../DataProtectionPermission.xml | 6 +- .../DataProtectionPermissionAttribute.xml | 66 +- .../EnvironmentPermission.xml | 6 +- .../EnvironmentPermissionAccess.xml | 12 +- .../FileDialogPermission.xml | 2 +- .../FileIOPermission.xml | 14 +- .../FileIOPermissionAccess.xml | 8 +- .../FileIOPermissionAttribute.xml | 6 +- .../GacIdentityPermission.xml | 12 +- .../HostProtectionAttribute.xml | 2 +- .../IsolatedStorageFilePermission.xml | 76 +- .../KeyContainerPermission.xml | 6 +- .../KeyContainerPermissionAccessEntry.xml | 2 +- ...ntainerPermissionAccessEntryCollection.xml | 8 +- ...ntainerPermissionAccessEntryEnumerator.xml | 20 +- .../PermissionSetAttribute.xml | 4 +- .../PrincipalPermission.xml | 10 +- .../PrincipalPermissionAttribute.xml | 4 +- .../PublisherIdentityPermission.xml | 8 +- .../PublisherIdentityPermissionAttribute.xml | 76 +- .../ReflectionPermission.xml | 2 +- .../RegistryPermission.xml | 8 +- .../RegistryPermissionAccess.xml | 12 +- .../RegistryPermissionAttribute.xml | 112 +-- .../ResourcePermissionBase.xml | 4 +- .../ResourcePermissionBaseEntry.xml | 2 +- .../SecurityPermission.xml | 2 +- .../SiteIdentityPermission.xml | 166 ++-- .../StorePermission.xml | 6 +- .../StorePermissionAttribute.xml | 112 +-- .../StrongNameIdentityPermission.xml | 4 +- .../TypeDescriptorPermission.xml | 24 +- .../UIPermission.xml | 4 +- .../UIPermissionWindow.xml | 6 +- .../UrlIdentityPermission.xml | 12 +- .../WebBrowserPermissionAttribute.xml | 4 +- .../ZoneIdentityPermission.xml | 2 +- .../AllMembershipCondition.xml | 20 +- .../ApplicationSecurityManager.xml | 6 +- .../ApplicationTrust.xml | 8 +- .../ApplicationTrustCollection.xml | 16 +- .../ApplicationTrustEnumerator.xml | 20 +- .../ApplicationVersionMatch.xml | 10 +- .../CodeConnectAccess.xml | 18 +- xml/System.Security.Policy/CodeGroup.xml | 228 +++--- xml/System.Security.Policy/Evidence.xml | 18 +- xml/System.Security.Policy/FileCodeGroup.xml | 6 +- .../FirstMatchCodeGroup.xml | 8 +- xml/System.Security.Policy/GacInstalled.xml | 4 +- .../GacMembershipCondition.xml | 264 +++--- xml/System.Security.Policy/Hash.xml | 4 +- .../IApplicationTrustManager.xml | 6 +- .../IIdentityPermissionFactory.xml | 8 +- xml/System.Security.Policy/NetCodeGroup.xml | 10 +- .../PolicyException.xml | 12 +- xml/System.Security.Policy/PolicyLevel.xml | 18 +- .../PolicyStatement.xml | 4 +- xml/System.Security.Policy/Publisher.xml | 26 +- xml/System.Security.Policy/Site.xml | 28 +- .../SiteMembershipCondition.xml | 42 +- .../StrongNameMembershipCondition.xml | 2 +- .../TrustManagerContext.xml | 14 +- xml/System.Security.Policy/UnionCodeGroup.xml | 76 +- xml/System.Security.Policy/Url.xml | 16 +- xml/System.Security.Policy/Zone.xml | 30 +- .../GenericIdentity.xml | 4 +- .../GenericPrincipal.xml | 4 +- xml/System.Security.Principal/IIdentity.xml | 44 +- .../IdentityReference.xml | 8 +- .../PrincipalPolicy.xml | 14 +- .../WindowsAccountType.xml | 24 +- .../WindowsBuiltInRole.xml | 28 +- .../WindowsIdentity.xml | 48 +- .../WindowsImpersonationContext.xml | 8 +- .../WindowsPrincipal.xml | 40 +- .../ContentGrant.xml | 2 +- .../ContentUser.xml | 12 +- .../CryptoProvider.xml | 34 +- .../LocalizedNameDescriptionPair.xml | 4 +- .../PublishLicense.xml | 12 +- .../RightsManagementException.xml | 8 +- .../RightsManagementFailureCode.xml | 14 +- .../SecureEnvironment.xml | 14 +- .../UnsignedPublishLicense.xml | 10 +- .../UseLicense.xml | 106 +-- .../UserActivationMode.xml | 24 +- xml/System.Security/CodeAccessPermission.xml | 44 +- .../HostProtectionException.xml | 6 +- xml/System.Security/HostSecurityManager.xml | 22 +- xml/System.Security/IPermission.xml | 16 +- xml/System.Security/ISecurityEncodable.xml | 10 +- .../ISecurityPolicyEncodable.xml | 34 +- xml/System.Security/IStackWalk.xml | 88 +- xml/System.Security/ManifestKinds.xml | 2 +- xml/System.Security/NamedPermissionSet.xml | 70 +- .../PartialTrustVisibilityLevel.xml | 2 +- xml/System.Security/PermissionSet.xml | 36 +- xml/System.Security/ReadOnlyPermissionSet.xml | 42 +- xml/System.Security/SecureString.xml | 30 +- xml/System.Security/SecureStringMarshal.xml | 30 +- xml/System.Security/SecurityContext.xml | 14 +- .../SecurityCriticalAttribute.xml | 2 +- xml/System.Security/SecurityElement.xml | 44 +- xml/System.Security/SecurityException.xml | 118 +-- xml/System.Security/SecurityManager.xml | 18 +- xml/System.Security/SecurityState.xml | 190 ++--- xml/System.Security/VerificationException.xml | 4 +- xml/System.Security/XmlSyntaxException.xml | 22 +- .../ServiceInstallerDialog.xml | 90 +-- xml/System.ServiceProcess/ServiceBase.xml | 126 +-- .../ServiceController.xml | 60 +- .../ServiceInstaller.xml | 68 +- .../ServiceProcessDescriptionAttribute.xml | 2 +- .../ServiceProcessInstaller.xml | 46 +- .../SessionChangeDescription.xml | 20 +- .../SessionChangeReason.xml | 14 +- .../TimeoutException.xml | 2 +- .../SpeechAudioFormatInfo.xml | 2 +- .../SrgsDocument.xml | 14 +- .../SrgsGrammarCompiler.xml | 84 +- .../SrgsItem.xml | 14 +- .../SrgsNameValueTag.xml | 10 +- .../SrgsOneOf.xml | 6 +- .../SrgsPhoneticAlphabet.xml | 14 +- .../SrgsRule.xml | 12 +- .../SrgsRuleRef.xml | 50 +- .../SrgsRulesCollection.xml | 2 +- .../SrgsSemanticInterpretationTag.xml | 2 +- .../SrgsText.xml | 2 +- .../SrgsToken.xml | 14 +- .../AudioSignalProblemOccurredEventArgs.xml | 8 +- xml/System.Speech.Recognition/AudioState.xml | 70 +- xml/System.Speech.Recognition/Choices.xml | 18 +- .../DictationGrammar.xml | 10 +- .../EmulateRecognizeCompletedEventArgs.xml | 2 +- xml/System.Speech.Recognition/Grammar.xml | 50 +- .../GrammarBuilder.xml | 92 +-- .../RecognitionResult.xml | 18 +- .../RecognizeCompletedEventArgs.xml | 14 +- .../RecognizeMode.xml | 96 +-- .../RecognizedAudio.xml | 16 +- .../RecognizedPhrase.xml | 4 +- .../RecognizedWordUnit.xml | 28 +- .../RecognizerInfo.xml | 8 +- .../RecognizerState.xml | 2 +- .../RecognizerUpdateReachedEventArgs.xml | 472 +++++------ .../ReplacementText.xml | 6 +- .../SemanticResultKey.xml | 12 +- .../SemanticResultValue.xml | 14 +- .../SemanticValue.xml | 26 +- .../SpeechRecognitionEngine.xml | 244 +++--- .../SpeechRecognizer.xml | 70 +- xml/System.Speech.Recognition/SpeechUI.xml | 184 ++--- .../StateChangedEventArgs.xml | 4 +- .../SubsetMatchingMode.xml | 2 +- .../ContourPoint.xml | 6 +- .../EmphasisBreak.xml | 4 +- .../EmphasisWord.xml | 4 +- .../EventParameterType.xml | 6 +- .../FragmentState.xml | 28 +- .../ProsodyNumber.xml | 4 +- .../SpeechEventInfo.xml | 40 +- .../TextFragment.xml | 24 +- .../TtsEngineAction.xml | 4 +- .../TtsEngineSsml.xml | 20 +- .../TtsEventId.xml | 8 +- .../BookmarkReachedEventArgs.xml | 134 +-- xml/System.Speech.Synthesis/FilePrompt.xml | 110 +-- .../InstalledVoice.xml | 2 +- xml/System.Speech.Synthesis/Prompt.xml | 196 ++--- xml/System.Speech.Synthesis/PromptBuilder.xml | 96 +-- .../PromptEmphasis.xml | 2 +- xml/System.Speech.Synthesis/PromptRate.xml | 2 +- xml/System.Speech.Synthesis/PromptStyle.xml | 226 +++--- xml/System.Speech.Synthesis/PromptVolume.xml | 2 +- xml/System.Speech.Synthesis/SayAs.xml | 10 +- .../SpeakCompletedEventArgs.xml | 10 +- .../SpeakProgressEventArgs.xml | 18 +- .../SpeakStartedEventArgs.xml | 14 +- .../SpeechSynthesizer.xml | 162 ++-- .../StateChangedEventArgs.xml | 2 +- .../SynthesisTextFormat.xml | 12 +- .../SynthesizerState.xml | 4 +- xml/System.Speech.Synthesis/VoiceAge.xml | 2 +- .../VoiceChangeEventArgs.xml | 4 +- xml/System.Speech.Synthesis/VoiceGender.xml | 2 +- xml/System.Speech.Synthesis/VoiceInfo.xml | 4 +- 364 files changed, 5714 insertions(+), 5714 deletions(-) diff --git a/xml/System.Security.AccessControl/AceEnumerator.xml b/xml/System.Security.AccessControl/AceEnumerator.xml index 6f4b48677f3..1e971c98360 100644 --- a/xml/System.Security.AccessControl/AceEnumerator.xml +++ b/xml/System.Security.AccessControl/AceEnumerator.xml @@ -115,15 +115,15 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - method, an enumerator is positioned before the first element of the collection, and the first call to the method moves the enumerator over the first element of the collection. - - After the end of the collection is passed, subsequent calls to return `false` until is called. - - An enumerator remains valid as long as the collection remains unchanged. If changes, such as adding, modifying, or deleting elements, are made to the collection, the enumerator is irrecoverably invalidated and the next call to or throws an . - + method, an enumerator is positioned before the first element of the collection, and the first call to the method moves the enumerator over the first element of the collection. + + After the end of the collection is passed, subsequent calls to return `false` until is called. + + An enumerator remains valid as long as the collection remains unchanged. If changes, such as adding, modifying, or deleting elements, are made to the collection, the enumerator is irrecoverably invalidated and the next call to or throws an . + ]]> The collection was modified after the enumerator was created. @@ -165,11 +165,11 @@ Sets the enumerator to its initial position, which is before the first element in the collection. - method or the method throws an - + method or the method throws an + ]]> The collection was modified after the enumerator was created. @@ -214,17 +214,17 @@ Gets the current element in the collection. The current element in the collection. - method, you must call the method to advance the enumerator to the first element of the collection before reading the value of ; otherwise, is undefined. - - also throws an exception if the last call to returned `false`, which indicates the end of the collection. - - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - - An enumerator remains valid as long as the collection remains unchanged. If changes, such as adding, modifying, or deleting elements, are made to the collection, the enumerator is irrecoverably invalidated, and the next call to or throws an . If the collection is modified between and , returns the element that it is set to, even if the enumerator is already invalidated. - + method, you must call the method to advance the enumerator to the first element of the collection before reading the value of ; otherwise, is undefined. + + also throws an exception if the last call to returned `false`, which indicates the end of the collection. + + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + + An enumerator remains valid as long as the collection remains unchanged. If changes, such as adding, modifying, or deleting elements, are made to the collection, the enumerator is irrecoverably invalidated, and the next call to or throws an . If the collection is modified between and , returns the element that it is set to, even if the enumerator is already invalidated. + ]]> The collection was modified after the enumerator was created. diff --git a/xml/System.Security.AccessControl/CommonAcl.xml b/xml/System.Security.AccessControl/CommonAcl.xml index fab2f93ecde..fcae287b277 100644 --- a/xml/System.Security.AccessControl/CommonAcl.xml +++ b/xml/System.Security.AccessControl/CommonAcl.xml @@ -73,7 +73,7 @@ - Unrecognized and custom ACEs are disallowed in both DACLs and SACLs. -- Within contiguous ranges (explicit AccessDenied and AccessAllowed ACEs on DACLs, all explicit ACEs on SACLs), the ACEs are sorted by using the methods of the objects associated with the ACEs. +- Within contiguous ranges (explicit AccessDenied and AccessAllowed ACEs on DACLs, all explicit ACEs on SACLs), the ACEs are sorted by using the methods of the objects associated with the ACEs. Adjacent ACEs are combined, if appropriate. This reduces the size of the ACL without affecting the access control semantics it grants. diff --git a/xml/System.Security.AccessControl/CommonSecurityDescriptor.xml b/xml/System.Security.AccessControl/CommonSecurityDescriptor.xml index fde5a27a26d..b1808149042 100644 --- a/xml/System.Security.AccessControl/CommonSecurityDescriptor.xml +++ b/xml/System.Security.AccessControl/CommonSecurityDescriptor.xml @@ -86,13 +86,13 @@ The object from which to create the new object. Initializes a new instance of the class from the specified object. - object is created contains `null` for its discretionary access control list (DACL), a single access control entry (ACE) that allows everyone full access (AEFA) is added to the DACL. If an application modifies the DACL of a security descriptor to which an AEFA ACE has been added, the AEFA ACE is persisted with the DACL when that DACL is persisted. - - This can result in an application unintentionally allowing access to principals. Because of this, an application should check for the existence of an AEFA ACE and remove it before modifying any security descriptor. - + object is created contains `null` for its discretionary access control list (DACL), a single access control entry (ACE) that allows everyone full access (AEFA) is added to the DACL. If an application modifies the DACL of a security descriptor to which an AEFA ACE has been added, the AEFA ACE is persisted with the DACL when that DACL is persisted. + + This can result in an application unintentionally allowing access to principals. Because of this, an application should check for the existence of an AEFA ACE and remove it before modifying any security descriptor. + ]]> @@ -142,13 +142,13 @@ The SDDL string from which to create the new object. Initializes a new instance of the class from the specified Security Descriptor Definition Language (SDDL) string. - object is created contains `null` for its discretionary access control list (DACL), a single access control entry (ACE) that allows everyone full access (AEFA) is added to the DACL. If an application modifies the DACL of a security descriptor to which an AEFA ACE has been added, the AEFA ACE is persisted with the DACL when that DACL is persisted. - - This can result in an application unintentionally allowing access to principals. Because of this, an application should check for the existence of an AEFA ACE and remove it before modifying any security descriptor. - + object is created contains `null` for its discretionary access control list (DACL), a single access control entry (ACE) that allows everyone full access (AEFA) is added to the DACL. If an application modifies the DACL of a security descriptor to which an AEFA ACE has been added, the AEFA ACE is persisted with the DACL when that DACL is persisted. + + This can result in an application unintentionally allowing access to principals. Because of this, an application should check for the existence of an AEFA ACE and remove it before modifying any security descriptor. + ]]> @@ -194,13 +194,13 @@ The offset in the array at which to begin copying. Initializes a new instance of the class from the specified array of byte values. - object is created contains `null` for its discretionary access control list (DACL),a single access control entry (ACE) that allows everyone full access (AEFA) is added to the DACL. If an application modifies the DACL of a security descriptor to which an AEFA ACE has been added, the AEFA ACE is persisted with the DACL when that DACL is persisted. - - This can result in an application unintentionally allowing access to principals. Because of this, an application should check for the existence of an AEFA ACE and remove it before modifying any security descriptor. - + object is created contains `null` for its discretionary access control list (DACL),a single access control entry (ACE) that allows everyone full access (AEFA) is added to the DACL. If an application modifies the DACL of a security descriptor to which an AEFA ACE has been added, the AEFA ACE is persisted with the DACL when that DACL is persisted. + + This can result in an application unintentionally allowing access to principals. Because of this, an application should check for the existence of an AEFA ACE and remove it before modifying any security descriptor. + ]]> @@ -253,13 +253,13 @@ The Discretionary Access Control List (DACL) for the new object. Initializes a new instance of the class from the specified information. - object is created contains `null` for its discretionary access control list (DACL), a single access control entry (ACE) that allows everyone full access (AEFA) is added to the DACL. If an application modifies the DACL of a security descriptor to which an AEFA ACE has been added, the AEFA ACE is persisted with the DACL when that DACL is persisted. - - This can result in an application unintentionally allowing access to principals. Because of this, an application should check for the existence of an AEFA ACE and remove it before modifying any security descriptor. - + object is created contains `null` for its discretionary access control list (DACL), a single access control entry (ACE) that allows everyone full access (AEFA) is added to the DACL. If an application modifies the DACL of a security descriptor to which an AEFA ACE has been added, the AEFA ACE is persisted with the DACL when that DACL is persisted. + + This can result in an application unintentionally allowing access to principals. Because of this, an application should check for the existence of an AEFA ACE and remove it before modifying any security descriptor. + ]]> @@ -301,11 +301,11 @@ The number of Access Control Entries (ACEs) this object can contain. This number is to be used only as a hint. Sets the property for this instance and sets the flag. - uses the and properties for this . - + uses the and properties for this . + ]]> @@ -347,11 +347,11 @@ The number of Access Control Entries (ACEs) this object can contain. This number should only be used as a hint. Sets the property for this instance and sets the flag. - uses the and properties for this . - + uses the and properties for this . + ]]> @@ -425,13 +425,13 @@ Gets or sets the discretionary access control list (DACL) for this object. The DACL contains access rules. The DACL for this object. - @@ -688,11 +688,11 @@ The security identifier for which to remove access rules. Removes all access rules for the specified security identifier from the Discretionary Access Control List (DACL) associated with this object. - diff --git a/xml/System.Security.AccessControl/DirectorySecurity.xml b/xml/System.Security.AccessControl/DirectorySecurity.xml index 0a5ea847dca..890dcda6dac 100644 --- a/xml/System.Security.AccessControl/DirectorySecurity.xml +++ b/xml/System.Security.AccessControl/DirectorySecurity.xml @@ -53,10 +53,10 @@ |Task|Methods| |----------|-------------| -|Add rules|

| -|Remove rules|

| -|Retrieve the access control to a directory|

| -|Persist the access control to a directory|

| +|Add rules|

| +|Remove rules|

| +|Retrieve the access control to a directory|

| +|Persist the access control to a directory|

| ## Examples The following code example uses the class to add and then remove an access control list (ACL) entry from a directory. You must supply a valid user or group account to run this example. @@ -182,14 +182,14 @@ The specified path, file name, or both exceed the system-defined maximum length. The current system account does not have administrative privileges. The directory could not be found. - The parameter specified a directory that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - + The parameter specified a directory that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + The caller does not have the required permission. diff --git a/xml/System.Security.AccessControl/EventWaitHandleAccessRule.xml b/xml/System.Security.AccessControl/EventWaitHandleAccessRule.xml index bce9568bf4a..2748bd0ea1e 100644 --- a/xml/System.Security.AccessControl/EventWaitHandleAccessRule.xml +++ b/xml/System.Security.AccessControl/EventWaitHandleAccessRule.xml @@ -57,7 +57,7 @@ > [!NOTE] > Windows access control security is meaningful only for named system events. If an object represents a local event, access control is irrelevant. - To get a list of the rules currently applied to a named event, use the method to get an object, and then use its method to obtain a collection of objects. + To get a list of the rules currently applied to a named event, use the method to get an object, and then use its method to obtain a collection of objects. objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all access rules for an event, the set contains the minimum number of rules currently required to express all the access control entries. @@ -66,10 +66,10 @@ Use objects to specify the access rights to allow or deny to a user or group. An object always represents either allowed access or denied access, never both. - To apply a rule to a named system event, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. + To apply a rule to a named system event, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. > [!IMPORTANT] -> Changes you make to an object do not affect the access levels of the named event until you call the method to assign the altered security object to the named event. +> Changes you make to an object do not affect the access levels of the named event until you call the method to assign the altered security object to the named event. objects are immutable. Security for an event is modified using the methods of the class to add or remove rules; as you do this, the underlying access control entries are modified. @@ -77,7 +77,7 @@ The following code example demonstrates the creation and use of objects. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.vb" id="Snippet1"::: @@ -137,7 +137,7 @@ (by calling the , or method), a user must have access. To signal an event by calling the method, or to reset it to the unsignaled state by calling the method, a user must have access. To signal an object and then wait on it by calling the method, a user must have and access. + To wait on an (by calling the , or method), a user must have access. To signal an event by calling the method, or to reset it to the unsignaled state by calling the method, a user must have access. To signal an object and then wait on it by calling the method, a user must have and access. ]]> @@ -198,9 +198,9 @@ (by calling the , or method), a user must have access. To signal an event by calling the method, or to reset it to the unsignaled state by calling the method, a user must have access. To signal an object and then wait on it by calling the method, a user must have and access. + To wait on an (by calling the , or method), a user must have access. To signal an event by calling the method, or to reset it to the unsignaled state by calling the method, a user must have access. To signal an object and then wait on it by calling the method, a user must have and access. - This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. + This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. @@ -208,7 +208,7 @@ The following code example demonstrates the use of this constructor to create objects. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.vb" id="Snippet1"::: @@ -280,7 +280,7 @@ The following code example demonstrates the use of the property to display the rights in the set of rules contained in an object. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.vb" id="Snippet1"::: diff --git a/xml/System.Security.AccessControl/EventWaitHandleAuditRule.xml b/xml/System.Security.AccessControl/EventWaitHandleAuditRule.xml index 202f78244b3..5a0f883ca2a 100644 --- a/xml/System.Security.AccessControl/EventWaitHandleAuditRule.xml +++ b/xml/System.Security.AccessControl/EventWaitHandleAuditRule.xml @@ -41,32 +41,32 @@ Represents a set of access rights to be audited for a user or group. This class cannot be inherited. - [!NOTE] > This type is only supported on Windows. - The class is one of a set of classes that the .NET Framework provides for managing Windows access control security on named system events. For an overview of these classes and their relationship to the underlying Windows access control structures, see . - + The class is one of a set of classes that the .NET Framework provides for managing Windows access control security on named system events. For an overview of these classes and their relationship to the underlying Windows access control structures, see . + > [!NOTE] -> Windows access control security is meaningful only for named system events. If an object represents a local event, access control is irrelevant. - - To get a list of the audit rules currently applied to a named event, use the method to get an object, and then use its method to obtain a collection of objects. - - objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all audit rules for an event, the set contains the minimum number of rules currently required to express all the access control entries. - +> Windows access control security is meaningful only for named system events. If an object represents a local event, access control is irrelevant. + + To get a list of the audit rules currently applied to a named event, use the method to get an object, and then use its method to obtain a collection of objects. + + objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all audit rules for an event, the set contains the minimum number of rules currently required to express all the access control entries. + > [!NOTE] -> The underlying access control entries change as you apply and remove rules. The information in rules is merged if possible, to maintain the smallest number of access control entries. Thus, when you read the current list of rules, it might not look exactly like the list of all the rules you have added. - - Use objects to specify access rights to be audited for a user or group. To apply a rule to a named system event, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. - +> The underlying access control entries change as you apply and remove rules. The information in rules is merged if possible, to maintain the smallest number of access control entries. Thus, when you read the current list of rules, it might not look exactly like the list of all the rules you have added. + + Use objects to specify access rights to be audited for a user or group. To apply a rule to a named system event, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. + > [!IMPORTANT] -> Changes you make to an object do not affect the access levels of the named event until you call the method to assign the altered security object to the named event. - +> Changes you make to an object do not affect the access levels of the named event until you call the method to assign the altered security object to the named event. + objects are immutable. Security for an event is modified using the methods of the class to add or remove rules; as you do this, the underlying access control entries are modified. - + ]]> @@ -109,24 +109,24 @@ A bitwise combination of values specifying whether to audit success, failure, or both. Initializes a new instance of the class, specifying the user or group to audit, the rights to audit, and whether to audit success, failure, or both. - object from a string representing a user or group name, use the constructor. - + object from a string representing a user or group name, use the constructor. + ]]> - specifies an invalid value. - - -or- - + specifies an invalid value. + + -or- + specifies an invalid value. - is . - - -or- - + is . + + -or- + is zero. is neither of type nor of a type such as that can be converted to type . @@ -166,11 +166,11 @@ Gets the access rights affected by the audit rule. A bitwise combination of values that indicates the rights affected by the audit rule. - objects are immutable. You can create a new audit rule representing a different user, different rights, or a different combination of flags, but you cannot modify an existing audit rule. - + objects are immutable. You can create a new audit rule representing a different user, different rights, or a different combination of flags, but you cannot modify an existing audit rule. + ]]> diff --git a/xml/System.Security.AccessControl/EventWaitHandleRights.xml b/xml/System.Security.AccessControl/EventWaitHandleRights.xml index f762e214623..4a2bf882de9 100644 --- a/xml/System.Security.AccessControl/EventWaitHandleRights.xml +++ b/xml/System.Security.AccessControl/EventWaitHandleRights.xml @@ -44,24 +44,24 @@ Specifies the access control rights that can be applied to named system event objects. - [!NOTE] > This type is only supported on Windows. - Use the enumeration to specify access control rights when you create objects. To apply access rights to a named system event, first add objects to an object, then attach the object to the named system event using the constructor or the method. - -## Examples - The following code example demonstrates the use of values when creating and using objects. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. - + Use the enumeration to specify access control rights when you create objects. To apply access rights to a named system event, first add objects to an object, then attach the object to the named system event using the constructor or the method. + +## Examples + The following code example demonstrates the use of values when creating and using objects. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. + > [!NOTE] -> This example does not attach the security object to an object; see , method, and . - +> This example does not attach the security object to an object; see , method, and . + :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Security.AccessControl/EventWaitHandleSecurity.xml b/xml/System.Security.AccessControl/EventWaitHandleSecurity.xml index fcc1e12b265..494ec3dabaa 100644 --- a/xml/System.Security.AccessControl/EventWaitHandleSecurity.xml +++ b/xml/System.Security.AccessControl/EventWaitHandleSecurity.xml @@ -79,14 +79,14 @@ - Adding or removing access control entries in ways that do not maintain the canonical ordering. - To modify Windows access control security for a named wait handle, use the method to get the object. Modify the security object by adding and removing rules, and then use the method to reattach it. + To modify Windows access control security for a named wait handle, use the method to get the object. Modify the security object by adding and removing rules, and then use the method to reattach it. > [!IMPORTANT] -> Changes you make to an object do not affect the access levels of the named wait handle until you call the method to assign the altered security object to the named wait handle. +> Changes you make to an object do not affect the access levels of the named wait handle until you call the method to assign the altered security object to the named wait handle. - To copy access control security from one wait handle to another, use the method to get an object representing the access and audit rules for the first wait handle, and then use the method, or a constructor that accepts an object, to assign those rules to the second wait handle. + To copy access control security from one wait handle to another, use the method to get an object representing the access and audit rules for the first wait handle, and then use the method, or a constructor that accepts an object, to assign those rules to the second wait handle. - Users with an investment in the security descriptor definition language (SDDL) can use the method to set access rules for a named wait handle, and the method to obtain a string that represents the access rules in SDDL format. This is not recommended for new development. + Users with an investment in the security descriptor definition language (SDDL) can use the method to set access rules for a named wait handle, and the method to obtain a string that represents the access rules in SDDL format. This is not recommended for new development. @@ -94,7 +94,7 @@ The following code example demonstrates the separation between rules and rules, and shows the combination of rights in compatible rules. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.vb" id="Snippet1"::: @@ -343,7 +343,7 @@ method searches for rules with the same user or group and the same as `rule`. If none are found, `rule` is added. If a matching rule is found, the rights in `rule` are merged with the existing rule. + The method searches for rules with the same user or group and the same as `rule`. If none are found, `rule` is added. If a matching rule is found, the rights in `rule` are merged with the existing rule. @@ -351,7 +351,7 @@ The following code example demonstrates the separation between rules and rules, and shows the combination of rights in compatible rules. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.vb" id="Snippet1"::: @@ -402,7 +402,7 @@ method searches for rules with the same user or group as `rule`. If none are found, `rule` is added. If a matching rule is found, the flags in `rule` are merged into the existing rule. + The method searches for rules with the same user or group as `rule`. If none are found, `rule` is added. If a matching rule is found, the flags in `rule` are merged into the existing rule. ]]> @@ -568,17 +568,17 @@ The current is searched for a rule that has the same user and the same value as `rule`. If no such rule is found, no action is taken, and the method returns `false`. If matching rules are found, their inheritance and compatibility flags are checked for compatibility with the flags specified in `rule`. If no compatible rule is found, no action is taken, and the method returns `false`. If a rule with compatible flags is found, the rights specified in `rule` are removed from the compatible rule, and the method returns `true`. If `rule` specifies rights not contained in the compatible rule, no action is taken with respect to those rights. If all rights are removed from the compatible rule, the entire rule is removed from the current object. > [!IMPORTANT] -> Although you can specify inheritance and propagation flags for event access rules, by creating them with the method, this is not recommended. Inheritance and propagation have no meaning for named events, and they make the maintenance of access rules more complicated. +> Although you can specify inheritance and propagation flags for event access rules, by creating them with the method, this is not recommended. Inheritance and propagation have no meaning for named events, and they make the maintenance of access rules more complicated. ## Examples - The following code example demonstrates the use of the method to remove rights from an rule in an object. It also shows that other rights in `rule` are ignored. + The following code example demonstrates the use of the method to remove rights from an rule in an object. It also shows that other rights in `rule` are ignored. - The example creates an object and adds rules that allow and deny various rights for the current user. The rights allowed include , , and . The example then creates a new rule for the current user, including and rights, and uses that rule with the method to remove from the rule in the object. The right in `rule` is ignored. + The example creates an object and adds rules that allow and deny various rights for the current user. The rights allowed include , , and . The example then creates a new rule for the current user, including and rights, and uses that rule with the method to remove from the rule in the object. The right in `rule` is ignored. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/EventWaitHandleSecurity/RemoveAccessRule/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/EventWaitHandleSecurity/RemoveAccessRule/source.vb" id="Snippet1"::: @@ -634,12 +634,12 @@ ## Examples - The following code example shows that the method removes all rules that match user and , ignoring rights. + The following code example shows that the method removes all rules that match user and , ignoring rights. The example creates an object, adds rules that allow and deny various rights for the current user, and then merges additional rights into the rule. The example then creates a new rule that allows the current user to take ownership, and uses that rule to remove the rule from the object. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/EventWaitHandleSecurity/RemoveAccessRuleAll/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/EventWaitHandleSecurity/RemoveAccessRuleAll/source.vb" id="Snippet1"::: @@ -693,17 +693,17 @@ The rule is removed only if it exactly matches `rule` in all details, including flags. Other rules with the same user and are not affected. > [!IMPORTANT] -> A rule represents one or more underlying access control entries (ACE), and these entries are split or combined as necessary when you modify the access security rules for a user. Thus, a rule might no longer exist in the specific form it had when it was added, and in that case the method cannot remove it. +> A rule represents one or more underlying access control entries (ACE), and these entries are split or combined as necessary when you modify the access security rules for a user. Thus, a rule might no longer exist in the specific form it had when it was added, and in that case the method cannot remove it. ## Examples - The following code example shows that the method requires an exact match in order to remove a rule, and that rules to allow and deny rights are independent of each other. + The following code example shows that the method requires an exact match in order to remove a rule, and that rules to allow and deny rights are independent of each other. - The example creates an object, adds rules that allow and deny various rights for the current user, and then merges additional rights into the access rule. The example then passes the original rule to the method, and displays the results, showing that nothing is deleted. The example then constructs a rule that matches the rule in the object, and successfully uses the method to remove the rule. + The example creates an object, adds rules that allow and deny various rights for the current user, and then merges additional rights into the access rule. The example then passes the original rule to the method, and displays the results, showing that nothing is deleted. The example then constructs a rule that matches the rule in the object, and successfully uses the method to remove the rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/EventWaitHandleSecurity/RemoveAccessRuleSpecific/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/EventWaitHandleSecurity/RemoveAccessRuleSpecific/source.vb" id="Snippet1"::: @@ -759,7 +759,7 @@ The current is searched for an audit rule that has the same user as `rule`. If no such rule is found, no action is taken, and the method returns `false`. If matching rules are found, their inheritance and compatibility flags are checked for compatibility with the flags specified in `rule`. If no compatible rule is found, no action is taken, and the method returns `false`. If a rule with compatible flags is found, the rights specified in `rule` are removed from the compatible rule, and the method returns `true`. If `rule` specifies rights not contained in the compatible rule, no action is taken with respect to those rights. If all rights are removed from the compatible rule, the entire rule is removed from the current object. > [!IMPORTANT] -> Although you can specify inheritance and propagation flags for event audit rules, by creating them with the method, this is not recommended. Inheritance and propagation have no meaning for named events, and they make the maintenance of audit rules more complicated. +> Although you can specify inheritance and propagation flags for event audit rules, by creating them with the method, this is not recommended. Inheritance and propagation have no meaning for named events, and they make the maintenance of audit rules more complicated. ]]> @@ -858,7 +858,7 @@ The rule is removed only if it exactly matches `rule` in all details, including flags. Other audit rules for the same user are not affected. > [!IMPORTANT] -> A rule represents one or more underlying access control entries (ACE), and these entries are split or combined as necessary when you modify the audit security rules for a user. Thus, a rule might no longer exist in the specific form it had when it was added, and in that case the method cannot remove it. +> A rule represents one or more underlying access control entries (ACE), and these entries are split or combined as necessary when you modify the audit security rules for a user. Thus, a rule might no longer exist in the specific form it had when it was added, and in that case the method cannot remove it. ]]> @@ -911,12 +911,12 @@ ## Examples - The following code example shows how the method replaces all rules for the matching user with the rule specified for the match. + The following code example shows how the method replaces all rules for the matching user with the rule specified for the match. - The example creates an object and adds rules that allow and deny various rights for the current user. The example then creates a new rule that allows the current user full control, and uses the method to replace both of the existing rules with the new rule. + The example creates an object and adds rules that allow and deny various rights for the current user. The example then creates a new rule that allows the current user full control, and uses the method to replace both of the existing rules with the new rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/EventWaitHandleSecurity/ResetAccessRule/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/EventWaitHandleSecurity/ResetAccessRule/source.vb" id="Snippet1"::: @@ -974,12 +974,12 @@ ## Examples - The following code example shows how the method removes all rules that match both the user and the of `rule`, replacing them with `rule`. + The following code example shows how the method removes all rules that match both the user and the of `rule`, replacing them with `rule`. - The example creates an object and adds rules that allow and deny various rights for the current user. The example then creates a new rule that allows the current user full control, and uses the method to replace the existing rule with the new rule. The rule that denies access is not affected. + The example creates an object and adds rules that allow and deny various rights for the current user. The example then creates a new rule that allows the current user full control, and uses the method to replace the existing rule with the new rule. The rule that denies access is not affected. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/EventWaitHandleSecurity/SetAccessRule/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/EventWaitHandleSecurity/SetAccessRule/source.vb" id="Snippet1"::: diff --git a/xml/System.Security.AccessControl/FileSecurity.xml b/xml/System.Security.AccessControl/FileSecurity.xml index 887107492c1..042940812d1 100644 --- a/xml/System.Security.AccessControl/FileSecurity.xml +++ b/xml/System.Security.AccessControl/FileSecurity.xml @@ -119,7 +119,7 @@ The following code example uses the object that's not based on an existing file. You can then populate the object with access control information and apply it to a file. -You can add access or audit rules to the object using the method. You can remove access or audit rules using the method. +You can add access or audit rules to the object using the method. You can remove access or audit rules using the method. ]]> @@ -174,7 +174,7 @@ You can add access or audit rules to the object that encapsulates that information. You can then inspect, add, or delete the access control information for the specified file. -You can add access or audit rules to the object using the method. You can remove access or audit rules using the method. +You can add access or audit rules to the object using the method. You can remove access or audit rules using the method. ]]> @@ -192,18 +192,18 @@ You can add access or audit rules to the The specified path, file name, or both exceed the system-defined maximum length. The current system account does not have administrative privileges. The file could not be found. - The parameter specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - The parameter specified a directory. - - -or- - + The parameter specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + The parameter specified a directory. + + -or- + The caller does not have the required permission. diff --git a/xml/System.Security.AccessControl/FileSystemSecurity.xml b/xml/System.Security.AccessControl/FileSystemSecurity.xml index c883c47dddf..e289be29522 100644 --- a/xml/System.Security.AccessControl/FileSystemSecurity.xml +++ b/xml/System.Security.AccessControl/FileSystemSecurity.xml @@ -167,7 +167,7 @@ Use the following .NET implementation-dependent methods to add or retrieve ACL i ## Remarks The recommended way to create access control rules is to use the constructors of the class. - The return type of the method is the base class, , but the return value can be cast safely to the derived class. + The return type of the method is the base class, , but the return value can be cast safely to the derived class. ]]> @@ -263,9 +263,9 @@ Use the following .NET implementation-dependent methods to add or retrieve ACL i method adds a new rule to the list of rules contained within a object. + The method adds a new rule to the list of rules contained within a object. - If an access control list (ACL) already exists for the specified rule, the method will still add the rule, with one exception: a object created using the enumeration value supersedes an object created using the enumeration value. + If an access control list (ACL) already exists for the specified rule, the method will still add the rule, with one exception: a object created using the enumeration value supersedes an object created using the enumeration value. Use the following .NET implementation-dependent methods to add or retrieve ACL information from a file: @@ -327,14 +327,14 @@ Use the following .NET implementation-dependent methods to add or retrieve ACL i method adds a new audit rule to the list of rules contained within a object. + The method adds a new audit rule to the list of rules contained within a object. - If an audit rule already exists for the specified rule, the method will still add the rule. + If an audit rule already exists for the specified rule, the method will still add the rule. ## Examples - The following code example uses the method to add an audit rule to a file and uses the method to remove the audit rule from the file. You must supply a valid user or group account to run this example. + The following code example uses the method to add an audit rule to a file and uses the method to remove the audit rule from the file. You must supply a valid user or group account to run this example. :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/FileSystemAuditRule/Overview/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/FileSystemAuditRule/Overview/sample.vb" id="Snippet1"::: @@ -398,7 +398,7 @@ Use the following .NET implementation-dependent methods to add or retrieve ACL i ## Remarks The recommended way to create audit rules is to use the constructors of the class. - The return type of the method is the base class, , but the return value can be cast safely to the derived class. + The return type of the method is the base class, , but the return value can be cast safely to the derived class. ]]> @@ -502,7 +502,7 @@ Use the following .NET implementation-dependent methods to add or retrieve ACL i method removes either all matching access rules or all matching access rules from the current object. For example, you can use this method to remove all access rules for a user by passing a object created using the value, the value, and a user account. When you do this, the method removes any deny rules that specify the value or the value. + The method removes either all matching access rules or all matching access rules from the current object. For example, you can use this method to remove all access rules for a user by passing a object created using the value, the value, and a user account. When you do this, the method removes any deny rules that specify the value or the value. Use the following .NET implementation-dependent methods to add or retrieve ACL information from a file: @@ -564,7 +564,7 @@ Use the following .NET implementation-dependent methods to add or retrieve ACL i method removes all access control list (ACL) permissions for the specified user. The method ignores all values in the object except the user account. + The method removes all access control list (ACL) permissions for the specified user. The method ignores all values in the object except the user account. Use the following .NET implementation-dependent methods to add or retrieve ACL information from a file: @@ -626,7 +626,7 @@ Use the following .NET implementation-dependent methods to add or retrieve ACL i method removes the specified access rule or the specified matching access rule from the current object. For example, you can use this method to remove a specified access rule for a user by passing a object created using the value, the value, and a user account. When you do this, the method removes only the deny rule that specifies the value. It does not remove any deny rules that specify the value. + The method removes the specified access rule or the specified matching access rule from the current object. For example, you can use this method to remove a specified access rule for a user by passing a object created using the value, the value, and a user account. When you do this, the method removes only the deny rule that specifies the value. It does not remove any deny rules that specify the value. Use the following .NET implementation-dependent methods to add or retrieve ACL information from a file: @@ -684,12 +684,12 @@ Use the following .NET implementation-dependent methods to add or retrieve ACL i method removes either all matching audit rules or all matching audit rules from the current object. For example, you can use this method to remove all audit rules for a user by passing a object created using the value, the value, and a user account. When you do this, the method removes any deny rules that specify the value or the value. + The method removes either all matching audit rules or all matching audit rules from the current object. For example, you can use this method to remove all audit rules for a user by passing a object created using the value, the value, and a user account. When you do this, the method removes any deny rules that specify the value or the value. ## Examples - The following code example uses the method to add an audit rule to a file and uses the method to remove the audit rule from the file. You must supply a valid user or group account to run this example. + The following code example uses the method to add an audit rule to a file and uses the method to remove the audit rule from the file. You must supply a valid user or group account to run this example. :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/FileSystemAuditRule/Overview/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/FileSystemAuditRule/Overview/sample.vb" id="Snippet1"::: @@ -739,7 +739,7 @@ Use the following .NET implementation-dependent methods to add or retrieve ACL i method removes all audit rules for the specified user. It ignores all values in the object except the user account. + The method removes all audit rules for the specified user. It ignores all values in the object except the user account. ]]> @@ -786,7 +786,7 @@ Use the following .NET implementation-dependent methods to add or retrieve ACL i method removes the specified matching audit rule or the specified matching audit rule from the current object. For example, you can use this method to remove a specified audit rule for a user by passing a object created using the value, the value, and a user account. When you do this, the method removes only a deny rule that specifies the value. It does not remove any deny rules that specify the value. + The method removes the specified matching audit rule or the specified matching audit rule from the current object. For example, you can use this method to remove a specified audit rule for a user by passing a object created using the value, the value, and a user account. When you do this, the method removes only a deny rule that specifies the value. It does not remove any deny rules that specify the value. ]]> @@ -833,7 +833,7 @@ Use the following .NET implementation-dependent methods to add or retrieve ACL i method adds the specified access control list (ACL) rule or overwrites any identical ACL rules that match the `rule` parameter. For example, if the `rule` parameter specifies a value and the method finds an identical ACL rule that specifies the value, the identical rule will be overwritten. If the method finds an identical ACL rule that specifies the value, the identical rule will also be overwritten. + The method adds the specified access control list (ACL) rule or overwrites any identical ACL rules that match the `rule` parameter. For example, if the `rule` parameter specifies a value and the method finds an identical ACL rule that specifies the value, the identical rule will be overwritten. If the method finds an identical ACL rule that specifies the value, the identical rule will also be overwritten. Use the following .NET implementation-dependent methods to add or retrieve ACL information from a file: @@ -887,7 +887,7 @@ Use the following .NET implementation-dependent methods to add or retrieve ACL i method adds the specified access control list (ACL) rule or overwrites any identical ACL rules that match the value of the `rule` parameter. For example, if the `rule` parameter specifies a value and the method finds an identical ACL rule that specifies the value, the identical rule will be overwritten. If the method finds an identical ACL rule that specifies the value, the identical rule will not be overwritten. + The method adds the specified access control list (ACL) rule or overwrites any identical ACL rules that match the value of the `rule` parameter. For example, if the `rule` parameter specifies a value and the method finds an identical ACL rule that specifies the value, the identical rule will be overwritten. If the method finds an identical ACL rule that specifies the value, the identical rule will not be overwritten. Use the following .NET implementation-dependent methods to add or retrieve ACL information from a file: @@ -941,7 +941,7 @@ Use the following .NET implementation-dependent methods to add or retrieve ACL i method adds the specified audit rule or overwrites any identical audit rules that match the value of the `rule` parameter. For example, if the `rule` parameter specifies a value and the method finds an identical audit rule that specifies the value, the identical rule will be overwritten. If the method finds an identical audit rule that specifies the value, the identical rule will not be overwritten. + The method adds the specified audit rule or overwrites any identical audit rules that match the value of the `rule` parameter. For example, if the `rule` parameter specifies a value and the method finds an identical audit rule that specifies the value, the identical rule will be overwritten. If the method finds an identical audit rule that specifies the value, the identical rule will not be overwritten. ]]> diff --git a/xml/System.Security.AccessControl/GenericAce.xml b/xml/System.Security.AccessControl/GenericAce.xml index 67850ccfa19..d9261bae51d 100644 --- a/xml/System.Security.AccessControl/GenericAce.xml +++ b/xml/System.Security.AccessControl/GenericAce.xml @@ -507,7 +507,7 @@ if the two objects are equal; otherwise, . - .]]> + .]]> @@ -552,7 +552,7 @@ if the two objects are unequal; otherwise, . - .]]> + .]]> diff --git a/xml/System.Security.AccessControl/MutexAccessRule.xml b/xml/System.Security.AccessControl/MutexAccessRule.xml index 8671bc2f13b..08db3bef49b 100644 --- a/xml/System.Security.AccessControl/MutexAccessRule.xml +++ b/xml/System.Security.AccessControl/MutexAccessRule.xml @@ -57,7 +57,7 @@ > [!NOTE] > Windows access control security is meaningful only for named system mutexes. If a object represents a local mutex, access control is irrelevant. - To get a list of the rules currently applied to a named mutex, use the method to get a object, and then use its method to obtain a collection of objects. + To get a list of the rules currently applied to a named mutex, use the method to get a object, and then use its method to obtain a collection of objects. objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all access rules for a mutex, the set contains the minimum number of rules currently required to express all the access control entries. @@ -66,10 +66,10 @@ Use objects to specify access rights to allow or deny to a user or group. A object always represents either allowed access or denied access, never both. - To apply a rule to a named system mutex, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. + To apply a rule to a named system mutex, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the named mutex until you call the method to assign the altered security object to the named mutex. +> Changes you make to a object do not affect the access levels of the named mutex until you call the method to assign the altered security object to the named mutex. objects are immutable. Security for a mutex is modified using the methods of the class to add or remove rules; as you do this, the underlying access control entries are modified. @@ -77,7 +77,7 @@ The following code example demonstrates the creation and use of objects. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/MutexAccessRule/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/MutexAccessRule/Overview/source.vb" id="Snippet1"::: @@ -137,7 +137,7 @@ (by calling the , or method), a user must have access. To release the mutex, by calling the method, the user must have access. + To wait on a (by calling the , or method), a user must have access. To release the mutex, by calling the method, the user must have access. ]]> @@ -198,9 +198,9 @@ (by calling the , or method), a user must have access. To release the mutex, by calling the methods, the user must have access. + To wait on a (by calling the , or method), a user must have access. To release the mutex, by calling the methods, the user must have access. - This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. + This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. @@ -208,7 +208,7 @@ The following code example demonstrates the use of this constructor to create objects. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/MutexAccessRule/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/MutexAccessRule/Overview/source.vb" id="Snippet1"::: @@ -280,7 +280,7 @@ The following code example demonstrates the use of the property to display the rights in the set of rules contained in a object. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/MutexAccessRule/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/MutexAccessRule/Overview/source.vb" id="Snippet1"::: diff --git a/xml/System.Security.AccessControl/MutexAuditRule.xml b/xml/System.Security.AccessControl/MutexAuditRule.xml index 877ce358dcc..a245da4090a 100644 --- a/xml/System.Security.AccessControl/MutexAuditRule.xml +++ b/xml/System.Security.AccessControl/MutexAuditRule.xml @@ -41,32 +41,32 @@ Represents a set of access rights to be audited for a user or group. This class cannot be inherited. - [!NOTE] > This type is only supported on Windows. - The class is one of a set of classes that the .NET Framework provides for managing Windows access control security on named system mutexes. For an overview of these classes and their relationship to the underlying Windows access control structures, see . - + The class is one of a set of classes that the .NET Framework provides for managing Windows access control security on named system mutexes. For an overview of these classes and their relationship to the underlying Windows access control structures, see . + > [!NOTE] -> Windows access control security is meaningful only for named system mutexes. If a object represents a local mutex, access control is irrelevant. - - To get a list of the audit rules currently applied to a named mutex, use the method to get a object, and then use its method to obtain a collection of objects. - - objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all audit rules for a mutex, the set contains the minimum number of rules currently required to express all the access control entries. - +> Windows access control security is meaningful only for named system mutexes. If a object represents a local mutex, access control is irrelevant. + + To get a list of the audit rules currently applied to a named mutex, use the method to get a object, and then use its method to obtain a collection of objects. + + objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all audit rules for a mutex, the set contains the minimum number of rules currently required to express all the access control entries. + > [!NOTE] -> The underlying access control entries change as you apply and remove rules. The information in rules is merged if possible, to maintain the smallest number of access control entries. Thus, when you read the current list of rules, it might not look exactly like the list of all the rules you have added. - - Use objects to specify access rights to be audited for a user or group. To apply a rule to a named system mutex, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. - +> The underlying access control entries change as you apply and remove rules. The information in rules is merged if possible, to maintain the smallest number of access control entries. Thus, when you read the current list of rules, it might not look exactly like the list of all the rules you have added. + + Use objects to specify access rights to be audited for a user or group. To apply a rule to a named system mutex, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. + > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the named mutex until you call the method to assign the altered security object to the named mutex. - +> Changes you make to a object do not affect the access levels of the named mutex until you call the method to assign the altered security object to the named mutex. + objects are immutable. Security for a mutex is modified using the methods of the class to add or remove rules; as you do this, the underlying access control entries are modified. - + ]]> @@ -109,24 +109,24 @@ A bitwise combination of values specifying whether to audit success, failure, or both. Initializes a new instance of the class, specifying the user or group to audit, the rights to audit, and whether to audit success, failure, or both. - object from a string representing a user or group name, use the constructor. - + object from a string representing a user or group name, use the constructor. + ]]> - specifies an invalid value. - - -or- - + specifies an invalid value. + + -or- + specifies an invalid value. - is . - - -or- - + is . + + -or- + is zero. is neither of type nor of a type such as that can be translated to type . @@ -166,11 +166,11 @@ Gets the access rights affected by the audit rule. A bitwise combination of values that indicates the rights affected by the audit rule. - objects are immutable. You can create a new audit rule representing a different user, different rights, or a different combination of flags, but you cannot modify an existing audit rule. - + objects are immutable. You can create a new audit rule representing a different user, different rights, or a different combination of flags, but you cannot modify an existing audit rule. + ]]> diff --git a/xml/System.Security.AccessControl/MutexRights.xml b/xml/System.Security.AccessControl/MutexRights.xml index 49ed2430075..52a7f2779df 100644 --- a/xml/System.Security.AccessControl/MutexRights.xml +++ b/xml/System.Security.AccessControl/MutexRights.xml @@ -44,24 +44,24 @@ Specifies the access control rights that can be applied to named system mutex objects. - [!NOTE] > This type is only supported on Windows. - Use the enumeration to specify access control rights when you create objects. To apply access rights to a named system mutex, use objects with the constructor and the method. - -## Examples - The following code example demonstrates the use of values when creating and using objects. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. - + Use the enumeration to specify access control rights when you create objects. To apply access rights to a named system mutex, use objects with the constructor and the method. + +## Examples + The following code example demonstrates the use of values when creating and using objects. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. + > [!NOTE] -> This example does not attach the security object to a object; see , method, and . - +> This example does not attach the security object to a object; see , method, and . + :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/MutexAccessRule/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/MutexAccessRule/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/MutexAccessRule/Overview/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Security.AccessControl/MutexSecurity.xml b/xml/System.Security.AccessControl/MutexSecurity.xml index 29971581f37..59cbefa5e2d 100644 --- a/xml/System.Security.AccessControl/MutexSecurity.xml +++ b/xml/System.Security.AccessControl/MutexSecurity.xml @@ -79,20 +79,20 @@ - Adding or removing access control entries in ways that do not maintain the canonical ordering. - To modify Windows access control security for a named mutex, use the method to get the object. Modify the security object by adding and removing rules, and then use the method to reattach it. + To modify Windows access control security for a named mutex, use the method to get the object. Modify the security object by adding and removing rules, and then use the method to reattach it. > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the named mutex until you call the method to assign the altered security object to the named mutex. +> Changes you make to a object do not affect the access levels of the named mutex until you call the method to assign the altered security object to the named mutex. - To copy access control security from one mutex to another, use the method to get a object representing the access and audit rules for the first mutex, and then use the method, or a constructor that accepts a object, to assign those rules to the second mutex. + To copy access control security from one mutex to another, use the method to get a object representing the access and audit rules for the first mutex, and then use the method, or a constructor that accepts a object, to assign those rules to the second mutex. - Users with an investment in the security descriptor definition language (SDDL) can use the method to set access rules for a named mutex, and the method to obtain a string that represents the access rules in SDDL format. This is not recommended for new development. + Users with an investment in the security descriptor definition language (SDDL) can use the method to set access rules for a named mutex, and the method to obtain a string that represents the access rules in SDDL format. This is not recommended for new development. ## Examples The following code example demonstrates the separation between rules and rules, and shows the combination of rights in compatible rules. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/MutexAccessRule/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/MutexAccessRule/Overview/source.vb" id="Snippet1"::: @@ -404,7 +404,7 @@ method searches for rules with the same user or group and the same as `rule`. If none are found, `rule` is added. If a matching rule is found, the rights in `rule` are merged with the existing rule. + The method searches for rules with the same user or group and the same as `rule`. If none are found, `rule` is added. If a matching rule is found, the rights in `rule` are merged with the existing rule. @@ -412,7 +412,7 @@ The following code example demonstrates the separation between rules and rules, and shows the combination of rights in compatible rules. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in . +> This example does not attach the security object to a object. Examples that attach security objects can be found in . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/MutexAccessRule/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/MutexAccessRule/Overview/source.vb" id="Snippet1"::: @@ -465,7 +465,7 @@ method searches for rules with the same user or group as `rule`. If none are found, `rule` is added. If a matching rule is found, the flags in `rule` are merged into the existing rule. + The method searches for rules with the same user or group as `rule`. If none are found, `rule` is added. If a matching rule is found, the flags in `rule` are merged into the existing rule. ]]> @@ -629,17 +629,17 @@ The current is searched for a rule that has the same user and the same value as `rule`. If no such rule is found, no action is taken, and the method returns `false`. If matching rules are found, their inheritance and compatibility flags are checked for compatibility with the flags specified in `rule`. If no compatible rule is found, no action is taken, and the method returns `false`. If a rule with compatible flags is found, the rights specified in `rule` are removed from the compatible rule, and the method returns `true`. If `rule` specifies rights not contained in the compatible rule, no action is taken with respect to those rights. If all rights are removed from the compatible rule, the entire rule is removed from the current object. > [!IMPORTANT] -> Although you can specify inheritance and propagation flags for mutex access rules, by creating them with the method, this is not recommended. Inheritance and propagation have no meaning for named mutexes, and they make the maintenance of access rules more complicated. +> Although you can specify inheritance and propagation flags for mutex access rules, by creating them with the method, this is not recommended. Inheritance and propagation have no meaning for named mutexes, and they make the maintenance of access rules more complicated. ## Examples - The following code example demonstrates the use of the method to remove rights from an rule in a object. It also shows that other rights in `rule` are ignored. + The following code example demonstrates the use of the method to remove rights from an rule in a object. It also shows that other rights in `rule` are ignored. - The example creates a object and adds rules that allow and deny various rights for the current user. The rights allowed include , , and . The example then creates a new rule for the current user, including and rights, and uses that rule with the method to remove from the rule in the object. The extraneous right in `rule` is ignored. + The example creates a object and adds rules that allow and deny various rights for the current user. The rights allowed include , , and . The example then creates a new rule for the current user, including and rights, and uses that rule with the method to remove from the rule in the object. The extraneous right in `rule` is ignored. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/MutexSecurity/RemoveAccessRule/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/MutexSecurity/RemoveAccessRule/source.vb" id="Snippet1"::: @@ -695,12 +695,12 @@ ## Examples - The following code example shows that the method removes all rules that match user and , ignoring rights. + The following code example shows that the method removes all rules that match user and , ignoring rights. The example creates a object, adds rules that allow and deny various rights for the current user, and then merges additional rights into the rule. The example then creates a new rule that allows the current user to take ownership, and uses that rule to remove the rule from the object. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/MutexSecurity/RemoveAccessRuleAll/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/MutexSecurity/RemoveAccessRuleAll/source.vb" id="Snippet1"::: @@ -754,17 +754,17 @@ The rule is removed only if it exactly matches `rule` in all details, including flags. Other rules with the same user and are not affected. > [!IMPORTANT] -> A rule represents one or more underlying access control entries (ACE), and these entries are split or combined as necessary when you modify the access security rules for a user. Thus, a rule might no longer exist in the specific form it had when it was added, and in that case the method cannot remove it. +> A rule represents one or more underlying access control entries (ACE), and these entries are split or combined as necessary when you modify the access security rules for a user. Thus, a rule might no longer exist in the specific form it had when it was added, and in that case the method cannot remove it. ## Examples - The following code example shows that the method requires an exact match in order to remove a rule, and that rules to allow and deny rights are independent of each other. + The following code example shows that the method requires an exact match in order to remove a rule, and that rules to allow and deny rights are independent of each other. - The example creates a object, adds rules that allow and deny various rights for the current user, and then merges additional rights into the access rule. The example then passes the original rule to the method, and displays the results, showing that nothing is deleted. The example then constructs a rule that matches the rule in the object, and successfully uses the method to remove the rule. + The example creates a object, adds rules that allow and deny various rights for the current user, and then merges additional rights into the access rule. The example then passes the original rule to the method, and displays the results, showing that nothing is deleted. The example then constructs a rule that matches the rule in the object, and successfully uses the method to remove the rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/MutexSecurity/RemoveAccessRuleSpecific/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/MutexSecurity/RemoveAccessRuleSpecific/source.vb" id="Snippet1"::: @@ -820,7 +820,7 @@ The current is searched for an audit rule that has the same user as `rule`. If no such rule is found, no action is taken, and the method returns `false`. If matching rules are found, their inheritance and compatibility flags are checked for compatibility with the flags specified in `rule`. If no compatible rule is found, no action is taken, and the method returns `false`. If a rule with compatible flags is found, the rights specified in `rule` are removed from the compatible rule, and the method returns `true`. If `rule` specifies rights not contained in the compatible rule, no action is taken with respect to those rights. If all rights are removed from the compatible rule, the entire rule is removed from the current object. > [!IMPORTANT] -> Although you can specify inheritance and propagation flags for mutex audit rules, by creating them with the method, this is not recommended. Inheritance and propagation have no meaning for named mutexes, and they make the maintenance of audit rules more complicated. +> Although you can specify inheritance and propagation flags for mutex audit rules, by creating them with the method, this is not recommended. Inheritance and propagation have no meaning for named mutexes, and they make the maintenance of audit rules more complicated. ]]> @@ -919,7 +919,7 @@ The rule is removed only if it exactly matches `rule` in all details, including flags. Other audit rules for the same user are not affected. > [!IMPORTANT] -> A rule represents one or more underlying access control entries (ACE), and these entries are split or combined as necessary when you modify the audit security rules for a user. Thus, a rule might no longer exist in the specific form it had when it was added, and in that case the method cannot remove it. +> A rule represents one or more underlying access control entries (ACE), and these entries are split or combined as necessary when you modify the audit security rules for a user. Thus, a rule might no longer exist in the specific form it had when it was added, and in that case the method cannot remove it. ]]> @@ -972,12 +972,12 @@ ## Examples - The following code example shows how the method replaces all rules for the matching user with the rule specified for the match. + The following code example shows how the method replaces all rules for the matching user with the rule specified for the match. - The example creates a object and adds rules that allow and deny various rights for the current user. The example then creates a new rule that allows the current user full control, and uses the method to replace both of the existing rules with the new rule. + The example creates a object and adds rules that allow and deny various rights for the current user. The example then creates a new rule that allows the current user full control, and uses the method to replace both of the existing rules with the new rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/MutexSecurity/ResetAccessRule/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/MutexSecurity/ResetAccessRule/source.vb" id="Snippet1"::: @@ -1035,12 +1035,12 @@ ## Examples - The following code example shows how the method removes all rules that match both the user and the of `rule`, replacing them with `rule`. + The following code example shows how the method removes all rules that match both the user and the of `rule`, replacing them with `rule`. - The example creates a object and adds rules that allow and deny various rights for the current user. The example then creates a new rule that allows the current user full control, and uses the method to replace the existing Allow rule with the new rule. The rule that denies access is not affected. + The example creates a object and adds rules that allow and deny various rights for the current user. The example then creates a new rule that allows the current user full control, and uses the method to replace the existing Allow rule with the new rule. The rule that denies access is not affected. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/MutexSecurity/SetAccessRule/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/MutexSecurity/SetAccessRule/source.vb" id="Snippet1"::: diff --git a/xml/System.Security.AccessControl/NativeObjectSecurity.xml b/xml/System.Security.AccessControl/NativeObjectSecurity.xml index 898a1690c18..f48fbad5c39 100644 --- a/xml/System.Security.AccessControl/NativeObjectSecurity.xml +++ b/xml/System.Security.AccessControl/NativeObjectSecurity.xml @@ -138,11 +138,11 @@ One of the enumeration values that specifies the sections of the security descriptor (access rules, audit rules, owner, primary group) of the securable object to include in this object. Initializes a new instance of the class with the specified values. We recommend that the values of the parameters passed to the constructor and persist methods be identical. - object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. - + object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. + ]]> @@ -243,11 +243,11 @@ One of the enumeration values that specifies the sections of the security descriptor (access rules, audit rules, owner, primary group) of the securable object to include in this object. Initializes a new instance of the class with the specified values. We recommend that the values of the parameters passed to the constructor and persist methods be identical. - object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. - + object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. + ]]> @@ -303,11 +303,11 @@ An object that contains contextual information about the source or destination of the exception. Initializes a new instance of the class with the specified values. We recommend that the values of the parameters passed to the constructor and persist methods be identical. - object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. - + object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. + ]]> @@ -363,11 +363,11 @@ An object that contains contextual information about the source or destination of the exception. Initializes a new instance of the class with the specified values. We recommend that the values of the parameters passed to the constructor and persist methods be identical. - object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. - + object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. + ]]> @@ -425,11 +425,11 @@ One of the enumeration values that specifies the sections of the security descriptor (access rules, audit rules, owner, primary group) of the securable object to save. Saves the specified sections of the security descriptor associated with this object to permanent storage. We recommend.persist that the values of the parameters passed to the constructor and persist methods be identical. - object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. - + object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. + ]]> The securable object with which this object is associated is either a directory or a file, and that directory or file could not be found. @@ -479,11 +479,11 @@ One of the enumeration values that specifies the sections of the security descriptor (access rules, audit rules, owner, primary group) of the securable object to save. Saves the specified sections of the security descriptor associated with this object to permanent storage. We recommend that the values of the parameters passed to the constructor and persist methods be identical. - object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. - + object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. + ]]> The securable object with which this object is associated is either a directory or a file, and that directory or file could not be found. @@ -543,11 +543,11 @@ An object that contains contextual information about the source or destination of the exception. Saves the specified sections of the security descriptor associated with this object to permanent storage. We recommend that the values of the parameters passed to the constructor and persist methods be identical. - object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. - + object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. + ]]> The securable object with which this object is associated is either a directory or a file, and that directory or file could not be found. @@ -607,11 +607,11 @@ An object that contains contextual information about the source or destination of the exception. Saves the specified sections of the security descriptor associated with this object to permanent storage. We recommend that the values of the parameters passed to the constructor and persist methods be identical. - object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. - + object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. + ]]> The securable object with which this object is associated is either a directory or a file, and that directory or file could not be found. diff --git a/xml/System.Security.AccessControl/ObjectAce.xml b/xml/System.Security.AccessControl/ObjectAce.xml index 944636f17a9..8bab8552248 100644 --- a/xml/System.Security.AccessControl/ObjectAce.xml +++ b/xml/System.Security.AccessControl/ObjectAce.xml @@ -212,7 +212,7 @@ parameter does not contain the value , this property is ignored. + If the value of the parameter does not contain the value , this property is ignored. ]]> @@ -328,7 +328,7 @@ parameter does not contain the value , this property is ignored. + If the value of the parameter does not contain the value , this property is ignored. ]]> diff --git a/xml/System.Security.AccessControl/ObjectSecurity.xml b/xml/System.Security.AccessControl/ObjectSecurity.xml index 41c7b385781..137c1590161 100644 --- a/xml/System.Security.AccessControl/ObjectSecurity.xml +++ b/xml/System.Security.AccessControl/ObjectSecurity.xml @@ -701,11 +701,11 @@ Returns an array of byte values that represents the security descriptor information for this object. An array of byte values that represents the security descriptor for this object. This method returns if there is no security information in this object. - @@ -943,11 +943,11 @@ if the DACL is successfully modified; otherwise, . - @@ -995,11 +995,11 @@ if the DACL is successfully modified; otherwise, . - @@ -1183,11 +1183,11 @@ One of the enumeration values that specifies the sections of the security descriptor (access rules, audit rules, owner, primary group) of the securable object to save. Saves the specified sections of the security descriptor associated with this object to permanent storage. We recommend that the values of the parameters passed to the constructor and persist methods be identical. - object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. - + object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. + ]]> @@ -1230,11 +1230,11 @@ One of the enumeration values that specifies the sections of the security descriptor (access rules, audit rules, owner, primary group) of the securable object to save. Saves the specified sections of the security descriptor associated with this object to permanent storage. We recommend that the values of the parameters passed to the constructor and persist methods be identical. - object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. - + object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. + ]]> @@ -1290,11 +1290,11 @@ One of the enumeration values that specifies the sections of the security descriptor (access rules, audit rules, owner, primary group) of the securable object to save. Saves the specified sections of the security descriptor associated with this object to permanent storage. We recommend that the values of the parameters passed to the constructor and persist methods be identical. - object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. - + object, if the value of the `includeSections` parameter passed to the method is not identical to the value of the `includeSections` parameter passed to the constructor used to create that object, sections of the persisted object can contain unpredictable values. For example, if a constructor is called with an `includeSections` value of , and later a method is called on that object with an `includeSections` value of , the resulting persisted object will contain unpredictable values for its audit rules, group, and owner. + ]]> @@ -1515,13 +1515,13 @@ to preserve inherited access rules; to remove inherited access rules. This parameter is ignored if is . Sets or removes protection of the access rules associated with this object. Protected access rules cannot be modified by parent objects through inheritance. - This method attempts to remove inherited rules from a non-canonical Discretionary Access Control List (DACL). @@ -1654,13 +1654,13 @@ For more information on the canonical ordering of ACLs, see [Order of ACEs in a Sets the security descriptor for this object from the specified binary data. - @@ -1701,13 +1701,13 @@ For more information on the canonical ordering of ACLs, see [Order of ACEs in a The array of bytes from which to set the security descriptor. Sets the security descriptor for this object from the specified array of byte values. - @@ -1750,13 +1750,13 @@ For more information on the canonical ordering of ACLs, see [Order of ACEs in a The sections (access rules, audit rules, owner, primary group) of the security descriptor to set. Sets the specified sections of the security descriptor for this object from the specified array of byte values. - @@ -1769,13 +1769,13 @@ For more information on the canonical ordering of ACLs, see [Order of ACEs in a Sets the security descriptor for this object from the specified Security Descriptor Definition Language (SDDL) string. - @@ -1822,13 +1822,13 @@ For more information on the canonical ordering of ACLs, see [Order of ACEs in a The SDDL string from which to set the security descriptor. Sets the security descriptor for this object from the specified Security Descriptor Definition Language (SDDL) string. - @@ -1877,13 +1877,13 @@ For more information on the canonical ordering of ACLs, see [Order of ACEs in a The sections (access rules, audit rules, owner, primary group) of the security descriptor to set. Sets the specified sections of the security descriptor for this object from the specified Security Descriptor Definition Language (SDDL) string. - diff --git a/xml/System.Security.AccessControl/RegistryAccessRule.xml b/xml/System.Security.AccessControl/RegistryAccessRule.xml index 43dfa8b7199..2320a71aa17 100644 --- a/xml/System.Security.AccessControl/RegistryAccessRule.xml +++ b/xml/System.Security.AccessControl/RegistryAccessRule.xml @@ -67,7 +67,7 @@ > [!NOTE] > Windows access control security can only be applied to registry keys. It cannot be applied to individual key/value pairs stored in a key. - To get a list of the rules currently applied to a registry key, use the method to get a object, and then use its method to obtain a collection of objects. + To get a list of the rules currently applied to a registry key, use the method to get a object, and then use its method to obtain a collection of objects. objects do not map one-to-one with access control entries in the underlying discretionary control access list (DACL). When you get the set of all access rules for a registry key, the set contains the minimum number of rules currently required to express all the access control entries. @@ -76,10 +76,10 @@ Use objects to specify access rights to allow or deny to a user or group. A object always represents either allowed access or denied access, never both. - To apply a rule to a registry key, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. + To apply a rule to a registry key, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the registry key until you call the method to assign the altered security object to the registry key. +> Changes you make to a object do not affect the access levels of the registry key until you call the method to assign the altered security object to the registry key. objects are immutable. Security for a registry key is modified using the methods of the class to add or remove rules; as you do this, the underlying access control entries are modified. @@ -155,16 +155,16 @@ ]]> - specifies an invalid value. - - -or- - + specifies an invalid value. + + -or- + specifies an invalid value. - is . - - -or- - + is . + + -or- + is zero. is neither of type nor of a type such as that can be converted to type . @@ -216,7 +216,7 @@ ## Remarks This constructor specifies default propagation and inheritance. That is, and . - This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. + This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. @@ -229,22 +229,22 @@ ]]> - specifies an invalid value. - - -or- - + specifies an invalid value. + + -or- + specifies an invalid value. is zero. - is . - - -or- - - is a zero-length string. - - -or- - + is . + + -or- + + is a zero-length string. + + -or- + is longer than 512 characters. @@ -315,24 +315,24 @@ ]]> - specifies an invalid value. - - -or- - - specifies an invalid value. - - -or- - - specifies an invalid value. - - -or- - + specifies an invalid value. + + -or- + + specifies an invalid value. + + -or- + + specifies an invalid value. + + -or- + specifies an invalid value. - is . - - -or- - + is . + + -or- + is zero. is neither of type , nor of a type such as that can be converted to type . @@ -402,7 +402,7 @@ > [!NOTE] > Although you can specify the flag for `inheritanceFlags`, there is no point in doing so. For the purposes of access control, the name/value pairs in a subkey are not separate objects. The access rights to name/value pairs are controlled by the rights of the subkey. Furthermore, since all subkeys are containers (that is, they can contain other subkeys), they are not affected by the flag. Finally, specifying the flag needlessly complicates the maintenance of rules, because it interferes with the combination of otherwise compatible rules. - This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. + This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. @@ -417,30 +417,30 @@ ]]> - specifies an invalid value. - - -or- - - specifies an invalid value. - - -or- - - specifies an invalid value. - - -or- - + specifies an invalid value. + + -or- + + specifies an invalid value. + + -or- + + specifies an invalid value. + + -or- + specifies an invalid value. is zero. - is . - - -or- - - is a zero-length string. - - -or- - + is . + + -or- + + is a zero-length string. + + -or- + is longer than 512 characters. diff --git a/xml/System.Security.AccessControl/RegistryAuditRule.xml b/xml/System.Security.AccessControl/RegistryAuditRule.xml index e82ad7c1828..a9cf07c31be 100644 --- a/xml/System.Security.AccessControl/RegistryAuditRule.xml +++ b/xml/System.Security.AccessControl/RegistryAuditRule.xml @@ -67,17 +67,17 @@ > [!NOTE] > Windows access control security can only be applied to registry keys. It cannot be applied to individual key/value pairs stored in a key. - To get a list of the audit rules currently applied to a registry key, use the method to get a object, and then use its method to obtain a collection of objects. + To get a list of the audit rules currently applied to a registry key, use the method to get a object, and then use its method to obtain a collection of objects. objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all audit rules for a registry key, the set contains the minimum number of rules currently required to express all the access control entries. > [!NOTE] > The underlying access control entries change as you apply and remove rules. The information in rules is merged if possible, to maintain the smallest number of access control entries. Thus, when you read the current list of rules, it might not look exactly like the list of all the rules you have added. - Use objects to specify access rights to be audited for a user or group. To apply a rule to a registry key, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. + Use objects to specify access rights to be audited for a user or group. To apply a rule to a registry key, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the registry key until you call the method to assign the altered security object to the registry key. +> Changes you make to a object do not affect the access levels of the registry key until you call the method to assign the altered security object to the registry key. objects are immutable. Security for a registry key is modified by using the methods of the class to add or remove rules; as you do this, the underlying access control entries are modified. @@ -161,24 +161,24 @@ ]]> - specifies an invalid value. - - -or- - - specifies an invalid value. - - -or- - - specifies an invalid value. - - -or- - + specifies an invalid value. + + -or- + + specifies an invalid value. + + -or- + + specifies an invalid value. + + -or- + specifies an invalid value. - is . - - -or- - + is . + + -or- + is zero. is neither of type nor of a type such as that can be converted to type . @@ -248,35 +248,35 @@ > [!NOTE] > Although you can specify the flag for `inheritanceFlags`, there is no point in doing so. For the purposes of access control, the name/value pairs in a subkey are not separate objects. The access rights to name/value pairs are controlled by the rights of the subkey. Furthermore, since all subkeys are containers (that is, they can contain other subkeys), they are not affected by the flag. Finally, specifying the flag needlessly complicates the maintenance of rules, because it interferes with the normal combination of compatible rules. - This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. + This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. ]]> - specifies an invalid value. - - -or- - - specifies an invalid value. - - -or- - - specifies an invalid value. - - -or- - + specifies an invalid value. + + -or- + + specifies an invalid value. + + -or- + + specifies an invalid value. + + -or- + specifies an invalid value. is zero. - is . - - -or- - - is a zero-length string. - - -or- - + is . + + -or- + + is a zero-length string. + + -or- + is longer than 512 characters. diff --git a/xml/System.Security.AccessControl/RegistryRights.xml b/xml/System.Security.AccessControl/RegistryRights.xml index e9b7dfb0e73..f4b29b78228 100644 --- a/xml/System.Security.AccessControl/RegistryRights.xml +++ b/xml/System.Security.AccessControl/RegistryRights.xml @@ -40,7 +40,7 @@ enumeration to specify registry access rights when you create objects. To apply access rights to a registry key, first add objects to a object, then attach the object to the key using the method, or an appropriate overload of the method. + Use the enumeration to specify registry access rights when you create objects. To apply access rights to a registry key, first add objects to a object, then attach the object to the key using the method, or an appropriate overload of the method. @@ -50,7 +50,7 @@ Before the key is deleted, the code pauses. You can switch to the Registry Editor (Regedit.exe or Regedt32.exe) and verify that the same access rights apply when the key is accessed using the Registry Editor. This example works best if you use **RunAs** from the command line to run the Registry Editor and the sample code as a local user without administrator rights. For example, if you have defined a local user named TestUser, the command `runas /user:TestUser cmd` opens a command window from which you can run the Registry Editor and then the example code. - + :::code language="csharp" source="~/snippets/csharp/Microsoft.Win32/RegistryKey/SetAccessControl/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/Microsoft.Win32/RegistryKey/SetAccessControl/source.vb" id="Snippet1"::: diff --git a/xml/System.Security.AccessControl/RegistrySecurity.xml b/xml/System.Security.AccessControl/RegistrySecurity.xml index dbabeccdcf5..ff529be558f 100644 --- a/xml/System.Security.AccessControl/RegistrySecurity.xml +++ b/xml/System.Security.AccessControl/RegistrySecurity.xml @@ -89,14 +89,14 @@ - Adding or removing access control entries in ways that do not maintain the canonical ordering. - To modify Windows access control security for a registry key, use the method to get the object. Modify the security object by adding and removing rules, and then use the method to reattach it. + To modify Windows access control security for a registry key, use the method to get the object. Modify the security object by adding and removing rules, and then use the method to reattach it. > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the registry key until you call the method to assign the altered security object to the registry key. +> Changes you make to a object do not affect the access levels of the registry key until you call the method to assign the altered security object to the registry key. - To copy access control security from one registry key to another, use the method to get a object representing the access and audit rules for the first registry key, and then use the method to assign those rules to the second registry key. You can also assign the rules to a second registry key with an or method that takes a object parameter. + To copy access control security from one registry key to another, use the method to get a object representing the access and audit rules for the first registry key, and then use the method to assign those rules to the second registry key. You can also assign the rules to a second registry key with an or method that takes a object parameter. - Users with an investment in the security descriptor definition language (SDDL) can use the method to set access rules for a registry key, and the method to obtain a string that represents the access rules in SDDL format. This is not recommended for new development. + Users with an investment in the security descriptor definition language (SDDL) can use the method to set access rules for a registry key, and the method to obtain a string that represents the access rules in SDDL format. This is not recommended for new development. @@ -105,14 +105,14 @@ Example 1 - The following code example shows how the method removes rights from a compatible rule, and how the method merges rights with compatible rules. + The following code example shows how the method removes rights from a compatible rule, and how the method merges rights with compatible rules. - The example creates a object and adds a rule that allows the current user rights. The example then creates a rule that grants the user , with the same inheritance and propagation rights as the first rule, and uses the method to remove this new rule from the object. is a constituent of , so it is removed from the compatible rule. The rules in the object are displayed, showing the remaining constituents of . + The example creates a object and adds a rule that allows the current user rights. The example then creates a rule that grants the user , with the same inheritance and propagation rights as the first rule, and uses the method to remove this new rule from the object. is a constituent of , so it is removed from the compatible rule. The rules in the object are displayed, showing the remaining constituents of . - The example code then calls the method to merge the right back into the rule in the object. + The example code then calls the method to merge the right back into the rule in the object. > [!NOTE] -> This example does not attach the security object to a object. The second example in this section attaches a security object, and so do the examples in and . +> This example does not attach the security object to a object. The second example in this section attaches a security object, and so do the examples in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/RegistrySecurity/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/RegistrySecurity/Overview/source.vb" id="Snippet1"::: @@ -380,9 +380,9 @@ method searches for rules with the same user or group and the same as `rule`. If none are found, `rule` is added. If a matching rule is found, the rights in `rule` are merged with the existing rule. + The method searches for rules with the same user or group and the same as `rule`. If none are found, `rule` is added. If a matching rule is found, the rights in `rule` are merged with the existing rule. - Rules cannot be merged if they have different inheritance flags. For example, if a user is allowed read access with no inheritance flags, and is used to add a rule giving the user write access with inheritance for subkeys (), the two rules cannot be merged. + Rules cannot be merged if they have different inheritance flags. For example, if a user is allowed read access with no inheritance flags, and is used to add a rule giving the user write access with inheritance for subkeys (), the two rules cannot be merged. Rules with different values are never merged. @@ -394,7 +394,7 @@ The following code example creates registry access rules and adds them to a object, showing how rules that allow and deny rights remain separate, while compatible rules of the same kind are merged. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . A code example that demonstrates inheritance and propagation flags can be found in the class. @@ -450,9 +450,9 @@ method searches for rules with the same user or group as `rule`. If none are found, `rule` is added. If a matching rule is found, the flags in `rule` are merged into the existing rule. + The method searches for rules with the same user or group as `rule`. If none are found, `rule` is added. If a matching rule is found, the flags in `rule` are merged into the existing rule. - Rules cannot be merged if they have different inheritance flags. For example, if failed attempts to write to a key are audited for a particular user, with no inheritance flags, and is used to add a rule specifying that failed attempts to change permissions are to be audited for the same user, but with inheritance for subkeys (), the two rules cannot be merged. + Rules cannot be merged if they have different inheritance flags. For example, if failed attempts to write to a key are audited for a particular user, with no inheritance flags, and is used to add a rule specifying that failed attempts to change permissions are to be audited for the same user, but with inheritance for subkeys (), the two rules cannot be merged. ]]> @@ -627,14 +627,14 @@ ## Examples - The following code example shows how the method removes rights from a compatible rule, and how the method merges rights with compatible rules. + The following code example shows how the method removes rights from a compatible rule, and how the method merges rights with compatible rules. - The example creates a object and adds a rule that allows the current user rights. The example then creates a rule that grants the user , with the same inheritance and propagation rights as the first rule, and uses the method to remove this new rule from the object. is a constituent of , so it is removed from the compatible rule. The rules in the object are displayed, showing the remaining constituents of . + The example creates a object and adds a rule that allows the current user rights. The example then creates a rule that grants the user , with the same inheritance and propagation rights as the first rule, and uses the method to remove this new rule from the object. is a constituent of , so it is removed from the compatible rule. The rules in the object are displayed, showing the remaining constituents of . - The example code then calls the method to merge the right back into the rule in the object. + The example code then calls the method to merge the right back into the rule in the object. > [!NOTE] -> This example does not attach the security object to a object. The second example in this section attaches a security object, and so do the examples in . +> This example does not attach the security object to a object. The second example in this section attaches a security object, and so do the examples in . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/RegistrySecurity/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/RegistrySecurity/Overview/source.vb" id="Snippet1"::: @@ -690,17 +690,17 @@ ## Remarks The current is searched for rules that have the same user and the same value as `rule`. Any rights, inheritance flags, or propagation flags specified by `rule` are ignored when performing this search. If no matching rules are found, no action is taken. - For example, if a user has multiple rules that allow various rights with different inheritance and propagation flags, you can remove all those rules by creating a object that specifies the user and , with any arbitrary rights and flags, and passing that rule to the method. + For example, if a user has multiple rules that allow various rights with different inheritance and propagation flags, you can remove all those rules by creating a object that specifies the user and , with any arbitrary rights and flags, and passing that rule to the method. ## Examples - The following code example shows that the method removes all rules that match user and , ignoring rights and flags. + The following code example shows that the method removes all rules that match user and , ignoring rights and flags. - The example creates a object and adds rules that allow and deny various rights for the current user, with different inheritance and propagation flags. The example then creates a new rule that allows the current user to take ownership, and passes that rule to the method to remove the two rules that allow access. + The example creates a object and adds rules that allow and deny various rights for the current user, with different inheritance and propagation flags. The example then creates a new rule that allows the current user to take ownership, and passes that rule to the method to remove the two rules that allow access. > [!NOTE] -> This example does not attach the security object to a object. See the method and the method. +> This example does not attach the security object to a object. See the method and the method. :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/RegistrySecurity/RemoveAccessRuleAll/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/RegistrySecurity/RemoveAccessRuleAll/source.vb" id="Snippet1"::: @@ -757,17 +757,17 @@ The rule is removed only if it exactly matches `rule` in all details, including flags. Other rules with the same user and are not affected. > [!IMPORTANT] -> A rule represents one or more underlying access control entries (ACE), and these entries are split or combined as necessary when you modify the access security rules for a user. Thus, a rule might no longer exist in the specific form it had when it was added, and in that case the method cannot remove it. +> A rule represents one or more underlying access control entries (ACE), and these entries are split or combined as necessary when you modify the access security rules for a user. Thus, a rule might no longer exist in the specific form it had when it was added, and in that case the method cannot remove it. ## Examples - The following code example shows that the method removes a rule only if it matches exactly. + The following code example shows that the method removes a rule only if it matches exactly. - The example creates two rules that allow different rights. The rules have compatible inheritance and propagation flags, so when the second rule is added it merges with the first. The example calls the method, specifying the first rule, but because the rules are merged there is no rule that matches. The example then calls the method to the remove the second rule from the merged rule, and finally calls the method to remove the first rule. + The example creates two rules that allow different rights. The rules have compatible inheritance and propagation flags, so when the second rule is added it merges with the first. The example calls the method, specifying the first rule, but because the rules are merged there is no rule that matches. The example then calls the method to the remove the second rule from the merged rule, and finally calls the method to remove the first rule. > [!NOTE] -> This example does not attach the security object to a object. See the method and the method. +> This example does not attach the security object to a object. See the method and the method. :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/RegistrySecurity/RemoveAccessRuleSpecific/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/RegistrySecurity/RemoveAccessRuleSpecific/source.vb" id="Snippet1"::: @@ -928,7 +928,7 @@ The rule is removed only if it exactly matches `rule` in all details, including flags. Other audit rules for the same user are not affected. > [!IMPORTANT] -> A rule represents one or more underlying access control entries (ACE), and these entries are split or combined as necessary when you modify the audit security rules for a user. Thus, a rule might no longer exist in the specific form it had when it was added, and in that case the method cannot remove it. +> A rule represents one or more underlying access control entries (ACE), and these entries are split or combined as necessary when you modify the audit security rules for a user. Thus, a rule might no longer exist in the specific form it had when it was added, and in that case the method cannot remove it. ]]> @@ -984,12 +984,12 @@ ## Examples - The following code example shows how the method replaces all rules for the matching user with the rule specified for the match. + The following code example shows how the method replaces all rules for the matching user with the rule specified for the match. - The example creates a object and adds rules that allow and deny various rights for the current user, with different inheritance and propagation flags. The example then creates a new rule that allows the current user only to read the key, and uses the method to remove the all rules for the user and replace them with the new rule. + The example creates a object and adds rules that allow and deny various rights for the current user, with different inheritance and propagation flags. The example then creates a new rule that allows the current user only to read the key, and uses the method to remove the all rules for the user and replace them with the new rule. > [!NOTE] -> This example does not attach the security object to a object. See the method and the method. +> This example does not attach the security object to a object. See the method and the method. :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/RegistrySecurity/ResetAccessRule/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/RegistrySecurity/ResetAccessRule/source.vb" id="Snippet1"::: @@ -1048,12 +1048,12 @@ ## Examples - The following code example shows that the method removes all rules that match both the user and the of `rule`, ignoring rights and flags, and replaces them with `rule`. + The following code example shows that the method removes all rules that match both the user and the of `rule`, ignoring rights and flags, and replaces them with `rule`. - The example creates a object and adds rules that allow and deny various rights for the current user, with different inheritance and propagation flags. The example then creates a new rule that allows the current user only to read the key, and uses the method to remove the two rules that allow access and to replace them with the new rule. The rule that denies access is not affected. + The example creates a object and adds rules that allow and deny various rights for the current user, with different inheritance and propagation flags. The example then creates a new rule that allows the current user only to read the key, and uses the method to remove the two rules that allow access and to replace them with the new rule. The rule that denies access is not affected. > [!NOTE] -> This example does not attach the security object to a object. See the method and the method. +> This example does not attach the security object to a object. See the method and the method. :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/RegistrySecurity/SetAccessRule/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/RegistrySecurity/SetAccessRule/source.vb" id="Snippet1"::: diff --git a/xml/System.Security.AccessControl/SemaphoreAccessRule.xml b/xml/System.Security.AccessControl/SemaphoreAccessRule.xml index 0c7eb786104..a181161887f 100644 --- a/xml/System.Security.AccessControl/SemaphoreAccessRule.xml +++ b/xml/System.Security.AccessControl/SemaphoreAccessRule.xml @@ -61,7 +61,7 @@ > [!NOTE] > Windows access control security is meaningful only for named system semaphores. If a object represents a local semaphore, access control is irrelevant. - To get a list of the rules currently applied to a named semaphore, use the method to get a object, then use its method to obtain a collection of objects. + To get a list of the rules currently applied to a named semaphore, use the method to get a object, then use its method to obtain a collection of objects. objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all access rules for a semaphore, the set contains the minimum number of rules currently required to express all the access control entries. @@ -70,10 +70,10 @@ Use objects to specify access rights to allow or deny to a user or group. A object always represents either allowed access or denied access, never both. - To apply a rule to a named system semaphore, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. + To apply a rule to a named system semaphore, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the named semaphore until you call the method to assign the altered security object to the named semaphore. +> Changes you make to a object do not affect the access levels of the named semaphore until you call the method to assign the altered security object to the named semaphore. objects are immutable. Security for a semaphore is modified using the methods of the class to add or remove rules; as you do this, the underlying access control entries are modified. @@ -81,7 +81,7 @@ The following code example demonstrates the separation between rules and rules, and shows the combination of rights in compatible rules. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.vb" id="Snippet1"::: @@ -147,7 +147,7 @@ , for example by calling the method, a user must have access. To exit the semaphore, by calling the method, the user must have access. + To enter a , for example by calling the method, a user must have access. To exit the semaphore, by calling the method, the user must have access. ]]> @@ -208,9 +208,9 @@ , for example by calling the method, a user must have access. To exit the semaphore, by calling the method, the user must have access. + To enter a , for example by calling the method, a user must have access. To exit the semaphore, by calling the method, the user must have access. - This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. + This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. @@ -218,7 +218,7 @@ The following code example demonstrates the use of this constructor to create objects. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.vb" id="Snippet1"::: @@ -290,7 +290,7 @@ The following code example demonstrates the use of the property to display the rights in the set of rules contained in a object. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.vb" id="Snippet1"::: diff --git a/xml/System.Security.AccessControl/SemaphoreAuditRule.xml b/xml/System.Security.AccessControl/SemaphoreAuditRule.xml index b0f94fafbfb..230df4bcff2 100644 --- a/xml/System.Security.AccessControl/SemaphoreAuditRule.xml +++ b/xml/System.Security.AccessControl/SemaphoreAuditRule.xml @@ -45,32 +45,32 @@ Represents a set of access rights to be audited for a user or group. This class cannot be inherited. - [!NOTE] > This type is only supported on Windows. - The class is one of a set of classes that the .NET Framework provides for managing Windows access control security on named system semaphores. For an overview of these classes and their relationship to the underlying Windows access control structures, see . - + The class is one of a set of classes that the .NET Framework provides for managing Windows access control security on named system semaphores. For an overview of these classes and their relationship to the underlying Windows access control structures, see . + > [!NOTE] -> Windows access control security is meaningful only for named system semaphores. If a object represents a local semaphore, access control is irrelevant. - - To get a list of the audit rules currently applied to a named semaphore, use the method to get a object, and then use its method to obtain a collection of objects. - - objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all audit rules for a semaphore, the set contains the minimum number of rules currently required to express all the access control entries. - +> Windows access control security is meaningful only for named system semaphores. If a object represents a local semaphore, access control is irrelevant. + + To get a list of the audit rules currently applied to a named semaphore, use the method to get a object, and then use its method to obtain a collection of objects. + + objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all audit rules for a semaphore, the set contains the minimum number of rules currently required to express all the access control entries. + > [!NOTE] -> The underlying access control entries change as you apply and remove rules. The information in rules is merged if possible, to maintain the smallest number of access control entries. Thus, when you read the current list of rules, it might not look exactly like the list of all the rules you have added. - - Use objects to specify access rights to be audited for a user or group. To apply a rule to a named system semaphore, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. - +> The underlying access control entries change as you apply and remove rules. The information in rules is merged if possible, to maintain the smallest number of access control entries. Thus, when you read the current list of rules, it might not look exactly like the list of all the rules you have added. + + Use objects to specify access rights to be audited for a user or group. To apply a rule to a named system semaphore, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. + > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the named semaphore until you call the method to assign the altered security object to the named semaphore. - +> Changes you make to a object do not affect the access levels of the named semaphore until you call the method to assign the altered security object to the named semaphore. + objects are immutable. Security for a semaphore is modified using the methods of the class to add or remove rules; as you do this, the underlying access control entries are modified. - + ]]> @@ -119,24 +119,24 @@ A bitwise combination of values specifying whether to audit success, failure, or both. Initializes a new instance of the class, specifying the user or group to audit, the rights to audit, and whether to audit success, failure, or both. - object from a string representing a user or group name, use the constructor. - + object from a string representing a user or group name, use the constructor. + ]]> - specifies an invalid value. - - -or- - + specifies an invalid value. + + -or- + specifies an invalid value. - is . - - -or- - + is . + + -or- + is zero. is neither of type nor of a type such as that can be converted to type . @@ -176,11 +176,11 @@ Gets the access rights affected by the audit rule. A bitwise combination of values that indicates the rights affected by the audit rule. - objects are immutable. You can create a new audit rule representing a different user, different rights, or a different combination of values, but you cannot modify an existing audit rule. - + objects are immutable. You can create a new audit rule representing a different user, different rights, or a different combination of values, but you cannot modify an existing audit rule. + ]]> diff --git a/xml/System.Security.AccessControl/SemaphoreRights.xml b/xml/System.Security.AccessControl/SemaphoreRights.xml index ada798aa891..15d5740d135 100644 --- a/xml/System.Security.AccessControl/SemaphoreRights.xml +++ b/xml/System.Security.AccessControl/SemaphoreRights.xml @@ -48,26 +48,26 @@ Specifies the access control rights that can be applied to named system semaphore objects. - [!NOTE] > This type is only supported on Windows. - Use the enumeration to specify access control rights when you create objects. To apply access rights to a named system semaphore, use objects with the constructor and the method. - + Use the enumeration to specify access control rights when you create objects. To apply access rights to a named system semaphore, use objects with the constructor and the method. + For the numeric values of the underlying Windows access rights, see [Synchronization Object Security and Access Rights (Windows)](https://go.microsoft.com/fwlink/p/?LinkId=243073). - -## Examples - The following code example demonstrates the use of values when creating and using objects. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. - + +## Examples + The following code example demonstrates the use of values when creating and using objects. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. + > [!NOTE] -> This example does not attach the security object to an object; see , method, and . - +> This example does not attach the security object to an object; see , method, and . + :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Security.AccessControl/SemaphoreSecurity.xml b/xml/System.Security.AccessControl/SemaphoreSecurity.xml index 784c7ada876..fc17e301783 100644 --- a/xml/System.Security.AccessControl/SemaphoreSecurity.xml +++ b/xml/System.Security.AccessControl/SemaphoreSecurity.xml @@ -83,20 +83,20 @@ - Adding or removing access control entries in ways that do not maintain the canonical ordering. - To modify Windows access control security for a named semaphore, use the method to get the object. Modify the security object by adding and removing rules, and then use the method to reattach it. + To modify Windows access control security for a named semaphore, use the method to get the object. Modify the security object by adding and removing rules, and then use the method to reattach it. > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the named semaphore until you call the method to assign the altered security object to the named semaphore. +> Changes you make to a object do not affect the access levels of the named semaphore until you call the method to assign the altered security object to the named semaphore. - To copy access control security from one semaphore to another, use the method to get a object representing the access and audit rules for the first semaphore, then use the method, or a constructor that accepts a object, to assign those rules to the second semaphore. + To copy access control security from one semaphore to another, use the method to get a object representing the access and audit rules for the first semaphore, then use the method, or a constructor that accepts a object, to assign those rules to the second semaphore. - Users with an investment in the security descriptor definition language (SDDL) can use the method to set access rules for a named semaphore, and the method to obtain a string that represents the access rules in SDDL format. This is not recommended for new development. + Users with an investment in the security descriptor definition language (SDDL) can use the method to set access rules for a named semaphore, and the method to obtain a string that represents the access rules in SDDL format. This is not recommended for new development. ## Examples The following code example demonstrates the separation between rules and rules, and shows the combination of rights in compatible rules. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.vb" id="Snippet1"::: @@ -401,7 +401,7 @@ method searches for rules with the same user or group and the same as `rule`. If none are found, `rule` is added. If a matching rule is found, the rights in `rule` are merged with the existing rule. + The method searches for rules with the same user or group and the same as `rule`. If none are found, `rule` is added. If a matching rule is found, the rights in `rule` are merged with the existing rule. @@ -409,7 +409,7 @@ The following code example demonstrates the separation between rules and rules, and shows the combination of rights in compatible rules. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.vb" id="Snippet1"::: @@ -460,7 +460,7 @@ method searches for rules with the same user or group as `rule`. If none are found, `rule` is added. If a matching rule is found, the flags in `rule` are merged into the existing rule. + The method searches for rules with the same user or group as `rule`. If none are found, `rule` is added. If a matching rule is found, the flags in `rule` are merged into the existing rule. ]]> @@ -624,17 +624,17 @@ The current is searched for a rule that has the same user and the same value as `rule`. If no such rule is found, no action is taken, and the method returns `false`. If matching rules are found, their inheritance and compatibility flags are checked for compatibility with the flags specified in `rule`. If no compatible rule is found, no action is taken, and the method returns `false`. If a rule with compatible flags is found, the rights specified in `rule` are removed from the compatible rule, and the method returns `true`. If `rule` specifies rights not contained in the compatible rule, no action is taken with respect to those rights. If all rights are removed from the compatible rule, the entire rule is removed from the current object. > [!IMPORTANT] -> Although you can specify inheritance and propagation flags for semaphore access rules, by creating them with the method, this is not recommended. Inheritance and propagation have no meaning for named semaphores, and they make the maintenance of access rules more complicated. +> Although you can specify inheritance and propagation flags for semaphore access rules, by creating them with the method, this is not recommended. Inheritance and propagation have no meaning for named semaphores, and they make the maintenance of access rules more complicated. ## Examples - The following code example demonstrates the use of the method to remove rights from an rule in a object. It also shows that other rights in `rule` are ignored. + The following code example demonstrates the use of the method to remove rights from an rule in a object. It also shows that other rights in `rule` are ignored. - The example creates a object and adds rules that allow and deny various rights for the current user. The rights allowed include , , and . The example then creates a new rule for the current user, including and rights, and uses that rule with the method to remove from the rule in the object. The extraneous right in `rule` is ignored. + The example creates a object and adds rules that allow and deny various rights for the current user. The rights allowed include , , and . The example then creates a new rule for the current user, including and rights, and uses that rule with the method to remove from the rule in the object. The extraneous right in `rule` is ignored. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/SemaphoreSecurity/RemoveAccessRule/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/SemaphoreSecurity/RemoveAccessRule/source.vb" id="Snippet1"::: @@ -690,12 +690,12 @@ ## Examples - The following code example shows that the method removes all rules that match user and , ignoring rights. + The following code example shows that the method removes all rules that match user and , ignoring rights. The example creates a object, adds rules that allow and deny various rights for the current user, and then merges additional rights into the rule. The example then creates a new rule that allows the current user to take ownership, and uses that rule to remove the rule from the object. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/SemaphoreSecurity/RemoveAccessRuleAll/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/SemaphoreSecurity/RemoveAccessRuleAll/source.vb" id="Snippet1"::: @@ -749,17 +749,17 @@ The rule is removed only if it exactly matches `rule` in all details, including flags. Other rules with the same user and are not affected. > [!IMPORTANT] -> A rule represents one or more underlying access control entries (ACE), and these entries are split or combined as necessary when you modify the access security rules for a user. Thus, a rule might no longer exist in the specific form it had when it was added, and in that case the method cannot remove it. +> A rule represents one or more underlying access control entries (ACE), and these entries are split or combined as necessary when you modify the access security rules for a user. Thus, a rule might no longer exist in the specific form it had when it was added, and in that case the method cannot remove it. ## Examples - The following code example shows that the method requires an exact match in order to remove a rule, and that rules to allow and deny rights are independent of each other. + The following code example shows that the method requires an exact match in order to remove a rule, and that rules to allow and deny rights are independent of each other. - The example creates a object, adds rules that allow and deny various rights for the current user, and then merges additional rights into the access rule. The example then passes the original rule to the method, and displays the results, showing that nothing is deleted. The example then constructs a rule that matches the rule in the object, and successfully uses the method to remove the rule. + The example creates a object, adds rules that allow and deny various rights for the current user, and then merges additional rights into the access rule. The example then passes the original rule to the method, and displays the results, showing that nothing is deleted. The example then constructs a rule that matches the rule in the object, and successfully uses the method to remove the rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/SemaphoreSecurity/RemoveAccessRuleSpecific/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/SemaphoreSecurity/RemoveAccessRuleSpecific/source.vb" id="Snippet1"::: @@ -815,7 +815,7 @@ The current is searched for an audit rule that has the same user as `rule`. If no such rule is found, no action is taken, and the method returns `false`. If matching rules are found, their inheritance and compatibility flags are checked for compatibility with the flags specified in `rule`. If no compatible rule is found, no action is taken, and the method returns `false`. If a rule with compatible flags is found, the rights specified in `rule` are removed from the compatible rule, and the method returns `true`. If `rule` specifies rights not contained in the compatible rule, no action is taken with respect to those rights. If all rights are removed from the compatible rule, the entire rule is removed from the current object. > [!IMPORTANT] -> Although you can specify inheritance and propagation flags for semaphore audit rules, by creating them with the method, this is not recommended. Inheritance and propagation have no meaning for named semaphores, and they make the maintenance of audit rules more complicated. +> Although you can specify inheritance and propagation flags for semaphore audit rules, by creating them with the method, this is not recommended. Inheritance and propagation have no meaning for named semaphores, and they make the maintenance of audit rules more complicated. ]]> @@ -914,7 +914,7 @@ The rule is removed only if it exactly matches `rule` in all details, including flags. Other audit rules for the same user are not affected. > [!IMPORTANT] -> A rule represents one or more underlying access control entries (ACE), and these entries are split or combined as necessary when you modify the audit security rules for a user. Thus, a rule might no longer exist in the specific form it had when it was added, and in that case the method cannot remove it. +> A rule represents one or more underlying access control entries (ACE), and these entries are split or combined as necessary when you modify the audit security rules for a user. Thus, a rule might no longer exist in the specific form it had when it was added, and in that case the method cannot remove it. ]]> @@ -967,12 +967,12 @@ ## Examples - The following code example shows how the method replaces all rules for the matching user with the rule specified for the match. + The following code example shows how the method replaces all rules for the matching user with the rule specified for the match. - The example creates a object and adds rules that allow and deny various rights for the current user. The example then creates a new rule that allows the current user full control, and uses the method to replace both of the existing rules with the new rule. + The example creates a object and adds rules that allow and deny various rights for the current user. The example then creates a new rule that allows the current user full control, and uses the method to replace both of the existing rules with the new rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/SemaphoreSecurity/ResetAccessRule/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/SemaphoreSecurity/ResetAccessRule/source.vb" id="Snippet1"::: @@ -1030,12 +1030,12 @@ ## Examples - The following code example shows how the method removes all rules that match both the user and the of `rule`, replacing them with `rule`. + The following code example shows how the method removes all rules that match both the user and the of `rule`, replacing them with `rule`. - The example creates a object and adds rules that allow and deny various rights for the current user. The example then creates a new rule that allows the current user full control, and uses the method to replace the existing Allow rule with the new rule. The rule that denies access is not affected. + The example creates a object and adds rules that allow and deny various rights for the current user. The example then creates a new rule that allows the current user full control, and uses the method to replace the existing Allow rule with the new rule. The rule that denies access is not affected. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/SemaphoreSecurity/SetAccessRule/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/SemaphoreSecurity/SetAccessRule/source.vb" id="Snippet1"::: diff --git a/xml/System.Security.Authentication.ExtendedProtection.Configuration/ExtendedProtectionPolicyElement.xml b/xml/System.Security.Authentication.ExtendedProtection.Configuration/ExtendedProtectionPolicyElement.xml index d1fd044909f..351cbffaf83 100644 --- a/xml/System.Security.Authentication.ExtendedProtection.Configuration/ExtendedProtectionPolicyElement.xml +++ b/xml/System.Security.Authentication.ExtendedProtection.Configuration/ExtendedProtectionPolicyElement.xml @@ -47,7 +47,7 @@ ## Remarks When this constructor is used to initialize a new instance of the class, the property is set to , the property is set to , and the property is set to `null`. - The properties on the class instance should be set to appropriate values for the application before calling the method. + The properties on the class instance should be set to appropriate values for the application before calling the method. ]]> @@ -77,7 +77,7 @@ class instance must be set before calling the method. + The properties on the class instance must be set before calling the method. ]]> diff --git a/xml/System.Security.Authentication.ExtendedProtection.Configuration/ServiceNameElement.xml b/xml/System.Security.Authentication.ExtendedProtection.Configuration/ServiceNameElement.xml index 960b2bb16a6..593cd2e15f8 100644 --- a/xml/System.Security.Authentication.ExtendedProtection.Configuration/ServiceNameElement.xml +++ b/xml/System.Security.Authentication.ExtendedProtection.Configuration/ServiceNameElement.xml @@ -40,7 +40,7 @@ ## Remarks When this constructor is used to initialize a new instance of the class, the property is set to `null`. - The property should be set to an appropriate value for the application before calling the method to add the instance to the class. + The property should be set to an appropriate value for the application before calling the method to add the instance to the class. ]]> diff --git a/xml/System.Security.Authentication.ExtendedProtection.Configuration/ServiceNameElementCollection.xml b/xml/System.Security.Authentication.ExtendedProtection.Configuration/ServiceNameElementCollection.xml index f522f7c96e6..2599480b0fc 100644 --- a/xml/System.Security.Authentication.ExtendedProtection.Configuration/ServiceNameElementCollection.xml +++ b/xml/System.Security.Authentication.ExtendedProtection.Configuration/ServiceNameElementCollection.xml @@ -72,13 +72,13 @@ The instance to add to this . The method adds a instance to this . - method ignores a duplicate name provided in the `element` parameter. - - The class is a collection of Service Principal Names (SPNs) that represent a configuration element for an . - + method ignores a duplicate name provided in the `element` parameter. + + The class is a collection of Service Principal Names (SPNs) that represent a configuration element for an . + ]]> diff --git a/xml/System.Security.Authentication.ExtendedProtection/ChannelBinding.xml b/xml/System.Security.Authentication.ExtendedProtection/ChannelBinding.xml index a2ff923bab8..56414464b04 100644 --- a/xml/System.Security.Authentication.ExtendedProtection/ChannelBinding.xml +++ b/xml/System.Security.Authentication.ExtendedProtection/ChannelBinding.xml @@ -52,11 +52,11 @@ The class encapsulates a pointer to the opaque data used to bind an authenticated transaction to a secure channel. - class instance is used to provide extended protection for integrated windows authentication. - + class instance is used to provide extended protection for integrated windows authentication. + ]]> @@ -99,11 +99,11 @@ Initializes a new instance of the class. - @@ -153,11 +153,11 @@ A Boolean value that indicates if the application owns the safe handle to a native memory region containing the byte data that would be passed to native calls that provide extended protection for integrated windows authentication. Initializes a new instance of the class. - constructor is designed to deal with how the channel binding is acquired to compensate for allocation and deallocation semantics in the native calls that provide extended protection for integrated windows authentication. - + constructor is designed to deal with how the channel binding is acquired to compensate for allocation and deallocation semantics in the native calls that provide extended protection for integrated windows authentication. + ]]> @@ -202,11 +202,11 @@ The property gets the size, in bytes, of the channel binding token associated with the instance. The size, in bytes, of the channel binding token in the instance. - instance that contains a channel binding token to other classes or to the native Windows security functions that implement extended protection. The channel binding token is used to provide extended protection for integrated Windows authentication. - + instance that contains a channel binding token to other classes or to the native Windows security functions that implement extended protection. The channel binding token is used to provide extended protection for integrated Windows authentication. + ]]> diff --git a/xml/System.Security.Authentication.ExtendedProtection/ExtendedProtectionPolicy.xml b/xml/System.Security.Authentication.ExtendedProtection/ExtendedProtectionPolicy.xml index e0bc09e4e6b..48767e2fb2b 100644 --- a/xml/System.Security.Authentication.ExtendedProtection/ExtendedProtectionPolicy.xml +++ b/xml/System.Security.Authentication.ExtendedProtection/ExtendedProtectionPolicy.xml @@ -195,7 +195,7 @@ ## Remarks This constructor implements the interface for the class. - The method can be used to serialize an object. This serialized object can then be used with to construct a new object. + The method can be used to serialize an object. This serialized object can then be used with to construct a new object. ]]> @@ -702,7 +702,7 @@ method can be used to serialize an object. This serialized object can then be used with to construct a new object. + The method can be used to serialize an object. This serialized object can then be used with to construct a new object. ]]> diff --git a/xml/System.Security.Claims/AuthorizationContext.xml b/xml/System.Security.Claims/AuthorizationContext.xml index 5105bcce35e..81fa021afe7 100644 --- a/xml/System.Security.Claims/AuthorizationContext.xml +++ b/xml/System.Security.Claims/AuthorizationContext.xml @@ -19,7 +19,7 @@ class represents the context that is used by a claims authorization manager, an implementation of the class, to determine whether a principal (subject) should be authorized to perform a specified action on a given resource. The claims authorization manager evaluates the authorization context in the method and either denies or grants access based on the claims presented by the principal. + The class represents the context that is used by a claims authorization manager, an implementation of the class, to determine whether a principal (subject) should be authorized to perform a specified action on a given resource. The claims authorization manager evaluates the authorization context in the method and either denies or grants access based on the claims presented by the principal. The property contains the principal for which authorization is being requested, the property contains the resource on which the principal is being authorized, and the property contains the actions that the principal intends to perform on the resource. Both the resource and the action are represented as a collection of claims; however, in most cases, each collection contains a single claim. @@ -28,7 +28,7 @@ ## Examples The code example that is used in the topic is taken from the `Claims Based Authorization` sample. This sample provides a custom claims authorization manager that can authorize subjects based on a policy that is specified in configuration. This custom manager consists of three basic components: a class derived from that implements the manager, the `ResourceAction` class that pairs a resource and an action, and a policy reader that reads and compiles policy that is specified in the configuration file. This compiled policy can then be used by the claims authorization manager to evaluate a principal in order to authorize access to resources. Not all elements are shown for the sake of brevity. For information about this sample and other samples available for WIF and about where to download them, see [WIF Code Sample Index](/previous-versions/dotnet/framework/windows-identity-foundation/wif-code-sample-index). - The following code shows the method for the custom claims authorization manager. A function that evaluates the principal based on the resource and action specified in the is invoked. This function returns either `true` or `false`, which either grants or denies access to the principal. + The following code shows the method for the custom claims authorization manager. A function that evaluates the principal based on the resource and action specified in the is invoked. This function returns either `true` or `false`, which either grants or denies access to the principal. :::code language="csharp" source="~/snippets/csharp/System.Security.Claims/AuthorizationContext/Overview/myclaimsauthorizationmanager.cs" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Claims/AuthorizationContext/Overview/myclaimsauthorizationmanager.cs" id="Snippet5"::: diff --git a/xml/System.Security.Claims/Claim.xml b/xml/System.Security.Claims/Claim.xml index 39a5f2e9d56..e5499628a07 100644 --- a/xml/System.Security.Claims/Claim.xml +++ b/xml/System.Security.Claims/Claim.xml @@ -155,7 +155,7 @@ if (null != principal) . + Normally, the reader is constructed from the bytes returned from . ]]> @@ -373,7 +373,7 @@ if (null != principal) property is set to `null`. The and properties are set to . The property is set to + The property is set to `null`. The and properties are set to . The property is set to ]]> @@ -438,7 +438,7 @@ if (null != principal) property is set to `null`. The and properties are set to . + The property is set to `null`. The and properties are set to . ]]> @@ -1103,7 +1103,7 @@ if (null != principal) and properties in the following format:."Type: Value". + The string that is returned contains the values of the and properties in the following format:."Type: Value". ]]> diff --git a/xml/System.Security.Claims/ClaimsAuthenticationManager.xml b/xml/System.Security.Claims/ClaimsAuthenticationManager.xml index 050199a693b..591c5d9f22a 100644 --- a/xml/System.Security.Claims/ClaimsAuthenticationManager.xml +++ b/xml/System.Security.Claims/ClaimsAuthenticationManager.xml @@ -20,37 +20,37 @@ Defines the base implementation for a claims authentication manager. The claims authentication manager provides a place in the claims processing pipeline for applying processing logic (filtering, validation, extension) to the claims collection in the incoming principal before execution reaches your application code. - before the RP application code is executed. You can even return a custom implementation of if your RP application requires it. The default implementation provided by the class returns the claims in the unmodified; however, you can derive from this class and override the method to modify the claims in the (or to return a custom ). - - A typical reason for creating a custom claims authentication manager is to add, remove, or transform claims based on information that is only known by or is, perhaps, better maintained by the RP application. For example, a history of customer purchases in a shopping cart application might be kept in a data base maintained by the RP application and then added to the claims principal returned by the claims authentication manager based on the value of a name claim found in the incoming principal. - - You can configure your application to use a `ClaimsAuthenticationManager` either programmatically by using the class or in configuration through the [<claimsAuthenticationManager>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthenticationmanager) element (which is a child element of the [<identityConfiguration>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/identityconfiguration) element). You can override the method to provide processing for custom child elements of the `` element through which your custom manager can be configured. The base implementation of does not handle any child elements. - - Configuring your application to use a claims authentication manager ensures that it will be invoked by Windows Identity Foundation (WIF) from the request pipeline. - - - -## Examples - The following code shows a simple claims authentication manager that adds a role claim to the incoming principal without performing any check on the incoming claims. - - :::code language="csharp" source="~/snippets/csharp/System.Security.Claims/ClaimsAuthenticationManager/Overview/simpleclaimsauthenticatonmanager.cs" id="Snippet1"::: - - The following XML shows the `` element. - -```xml - - - - - ... - - - -``` - + before the RP application code is executed. You can even return a custom implementation of if your RP application requires it. The default implementation provided by the class returns the claims in the unmodified; however, you can derive from this class and override the method to modify the claims in the (or to return a custom ). + + A typical reason for creating a custom claims authentication manager is to add, remove, or transform claims based on information that is only known by or is, perhaps, better maintained by the RP application. For example, a history of customer purchases in a shopping cart application might be kept in a data base maintained by the RP application and then added to the claims principal returned by the claims authentication manager based on the value of a name claim found in the incoming principal. + + You can configure your application to use a `ClaimsAuthenticationManager` either programmatically by using the class or in configuration through the [<claimsAuthenticationManager>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthenticationmanager) element (which is a child element of the [<identityConfiguration>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/identityconfiguration) element). You can override the method to provide processing for custom child elements of the `` element through which your custom manager can be configured. The base implementation of does not handle any child elements. + + Configuring your application to use a claims authentication manager ensures that it will be invoked by Windows Identity Foundation (WIF) from the request pipeline. + + + +## Examples + The following code shows a simple claims authentication manager that adds a role claim to the incoming principal without performing any check on the incoming claims. + + :::code language="csharp" source="~/snippets/csharp/System.Security.Claims/ClaimsAuthenticationManager/Overview/simpleclaimsauthenticatonmanager.cs" id="Snippet1"::: + + The following XML shows the `` element. + +```xml + + + + + ... + + + +``` + ]]> @@ -97,11 +97,11 @@ When overridden in a derived class, returns a object consistent with the requirements of the RP application. The default implementation does not modify the incoming . A claims principal that contains any modifications necessary for the RP application. The default implementation returns the incoming claims principal unmodified. - method is called from the request processing pipeline You can override this method in a derived class to filter, modify, or inject claims into the claims principal according to the policy of your RP application. Depending on the requirements of the RP application, you can even return a custom implementation of . - + method is called from the request processing pipeline You can override this method in a derived class to filter, modify, or inject claims into the claims principal according to the policy of your RP application. Depending on the requirements of the RP application, you can even return a custom implementation of . + ]]> @@ -131,13 +131,13 @@ The custom configuration elements. Each node in the list is of type . When overridden in a derived class, loads custom configuration from XML. - method is called by the configuration infrastructure. When this method is called, the `nodelist` will contain the top-level child elements of the [<claimsAuthenticationManager>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthenticationmanager) element from the configuration file. Each of these elements may, in turn, contain attributes or child elements depending on the configuration schema you define for your derived class. If no child elements appear under the `` element in the configuration file, this method is not called. - - The default implementation throws a . Override this method in your derived class to enable initialization of your claims authentication manager from a configuration file. For example, the configuration elements might describe a policy to be followed when authenticating a claims principal; or they might be used to point to an attribute store from which additional claims are to be added to the principal. - + method is called by the configuration infrastructure. When this method is called, the `nodelist` will contain the top-level child elements of the [<claimsAuthenticationManager>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthenticationmanager) element from the configuration file. Each of these elements may, in turn, contain attributes or child elements depending on the configuration schema you define for your derived class. If no child elements appear under the `` element in the configuration file, this method is not called. + + The default implementation throws a . Override this method in your derived class to enable initialization of your claims authentication manager from a configuration file. For example, the configuration elements might describe a policy to be followed when authenticating a claims principal; or they might be used to point to an attribute store from which additional claims are to be added to the principal. + ]]> diff --git a/xml/System.Security.Claims/ClaimsAuthorizationManager.xml b/xml/System.Security.Claims/ClaimsAuthorizationManager.xml index 92b218f7617..28c46c8e6aa 100644 --- a/xml/System.Security.Claims/ClaimsAuthorizationManager.xml +++ b/xml/System.Security.Claims/ClaimsAuthorizationManager.xml @@ -29,21 +29,21 @@ - When you use the class or the class to perform either imperative or declarative claims-based access checks in your code, the claims authorization manager that is configured for your application is called by the system to perform the check. Claims-based access checks can be performed in both web-based applications and desktop applications. - The default implementation provided by the class authorizes access for each claim presented; however, you can derive from this class and override the method to provide your own authorization logic. + The default implementation provided by the class authorizes access for each claim presented; however, you can derive from this class and override the method to provide your own authorization logic. The use of a claims authorization manager is optional. You can configure your application to use a claims authorization manager either programmatically by using the class or declaratively, by specifying the [<claimsAuthorizationManager>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthorizationmanager) element, which is a child element of the [<identityConfiguration>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/identityconfiguration) element in your application configuration file. If your application is a web site or a web application hosted in Internet Information Services (IIS), you must also add the in the ASP.NET HTTP Modules collection. > [!IMPORTANT] > When you use the class or the class, the claims authorization manager that is used to perform the access check is the one that is specified in the identity configuration under the property. In a configuration file, it is the `` section that is referenced from the default `` element. This is true even for Windows Communication Foundation (WCF) services and desktop applications. - The base class does not take any additional configuration; however, you can override the in derived classes to provide initialization of your claims authorization manager from child elements of the ``. The typical scenario is to use these child elements to specify authorization policies which determine which claim types and values are required in order to gain access to which resource. This is not a hard requirement, though you are free to define whatever usage and syntax make sense for your implementation. + The base class does not take any additional configuration; however, you can override the in derived classes to provide initialization of your claims authorization manager from child elements of the ``. The typical scenario is to use these child elements to specify authorization policies which determine which claim types and values are required in order to gain access to which resource. This is not a hard requirement, though you are free to define whatever usage and syntax make sense for your implementation. ## Examples The code examples that are used in the topics are taken from the `Claims Based Authorization` sample. This sample provides a custom claims authorization manager that can authorize subjects based on a policy that is specified in configuration. The custom claims authorization manager consists of three basic components: a class derived from that implements the manager, the `ResourceAction` class that pairs a resource and an action, and a policy reader that reads and compiles policy that is specified in the configuration file. This compiled policy can then be used by the claims authorization manager to evaluate a principal in order to authorize access to resources. Not all elements are shown for the sake of brevity. For information about this sample and other samples available for WIF and about where to download them, see [WIF Code Sample Index](/previous-versions/dotnet/framework/windows-identity-foundation/wif-code-sample-index). - The following code shows the implementation of the custom claims authorization manager. The method reads and compiles the policy from configuration by using the policy reader helper class (not shown) and the method grants or denies access based on this policy. + The following code shows the implementation of the custom claims authorization manager. The method reads and compiles the policy from configuration by using the policy reader helper class (not shown) and the method grants or denies access based on this policy. :::code language="csharp" source="~/snippets/csharp/System.Security.Claims/AuthorizationContext/Overview/myclaimsauthorizationmanager.cs" id="Snippet2"::: @@ -211,7 +211,7 @@ ## Examples The code examples that are used in the topics are taken from the `Claims Based Authorization` sample. This sample provides a custom claims authorization manager that can authorize subjects based on a policy that is specified in configuration. The custom claims authorization manager consists of three basic components: a class derived from that implements the manager, the `ResourceAction` class that pairs a resource and an action, and a policy reader that reads and compiles policy that is specified in the configuration file. This compiled policy can then be used by the claims authorization manager to evaluate a principal in order to authorize access to resources. Not all elements are shown for the sake of brevity. For information about this sample and other samples available for WIF and about where to download them, see [WIF Code Sample Index](/previous-versions/dotnet/framework/windows-identity-foundation/wif-code-sample-index). - The following code shows the override of the method. This method grants or denies access based on a policy read and compiled from the configuration file. + The following code shows the override of the method. This method grants or denies access based on a policy read and compiled from the configuration file. :::code language="csharp" source="~/snippets/csharp/System.Security.Claims/AuthorizationContext/Overview/myclaimsauthorizationmanager.cs" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Claims/AuthorizationContext/Overview/myclaimsauthorizationmanager.cs" id="Snippet5"::: @@ -220,7 +220,7 @@ :::code language="csharp" source="~/snippets/csharp/System.Security.Claims/AuthorizationContext/Overview/resourceaction.cs" id="Snippet1"::: - The policy used by the claims authorization manager is specified by custom `` elements under the [<claimsAuthorizationManager>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthorizationmanager) element. This policy is read and compiled by the method. In the first policy, the principal must possess one of the specified claims in order to perform the specified action on the specified resource. In the second policy, the principal must possess both claims to be able to perform the specified action on the specified resource. In all others, the principal is automatically granted access regardless of the claims it possesses. + The policy used by the claims authorization manager is specified by custom `` elements under the [<claimsAuthorizationManager>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthorizationmanager) element. This policy is read and compiled by the method. In the first policy, the principal must possess one of the specified claims in order to perform the specified action on the specified resource. In the second policy, the principal must possess both claims to be able to perform the specified action on the specified resource. In all others, the principal is automatically granted access regardless of the claims it possesses. ```xml @@ -284,7 +284,7 @@ method is called by the configuration infrastructure. When this method is called, the `nodelist` will contain the top-level child elements of the [<claimsAuthorizationManager>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthorizationmanager) element from the configuration file. Each of these elements may, in turn, contain attributes or child elements depending on the configuration schema you define for your derived class. If no child elements appear under the `` element in the configuration file, this method is not called. + The method is called by the configuration infrastructure. When this method is called, the `nodelist` will contain the top-level child elements of the [<claimsAuthorizationManager>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthorizationmanager) element from the configuration file. Each of these elements may, in turn, contain attributes or child elements depending on the configuration schema you define for your derived class. If no child elements appear under the `` element in the configuration file, this method is not called. The default implementation throws a . Override this method in your derived class to enable initialization of your claims authorization manager from a configuration file. Typically, the configuration elements are used to express an authorization policy; however, you can define elements and use them in any way that makes sense based on the requirements of your application. @@ -293,7 +293,7 @@ ## Examples The code examples that are used in the topics are taken from the `Claims Based Authorization` sample. This sample provides a custom claims authorization manager that can authorize subjects based on a policy that is specified in configuration. The custom claims authorization manager consists of three basic components: a class derived from that implements the manager, the `ResourceAction` class that pairs a resource and an action, and a policy reader that reads and compiles policy that is specified in the configuration file. This compiled policy can then be used by the claims authorization manager to evaluate a principal in order to authorize access to resources. Not all elements are shown for the sake of brevity. For information about this sample and other samples available for WIF and about where to download them, see [WIF Code Sample Index](/previous-versions/dotnet/framework/windows-identity-foundation/wif-code-sample-index). - The following code shows the override of the method. This method uses a helper policy reader class (not shown) to read and compile authorization policies specified in the configuration file. Policies are added to a dictionary and are accessed by a `ResourceAction` key object that is created from the resource and action for which they are intended. + The following code shows the override of the method. This method uses a helper policy reader class (not shown) to read and compile authorization policies specified in the configuration file. Policies are added to a dictionary and are accessed by a `ResourceAction` key object that is created from the resource and action for which they are intended. :::code language="csharp" source="~/snippets/csharp/System.Security.Claims/AuthorizationContext/Overview/myclaimsauthorizationmanager.cs" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Claims/AuthorizationContext/Overview/myclaimsauthorizationmanager.cs" id="Snippet4"::: @@ -302,7 +302,7 @@ :::code language="csharp" source="~/snippets/csharp/System.Security.Claims/AuthorizationContext/Overview/resourceaction.cs" id="Snippet1"::: - The policy used by the claims authorization manager is specified by custom `` elements under the [<claimsAuthorizationManager>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthorizationmanager) element. This policy is read and compiled by the method. In the first policy, the principal must possess one of the specified claims in order to perform the specified action on the specified resource. In the second policy, the principal must possess both claims to be able to perform the specified action on the specified resource. In all others, the principal is automatically granted access regardless of the claims it possesses. + The policy used by the claims authorization manager is specified by custom `` elements under the [<claimsAuthorizationManager>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthorizationmanager) element. This policy is read and compiled by the method. In the first policy, the principal must possess one of the specified claims in order to perform the specified action on the specified resource. In the second policy, the principal must possess both claims to be able to perform the specified action on the specified resource. In all others, the principal is automatically granted access regardless of the claims it possesses. ```xml diff --git a/xml/System.Security.Claims/ClaimsIdentity.xml b/xml/System.Security.Claims/ClaimsIdentity.xml index 7ccc5218e47..819bb13aeae 100644 --- a/xml/System.Security.Claims/ClaimsIdentity.xml +++ b/xml/System.Security.Claims/ClaimsIdentity.xml @@ -70,17 +70,17 @@ ## Remarks The class is a concrete implementation of a claims-based identity; that is, an identity described by a collection of claims. A claim is a statement about an entity made by an issuer that describes a property, right, or some other quality of that entity. Such an entity is said to be the subject of the claim. A claim is represented by the class. The claims contained in a describe the entity that the corresponding identity represents, and can be used to make authorization and authentication decisions. A claims-based access model has many advantages over more traditional access models that rely exclusively on roles. For example, claims can provide much richer information about the identity they represent and can be evaluated for authorization or authentication in a far more specific manner. - Beginning with .NET Framework 4.5, Windows Identity Foundation (WIF) and claims-based identity have been fully integrated into the .NET Framework. This means that many classes that represent an identity in the .NET Framework now derive from and describe their properties through a collection of claims. This is different from previous versions of the .NET Framework, in which, these classes implemented the interface directly. The collection of claims that describe the identity can be accessed through the property. The class provides several methods for finding and modifying claims and fully supports language integrated queries (LINQ). In application code, objects are typically accessed through objects; for example, the principal returned by . + Beginning with .NET Framework 4.5, Windows Identity Foundation (WIF) and claims-based identity have been fully integrated into the .NET Framework. This means that many classes that represent an identity in the .NET Framework now derive from and describe their properties through a collection of claims. This is different from previous versions of the .NET Framework, in which, these classes implemented the interface directly. The collection of claims that describe the identity can be accessed through the property. The class provides several methods for finding and modifying claims and fully supports language integrated queries (LINQ). In application code, objects are typically accessed through objects; for example, the principal returned by . > [!NOTE] -> The class has a property as well. In the majority of cases you should access the user's claims through the collection rather than through the collection. You will need to access the claims of an individual only in the cases where the principal contains more than one and you need to evaluate or modify a specific identity. +> The class has a property as well. In the majority of cases you should access the user's claims through the collection rather than through the collection. You will need to access the claims of an individual only in the cases where the principal contains more than one and you need to evaluate or modify a specific identity. > [!IMPORTANT] -> To add or remove claims from the collection, a caller must have full trust. +> To add or remove claims from the collection, a caller must have full trust. - In the claims-based model, the property and the method are implemented by evaluating the claims contained by an identity. The base implementations in the claims-based model are provided by the property and the method. The and properties enable you to specify a claim type that should be used to evaluate the claims contained by the identity when performing these operations. + In the claims-based model, the property and the method are implemented by evaluating the claims contained by an identity. The base implementations in the claims-based model are provided by the property and the method. The and properties enable you to specify a claim type that should be used to evaluate the claims contained by the identity when performing these operations. - Delegation scenarios are supported through the and properties. + Delegation scenarios are supported through the and properties. ]]> @@ -144,15 +144,15 @@ |Property|Value| |--------------|-----------| -||`null`.| -||`null`.| -||`null`.| -||A empty collection.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| -||`null`.| -||**Note:** When accessed, the value of the property is returned based on the and the collection.| -||.| -||.| +||`null`.| +||`null`.| +||`null`.| +||A empty collection.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||`null`.| +||**Note:** When accessed, the value of the property is returned based on the and the collection.| +||.| +||.| ]]> @@ -213,15 +213,15 @@ |Property|Value| |--------------|-----------| -||`null`.| -||`null`.| -||`null`.| -||Initialized from the `claims` parameter.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| -||`null`.| -||**Note:** When accessed, the value of the property is returned based on the and the collection.| -||.| -||.| +||`null`.| +||`null`.| +||`null`.| +||Initialized from the `claims` parameter.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||`null`.| +||**Note:** When accessed, the value of the property is returned based on the and the collection.| +||.| +||.| ]]> @@ -270,7 +270,7 @@ . + Normally, the reader is constructed from the bytes returned from . ]]> @@ -381,14 +381,14 @@ | Property | Value | | -------- | ----- | -||If the value of the `other.Actor` property isn't `null`, the `other.Actor` is cloned and assigned; otherwise, `null`.| -||The value of the `other.AuthenticationType` property.| -||The value of the `other.BootstrapContext` property.| -||The `List` of claims, if any, in the `other.Claims` property.| -||The value of the `other.Label` property.| -||The value of the `other.NameClaimType` property.| -||The value of the `other.RoleClaimType` property.| -||If `other.CustomSerializationData` isn't `null`, `other.CustomSerializationData` is cloned and assigned; otherwise, `null`.| +||If the value of the `other.Actor` property isn't `null`, the `other.Actor` is cloned and assigned; otherwise, `null`.| +||The value of the `other.AuthenticationType` property.| +||The value of the `other.BootstrapContext` property.| +||The `List` of claims, if any, in the `other.Claims` property.| +||The value of the `other.Label` property.| +||The value of the `other.NameClaimType` property.| +||The value of the `other.RoleClaimType` property.| +||If `other.CustomSerializationData` isn't `null`, `other.CustomSerializationData` is cloned and assigned; otherwise, `null`.| ]]> @@ -444,15 +444,15 @@ |Property|Value| |--------------|-----------| -||If `identity` is assignable from , the value of the `identity.Actor` property; otherwise, `null`.| -||The value of the `identity.AuthenticationType` () property is used.| -||If `identity` is assignable from , the value of the `identity.BootStrapContext` property; otherwise, `null`.| -||If `identity` is assignable from , the claims from `identity` are added to the new instance; otherwise, an empty collection.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| -||If `identity` is assignable from , the value of the `identity.Label` property; otherwise, `null`.| -||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| -||If `identity` is assignable from , the value of the `identity.NameClaimType` property is used; otherwise, is used.| -||If `identity` is assignable from , the value of the `identity.RoleClaimType` property is used; otherwise, is used.| +||If `identity` is assignable from , the value of the `identity.Actor` property; otherwise, `null`.| +||The value of the `identity.AuthenticationType` () property is used.| +||If `identity` is assignable from , the value of the `identity.BootStrapContext` property; otherwise, `null`.| +||If `identity` is assignable from , the claims from `identity` are added to the new instance; otherwise, an empty collection.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||If `identity` is assignable from , the value of the `identity.Label` property; otherwise, `null`.| +||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| +||If `identity` is assignable from , the value of the `identity.NameClaimType` property is used; otherwise, is used.| +||If `identity` is assignable from , the value of the `identity.RoleClaimType` property is used; otherwise, is used.| ]]> @@ -506,15 +506,15 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| -||`null`.| -||An empty collection.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| -||`null`.| -||**Note:** When accessed, the value of the property is returned based on the and the collection.| -||.| -||.| +||`null`.| +||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| +||`null`.| +||An empty collection.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||`null`.| +||**Note:** When accessed, the value of the property is returned based on the and the collection.| +||.| +||.| ]]> @@ -577,15 +577,15 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| -||`null`.| -||Initialized from the `claims` parameter.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| -||`null`.| -||**Note:** When accessed, the value of the property is returned based on the and the collection.| -||.| -||.| +||`null`.| +||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| +||`null`.| +||Initialized from the `claims` parameter.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||`null`.| +||**Note:** When accessed, the value of the property is returned based on the and the collection.| +||.| +||.| ]]> @@ -770,15 +770,15 @@ |Property|Value| |--------------|-----------| -||If `identity` is assignable from , the value of the `identity.Actor` property; otherwise, `null`.| -||The `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the value of the `identity.AuthenticationType` () property is used.| -||If `identity` is assignable from , the value of the `identity.BootStrapContext` property; otherwise, `null`.| -||Initialized from the `claims` parameter. If `identity` is assignable from , the claims from `identity` are added to the new instance before those specified by the `claims` parameter.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| -||If `identity` is assignable from , the value of the `identity.Label` property; otherwise, `null`.| -||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| -||If `identity` is assignable from , the value of the `identity.NameClaimType` property is used; otherwise, is used.| -||If `identity` is assignable from , the value of the `identity.RoleClaimType` property is used; otherwise, is used.| +||If `identity` is assignable from , the value of the `identity.Actor` property; otherwise, `null`.| +||The `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the value of the `identity.AuthenticationType` () property is used.| +||If `identity` is assignable from , the value of the `identity.BootStrapContext` property; otherwise, `null`.| +||Initialized from the `claims` parameter. If `identity` is assignable from , the claims from `identity` are added to the new instance before those specified by the `claims` parameter.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||If `identity` is assignable from , the value of the `identity.Label` property; otherwise, `null`.| +||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| +||If `identity` is assignable from , the value of the `identity.NameClaimType` property is used; otherwise, is used.| +||If `identity` is assignable from , the value of the `identity.RoleClaimType` property is used; otherwise, is used.| ]]> @@ -836,15 +836,15 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| -||`null`.| -||An empty collection.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| -||`null`.| -||**Note:** When accessed, the value of the property is returned based on the and the collection.| -||The value of the `nameType` parameter. If the `nameType` parameter is null or an empty string, the property is set to .| -||The value of the `roleType` parameter. If the `roleType` parameter is null or an empty string, the property is set to .| +||`null`.| +||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| +||`null`.| +||An empty collection.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||`null`.| +||**Note:** When accessed, the value of the property is returned based on the and the collection.| +||The value of the `nameType` parameter. If the `nameType` parameter is null or an empty string, the property is set to .| +||The value of the `roleType` parameter. If the `roleType` parameter is null or an empty string, the property is set to .| ]]> @@ -911,15 +911,15 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| -||`null`.| -||Initialized from the `claims` parameter.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| -||`null`.| -||**Note:** When accessed, the value of the property is returned based on the and the collection.| -||The value of the `nameType` parameter. However, if the `nameType` parameter is `null` or an empty string, the property is set to .| -||The value of the `roleClaimType` parameter. However, if the `roleClaimType` parameter is `null` or an empty string, the property is set to .| +||`null`.| +||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| +||`null`.| +||Initialized from the `claims` parameter.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||`null`.| +||**Note:** When accessed, the value of the property is returned based on the and the collection.| +||The value of the `nameType` parameter. However, if the `nameType` parameter is `null` or an empty string, the property is set to .| +||The value of the `roleClaimType` parameter. However, if the `roleClaimType` parameter is `null` or an empty string, the property is set to .| ]]> @@ -988,15 +988,15 @@ |Property|Value| |--------------|-----------| -||If `identity` is assignable from , the value of the `identity.Actor` property; otherwise, `null`.| -||The `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the value of the `identity.AuthenticationType` () property is used.| -||If `identity` is assignable from , the value of the `identity.BootStrapContext` property; otherwise, `null`.| -||Initialized from the `claims` parameter. If `identity` is assignable from , the claims from `identity` are added to the new instance before those specified by the `claims` parameter.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| -||If `identity` is assignable from , the value of the `identity.Label` property; otherwise, `null`.| -||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| -||The value of the `nameType` parameter. However, if the value of the `nameType` parameter is `null` or an empty string and `identity` is assignable from , the value of the `identity.NameClaimType` property is used; otherwise, is used.| -||The value of the `roleClaimType` parameter. However, if the value of the `roleClaimType` parameter is `null` or an empty string and identity is assignable from , the value of the `identity.RoleClaimType` property is used; otherwise, is used.| +||If `identity` is assignable from , the value of the `identity.Actor` property; otherwise, `null`.| +||The `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the value of the `identity.AuthenticationType` () property is used.| +||If `identity` is assignable from , the value of the `identity.BootStrapContext` property; otherwise, `null`.| +||Initialized from the `claims` parameter. If `identity` is assignable from , the claims from `identity` are added to the new instance before those specified by the `claims` parameter.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||If `identity` is assignable from , the value of the `identity.Label` property; otherwise, `null`.| +||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| +||The value of the `nameType` parameter. However, if the value of the `nameType` parameter is `null` or an empty string and `identity` is assignable from , the value of the `identity.NameClaimType` property is used; otherwise, is used.| +||The value of the `roleClaimType` parameter. However, if the value of the `roleClaimType` parameter is `null` or an empty string and identity is assignable from , the value of the `identity.RoleClaimType` property is used; otherwise, is used.| ]]> @@ -1164,9 +1164,9 @@ method is invoked with this claims identity as the parameter to create a new claim with the correct subject. + The claim is examined and if the subject is different than this claims identity, the method is invoked with this claims identity as the parameter to create a new claim with the correct subject. - This method has the `SecurityCritical` attribute applied to control which entities can add claims to the identity. Further down the pipe, authorization decisions are made based on the claims that are present in the collection. + This method has the `SecurityCritical` attribute applied to control which entities can add claims to the identity. Further down the pipe, authorization decisions are made based on the claims that are present in the collection. ]]> @@ -1234,9 +1234,9 @@ method is invoked with this claims identity as the parameter to create a new claim with the correct subject. + Each claim is examined and if the subject is different than this claims identity, the method is invoked with this claims identity as the parameter to create a new claim with the correct subject. - This method has the `SecurityCritical` attribute applied to control which entities can add claims to the identity. Further down the pipe, authorization decisions are made based on the claims that are present in the collection. + This method has the `SecurityCritical` attribute applied to control which entities can add claims to the identity. Further down the pipe, authorization decisions are made based on the claims that are present in the collection. ]]> @@ -1421,10 +1421,10 @@ ## Remarks The collection may contain entries that are `null`. - The claims contained in the collection essentially describe the entity that is represented by the . The claims describe the properties and rights possessed by the entity and can be examined by applications to make decisions about authentication and authorization. + The claims contained in the collection essentially describe the entity that is represented by the . The claims describe the properties and rights possessed by the entity and can be examined by applications to make decisions about authentication and authorization. > [!NOTE] -> The class has a property as well. In the majority of cases you should access the user's claims through the collection rather than through the collection. You will need to access the claims of an individual only in the cases where the principal contains more than one and you need to evaluate or modify a specific identity. +> The class has a property as well. In the majority of cases you should access the user's claims through the collection rather than through the collection. You will need to access the claims of an individual only in the cases where the principal contains more than one and you need to evaluate or modify a specific identity. ]]> @@ -2083,7 +2083,7 @@ The comparison is done in or properties. The comparison is made using Ordinal, case sensitive on value; case in-sensitive on type. + Does not check the or properties. The comparison is made using Ordinal, case sensitive on value; case in-sensitive on type. ]]> @@ -2296,7 +2296,7 @@ The comparison is done in property specifies the claim type () that is used to provide the name for this identity. The name is accessed through the property. + The property specifies the claim type () that is used to provide the name for this identity. The name is accessed through the property. This property is set by the constructor. @@ -2358,11 +2358,11 @@ The comparison is done in method, which returns a Boolean value that indicates whether the claim has been removed, throws an exception if the claim could not be removed + It is possible that the claim cannot be removed because it is not owned by the identity. For example, this would be the case for role claims that are owned by the principal. Unlike the method, which returns a Boolean value that indicates whether the claim has been removed, throws an exception if the claim could not be removed - The specified claim is matched by object reference (). + The specified claim is matched by object reference (). - This method has the `SecurityCritical` attribute applied to control which entities can remove claims from the identity. Further down the pipe, authorization decisions are made based on the claims that are present in the collection. + This method has the `SecurityCritical` attribute applied to control which entities can remove claims from the identity. Further down the pipe, authorization decisions are made based on the claims that are present in the collection. ]]> @@ -2412,7 +2412,7 @@ The comparison is done in ) that is used when evaluating this identity for the method. The method is called to determine whether the current principal is in a specified role. The claims-based model extends this check to use claims presented by the principal. A object can contain one or more objects and each identity object can contain multiple objects. The property specifies the claim type of the claim that should be used to provide the value for the role when evaluating this object. The property is set by the constructor. A common value is . + The role claim type is the claim type () that is used when evaluating this identity for the method. The method is called to determine whether the current principal is in a specified role. The claims-based model extends this check to use claims presented by the principal. A object can contain one or more objects and each identity object can contain multiple objects. The property specifies the claim type of the claim that should be used to provide the value for the role when evaluating this object. The property is set by the constructor. A common value is . ]]> @@ -2476,9 +2476,9 @@ The comparison is done in ). + The specified claim is matched by object reference (). - This method has the `SecurityCritical` attribute applied to control which entities can remove claims from the identity. Further down the pipe, authorization decisions are made based on the claims that are present in the collection. + This method has the `SecurityCritical` attribute applied to control which entities can remove claims from the identity. Further down the pipe, authorization decisions are made based on the claims that are present in the collection. ]]> diff --git a/xml/System.Security.Claims/ClaimsPrincipal.xml b/xml/System.Security.Claims/ClaimsPrincipal.xml index 2568529683b..07a5fc7ae18 100644 --- a/xml/System.Security.Claims/ClaimsPrincipal.xml +++ b/xml/System.Security.Claims/ClaimsPrincipal.xml @@ -76,20 +76,20 @@ - The application code itself can work directly with the claims contained in the current principal to drive extra authentication, authorization, and personalization tasks. -- You can front your resources with a claims processing pipeline, which can deal with authentication requests and authorization policy even before execution reaches your code. For example, you can configure a web-based application or service with a custom claims authentication manager, an instance of a class that derives from the class. When so configured, the request processing pipeline invokes the method on your claims authentication manager passing it a that represents the context of the incoming request. Your claims authentication manager can then perform authentication based on the values of the incoming claims. It can also filter, transform, or add claims to the incoming claim set. For example, it could be used to enrich the incoming claim set with new claims created from a local data source such as a local user profile +- You can front your resources with a claims processing pipeline, which can deal with authentication requests and authorization policy even before execution reaches your code. For example, you can configure a web-based application or service with a custom claims authentication manager, an instance of a class that derives from the class. When so configured, the request processing pipeline invokes the method on your claims authentication manager passing it a that represents the context of the incoming request. Your claims authentication manager can then perform authentication based on the values of the incoming claims. It can also filter, transform, or add claims to the incoming claim set. For example, it could be used to enrich the incoming claim set with new claims created from a local data source such as a local user profile -- You can configure a web-based application with a custom claims authorization manager, an instance of a class that derives from the class. When so configured, the request processing pipeline packages the incoming in an and invokes the method on your claims authorization manager. Your claims authorization manager can then enforce authorization based on the incoming claims. +- You can configure a web-based application with a custom claims authorization manager, an instance of a class that derives from the class. When so configured, the request processing pipeline packages the incoming in an and invokes the method on your claims authorization manager. Your claims authorization manager can then enforce authorization based on the incoming claims. - Inline claims-based code access checks can be performed by configuring your application with a custom claims authorization manager and using either the class to perform imperative access checks or the to perform declarative access checks. Claims-based code access checks are performed inline, outside of the processing pipeline, and so are available to all applications as long as a claims authorization manager is configured. - You can obtain a instance for the principal associated with a request, or the principal under which a thread is executing, in a [relying party (RP) application](/archive/msdn-magazine/2010/august/federated-identity-passive-authentication-for-asp-net-with-wif) by casting the property to . The claims associated with an object are available through its property. The property returns all of the claims contained by the identities associated with the principal. In the uncommon case in which the contains multiple instances, you can use the property or you can access the primary identity by using the property. provides several methods through which these claims may be searched and fully supports Language Integrated Query (LINQ). Identities can be added to the principal by using the or methods. + You can obtain a instance for the principal associated with a request, or the principal under which a thread is executing, in a [relying party (RP) application](/archive/msdn-magazine/2010/august/federated-identity-passive-authentication-for-asp-net-with-wif) by casting the property to . The claims associated with an object are available through its property. The property returns all of the claims contained by the identities associated with the principal. In the uncommon case in which the contains multiple instances, you can use the property or you can access the primary identity by using the property. provides several methods through which these claims may be searched and fully supports Language Integrated Query (LINQ). Identities can be added to the principal by using the or methods. > [!NOTE] > To add identities to the , a caller must have full trust. By default, WIF prioritizes objects when selecting the primary identity to return through the property. You can modify this behavior by supplying a delegate through the property to perform the selection. The property provides similar functionality for the property. - In the claim-based model, whether a principal is in a specified role is determined by the claims presented by its underlying identities. The method essentially examines each identity associated with the principal to determine whether it possesses a claim with the specified role value. The type of the claim (represented by its property) used to determine which claims should be examined during role checks is specified on an identity through its property. Thus, the claims examined during role checks can be of a different type for different identities associated with the principal. + In the claim-based model, whether a principal is in a specified role is determined by the claims presented by its underlying identities. The method essentially examines each identity associated with the principal to determine whether it possesses a claim with the specified role value. The type of the claim (represented by its property) used to determine which claims should be examined during role checks is specified on an identity through its property. Thus, the claims examined during role checks can be of a different type for different identities associated with the principal. ## Examples The following example extracts the claims presented by a user in an HTTP request and writes them to the HTTP response. The current user is read from the as a . The claims are then read from it and then are written to the response. @@ -161,7 +161,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) collection is empty). + No identities are associated with the new instance. (The collection is empty). ]]> @@ -210,7 +210,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) collection is initialized with the specified identities. + The collection is initialized with the specified identities. ]]> @@ -261,7 +261,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) is constructed using the bytes from and initialized in the same way as the . + Normally, the is constructed using the bytes from and initialized in the same way as the . ]]> @@ -312,7 +312,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) , it is used to initialize the collection. Otherwise, a is created using the specified identity and is used to initialize the collection. + If the specified identity is assignable from , it is used to initialize the collection. Otherwise, a is created using the specified identity and is used to initialize the collection. ]]> @@ -363,7 +363,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) , all of its identities are added to the collection. If the specified principal is not assignable from , a new is created from the in its property and added to the collection. + If the specified principal is assignable from , all of its identities are added to the collection. If the specified principal is not assignable from , a new is created from the in its property and added to the collection. ]]> @@ -481,7 +481,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) collection. + The identities are added to the collection. ]]> @@ -541,7 +541,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) collection. + The identity is added to the collection. ]]> @@ -812,7 +812,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) is returned. You can change this behavior by setting the property to specify a delegate to be called to determine the current principal. + By default, is returned. You can change this behavior by setting the property to specify a delegate to be called to determine the current principal. ]]> @@ -1293,7 +1293,7 @@ Each is called. or properties. The comparison is made using Ordinal, case sensitive on value; case in-sensitive on type. + Does not check the or properties. The comparison is made using Ordinal, case sensitive on value; case in-sensitive on type. ]]> @@ -1405,7 +1405,7 @@ Each is called. when returning the identity. The first found in the collection is returned. If there is no in the collection, the first identity assignable from is returned. If there is no , `null` is returned. If the collection is empty, an is thrown. + By default, the framework prioritizes identities of type when returning the identity. The first found in the collection is returned. If there is no in the collection, the first identity assignable from is returned. If there is no , `null` is returned. If the collection is empty, an is thrown. You can change the default behavior by setting the property to specify a delegate to be called to determine the identity. @@ -1465,7 +1465,7 @@ Each is called. method checks whether an identity that this claims principal possesses contains a claim of type where the value of the claim is equal to the value specified by the `role` parameter. + The method checks whether an identity that this claims principal possesses contains a claim of type where the value of the claim is equal to the value specified by the `role` parameter. > [!NOTE] > Each has its own definition of the claim type that represents a role. This claim type can be accessed and set through the property. diff --git a/xml/System.Security.Cryptography.Pkcs/AlgorithmIdentifier.xml b/xml/System.Security.Cryptography.Pkcs/AlgorithmIdentifier.xml index 9119146f345..bd2975acd61 100644 --- a/xml/System.Security.Cryptography.Pkcs/AlgorithmIdentifier.xml +++ b/xml/System.Security.Cryptography.Pkcs/AlgorithmIdentifier.xml @@ -76,18 +76,18 @@ The constructor creates an instance of the class by using a set of default parameters. - class has the following default property values. - -|Property|Default value| -|--------------|-------------------| -||1.2.840.113549.3.7 (RSA_DES_EDE3_CBC)| -||The maximum provided by the default Cryptographic Service Provider| - - To gain the highest degree of control over an application constructing an instance of this class, use one of the constructors that allows the algorithm to be set by passing in its object. This guards against the possibility that the default algorithm could change because of security or other considerations. - + class has the following default property values. + +|Property|Default value| +|--------------|-------------------| +||1.2.840.113549.3.7 (RSA_DES_EDE3_CBC)| +||The maximum provided by the default Cryptographic Service Provider| + + To gain the highest degree of control over an application constructing an instance of this class, use one of the constructors that allows the algorithm to be set by passing in its object. This guards against the possibility that the default algorithm could change because of security or other considerations. + ]]> A cryptographic operation could not be completed. @@ -127,11 +127,11 @@ An object identifier for the algorithm. The constructor creates an instance of the class with the specified algorithm identifier. - . - + . + ]]> A cryptographic operation could not be completed. @@ -173,11 +173,11 @@ The length, in bits, of the key. The constructor creates an instance of the class with the specified algorithm identifier and key length. - A cryptographic operation could not be completed. @@ -217,11 +217,11 @@ The property sets or retrieves the key length, in bits. This property is not used for algorithms that use a fixed key length. An int value that represents the key length, in bits. - diff --git a/xml/System.Security.Cryptography.Pkcs/CmsRecipient.xml b/xml/System.Security.Cryptography.Pkcs/CmsRecipient.xml index 913438d7d6a..9033f9ccb3d 100644 --- a/xml/System.Security.Cryptography.Pkcs/CmsRecipient.xml +++ b/xml/System.Security.Cryptography.Pkcs/CmsRecipient.xml @@ -94,8 +94,8 @@ |Property|Default value| |--------------|-------------------| -||| -||null| +||| +||null| ]]> @@ -185,7 +185,7 @@ |Property|Default value| |--------------|-------------------| -||| +||| ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml b/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml index bf498ef4c6c..0f651d3cd39 100644 --- a/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml +++ b/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml @@ -86,9 +86,9 @@ |Property|Default value| |--------------|-------------------| -||| -||2.16.840.1.101.3.4.2.1 (SHA-256)| -||| +||| +||2.16.840.1.101.3.4.2.1 (SHA-256)| +||| ]]> @@ -147,9 +147,9 @@ |Property|Default value| |--------------|-------------------| -||| -||2.16.840.1.101.3.4.2.1 (SHA-256)| -||| +||| +||2.16.840.1.101.3.4.2.1 (SHA-256)| +||| > [!IMPORTANT] > This method is only supported on .NET Framework. Its use on .NET Core throws a . @@ -198,8 +198,8 @@ |Property|Default value| |--------------|-------------------| -||2.16.840.1.101.3.4.2.1 (SHA-256)| -|| if is ,

otherwise| +||2.16.840.1.101.3.4.2.1 (SHA-256)| +|| if is ,

otherwise| ]]> @@ -245,11 +245,11 @@ |Property|Default value| |--------------|-------------------| -||| -||2.16.840.1.101.3.4.2.1 (SHA-256)| -||| +||| +||2.16.840.1.101.3.4.2.1 (SHA-256)| +||| - The signing certificate specified by the `certificate` parameter is not checked for validity on input. To validate the certificate prior to supplying it to this constructor, use the method. + The signing certificate specified by the `certificate` parameter is not checked for validity on input. To validate the certificate prior to supplying it to this constructor, use the method. ]]> @@ -297,10 +297,10 @@ |Property|Default value| |--------------|-------------------| -||2.16.840.1.101.3.4.2.1 (SHA-256)| -|| if is ,

otherwise| +||2.16.840.1.101.3.4.2.1 (SHA-256)| +|| if is ,

otherwise| - The signing certificate specified by the `certificate` parameter is not checked for validity on input. To validate the certificate prior to supplying it to this constructor, use the method. + The signing certificate specified by the `certificate` parameter is not checked for validity on input. To validate the certificate prior to supplying it to this constructor, use the method. ]]> @@ -348,10 +348,10 @@ |Property|Default value| |--------------|-------------------| -||2.16.840.1.101.3.4.2.1 (SHA-256)| -|| if is ,

otherwise| +||2.16.840.1.101.3.4.2.1 (SHA-256)| +|| if is ,

otherwise| - The signing certificate specified by the `certificate` parameter is not checked for validity on input. To validate the certificate prior to supplying it to this constructor, use the method. + The signing certificate specified by the `certificate` parameter is not checked for validity on input. To validate the certificate prior to supplying it to this constructor, use the method. This constructor does not validate that the `privateKey` parameter corresponds to the public key in `certificate`. If the keys don't match, the class and method throw a during the signing process. diff --git a/xml/System.Security.Cryptography.Pkcs/ContentInfo.xml b/xml/System.Security.Cryptography.Pkcs/ContentInfo.xml index cc98efb26c7..2d85f1d0bf0 100644 --- a/xml/System.Security.Cryptography.Pkcs/ContentInfo.xml +++ b/xml/System.Security.Cryptography.Pkcs/ContentInfo.xml @@ -94,7 +94,7 @@ |Property|Default value| |--------------|-------------------| -||1.2.840.113549.1.7.1 (data)| +||1.2.840.113549.1.7.1 (data)| ]]> @@ -142,7 +142,7 @@ ## Remarks The digestedData and encryptedData content types, which appear in the CMS/PKCS #7 standards document, are not content types that can be produced by this implementation. However these content types can be passed to this constructor. - Use the following OID strings as arguments to the constructor to build the `contentType` content type parameter. + Use the following OID strings as arguments to the constructor to build the `contentType` content type parameter. |`contentType` content type|OID string| |--------------------------------|----------------| diff --git a/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml b/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml index c952cc8bff0..7fff036d25e 100644 --- a/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml +++ b/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml @@ -102,8 +102,8 @@ |Property|Default value| |--------------|-------------------| -||Content Type: 1.2.840.113549.1.7.1 (data)
Length: zero| -||1.2.840.113549.3.7 (RSA_DES_EDE3_CBC) or 2.16.840.1.101.3.4.1.42 (AES-256-CBC)| +||Content Type: 1.2.840.113549.1.7.1 (data)
Length: zero| +||1.2.840.113549.3.7 (RSA_DES_EDE3_CBC) or 2.16.840.1.101.3.4.1.42 (AES-256-CBC)| The default for recipients is . @@ -327,9 +327,9 @@ class is being used to to encrypt data, the contents of this collection are embedded into the pending message during the call to one of the methods. Changes after the encryption operation have no effect. + When the class is being used to to encrypt data, the contents of this collection are embedded into the pending message during the call to one of the methods. Changes after the encryption operation have no effect. - The value of this property is replaced with a different collection object during a call to , which then represents the certificates that were read out of the decoded message. + The value of this property is replaced with a different collection object during a call to , which then represents the certificates that were read out of the decoded message. ]]> @@ -374,7 +374,7 @@ ## Remarks When the class is being used to to encrypt data, the value of this property indicates which symmetric encryption algorithm to use to encrypt the content of . - The value of this property is replaced during a call to , which then represents the symmetric encryption algorithm which was used to encrypt the decoded message. + The value of this property is replaced during a call to , which then represents the symmetric encryption algorithm which was used to encrypt the decoded message. ]]> @@ -417,9 +417,9 @@ class is being used to to encrypt data, the value of this property represents the data to encrypt. It is not replaced with encrypted content after a call to an method. + When the class is being used to to encrypt data, the value of this property represents the data to encrypt. It is not replaced with encrypted content after a call to an method. - The value of this property is replaced during a call to , which then represents the encrypted content decoded from the message. After a successful call to a method, the value is replaced again, with the decrypted message contents. + The value of this property is replaced during a call to , which then represents the encrypted content decoded from the message. After a successful call to a method, the value is replaced again, with the decrypted message contents. ]]> @@ -554,7 +554,7 @@ ## Remarks - should be called before or any other method. + should be called before or any other method. The method does not search the computer My store if it is inaccessible. @@ -824,7 +824,7 @@ The following permissions are required to access the decryption key on .NET Fram method. + This method can only be called after a successful call to an method. ]]> @@ -1010,9 +1010,9 @@ The following permissions are required to display the user interface on .NET Fra ## Remarks Although this property is read-only, a modification to the objects in the can be done by using their properties. - The property is not populated as a result of calling the method nor any of the overloaded EnvelopedCms.Encrypt methods. + The property is not populated as a result of calling the method nor any of the overloaded EnvelopedCms.Encrypt methods. - The value of this property is replaced with a different collection object during a call to , which then represents the certificates that were read out of the decoded message. + The value of this property is replaced with a different collection object during a call to , which then represents the certificates that were read out of the decoded message. ]]> @@ -1055,9 +1055,9 @@ The following permissions are required to display the user interface on .NET Fra class is being used to to encrypt data, the contents of this collection are embedded into the pending message during the call to one of the methods. Changes after the encryption operation have no effect. + When the class is being used to to encrypt data, the contents of this collection are embedded into the pending message during the call to one of the methods. Changes after the encryption operation have no effect. - The value of this property is replaced with a different collection object during a call to , which then represents the attributes which were attached to the message without being encrypted. + The value of this property is replaced with a different collection object during a call to , which then represents the attributes which were attached to the message without being encrypted. ]]> @@ -1100,7 +1100,7 @@ The following permissions are required to display the user interface on .NET Fra , which then represents the version number contained within the message. + The value of this property is replaced during a call to , which then represents the version number contained within the message. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs12Builder.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs12Builder.xml index d7ff5b19153..df1b21383de 100644 --- a/xml/System.Security.Cryptography.Pkcs/Pkcs12Builder.xml +++ b/xml/System.Security.Cryptography.Pkcs/Pkcs12Builder.xml @@ -436,9 +436,9 @@ ## Remarks Any hash algorithm that this method accepts can be processed by the class. - Some choices of hash algorithm can cause failures in or on some operating systems, because these methods depend on system libraries for support. + Some choices of hash algorithm can cause failures in or on some operating systems, because these methods depend on system libraries for support. - The hash algorithm used on a fresh installation of Windows 7 when exporting via as a PKCS#12 PFX is with an iteration count of 2000. + The hash algorithm used on a fresh installation of Windows 7 when exporting via as a PKCS#12 PFX is with an iteration count of 2000. Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better; however, some PFX readers might only support SHA-1. ]]> @@ -487,9 +487,9 @@ ## Remarks Any hash algorithm that this method accepts can be processed by the class. - Some choices of hash algorithm can cause failures in or on some operating systems, because these methods depend on system libraries for support. + Some choices of hash algorithm can cause failures in or on some operating systems, because these methods depend on system libraries for support. - The hash algorithm used on a fresh installation of Windows 7 when exporting via as a PKCS#12 PFX is with an iteration count of 2000. + The hash algorithm used on a fresh installation of Windows 7 when exporting via as a PKCS#12 PFX is with an iteration count of 2000. Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better; however, some PFX readers might only support SHA-1. ]]> @@ -530,7 +530,7 @@ ## Remarks This method exists for compatibility with the PKCS#12 specification, but its use is not recommended for purposes other than testing. - When building a PFX that can be used by the overloads of or that do not accept a password parameter, use the method with as the password. + When building a PFX that can be used by the overloads of or that do not accept a password parameter, use the method with as the password. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs12Info.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs12Info.xml index 9061b460096..8d18c710709 100644 --- a/xml/System.Security.Cryptography.Pkcs/Pkcs12Info.xml +++ b/xml/System.Security.Cryptography.Pkcs/Pkcs12Info.xml @@ -161,7 +161,7 @@ It's usually the case that a password-protected PFX uses the same password for the MAC algorithm providing integrity and the encryption algorithm providing confidentiality, but the file format doesn't make that a requirement. - Therefore, there is no guarantee that a password that results in a `true` return from this method will succeed on a call to . + Therefore, there is no guarantee that a password that results in a `true` return from this method will succeed on a call to . ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeBag.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeBag.xml index a5462a98c03..89fa636a2c5 100644 --- a/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeBag.xml +++ b/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeBag.xml @@ -64,15 +64,15 @@ to store without making a defensive copy; otherwise, . The default is . Called from constructors in derived classes to initialize the class. - or . + + If the `bagIdValue` is not a legal dotted decimal format of an OID value an exception will be thrown from or . ]]> The parameter is or the empty string. @@ -172,13 +172,13 @@ Gets the ASN.1 BER encoding of the contents of this SafeBag. The ASN.1 BER encoding of the contents of this SafeBag. - or , - and is removed during and similar methods. + The explicit tag is automatically applied by or , + and is removed during and similar methods. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml index ff6b30b8faa..bce25652369 100644 --- a/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml +++ b/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml @@ -743,7 +743,7 @@ The contents were not successfully decrypted. ## Remarks -A is read-only when the value is created to represent previously encoded values, such as from or the encoding operation internal to . +A is read-only when the value is created to represent previously encoded values, such as from or the encoding operation internal to . ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs9SigningTime.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs9SigningTime.xml index 054b940d9b6..e7b28b9ce29 100644 --- a/xml/System.Security.Cryptography.Pkcs/Pkcs9SigningTime.xml +++ b/xml/System.Security.Cryptography.Pkcs/Pkcs9SigningTime.xml @@ -42,12 +42,12 @@ Defines the signing date and time of a signature. A object can be used as an authenticated attribute of a object when an authenticated date and time are to accompany a digital signature. - @@ -91,17 +91,17 @@ A signing time attribute is also available in CAPICOM. For more information, see The constructor creates an instance of the class. - class has the following default property values. - -|Property|Default value| -|--------------|-------------------| -||The current date and time| - - If you want to specify a specific date and time for the object, use the constructor. - + class has the following default property values. + +|Property|Default value| +|--------------|-------------------| +||The current date and time| + + If you want to specify a specific date and time for the object, use the constructor. + ]]> @@ -215,11 +215,11 @@ A signing time attribute is also available in CAPICOM. For more information, see The object from which to copy information. Copies information from a object. - object with the specified object. - + object with the specified object. + ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/SignedCms.xml b/xml/System.Security.Cryptography.Pkcs/SignedCms.xml index 0f6e24a3881..13c6e7b0c7b 100644 --- a/xml/System.Security.Cryptography.Pkcs/SignedCms.xml +++ b/xml/System.Security.Cryptography.Pkcs/SignedCms.xml @@ -98,8 +98,8 @@ |Property|Default value| |--------------|-------------------| -||1.2.840.113549.1.7.1 (data)Length: zero| -||Detached state: `false` The content that is signed is included in the CMS/PKCS #7 message along with the signature information.| +||1.2.840.113549.1.7.1 (data)Length: zero| +||Detached state: `false` The content that is signed is included in the CMS/PKCS #7 message along with the signature information.| The default for signers is SubjectIdentifierType.IssuerAndSerialNumber. @@ -529,12 +529,12 @@ ## Examples - The following example shows the placement of among the steps necessary to verify the signatures on a message. In this example, the message content is not detached. The message content is included in the message. + The following example shows the placement of among the steps necessary to verify the signatures on a message. In this example, the message content is not detached. The message content is included in the message. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/mpkcs_SignedCMS/cs/Program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Pkcs/SignedCms/CheckSignature/Program.vb" id="Snippet1"::: - The following example shows the placement of among the steps necessary to verify the signatures on a message. In this example, the message content is detached, so the message content must verified independently of the message. + The following example shows the placement of among the steps necessary to verify the signatures on a message. In this example, the message content is detached, so the message content must verified independently of the message. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/mpkcs_SignedCMS/cs/Program.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Pkcs/SignedCms/CheckSignature/Program.vb" id="Snippet2"::: @@ -882,12 +882,12 @@ The following permissions are required to access the signature key on .NET Frame ## Examples - The following example shows the placement of the method in the process of verifying the signatures on a message. In this example, the message content is not detached, so the message content is included in the message. + The following example shows the placement of the method in the process of verifying the signatures on a message. In this example, the message content is not detached, so the message content is included in the message. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/mpkcs_SignedCMS/cs/Program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Pkcs/SignedCms/CheckSignature/Program.vb" id="Snippet1"::: - The following example shows the placement of the method in the process of verifying the signatures on a message. In this example, the message content is detached, so the message content must be verified independently of the message. + The following example shows the placement of the method in the process of verifying the signatures on a message. In this example, the message content is detached, so the message content must be verified independently of the message. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/mpkcs_SignedCMS/cs/Program.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Pkcs/SignedCms/CheckSignature/Program.vb" id="Snippet2"::: diff --git a/xml/System.Security.Cryptography.X509Certificates/PublicKey.xml b/xml/System.Security.Cryptography.X509Certificates/PublicKey.xml index 02ac69bf380..6f70738721d 100644 --- a/xml/System.Security.Cryptography.X509Certificates/PublicKey.xml +++ b/xml/System.Security.Cryptography.X509Certificates/PublicKey.xml @@ -65,7 +65,7 @@ object contains the object identifier () representing the public key algorithm, the ASN-encoded parameters, and the ASN.1-encoded key value. + The object contains the object identifier () representing the public key algorithm, the ASN-encoded parameters, and the ASN.1-encoded key value. @@ -76,7 +76,7 @@ :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/PublicKey/Overview/program.vb" id="Snippet1"::: The following example creates a command-line executable that takes a certificate file as an argument and prints various certificate properties to the console. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/PublicKey/Overview/certinfo.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/PublicKey/Overview/certinfo.vb" id="Snippet1"::: diff --git a/xml/System.Security.Cryptography.X509Certificates/X500DistinguishedName.xml b/xml/System.Security.Cryptography.X509Certificates/X500DistinguishedName.xml index 43a6bf4b477..2358025a5dd 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X500DistinguishedName.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X500DistinguishedName.xml @@ -65,7 +65,7 @@ or property, which is the name of the person or entity that the certificate is being issued to. X.500 is an international standard for distributed directory services. The distinguished name uses the following format: + This class is like an extension to the or property, which is the name of the person or entity that the certificate is being issued to. X.500 is an international standard for distributed directory services. The distinguished name uses the following format: [X500:/C=CountryCode/O=Organization/OU=OrganizationUnit/CN=CommonName] diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml b/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml index 0d2fdfcfc2d..ee0ade0cf66 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml @@ -106,14 +106,14 @@ For most scenarios, you should use the class instead. > [!IMPORTANT] -> Starting with the .NET Framework 4.6, 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. +> Starting with the .NET Framework 4.6, 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. > > For apps that target the .NET Framework 4.5.2 and earlier versions, the class does not implement the interface and therefore does not have a `Dispose` method. ## Examples - The following example loads an X.509 certificate from a file, calls the method, and displays the results to the console. + The following example loads an X.509 certificate from a file, calls the method, and displays the results to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/Overview/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/Overview/example.vb" id="Snippet1"::: @@ -493,7 +493,7 @@ ## Examples - The following example loads an X.509 certificate from a file, calls the method, and displays the results to the console. + The following example loads an X.509 certificate from a file, calls the method, and displays the results to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/Overview/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/Overview/example.vb" id="Snippet1"::: @@ -2182,7 +2182,7 @@ falls back to a calendar that can express the date. If the value is , the calendar is changed to the class; otherwise, it is changed to the . + Some cultures cannot convert future dates into strings. If the expiration date of an X.509 certificate is beyond the range of the culture, falls back to a calendar that can express the date. If the value is , the calendar is changed to the class; otherwise, it is changed to the . ]]> @@ -2242,7 +2242,7 @@ method to fill an array of bytes with the hash value for an X.509 certificate. + The following example uses the method to fill an array of bytes with the hash value for an X.509 certificate. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/GetCertHash/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/GetCertHash/example.vb" id="Snippet1"::: @@ -2358,7 +2358,7 @@ method to get an X.509 certificate hash value, convert it to a string, and display it to the console. + The following example uses the method to get an X.509 certificate hash value, convert it to a string, and display it to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/GetCertHashString/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/GetCertHashString/example.vb" id="Snippet1"::: @@ -2464,12 +2464,12 @@ ## Remarks The effective date is the date after which the X.509 certificate is considered valid. - 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. + 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. ## Examples - The following example uses the method to get the effective date of a certificate and displays it to the console. + The following example uses the method to get the effective date of a certificate and displays it to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/GetEffectiveDateString/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/GetEffectiveDateString/example.vb" id="Snippet1"::: @@ -2527,7 +2527,7 @@ ## Remarks The expiration date is the date after which the X.509 certificate is no longer considered valid. - 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. + 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. @@ -2535,7 +2535,7 @@ ## Examples - The following example uses the method to get the expiration date of a certificate and displays it to the console. + The following example uses the method to get the expiration date of a certificate and displays it to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/GetExpirationDateString/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/GetExpirationDateString/example.vb" id="Snippet1"::: @@ -2598,7 +2598,7 @@ ## Examples - The following example uses the method to get the format of a certificate and displays it to the console. + The following example uses the method to get the format of a certificate and displays it to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/GetFormat/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/GetFormat/example.vb" id="Snippet1"::: @@ -2667,7 +2667,7 @@ ## Examples - The following example uses the method to return an integer representation of a certificate's hash code and displays it to the console. + The following example uses the method to return an integer representation of a certificate's hash code and displays it to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/GetHashCode/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/GetHashCode/example.vb" id="Snippet1"::: @@ -2802,7 +2802,7 @@ method to get a certificate's key algorithm in string format and displays it to the console. + The following example uses the method to get a certificate's key algorithm in string format and displays it to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/GetKeyAlgorithm/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/GetKeyAlgorithm/example.vb" id="Snippet1"::: @@ -2868,7 +2868,7 @@ method to return a certificate's key algorithm parameters as an array of bytes and displays it to the console. + The following example uses the method to return a certificate's key algorithm parameters as an array of bytes and displays it to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/GetKeyAlgorithmParameters/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/GetKeyAlgorithmParameters/example.vb" id="Snippet1"::: @@ -2934,7 +2934,7 @@ method to return a certificate's key algorithm parameters in string format and displays it to the console. + The following example uses the method to return a certificate's key algorithm parameters in string format and displays it to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/GetKeyAlgorithmParametersString/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/GetKeyAlgorithmParametersString/example.vb" id="Snippet1"::: @@ -3066,7 +3066,7 @@ This value corresponds to the contents of the `subjectPublicKey` field of the SubjectPublicKeyInfo data within the certificate. ## Examples - The following example uses the method to return a certificate's public key as an array of bytes and displays it to the console. + The following example uses the method to return a certificate's public key as an array of bytes and displays it to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/GetPublicKey/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/GetPublicKey/example.vb" id="Snippet1"::: @@ -3125,7 +3125,7 @@ This value corresponds to the contents of the `subjectPublicKey` field of the Su This value corresponds to the contents of the `subjectPublicKey` field of the SubjectPublicKeyInfo data within the certificate. ## Examples - The following example uses the method to return a certificate's public key as a string and displays it to the console. + The following example uses the method to return a certificate's public key as a string and displays it to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/GetPublicKeyString/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/GetPublicKeyString/example.vb" id="Snippet1"::: @@ -3186,10 +3186,10 @@ This value corresponds to the contents of the `subjectPublicKey` field of the Su method with an output encoding of . +The output of this method is equivalent to the output of the method with an output encoding of . ## Examples - The following example uses the method to return a certificate's raw data as an array of bytes and displays it to the console. + The following example uses the method to return a certificate's raw data as an array of bytes and displays it to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/GetRawCertData/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/GetRawCertData/example.vb" id="Snippet1"::: @@ -3245,7 +3245,7 @@ The output of this method is equivalent to the output of the method to return a certificate's raw data as a string and displays it to the console. + The following example uses the method to return a certificate's raw data as a string and displays it to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/GetRawCertDataString/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/GetRawCertDataString/example.vb" id="Snippet1"::: @@ -3309,7 +3309,7 @@ The output of this method is equivalent to the output of the method to return a certificate's serial number as an array of bytes and displays it to the console. + The following example uses the method to return a certificate's serial number as an array of bytes and displays it to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/GetSerialNumber/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/GetSerialNumber/example.vb" id="Snippet1"::: @@ -3366,7 +3366,7 @@ The output of this method is equivalent to the output of the method to return a certificate's serial number as a string and displays it to the console. + The following example uses the method to return a certificate's serial number as a string and displays it to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/GetSerialNumberString/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/GetSerialNumberString/example.vb" id="Snippet1"::: @@ -3597,7 +3597,7 @@ The output of this method is equivalent to the output of the method, and displays the results to the console. + The following example loads an X.509 certificate from a file, calls the method, and displays the results to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/Import/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/Import/sample.vb" id="Snippet1"::: @@ -4074,7 +4074,7 @@ The output of this method is equivalent to the output of the method to reset the state of the certificate. This method also frees any resources associated with the certificate. + Use the method to reset the state of the certificate. This method also frees any resources associated with the certificate. ]]> @@ -4340,7 +4340,7 @@ The output of this method is equivalent to the output of the method to display the value of a certificate to the console. + The following example uses the method to display the value of a certificate to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/CreateFromCertFile/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/CreateFromCertFile/example.vb" id="Snippet1"::: @@ -4408,7 +4408,7 @@ The output of this method is equivalent to the output of the method to display the value of a certificate to the console. + The following example uses the method to display the value of a certificate to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/CreateFromCertFile/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/CreateFromCertFile/example.vb" id="Snippet1"::: diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2.xml b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2.xml index 98f76634a68..5a3cfd5fd15 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2.xml @@ -73,7 +73,7 @@ The X.509 structure originated in the International Organization for Standardization (ISO) working groups. This structure can be used to represent various types of information including identity, entitlement, and holder attributes (permissions, age, sex, location, affiliation, and so forth). Although the ISO specifications are most informative on the structure itself, the class is designed to model the usage scenarios defined in specifications issued by the Internet Engineering Task Force (IETF) Public Key Infrastructure, X.509 (PKIX) working group. The most informative of these specifications is RFC 3280, "[Certificate and Certificate Revocation List (CRL) Profile](https://go.microsoft.com/fwlink/?LinkId=45286)." > [!IMPORTANT] -> Starting with the .NET Framework 4.6, 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. +> Starting with the .NET Framework 4.6, 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. > > For apps that target the .NET Framework 4.5.2 and earlier versions, the class does not implement the interface and therefore does not have a `Dispose` method. @@ -1417,7 +1417,7 @@ If you create an object unless the property is set to `true`. No physical archival activity occurs when the value is set or unset. + In an X.509 store, archived certificates are not included in the returned object unless the property is set to `true`. No physical archival activity occurs when the value is set or unset. @@ -3446,7 +3446,7 @@ The certificate is encoded according to the IETF RFC 7468 "strict" method. + This property contains the name of the certificate authority (CA) that issued the certificate. To obtain the name of a certificate, use the method. The distinguished name for the certificate is a textual representation of the certificate subject or issuer. This representation consists of name attributes (for example, "CN=MyName, OU=MyOrgUnit, C=US"). @@ -3721,7 +3721,7 @@ The Subject Alternative Name extension or Subject Name could not be decoded. [!WARNING] > If you set this property to `null` or to another key without first deleting it, a private key file is left on the disk. - To properly delete the private key associated with this property, set `PersistKeyInCsp` to `false`, and then call the method. + To properly delete the private key associated with this property, set `PersistKeyInCsp` to `false`, and then call the method. @@ -3788,7 +3788,7 @@ The Subject Alternative Name extension or Subject Name could not be decoded. object, which contains the object identifier () representing the public key algorithm, the ASN.1-encoded parameters, and the ASN.1-encoded key value. + This property returns a object, which contains the object identifier () representing the public key algorithm, the ASN.1-encoded parameters, and the ASN.1-encoded key value. You can also obtain the key as an object by referencing the property. This property supports only RSA or DSA keys, so it returns either an or a object that represents the public key. @@ -4266,7 +4266,7 @@ Unlike object to obtain precise information about the content or use the method to obtain information about the certificate. + As with all `ToString` methods, the output might not be consistent across versions of the .NET Framework, so the method results should not be parsed for content. Use the properties on the object to obtain precise information about the content or use the method to obtain information about the certificate. This method displays the certificate in text format. diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Collection.xml b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Collection.xml index b5fd8215227..ad1b728afee 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Collection.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Collection.xml @@ -451,7 +451,7 @@ objects to add to an object. The and methods process requests transactionally, so that if a single add or remove fails, the entire operation is aborted. + Use this method if you have an array of objects to add to an object. The and methods process requests transactionally, so that if a single add or remove fails, the entire operation is aborted. ]]> @@ -509,7 +509,7 @@ object that you want to add to another object. The and methods process requests transactionally, so that if a single add or remove fails, the entire operation is aborted. + Use this method if you have certificates in an object that you want to add to another object. The and methods process requests transactionally, so that if a single add or remove fails, the entire operation is aborted. ]]> @@ -569,9 +569,9 @@ property. That is, this method is an O(`n`) operation, where `n` is . + This method performs a linear search; therefore, the average execution time is proportional to the property. That is, this method is an O(`n`) operation, where `n` is . - This method determines equality by calling the method. + This method determines equality by calling the method. ]]> @@ -978,7 +978,7 @@ objects if no user interaction is needed. Use the method to allow the user to select objects. + Use this method to find objects if no user interaction is needed. Use the method to allow the user to select objects. Note that this method can be used in a cascading or nested style, narrowing the search criteria with each call to the method. @@ -1900,7 +1900,7 @@ ## Remarks If the property already equals the capacity of the list, the capacity is doubled by automatically reallocating the internal array before the new element is inserted. - If `index` is equal to , `certificate` is added to the end of the collection. + If `index` is equal to , `certificate` is added to the end of the collection. ]]> @@ -2111,7 +2111,7 @@ objects to remove from an object. The and methods process requests transactionally, so that if a single add or remove fails, the entire operation is aborted. + Use this method if you have an array of objects to remove from an object. The and methods process requests transactionally, so that if a single add or remove fails, the entire operation is aborted. ]]> @@ -2169,7 +2169,7 @@ object that you want to remove from another object. The and methods process requests transactionally, so that if a single add or remove fails, the entire operation is aborted. + Use this method if you have certificates in an object that you want to remove from another object. The and methods process requests transactionally, so that if a single add or remove fails, the entire operation is aborted. ]]> diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Enumerator.xml b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Enumerator.xml index d45260f7311..c12e3abeed6 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Enumerator.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Enumerator.xml @@ -76,7 +76,7 @@ ## Remarks Enumerators provide read-only access to the data in the collection. Enumerators cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. The method also brings the enumerator back to this position. At this position, calling the property throws an exception. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . + Initially, the enumerator is positioned before the first element in the collection. The method also brings the enumerator back to this position. At this position, calling the property throws an exception. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . This class inherits from the interface. For more information about enumerating over a collection, see . @@ -140,7 +140,7 @@ does not move the position of the enumerator. Consecutive calls to the property return the same object until either the or method is called. + does not move the position of the enumerator. Consecutive calls to the property return the same object until either the or method is called. ]]> @@ -250,7 +250,7 @@ or method throws an . + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying or deleting elements, the enumerator is irrecoverably invalidated and the next call to the or method throws an . ]]> diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2UI.xml b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2UI.xml index cb6bca64fe2..ed898d020d2 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2UI.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2UI.xml @@ -48,7 +48,7 @@ ## Examples The following code example demonstrates how to display user interface dialogs to select and view X.509 certificates. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/PublicKey/Key/certselect.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/PublicKey/Key/certselect.vb" id="Snippet1"::: @@ -142,7 +142,7 @@ method displays a dialog box with detailed information about the specified X.509 certificate. The dialog box includes buttons for installing or copying the certificate. + The method displays a dialog box with detailed information about the specified X.509 certificate. The dialog box includes buttons for installing or copying the certificate. @@ -204,7 +204,7 @@ method displays a dialog box with detailed information about the specified X.509 certificate. This method can be used to nest dialog boxes that display certificate information. The dialog box includes buttons for installing or copying the certificate. + The method displays a dialog box with detailed information about the specified X.509 certificate. This method can be used to nest dialog boxes that display certificate information. The dialog box includes buttons for installing or copying the certificate. ]]> @@ -223,7 +223,7 @@ method. + Use this method if you require users to manually select X.509 certificates using a dialog box. If no user interaction is required, use the method. ]]> @@ -289,7 +289,7 @@ method if you require users to manually select X.509 certificates using a dialog box. If no user interaction is required, use the method. + Use the method if you require users to manually select X.509 certificates using a dialog box. If no user interaction is required, use the method. @@ -374,7 +374,7 @@ method if you require users to manually select X.509 certificates using a dialog box. If no user interaction is required, use the method. + Use the method if you require users to manually select X.509 certificates using a dialog box. If no user interaction is required, use the method. ]]> diff --git a/xml/System.Security.Cryptography.X509Certificates/X509CertificateCollection+X509CertificateEnumerator.xml b/xml/System.Security.Cryptography.X509Certificates/X509CertificateCollection+X509CertificateEnumerator.xml index 491147736d5..8b03c7f266b 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509CertificateCollection+X509CertificateEnumerator.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509CertificateCollection+X509CertificateEnumerator.xml @@ -72,7 +72,7 @@ ## Remarks Enumerators provide read-only access to the data in the collection. Enumerators cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. The method also brings the enumerator back to this position. At this position, calling the property throws an exception. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . + Initially, the enumerator is positioned before the first element in the collection. The method also brings the enumerator back to this position. At this position, calling the property throws an exception. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . This class inherits from the interface. For more information about enumerating over a collection, see . @@ -175,7 +175,7 @@ does not move the position of the enumerator. Consecutive calls to the property return the same object until either the or method is called. + does not move the position of the enumerator. Consecutive calls to the property return the same object until either the or method is called. ]]> @@ -287,7 +287,7 @@ or method throws an . + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying or deleting elements, the enumerator is irrecoverably invalidated and the next call to the or method throws an . ]]> diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Chain.xml b/xml/System.Security.Cryptography.X509Certificates/X509Chain.xml index d1ecd1c27db..6dcf3d4a4d1 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Chain.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Chain.xml @@ -74,10 +74,10 @@ 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. + 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] -> Starting with the .NET Framework 4.6, 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. +> Starting with the .NET Framework 4.6, 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. > > For apps that target the .NET Framework 4.5.2 and earlier versions, the class does not implement the interface and therefore does not have a `Dispose` method. @@ -85,7 +85,7 @@ ## Examples The following code example opens the current user's personal certificate store, allows you to select a certificate, then writes certificate and certificate chain information to the console. The output depends on the certificate you select. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Chain/Overview/x509chaintest.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Chain/Overview/x509chaintest.vb" id="Snippet1"::: @@ -349,7 +349,7 @@ object. Certificates that meet these chain policy rules might still be invalid for specific uses with such features as Security/MIME (SMIME), Authenticode, or Secure Sockets Layer (SSL). If further processing is required to determine whether the certificate is valid for a specific policy, derive a class from and override the method so that it calls the base class `Build` method first, and then does the additional processing. + Note that a valid X.509 certificate from a trusted issuer is valid only for the use specified in the object. Certificates that meet these chain policy rules might still be invalid for specific uses with such features as Security/MIME (SMIME), Authenticode, or Secure Sockets Layer (SSL). If further processing is required to determine whether the certificate is valid for a specific policy, derive a class from and override the method so that it calls the base class `Build` method first, and then does the additional processing. @@ -469,7 +469,7 @@ object is a representation of an element in the chain that was built during a call to the method. + Each object is a representation of an element in the chain that was built during a call to the method. A chain element consists of an object, an structure, and an extra information string. diff --git a/xml/System.Security.Cryptography.X509Certificates/X509ChainElementCollection.xml b/xml/System.Security.Cryptography.X509Certificates/X509ChainElementCollection.xml index 6703f21ba12..d50b99675f3 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509ChainElementCollection.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509ChainElementCollection.xml @@ -262,7 +262,7 @@ class implements , which enables you to use methods such as , and to view the contents of the collection. + The class implements , which enables you to use methods such as , and to view the contents of the collection. ]]> diff --git a/xml/System.Security.Cryptography.X509Certificates/X509ChainElementEnumerator.xml b/xml/System.Security.Cryptography.X509Certificates/X509ChainElementEnumerator.xml index d721a3284d5..fd025cb2ce9 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509ChainElementEnumerator.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509ChainElementEnumerator.xml @@ -71,15 +71,15 @@ Supports a simple iteration over an . This class cannot be inherited. - resets the enumerator to this position. At this position, calling throws an exception. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . - - This class inherits from . See the class for more information about enumerating over a collection. - + resets the enumerator to this position. At this position, calling throws an exception. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . + + This class inherits from . See the class for more information about enumerating over a collection. + ]]> @@ -137,11 +137,11 @@ Gets the current element in the . The current element in the . - does not move the position of the enumerator and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator and consecutive calls to return the same object until either or is called. + ]]> The enumerator is positioned before the first element of the collection or after the last element. @@ -196,11 +196,11 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - class inherits from ; see this class for more information on using enumerators. - + class inherits from ; see this class for more information on using enumerators. + ]]> The collection was modified after the enumerator was created. @@ -253,11 +253,11 @@ Sets the enumerator to its initial position, which is before the first element in the . - or throws an . - + or throws an . + ]]> The collection was modified after the enumerator was created. @@ -316,11 +316,11 @@ Gets the current element in the . The current element in the . - does not move the position of the enumerator and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator and consecutive calls to return the same object until either or is called. + ]]> The enumerator is positioned before the first element of the collection or after the last element. diff --git a/xml/System.Security.Cryptography.X509Certificates/X509ChainStatus.xml b/xml/System.Security.Cryptography.X509Certificates/X509ChainStatus.xml index b07e148a438..3bfe5a712bb 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509ChainStatus.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509ChainStatus.xml @@ -207,7 +207,7 @@ enumeration. + This property is a localized string that provides a description of the enumeration. diff --git a/xml/System.Security.Cryptography.X509Certificates/X509ExtensionCollection.xml b/xml/System.Security.Cryptography.X509Certificates/X509ExtensionCollection.xml index 2e2c66e56fe..9ebccb66576 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509ExtensionCollection.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509ExtensionCollection.xml @@ -179,7 +179,7 @@ method allows duplicate elements to be added to the collection. + The method allows duplicate elements to be added to the collection. ]]> @@ -585,7 +585,7 @@ interface. The .NET Framework classes based on provide their own synchronized version of the collection using the property. Classes that use arrays can also implement their own synchronization using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection. Note that some implementations of might return the array itself. + This property implements the interface. The .NET Framework classes based on provide their own synchronized version of the collection using the property. Classes that use arrays can also implement their own synchronization using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection. Note that some implementations of might return the array itself. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. diff --git a/xml/System.Security.Cryptography.X509Certificates/X509ExtensionEnumerator.xml b/xml/System.Security.Cryptography.X509Certificates/X509ExtensionEnumerator.xml index acc77708149..7c83c21c0b0 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509ExtensionEnumerator.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509ExtensionEnumerator.xml @@ -71,15 +71,15 @@ Supports a simple iteration over a . This class cannot be inherited. - also brings the enumerator back to this position. At this position, calling throws an exception. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . - - This class inherits from the interface. For more information about enumerating over a collection, see the topic. - + also brings the enumerator back to this position. At this position, calling throws an exception. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . + + This class inherits from the interface. For more information about enumerating over a collection, see the topic. + ]]> @@ -137,11 +137,11 @@ Gets the current element in the . The current element in the . - does not move the position of the enumerator and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator and consecutive calls to return the same object until either or is called. + ]]> The enumerator is positioned before the first element of the collection or after the last element. @@ -196,11 +196,11 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - interface. For more information about enumerating over a collection, see the topic. - + interface. For more information about enumerating over a collection, see the topic. + ]]> The collection was modified after the enumerator was created. @@ -253,11 +253,11 @@ Sets the enumerator to its initial position, which is before the first element in the . - or throws an . - + or throws an . + ]]> The collection was modified after the enumerator was created. @@ -316,11 +316,11 @@ Gets an object from a collection. The current element in the . - does not move the position of the enumerator and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator and consecutive calls to return the same object until either or is called. + ]]> The enumerator is positioned before the first element of the collection or after the last element. diff --git a/xml/System.Security.Cryptography.X509Certificates/X509FindType.xml b/xml/System.Security.Cryptography.X509Certificates/X509FindType.xml index 8cf4c34a0c3..56d4414b31a 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509FindType.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509FindType.xml @@ -58,7 +58,7 @@ identifies the type of value provided in the `findValue` parameter for the method. You can use to search an collection by subject name, thumbprint, serial number, valid date range, or other value. + identifies the type of value provided in the `findValue` parameter for the method. You can use to search an collection by subject name, thumbprint, serial number, valid date range, or other value. You can use a combination of `FindByTime` value types to find certificates that are valid in a given time range. The union of certificates returned using FindByTimeValid, FindByTimeNotYetValid, and FindByTimeExpired for a given time represents all certificates in the queried collection. @@ -66,7 +66,7 @@ ## Examples The following example opens the current user's personal certificate store, finds only valid certificates, allows the user to select a certificate, and then writes certificate information to the console. The output depends on the certificate you select. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/PublicKey/Key/certselect.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/PublicKey/Key/certselect.vb" id="Snippet1"::: diff --git a/xml/System.Security.Cryptography.X509Certificates/X509KeyUsageExtension.xml b/xml/System.Security.Cryptography.X509Certificates/X509KeyUsageExtension.xml index 731a1587cf7..6ccbb7e0b17 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509KeyUsageExtension.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509KeyUsageExtension.xml @@ -343,7 +343,7 @@ enumeration that indicates how to use the certificate key. + This property returns a value from the enumeration that indicates how to use the certificate key. ]]> diff --git a/xml/System.Security.Cryptography.X509Certificates/X509NameType.xml b/xml/System.Security.Cryptography.X509Certificates/X509NameType.xml index c33afcad9b4..5dba0b2e951 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509NameType.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509NameType.xml @@ -58,13 +58,13 @@ . + The name type can be a simple name, an email address, a User Principal Name (UPN), a Domain Name System (DNS) name or a URL. An X509 certificate can have one or more of these names. You can obtain the name of a certificate using the method . ## Examples The following example opens the current user certificate store, selects only active certificates, then allows the user to select one or more certificates. The example then writes certificate information to the console. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/PublicKey/Key/certselect.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/PublicKey/Key/certselect.vb" id="Snippet1"::: diff --git a/xml/System.Security.Cryptography.X509Certificates/X509SelectionFlag.xml b/xml/System.Security.Cryptography.X509Certificates/X509SelectionFlag.xml index 52d62cf3dfb..ea3143ccbc1 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509SelectionFlag.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509SelectionFlag.xml @@ -31,13 +31,13 @@ method. + This flag represents either a single or multiple certificate selection using the method. ## Examples - The following code example demonstrates how to use the selection flag with the method. This code example is part of a larger example provided for the class. The larger example opens the current user's personal certificate store, allows the user to select a certificate, then writes certificate and certificate chain information to the console. The output depends on the certificate the user selects. - + The following code example demonstrates how to use the selection flag with the method. This code example is part of a larger example provided for the class. The larger example opens the current user's personal certificate store, allows the user to select a certificate, then writes certificate and certificate chain information to the console. The output depends on the certificate the user selects. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Chain/Overview/x509chaintest.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Chain/Overview/x509chaintest.vb" id="Snippet2"::: diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Store.xml b/xml/System.Security.Cryptography.X509Certificates/X509Store.xml index b89c40bea1f..4ddf77f75bd 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Store.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Store.xml @@ -77,7 +77,7 @@ Use this class to work with an X.509 store. > [!IMPORTANT] -> Starting with the .NET Framework 4.6, 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. +> Starting with the .NET Framework 4.6, 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. > > For apps that target the .NET Framework 4.5.2 and earlier versions, the class does not implement the interface and therefore does not have a `Dispose` method. @@ -92,7 +92,7 @@ This example tries to open each standard store in each standard location on the current computer. It prints a summary that shows whether each store exists and, if so, the number of certificates it contains. - The example creates an object for each combination of standard name and standard location. It calls the method with the flag, which opens the physical store only if it already exists. If the physical store exists, the example uses the , , and properties to display the number of certificates in the store. + The example creates an object for each combination of standard name and standard location. It calls the method with the flag, which opens the physical store only if it already exists. If the physical store exists, the example uses the , , and properties to display the number of certificates in the store. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/OpenFlags/Overview/storenames1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/OpenFlags/Overview/storenames1.vb" id="Snippet2"::: @@ -828,7 +828,7 @@ or operations performed on the store will not have any effect on the collection that is returned. This snapshot is recalculated each time the property is called, so the use of this property inside an iterative function is not recommended. + This method returns a snapshot of the X.509 certificate store. Note that subsequent or operations performed on the store will not have any effect on the collection that is returned. This snapshot is recalculated each time the property is called, so the use of this property inside an iterative function is not recommended. @@ -841,7 +841,7 @@ This example tries to open each standard store in each standard location on the current computer. It prints a summary that shows whether each store exists and, if so, the number of certificates it contains. - The example creates an object for each combination of standard name and standard location. It calls the method with the flag, which opens the physical store only if it already exists. If the physical store exists, the example uses the , , and properties to display the number of certificates in the store. + The example creates an object for each combination of standard name and standard location. It calls the method with the flag, which opens the physical store only if it already exists. If the physical store exists, the example uses the , , and properties to display the number of certificates in the store. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/OpenFlags/Overview/storenames1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/OpenFlags/Overview/storenames1.vb" id="Snippet2"::: @@ -1079,7 +1079,7 @@ This example tries to open each standard store in each standard location on the current computer. It prints a summary that shows whether each store exists and, if so, the number of certificates it contains. - The example creates an object for each combination of standard name and standard location. It calls the method with the flag, which opens the physical store only if it already exists. If the physical store exists, the example uses the , , and properties to display the number of certificates in the store. + The example creates an object for each combination of standard name and standard location. It calls the method with the flag, which opens the physical store only if it already exists. If the physical store exists, the example uses the , , and properties to display the number of certificates in the store. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/OpenFlags/Overview/storenames1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/OpenFlags/Overview/storenames1.vb" id="Snippet2"::: @@ -1166,7 +1166,7 @@ This example tries to open each standard store in each standard location on the current computer. It prints a summary that shows whether each store exists and, if so, the number of certificates it contains. - The example creates an object for each combination of standard name and standard location. It calls the method with the flag, which opens the physical store only if it already exists. If the physical store exists, the example uses the , , and properties to display the number of certificates in the store. + The example creates an object for each combination of standard name and standard location. It calls the method with the flag, which opens the physical store only if it already exists. If the physical store exists, the example uses the , , and properties to display the number of certificates in the store. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/OpenFlags/Overview/storenames1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/OpenFlags/Overview/storenames1.vb" id="Snippet2"::: @@ -1366,7 +1366,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 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 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. diff --git a/xml/System.Security.Cryptography.Xml/CipherData.xml b/xml/System.Security.Cryptography.Xml/CipherData.xml index 6c55bdf9f99..166484fb618 100644 --- a/xml/System.Security.Cryptography.Xml/CipherData.xml +++ b/xml/System.Security.Cryptography.Xml/CipherData.xml @@ -44,7 +44,7 @@ ## Remarks The class represents the `` element in XML encryption. It is a required element that provides the encrypted data. It must either contain the encrypted data as base64-encoded text of the `` element, or provide a reference to an external location containing the encrypted data using the `` element. - In many cases, you do not need to directly create a new instance of the class. The , , and classes create instances for you. + In many cases, you do not need to directly create a new instance of the class. The , , and classes create instances for you. > [!NOTE] > A object can have either a property or a property, but not both. A is thrown if both are assigned to a object. @@ -153,7 +153,7 @@ This constructor creates a object that represents the `` element in XML encryption. The constructor assigns the `cipherValue` value to the property as the actual encrypted data. > [!NOTE] -> The `` element can have either a or a child element, but not both. A is thrown if both are assigned to a object. +> The `` element can have either a or a child element, but not both. A is thrown if both are assigned to a object. @@ -314,7 +314,7 @@ The `` element identifies a source that, when processed, yields The value is encrypted data. > [!NOTE] -> The `` element can have either a or a child element, but not both. A is thrown if both are assigned to a object. +> The `` element can have either a or a child element, but not both. A is thrown if both are assigned to a object. @@ -429,7 +429,7 @@ The `` element identifies a source that, when processed, yields method overwrites existing XML elements with the `value` parameter. + The method overwrites existing XML elements with the `value` parameter. ]]> diff --git a/xml/System.Security.Cryptography.Xml/CipherReference.xml b/xml/System.Security.Cryptography.Xml/CipherReference.xml index 30b04f06967..084bc6db78d 100644 --- a/xml/System.Security.Cryptography.Xml/CipherReference.xml +++ b/xml/System.Security.Cryptography.Xml/CipherReference.xml @@ -293,7 +293,7 @@ EncryptedXml exml = new EncryptedXml(doc, ev); ## Examples - The following code example shows one way to use the method. + The following code example shows one way to use the method. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/CipherReference/GetXml/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/CipherReference/GetXml/example.vb" id="Snippet1"::: diff --git a/xml/System.Security.Cryptography.Xml/DataObject.xml b/xml/System.Security.Cryptography.Xml/DataObject.xml index 774eef0f91f..7d0ac0b774d 100644 --- a/xml/System.Security.Cryptography.Xml/DataObject.xml +++ b/xml/System.Security.Cryptography.Xml/DataObject.xml @@ -105,7 +105,7 @@ class is used with XML signatures. After you have initialized the , you can assign the and properties. + The class is used with XML signatures. After you have initialized the , you can assign the and properties. diff --git a/xml/System.Security.Cryptography.Xml/EncryptedReference.xml b/xml/System.Security.Cryptography.Xml/EncryptedReference.xml index c3ee4098aea..1424423b3eb 100644 --- a/xml/System.Security.Cryptography.Xml/EncryptedReference.xml +++ b/xml/System.Security.Cryptography.Xml/EncryptedReference.xml @@ -47,8 +47,8 @@ ## Examples - The following example uses the method in the class to write the XML values to the console. - + The following example uses the method in the class to write the XML values to the console. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/CipherReference/GetXml/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/CipherReference/GetXml/example.vb" id="Snippet1"::: @@ -326,7 +326,7 @@ ## Examples - The following example uses the method in the class to write the XML values to the console. + The following example uses the method in the class to write the XML values to the console. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/CipherReference/GetXml/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/CipherReference/GetXml/example.vb" id="Snippet1"::: diff --git a/xml/System.Security.Cryptography.Xml/EncryptedXml.xml b/xml/System.Security.Cryptography.Xml/EncryptedXml.xml index 5866955f58b..d3c99077a06 100644 --- a/xml/System.Security.Cryptography.Xml/EncryptedXml.xml +++ b/xml/System.Security.Cryptography.Xml/EncryptedXml.xml @@ -362,9 +362,9 @@ method allows you to map a symmetric key or an asymmetric key to a string name. This method adds the values of the `keyName` and `keyObject` parameters to a table of valid key name mappings. + The method allows you to map a symmetric key or an asymmetric key to a string name. This method adds the values of the `keyName` and `keyObject` parameters to a table of valid key name mappings. - Use the method to clear the key name mappings table. + Use the method to clear the key name mappings table. @@ -419,7 +419,7 @@ method. + Use this method to clear all key name mapping that you have set using the method. ]]> @@ -466,9 +466,9 @@ method to decrypt an element using a symmetric key. + Use the method to decrypt an element using a symmetric key. - Note that the method only decrypts top-level `` tags. In cases where one or more `` tags have been encrypted and are contained within higher level `` tags, you can call the method separately for each one. See the method for a code example. + Note that the method only decrypts top-level `` tags. In cases where one or more `` tags have been encrypted and are contained within higher level `` tags, you can call the method separately for each one. See the method for a code example. @@ -532,12 +532,12 @@ method decrypts all `` elements of the XML document loaded during initialization. After you call this method, all `` elements in the document are replaced with plain text versions. + The method decrypts all `` elements of the XML document loaded during initialization. After you call this method, all `` elements in the document are replaced with plain text versions. - The method decrypts only top-level `` elements. If you need to decrypt a super-encrypted document (a document that is encrypted more than once), you must call the method repeatedly until all the `` elements have been decrypted. + The method decrypts only top-level `` elements. If you need to decrypt a super-encrypted document (a document that is encrypted more than once), you must call the method repeatedly until all the `` elements have been decrypted. > [!NOTE] -> The method decrypts only valid XML data. To decrypt arbitrary data, use the method. +> The method decrypts only valid XML data. To decrypt arbitrary data, use the method. To use XML Encryption with X.509 certificates, you must have the Microsoft Enhanced Cryptographic Provider installed and the X.509 certificate must use the Enhanced Provider. If you do not have the Microsoft Enhanced Cryptographic Provider installed or the X.509 certificate does not use the Enhanced Provider, a with an "Unknown Error" will be thrown when you decrypt an XML document. @@ -620,7 +620,7 @@ method decrypts an encrypted key contained within the `` element of an XML document. + The method decrypts an encrypted key contained within the `` element of an XML document. This recursive method finds the key represented by the object. Note that an object can contain another object that specifies its value. @@ -641,7 +641,7 @@ method to decrypt an `` element and retrieve the key used to decrypt that element. + Use the method to decrypt an `` element and retrieve the key used to decrypt that element. ]]> @@ -688,7 +688,7 @@ method decrypts an encrypted key contained within the `` element of an XML document. This method accepts a value for the `symmetricAlgorithm` parameter that represents either the Triple DES algorithm or the AES key wrap algorithm (also called Rijndael). + The method decrypts an encrypted key contained within the `` element of an XML document. This method accepts a value for the `symmetricAlgorithm` parameter that represents either the Triple DES algorithm or the AES key wrap algorithm (also called Rijndael). ]]> @@ -743,7 +743,7 @@ method decrypts an encrypted key contained within the `` element of an XML document. This method accepts a value for the `rsa` parameter that represents either the RSA PKCS#1 v1.5 algorithm or the RSA PKCS#1 type 2 algorithm (also called OAEP padding). + The method decrypts an encrypted key contained within the `` element of an XML document. This method accepts a value for the `rsa` parameter that represents either the RSA PKCS#1 v1.5 algorithm or the RSA PKCS#1 type 2 algorithm (also called OAEP padding). ]]> @@ -919,9 +919,9 @@ method is a convenient way to encrypt the outer XML of an element using a certificate. This method generates a 256-bit Advanced Encryption Standard (AES) session key to encrypt an XML element and then encrypts and signs the AES key using the object. The method then returns the resulting XML as an element. + The method is a convenient way to encrypt the outer XML of an element using a certificate. This method generates a 256-bit Advanced Encryption Standard (AES) session key to encrypt an XML element and then encrypts and signs the AES key using the object. The method then returns the resulting XML as an element. - If you need more control over the encryption, so you can place the encrypted information into a `` element or specify whether the entire XML element or just its contents should be encrypted, use the method overloads. + If you need more control over the encryption, so you can place the encrypted information into a `` element or specify whether the entire XML element or just its contents should be encrypted, use the method overloads. To use XML Encryption with X.509 certificates, you must have the Microsoft Enhanced Cryptographic Provider installed and the X.509 certificate must use the Enhanced Provider. If you do not have the Microsoft Enhanced Cryptographic Provider installed or the X.509 certificate does not use the Enhanced Provider, a with an "Unknown Error" will be thrown when you decrypt an XML document. @@ -994,7 +994,7 @@ ` element or specify whether the entire XML element or just its contents should be encrypted, use the method overloads. + This method is a convenient way to encrypt the outer XML of an element using a key name. If you need more control over the encryption, so you can place the encrypted information into a `` element or specify whether the entire XML element or just its contents should be encrypted, use the method overloads. For a list of all supported algorithms, see the list of constant fields associated with the class. @@ -1195,7 +1195,7 @@ method to encrypt the key that a recipient uses to decrypt an `` element. This method places the encrypted key within an `` element. + Use the method to encrypt the key that a recipient uses to decrypt an `` element. This method places the encrypted key within an `` element. @@ -1250,7 +1250,7 @@ method to encrypt the key that a recipient uses to decrypt an `` element. This method accepts a value for the `symmetricAlgorithm` parameter that represents either the Triple DES algorithm or the AES key wrap algorithm (also called Rijndael). + Use the method to encrypt the key that a recipient uses to decrypt an `` element. This method accepts a value for the `symmetricAlgorithm` parameter that represents either the Triple DES algorithm or the AES key wrap algorithm (also called Rijndael). Note that this method does not automatically place the encrypted key within an `` element. You must manually create the `` element within your document. @@ -1307,7 +1307,7 @@ method to encrypt the key that a recipient uses to decrypt an `` element. This method accepts a value for `rsa` that represents either the RSA PKCS#1 v1.5 algorithm or the RSA PKCS#1 type 2 algorithm (also called OAEP). + Use the method to encrypt the key that a recipient uses to decrypt an `` element. This method accepts a value for `rsa` that represents either the RSA PKCS#1 v1.5 algorithm or the RSA PKCS#1 type 2 algorithm (also called OAEP). Note that this method does not automatically place the encrypted key within an `` element. You must manually create the `` element within your document. @@ -1377,7 +1377,7 @@ object, this method retrieves the decryption initialization vector (IV). The default behavior retrieves the IV as the first bytes of the byte array. + Given an object, this method retrieves the decryption initialization vector (IV). The default behavior retrieves the IV as the first bytes of the byte array. For a list of Uniform Resource Identifier (URI) values supported by the `symmetricAlgorithmUri` parameter, see the list of constant fields associated with the class. @@ -1450,7 +1450,7 @@ The value of the parameter is not a su object, this method looks for the decryption key that can be used to retrieve the plain text data. If a key name is specified, the method looks for the symmetric algorithm or asymmetric algorithm that is associated with the key name as defined in the key name mapping. Otherwise, if a retrieval method or an object is specified, the method loads the object and calls the method. + Given an object, this method looks for the decryption key that can be used to retrieve the plain text data. If a key name is specified, the method looks for the symmetric algorithm or asymmetric algorithm that is associated with the key name as defined in the key name mapping. Otherwise, if a retrieval method or an object is specified, the method loads the object and calls the method. ]]> @@ -1510,7 +1510,7 @@ The value of the parameter is not a su method determines how to resolve internal Uniform Resource Identifiers (URIs). It looks for elements with a specified value or for elements with an ID attribute that has a specified value. + The method determines how to resolve internal Uniform Resource Identifiers (URIs). It looks for elements with a specified value or for elements with an ID attribute that has a specified value. ]]> @@ -1681,7 +1681,7 @@ The value of the parameter is not a su method replaces an `` element with the value of the `decryptedData` parameter. + The method replaces an `` element with the value of the `decryptedData` parameter. @@ -1743,7 +1743,7 @@ The value of the parameter is not a su method replaces the `inputElement` parameter with the value specified by the `encryptedData` parameter. + The method replaces the `inputElement` parameter with the value specified by the `encryptedData` parameter. diff --git a/xml/System.Security.Cryptography.Xml/EncryptionMethod.xml b/xml/System.Security.Cryptography.Xml/EncryptionMethod.xml index f9fc498b061..faeb864381e 100644 --- a/xml/System.Security.Cryptography.Xml/EncryptionMethod.xml +++ b/xml/System.Security.Cryptography.Xml/EncryptionMethod.xml @@ -204,7 +204,7 @@ method returns a representation of the `` element. + The method returns a representation of the `` element. ]]> @@ -334,7 +334,7 @@ method configures the object to match the state of an object. + The method configures the object to match the state of an object. ]]> diff --git a/xml/System.Security.Cryptography.Xml/EncryptionProperty.xml b/xml/System.Security.Cryptography.Xml/EncryptionProperty.xml index 8afe396dc60..91c123801cc 100644 --- a/xml/System.Security.Cryptography.Xml/EncryptionProperty.xml +++ b/xml/System.Security.Cryptography.Xml/EncryptionProperty.xml @@ -39,21 +39,21 @@ Represents the element used in XML encryption. This class cannot be inherited. - class encapsulates the `` element defined by the World Wide Web Consortium [XML Encryption Syntax and Processing](https://www.w3.org/TR/xmlenc-core/) specification. - - Use the class to provide additional encryption information related to the and elements. For example, use this class to specify a time stamp. - - - -## Examples - The following code example encrypts and decrypts an XML document. This code example creates an object that contains custom information about the element, and adds the object to the collection of the class. Finally, this code example displays information about the object and the collection. - + class encapsulates the `` element defined by the World Wide Web Consortium [XML Encryption Syntax and Processing](https://www.w3.org/TR/xmlenc-core/) specification. + + Use the class to provide additional encryption information related to the and elements. For example, use this class to specify a time stamp. + + + +## Examples + The following code example encrypts and decrypts an XML document. This code example creates an object that contains custom information about the element, and adds the object to the collection of the class. Finally, this code example displays information about the object and the collection. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptionProperty/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptionProperty/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptionProperty/Overview/sample.vb" id="Snippet1"::: + ]]> @@ -129,21 +129,21 @@ An object to use for initialization. Initializes a new instance of the class using an object. - object that contains custom information about the element, and adds the object to the collection of the class. Finally, this code example displays information about the object and the collection. - + object that contains custom information about the element, and adds the object to the collection of the class. Finally, this code example displays information about the object and the collection. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptionProperty/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptionProperty/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptionProperty/Overview/sample.vb" id="Snippet1"::: + ]]> The parameter is . - The property of the parameter is not "EncryptionProperty". - - -or- - + The property of the parameter is not "EncryptionProperty". + + -or- + The property of the parameter is not "http://www.w3.org/2001/04/xmlenc#". @@ -180,11 +180,11 @@ Returns an object that encapsulates an instance of the class. An object that encapsulates an instance of the class. - method returns a representation of the `` element. - + method returns a representation of the `` element. + ]]> @@ -222,19 +222,19 @@ Gets the ID of the current object. The ID of the current object. - object from another location. - - - -## Examples - The following code example encrypts and decrypts an XML document. This code example creates an object that contains custom information about the element, and adds the object to the collection of the class. Finally, this code example displays information about the object and the collection. - + object from another location. + + + +## Examples + The following code example encrypts and decrypts an XML document. This code example creates an object that contains custom information about the element, and adds the object to the collection of the class. Finally, this code example displays information about the object and the collection. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptionProperty/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptionProperty/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptionProperty/Overview/sample.vb" id="Snippet1"::: + ]]> @@ -274,18 +274,18 @@ An object to parse. Parses the input and configures the internal state of the object to match. - method configures the object to match the state of an object. - + method configures the object to match the state of an object. + ]]> The parameter is . - The property of the parameter is not "EncryptionProperty". - - -or- - + The property of the parameter is not "EncryptionProperty". + + -or- + The property of the parameter is not "http://www.w3.org/2001/04/xmlenc#". @@ -322,21 +322,21 @@ Gets or sets an object that represents an object. An object that represents an object. - object that contains custom information about the element, and adds the object to the collection of the class. Finally, this code example displays information about the object and the collection. - + object that contains custom information about the element, and adds the object to the collection of the class. Finally, this code example displays information about the object and the collection. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptionProperty/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptionProperty/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptionProperty/Overview/sample.vb" id="Snippet1"::: + ]]> The property was set to . - The property of the value set to the property is not "EncryptionProperty". - - -or- - + The property of the value set to the property is not "EncryptionProperty". + + -or- + The property of the value set to the property is not "http://www.w3.org/2001/04/xmlenc#". @@ -373,14 +373,14 @@ Gets the target of the object. The target of the object. - object that contains custom information about the element, and adds the object to the collection of the class. Finally, this code example displays information about the object and the collection. - + object that contains custom information about the element, and adds the object to the collection of the class. Finally, this code example displays information about the object and the collection. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptionProperty/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptionProperty/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptionProperty/Overview/sample.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Security.Cryptography.Xml/IRelDecryptor.xml b/xml/System.Security.Cryptography.Xml/IRelDecryptor.xml index 20b2a0aa252..c2c26b71ae0 100644 --- a/xml/System.Security.Cryptography.Xml/IRelDecryptor.xml +++ b/xml/System.Security.Cryptography.Xml/IRelDecryptor.xml @@ -40,7 +40,7 @@ ## Examples The following code example shows how to validate an XML digital signature using the interface and the class. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/IRelDecryptor/Overview/sample.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/IRelDecryptor/Overview/sample.vb" id="Snippet2"::: @@ -91,7 +91,7 @@ method decrypts an XrML `` element and returns a plaintext stream. + The method decrypts an XrML `` element and returns a plaintext stream. ]]> diff --git a/xml/System.Security.Cryptography.Xml/KeyInfoName.xml b/xml/System.Security.Cryptography.Xml/KeyInfoName.xml index 4e12c4ab0c3..f839383187d 100644 --- a/xml/System.Security.Cryptography.Xml/KeyInfoName.xml +++ b/xml/System.Security.Cryptography.Xml/KeyInfoName.xml @@ -265,7 +265,7 @@ method is typically used to process a `` subelement of a `` element. + The method is typically used to process a `` subelement of a `` element. ]]> diff --git a/xml/System.Security.Cryptography.Xml/KeyInfoX509Data.xml b/xml/System.Security.Cryptography.Xml/KeyInfoX509Data.xml index 1317b41cadd..644a3cd25bd 100644 --- a/xml/System.Security.Cryptography.Xml/KeyInfoX509Data.xml +++ b/xml/System.Security.Cryptography.Xml/KeyInfoX509Data.xml @@ -332,7 +332,7 @@ ## Remarks For identification, each X.509v3 certificate carries the name of the certification authority that issued the certificate paired with a unique serial number assigned by the certification authority. - The method adds information about an issuer name and serial number pair to a list of objects that are accessible through the property. + The method adds information about an issuer name and serial number pair to a list of objects that are accessible through the property. ]]> @@ -645,7 +645,7 @@ The issuer of an X.509 certificate is the name of the certification authority that issued the certificate. Certification authorities assign each certificate they issue a unique serial number. - You can add a name and serial number pair using the method. + You can add a name and serial number pair using the method. ]]> diff --git a/xml/System.Security.Cryptography.Xml/Reference.xml b/xml/System.Security.Cryptography.Xml/Reference.xml index 3827fb1dbe1..93c5ab54028 100644 --- a/xml/System.Security.Cryptography.Xml/Reference.xml +++ b/xml/System.Security.Cryptography.Xml/Reference.xml @@ -258,7 +258,7 @@ method modifies the `` element and associated subelements of an XML digital signature. + The method modifies the `` element and associated subelements of an XML digital signature. Transforms are applied in the order in which they were added. If no transforms are specified, the minimum required transforms are added automatically. @@ -375,7 +375,7 @@ The property contains the Base 64 encoded value of the digest of the object described by the property. - The property is automatically populated with the appropriate value whenever you make a call to . + The property is automatically populated with the appropriate value whenever you make a call to . For more information about XML digital signatures, see the [W3C specification](https://www.w3.org/TR/xmldsig-core/). diff --git a/xml/System.Security.Cryptography.Xml/Signature.xml b/xml/System.Security.Cryptography.Xml/Signature.xml index 12f51d0d46a..9737d25b1ed 100644 --- a/xml/System.Security.Cryptography.Xml/Signature.xml +++ b/xml/System.Security.Cryptography.Xml/Signature.xml @@ -43,7 +43,7 @@ class represents the `` element of an XML signature defined by the XML digital signature specification. The `` element is the root element of an XML digital signature. The , , , and properties encapsulate the subelements of the `` element. + The class represents the `` element of an XML signature defined by the XML digital signature specification. The `` element is the root element of an XML digital signature. The , , , and properties encapsulate the subelements of the `` element. For more information about the `` element, see the [W3C specification](https://www.w3.org/TR/xmldsig-core/). @@ -151,7 +151,7 @@ method adds a object to a collection that is accessible using the property. + The method adds a object to a collection that is accessible using the property. ]]> @@ -401,7 +401,7 @@ ## Remarks The property uses a collection of objects to represent the `` tag of an XML digital signature. - You can also add a to this collection using the method. + You can also add a to this collection using the method. For more information about XML digital signatures, see the [W3C specification](https://www.w3.org/TR/xmldsig-core/). diff --git a/xml/System.Security.Cryptography.Xml/SignedInfo.xml b/xml/System.Security.Cryptography.Xml/SignedInfo.xml index 7426e4abb1c..80be0c535d7 100644 --- a/xml/System.Security.Cryptography.Xml/SignedInfo.xml +++ b/xml/System.Security.Cryptography.Xml/SignedInfo.xml @@ -138,7 +138,7 @@ method adds a object to a collection that is accessible using the property. + The method adds a object to a collection that is accessible using the property. ]]> diff --git a/xml/System.Security.Cryptography.Xml/SignedXml.xml b/xml/System.Security.Cryptography.Xml/SignedXml.xml index 28368225cd5..48fca969484 100644 --- a/xml/System.Security.Cryptography.Xml/SignedXml.xml +++ b/xml/System.Security.Cryptography.Xml/SignedXml.xml @@ -281,9 +281,9 @@ The following code example shows how to sign and verify a single element of an X method adds an `` element that represents an object to be signed to the `` element of an XML digital signature. + The method adds an `` element that represents an object to be signed to the `` element of an XML digital signature. - The method internally calls the method of the object encapsulated by the object. You can also add a object by directly calling the method from the property. + The method internally calls the method of the object encapsulated by the object. You can also add a object by directly calling the method from the property. For more information about XML digital signatures, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/). @@ -338,9 +338,9 @@ The following code example shows how to sign and verify a single element of an X method adds a `` element to the object that describes a digest method, digest value, and transform to use for creating an XML digital signature. The `` element is a subelement of the `` element. + The method adds a `` element to the object that describes a digest method, digest value, and transform to use for creating an XML digital signature. The `` element is a subelement of the `` element. - The method internally calls the method of the object encapsulated by the object. You can also add a object by directly calling the method from the property. + The method internally calls the method of the object encapsulated by the object. You can also add a object by directly calling the method from the property. For more information about XML digital signatures, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/). @@ -415,7 +415,7 @@ The following code example shows how to sign and verify a single element of an X ## Remarks This method also computes the digest of the references and the value of the signature. - If an XML document was signed with an X.509 signature, the method will search the "AddressBook" store for certificates suitable for the verification. For example, if the certificate is referenced by a Subject Key Identifier (SKI), the method will select certificates with this SKI and try them one after another until it can verify the certificate. + If an XML document was signed with an X.509 signature, the method will search the "AddressBook" store for certificates suitable for the verification. For example, if the certificate is referenced by a Subject Key Identifier (SKI), the method will select certificates with this SKI and try them one after another until it can verify the certificate. @@ -637,7 +637,7 @@ The following code example shows how to sign and verify a single element of an X ## Remarks In version 1.1 of the .NET Framework, the X.509 certificate is not verified. In version 2.0 and later, the X.509 certificate is verified. - In version 2.0 and later of the .NET Framework, the method will search the "AddressBook" store for certificates suitable for the verification. For example, if the certificate is referenced by a Subject Key Identifier (SKI), the method will select certificates with this SKI and try them one after another until it can verify the certificate. + In version 2.0 and later of the .NET Framework, the method will search the "AddressBook" store for certificates suitable for the verification. For example, if the certificate is referenced by a Subject Key Identifier (SKI), the method will select certificates with this SKI and try them one after another until it can verify the certificate. @@ -765,7 +765,7 @@ The following code example shows how to sign and verify a single element of an X method creates an XML digital signature and constructs many of the XML elements needed. + The method creates an XML digital signature and constructs many of the XML elements needed. You must set the data to be signed and the property before calling this method. @@ -834,7 +834,7 @@ The following code example shows how to sign and verify a single element of an X method creates an XML digital signature using the specified MAC algorithm and constructs many of the XML elements needed. + The method creates an XML digital signature using the specified MAC algorithm and constructs many of the XML elements needed. You must set the data to be signed before calling this method. @@ -1000,7 +1000,7 @@ The following code example shows how to sign and verify a single element of an X method returns an object that contains a public key that can be used to verify an XML digital signature. + The method returns an object that contains a public key that can be used to verify an XML digital signature. The key must be either a or an key. @@ -1158,7 +1158,7 @@ The following code example shows how to sign and verify a single element of an X method to verify an XML document. + The following code example shows how to use the method to verify an XML document. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/KeyInfo/Overview/xmldsigdetach.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/KeyInfo/Overview/xmldsigdetach.vb" id="Snippet3"::: @@ -1333,7 +1333,7 @@ The following code example shows how to sign and verify a single element of an X Canonicalization methods convert an XML document to its canonical form. For more information about canonical XML, see [Canonical XML](https://www.w3.org/TR/xml-c14n) on the W3C website. > [!NOTE] -> behaves like a static property. Changes from one instance of will be observed in other instances. Modifying the collection is not a thread-safe operation. +> behaves like a static property. Changes from one instance of will be observed in other instances. Modifying the collection is not a thread-safe operation. ]]> @@ -1585,7 +1585,7 @@ The following code example shows how to sign and verify a single element of an X ## Remarks The property represents the `` element of an XML digital signature using an array of bytes contained within the property. The `` element is a subelement of the `` element. - Use the property to retrieve the value of the XML digital signature. This property is automatically populated when you make a successful call to the method. + Use the property to retrieve the value of the XML digital signature. This property is automatically populated when you make a successful call to the method. For more information about the `` element, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/). diff --git a/xml/System.Security.Cryptography.Xml/Transform.xml b/xml/System.Security.Cryptography.Xml/Transform.xml index 0922f84d660..0b16814363e 100644 --- a/xml/System.Security.Cryptography.Xml/Transform.xml +++ b/xml/System.Security.Cryptography.Xml/Transform.xml @@ -131,7 +131,7 @@ attribute of a `` element in an XMLDSIG signature. For example, the algorithm URI for the Base64 decoding transform is defined in the [XMLDSIG specification (Section 6.6.2)](https://www.w3.org/TR/xmldsig-core1/#sec-Base-64). + This property corresponds to the attribute of a `` element in an XMLDSIG signature. For example, the algorithm URI for the Base64 decoding transform is defined in the [XMLDSIG specification (Section 6.6.2)](https://www.w3.org/TR/xmldsig-core1/#sec-Base-64). You can conveniently set this value using one of the static fields associated with the class. @@ -275,7 +275,7 @@ object represents an XPath transform using the XPath expression `self::text()`,a call to results in an object that represents the following XML element: + If a object represents an XPath transform using the XPath expression `self::text()`,a call to results in an object that represents the following XML element: ``` @@ -382,7 +382,7 @@ method returns the output of the current transform after it is run on the value previously set by a call to the method. + The method returns the output of the current transform after it is run on the value previously set by a call to the method. The type of the returned object must be one of the type objects in the property. diff --git a/xml/System.Security.Cryptography.Xml/TransformChain.xml b/xml/System.Security.Cryptography.Xml/TransformChain.xml index 2ff0c3e9a20..a0d7fa41ea3 100644 --- a/xml/System.Security.Cryptography.Xml/TransformChain.xml +++ b/xml/System.Security.Cryptography.Xml/TransformChain.xml @@ -47,7 +47,7 @@ Use the class whenever you need to add one or more transform objects to an encrypted XML document or to a signed XML document. - Both the class and the class contain a object. You can add a object to the class by calling the method. You can add a object to the class by calling the method. You can also create a object manually and pass it to either the property or the property. + Both the class and the class contain a object. You can add a object to the class by calling the method. You can add a object to the class by calling the method. You can also create a object manually and pass it to either the property or the property. If you want to sign only a portion of an XML document, you can use a transform to identify the XML elements you intend to sign. Note that the property and the property automatically create internal transforms that allow you to sign a portion of a document. diff --git a/xml/System.Security.Cryptography.Xml/X509IssuerSerial.xml b/xml/System.Security.Cryptography.Xml/X509IssuerSerial.xml index 7de85653700..a30153a7349 100644 --- a/xml/System.Security.Cryptography.Xml/X509IssuerSerial.xml +++ b/xml/System.Security.Cryptography.Xml/X509IssuerSerial.xml @@ -49,7 +49,7 @@ The issuer of an X.509 certificate is the name of the certification authority that issued the certificate. Certification authorities assign each certificate they issue a unique serial number for identification purposes. - Use the structure to specify a certificate issuer's distinguished name and serial number pair when using the class. You can add an structure to the class using the property. Alternatively, you can add string values that represent the X.509 certificate issuer's distinguished name and serial number pair using the method. + Use the structure to specify a certificate issuer's distinguished name and serial number pair when using the class. You can add an structure to the class using the property. Alternatively, you can add string values that represent the X.509 certificate issuer's distinguished name and serial number pair using the method. For more information about the `` element, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/TR/xmldsig-core/). diff --git a/xml/System.Security.Cryptography.Xml/XmlDsigBase64Transform.xml b/xml/System.Security.Cryptography.Xml/XmlDsigBase64Transform.xml index e82fae489ec..7e11c78c9ed 100644 --- a/xml/System.Security.Cryptography.Xml/XmlDsigBase64Transform.xml +++ b/xml/System.Security.Cryptography.Xml/XmlDsigBase64Transform.xml @@ -93,7 +93,7 @@ constructor. This code example is part of a larger example provided for the class. + The following code example demonstrates how to use the constructor. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigBase64TransformUrl/members.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigBase64TransformUrl/members.vb" id="Snippet1"::: @@ -190,7 +190,7 @@ ## Examples - The following code example demonstrates the use of the method to retrieve the output of the current object. This code example is part of a larger example provided for the class. + The following code example demonstrates the use of the method to retrieve the output of the current object. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigBase64TransformUrl/members.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigBase64TransformUrl/members.vb" id="Snippet7"::: @@ -244,7 +244,7 @@ ## Examples - The following code example demonstrates how to use the method to retrieve the output of the current object. This code example is part of a larger example provided for the class. + The following code example demonstrates how to use the method to retrieve the output of the current object. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigBase64TransformUrl/members.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigBase64TransformUrl/members.vb" id="Snippet8"::: @@ -393,7 +393,7 @@ ## Examples - The following code example demonstrates how to call the method using the specified object as the input. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the method using the specified object as the input. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigBase64TransformUrl/members.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigBase64TransformUrl/members.vb" id="Snippet11"::: diff --git a/xml/System.Security.Cryptography.Xml/XmlDsigC14NTransform.xml b/xml/System.Security.Cryptography.Xml/XmlDsigC14NTransform.xml index b63afacee9a..30ef2b31347 100644 --- a/xml/System.Security.Cryptography.Xml/XmlDsigC14NTransform.xml +++ b/xml/System.Security.Cryptography.Xml/XmlDsigC14NTransform.xml @@ -115,7 +115,7 @@ constructor. This code example is part of a larger example provided for the class. + The following code example demonstrates how to use the constructor. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigC14NTransformUrl/members.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigC14NTransformUrl/members.vb" id="Snippet3"::: @@ -161,7 +161,7 @@ constructor. This code example is part of a larger example provided for the class. + The following code example demonstrates how to use the constructor. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigC14NTransformUrl/members.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigC14NTransformUrl/members.vb" id="Snippet1"::: @@ -302,7 +302,7 @@ ## Examples - The following code example demonstrates how to use the method to retrieve the output of the current object. This code example is part of a larger example provided for the class. + The following code example demonstrates how to use the method to retrieve the output of the current object. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigC14NTransformUrl/members.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigC14NTransformUrl/members.vb" id="Snippet8"::: @@ -356,7 +356,7 @@ ## Examples - The following code example demonstrates how to use the method to retrieve the output of the current object. This code example is part of a larger example provided for the class. + The following code example demonstrates how to use the method to retrieve the output of the current object. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigC14NTransformUrl/members.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigC14NTransformUrl/members.vb" id="Snippet9"::: @@ -505,7 +505,7 @@ ## Examples - The following code example demonstrates how to call the method using the specified object as the input. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the method using the specified object as the input. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigC14NTransformUrl/members.cs" id="Snippet12"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigC14NTransformUrl/members.vb" id="Snippet12"::: diff --git a/xml/System.Security.Cryptography.Xml/XmlDsigEnvelopedSignatureTransform.xml b/xml/System.Security.Cryptography.Xml/XmlDsigEnvelopedSignatureTransform.xml index d19f293c00b..c46411032f5 100644 --- a/xml/System.Security.Cryptography.Xml/XmlDsigEnvelopedSignatureTransform.xml +++ b/xml/System.Security.Cryptography.Xml/XmlDsigEnvelopedSignatureTransform.xml @@ -157,7 +157,7 @@ constructor with a value of `true` to include comments. This code example is part of a larger example provided for the class. + The following code example demonstrates how to use the constructor with a value of `true` to include comments. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigEnvelopedSignatureTransformUrl/members.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigEnvelopedSignatureTransformUrl/members.vb" id="Snippet3"::: @@ -254,7 +254,7 @@ ## Examples - The following code example demonstrates how to use the method. This code example is part of a larger example provided for the class. + The following code example demonstrates how to use the method. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigEnvelopedSignatureTransformUrl/members.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigEnvelopedSignatureTransformUrl/members.vb" id="Snippet8"::: @@ -309,7 +309,7 @@ ## Examples - The following code example demonstrates how to use the method to retrieve the output of the current object. This code example is part of a larger example provided for the class. + The following code example demonstrates how to use the method to retrieve the output of the current object. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigEnvelopedSignatureTransformUrl/members.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigEnvelopedSignatureTransformUrl/members.vb" id="Snippet9"::: @@ -413,7 +413,7 @@ ## Examples - The following code example demonstrates how to call the method using the specified object to configure the current object. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the method using the specified object to configure the current object. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigEnvelopedSignatureTransformUrl/members.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigEnvelopedSignatureTransformUrl/members.vb" id="Snippet11"::: @@ -466,7 +466,7 @@ ## Examples - The following code example demonstrates how to call the method using the specified object as the input. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the method using the specified object as the input. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigBase64TransformUrl/members.cs" id="Snippet12"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigBase64TransformUrl/members.vb" id="Snippet12"::: diff --git a/xml/System.Security.Cryptography.Xml/XmlDsigExcC14NTransform.xml b/xml/System.Security.Cryptography.Xml/XmlDsigExcC14NTransform.xml index e8d88ffa4f7..51d17b05b99 100644 --- a/xml/System.Security.Cryptography.Xml/XmlDsigExcC14NTransform.xml +++ b/xml/System.Security.Cryptography.Xml/XmlDsigExcC14NTransform.xml @@ -385,7 +385,7 @@ method returns the output of the current transform after it is run on the value previously set by a call to the method. + The method returns the output of the current transform after it is run on the value previously set by a call to the method. The type of the returned object must be one of the type objects in the property. diff --git a/xml/System.Security.Cryptography.Xml/XmlDsigXPathTransform.xml b/xml/System.Security.Cryptography.Xml/XmlDsigXPathTransform.xml index db78ed9c4f1..b03772bd62a 100644 --- a/xml/System.Security.Cryptography.Xml/XmlDsigXPathTransform.xml +++ b/xml/System.Security.Cryptography.Xml/XmlDsigXPathTransform.xml @@ -45,7 +45,7 @@ ## Remarks The class allows you to address an XML document using the XPath language. This class uses an XPath expression to select the XML nodes you want to sign or encrypt while removing all others from either cryptographic operation. - Use the class to sign or encrypt specific parts of an XML document using an XPath expression. For information on initializing the class to the value of an XPath transform string, see the method. + Use the class to sign or encrypt specific parts of an XML document using an XPath expression. For information on initializing the class to the value of an XPath transform string, see the method. The Uniform Resource Identifier (URI) that describes the class is defined by the field. @@ -159,7 +159,7 @@ method to retrieve a object that contains an XML representation of an XPath transform. + Use the method to retrieve a object that contains an XML representation of an XPath transform. ]]> @@ -204,12 +204,12 @@ ## Remarks The type of the returned object must be . - Use the method to retrieve a object that contains an XML representation of an XPath transform. + Use the method to retrieve a object that contains an XML representation of an XPath transform. ## Examples - The following code example demonstrates how to use the method to retrieve the output of the current object. This code example is part of a larger example provided for the class. + The following code example demonstrates how to use the method to retrieve the output of the current object. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigXPathTransformUrl/members.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigXPathTransformUrl/members.vb" id="Snippet8"::: @@ -260,12 +260,12 @@ ## Remarks The type of the returned object must be . - Use the method to retrieve a object that contains an XML representation of an XPath transform. + Use the method to retrieve a object that contains an XML representation of an XPath transform. ## Examples - The following code example demonstrates how to use the method to retrieve the output of the current object. This code example is part of a larger example provided for the class. + The following code example demonstrates how to use the method to retrieve the output of the current object. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigXPathTransformUrl/members.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigXPathTransformUrl/members.vb" id="Snippet7"::: @@ -364,15 +364,15 @@ method to initialize the class with an XPath transform. + Use the method to initialize the class with an XPath transform. To initialize the class with an XPath transform, complete the following steps. 1. Create a new class and set the property to the value of an XPath transform string. -2. Call the method to create an object that represents the transform. +2. Call the method to create an object that represents the transform. -3. Create a new instance of the class and pass the previously created object to the method. +3. Create a new instance of the class and pass the previously created object to the method. @@ -430,14 +430,14 @@ method to initialize an object to the value of an XPath transform using an , , or object. For information about initializing an object using an XPath transform string, see the method. + Use the method to initialize an object to the value of an XPath transform using an , , or object. For information about initializing an object using an XPath transform string, see the method. The type of the input object must be one of the types in the property. ## Examples - The following code example demonstrates how to call the method using the specified object as the input. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the method using the specified object as the input. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigXPathTransformUrl/members.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigXPathTransformUrl/members.vb" id="Snippet11"::: diff --git a/xml/System.Security.Cryptography.Xml/XmlDsigXsltTransform.xml b/xml/System.Security.Cryptography.Xml/XmlDsigXsltTransform.xml index 41b0abff3e0..cb92940cd66 100644 --- a/xml/System.Security.Cryptography.Xml/XmlDsigXsltTransform.xml +++ b/xml/System.Security.Cryptography.Xml/XmlDsigXsltTransform.xml @@ -248,7 +248,7 @@ ## Examples - The following code example demonstrates how to use the method to retrieve the output of the current object. This code example is part of a larger example provided for the class. + The following code example demonstrates how to use the method to retrieve the output of the current object. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigXsltTransformUrl/members.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigXsltTransformUrl/members.vb" id="Snippet8"::: @@ -302,7 +302,7 @@ ## Examples - The following code example demonstrates how to use the method to retrieve the output of the current object. This code example is part of a larger example provided for the class. + The following code example demonstrates how to use the method to retrieve the output of the current object. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigXsltTransformUrl/members.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigXsltTransformUrl/members.vb" id="Snippet7"::: @@ -464,7 +464,7 @@ ## Examples - The following code example demonstrates how to call the method using the specified object as the input. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the method using the specified object as the input. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigXsltTransformUrl/members.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigXsltTransformUrl/members.vb" id="Snippet11"::: diff --git a/xml/System.Security.Cryptography/AesCng.xml b/xml/System.Security.Cryptography/AesCng.xml index fdeaf628816..5aa6e6d21d7 100644 --- a/xml/System.Security.Cryptography/AesCng.xml +++ b/xml/System.Security.Cryptography/AesCng.xml @@ -199,7 +199,7 @@ value of and as the default key storage provider (KSP) to open the key. + This constructor uses a default value of and as the default key storage provider (KSP) to open the key. ]]> @@ -459,7 +459,7 @@ This method decrypts an encrypted message created using the overload with the same signature. + This method decrypts an encrypted message created using the overload with the same signature. > [!NOTE] > If you've created the object using an existing persisted key and you want to make use of that key when decrypting the message, you want to set the property and then call the parameterless overload instead; otherwise, using this method will create an ephemeral key as specified by the `rgbKey` parameter. @@ -537,7 +537,7 @@ This method decrypts an encrypted message created using the overload with the same signature to decrypt the result of this method. +Use this method to encrypt a message and then use the overload with the same signature to decrypt the result of this method. ]]> @@ -602,7 +602,7 @@ Use this method to encrypt a message and then use the overload with the same signature to decrypt the result of this method. + Use this method to encrypt a message and then use the overload with the same signature to decrypt the result of this method. > [!NOTE] > If you've created the object using an existing persisted key and you want to make use of that key when encrypting the message, you want to set the property and then call the parameterless overload instead; otherwise, using this method will create an ephemeral key as specified by the `rgbKey` parameter. diff --git a/xml/System.Security.Cryptography/AesCryptoServiceProvider.xml b/xml/System.Security.Cryptography/AesCryptoServiceProvider.xml index 6813bcb98f1..6b81a47e77d 100644 --- a/xml/System.Security.Cryptography/AesCryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/AesCryptoServiceProvider.xml @@ -321,7 +321,7 @@ method to decrypt an encrypted message. This code example is part of a larger example provided for the class. + The following example shows how to use the method to decrypt an encrypted message. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AesCryptoServiceProvider/Overview/program.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AesCryptoServiceProvider/Overview/program.vb" id="Snippet3"::: @@ -478,12 +478,12 @@ and properties to determine the size of the `key` and `iv` parameters. + See the code examples in the and properties to determine the size of the `key` and `iv` parameters. ## Examples - The following example shows how to use the method to encrypt a message. This code example is part of a larger example provided for the class. + The following example shows how to use the method to encrypt a message. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AesCryptoServiceProvider/Overview/program.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AesCryptoServiceProvider/Overview/program.vb" id="Snippet2"::: @@ -750,7 +750,7 @@ property is automatically set to a new random value whenever you create a new instance of one of the classes or when you manually call the method. The size of the property must be the same as the property divided by 8. + The property is automatically set to a new random value whenever you create a new instance of one of the classes or when you manually call the method. The size of the property must be the same as the property divided by 8. The classes that derive from the class use a chaining mode called cipher block chaining (CBC), which requires a key and an initialization vector to perform cryptographic transformations on data. To decrypt data that was encrypted using one of the classes, you must set the property and property to the same values that were used for encryption. diff --git a/xml/System.Security.Cryptography/AesManaged.xml b/xml/System.Security.Cryptography/AesManaged.xml index 20bd597a680..e9c24e92fbc 100644 --- a/xml/System.Security.Cryptography/AesManaged.xml +++ b/xml/System.Security.Cryptography/AesManaged.xml @@ -71,24 +71,24 @@ Provides a managed implementation of the Advanced Encryption Standard (AES) symmetric algorithm. - class but limits blocks to 128 bits and does not allow feedback modes. - + class but limits blocks to 128 bits and does not allow feedback modes. + > [!NOTE] -> If the Windows security policy setting for Federal Information Processing Standards (FIPS)-compliant algorithms is enabled, using this algorithm throws a . - +> If the Windows security policy setting for Federal Information Processing Standards (FIPS)-compliant algorithms is enabled, using this algorithm throws a . + > [!NOTE] > Microsoft believes that it's no longer safe to decrypt data encrypted with the Cipher-Block-Chaining (CBC) mode of symmetric encryption (which is the default value of the property) when verifiable padding has been applied without first ensuring the integrity of the ciphertext, except for very specific circumstances. For more information, see [Timing vulnerabilities with CBC-mode symmetric decryption using padding](/dotnet/standard/security/vulnerabilities-cbc-mode). - -## Examples - The following example demonstrates how to encrypt and decrypt sample data using the class. - + +## Examples + The following example demonstrates how to encrypt and decrypt sample data using the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AesManaged/Overview/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AesManaged/Overview/program.vb" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/aesmanaged/fs/program.fs" id="Snippet1"::: - + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/aesmanaged/fs/program.fs" id="Snippet1"::: + ]]> @@ -170,10 +170,10 @@ Gets or sets the block size, in bits, of the cryptographic operation. The block size, in bits, of the cryptographic operation. The default is 128 bits. - for more information about block size. + for more information about block size. ]]> @@ -299,15 +299,15 @@ Creates a symmetric decryptor object using the specified key and initialization vector (IV). A symmetric decryptor object. - method to decrypt an encrypted message. This code example is part of a larger example provided for the class. - + method to decrypt an encrypted message. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AesManaged/Overview/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AesManaged/Overview/program.vb" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/aesmanaged/fs/program.fs" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AesManaged/Overview/program.vb" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/aesmanaged/fs/program.fs" id="Snippet3"::: + ]]> @@ -436,15 +436,15 @@ Creates a symmetric encryptor object using the specified key and initialization vector (IV). A symmetric encryptor object. - method to encrypt a message. This code example is part of a larger example provided for the class. - + method to encrypt a message. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AesManaged/Overview/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AesManaged/Overview/program.vb" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/aesmanaged/fs/program.fs" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AesManaged/Overview/program.vb" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/aesmanaged/fs/program.fs" id="Snippet2"::: + ]]> @@ -542,14 +542,14 @@ Gets or sets the number of bits to use as feedback. The feedback size, in bits. - [!NOTE] -> Because this algorithm does not support feedback modes, using this property is discouraged. - +> Because this algorithm does not support feedback modes, using this property is discouraged. + ]]> @@ -684,10 +684,10 @@ Gets or sets the initialization vector (IV) to use for the symmetric algorithm. The initialization vector to use for the symmetric algorithm. - for more information about initialization vector. + for more information about initialization vector. ]]> @@ -779,11 +779,11 @@ Gets or sets the size, in bits, of the secret key used for the symmetric algorithm. The size, in bits, of the key used by the symmetric algorithm. - @@ -823,10 +823,10 @@ Gets the block sizes, in bits, that are supported by the symmetric algorithm. The block sizes, in bits, that are supported by the symmetric algorithm. - @@ -867,10 +867,10 @@ Gets the key sizes, in bits, that are supported by the symmetric algorithm. The key sizes, in bits, that are supported by the symmetric algorithm. - @@ -918,11 +918,11 @@ Gets or sets the mode for operation of the symmetric algorithm. One of the enumeration values that specifies the block cipher mode to use for encryption. The default is . - and modes are not supported. - + and modes are not supported. + ]]> @@ -971,10 +971,10 @@ Gets or sets the padding mode used in the symmetric algorithm. One of the enumeration values that specifies the type of padding to apply. The default is . - for more information about padding. + for more information about padding. ]]> diff --git a/xml/System.Security.Cryptography/AsnEncodedDataEnumerator.xml b/xml/System.Security.Cryptography/AsnEncodedDataEnumerator.xml index 75680d3df65..c996e2cd4fd 100644 --- a/xml/System.Security.Cryptography/AsnEncodedDataEnumerator.xml +++ b/xml/System.Security.Cryptography/AsnEncodedDataEnumerator.xml @@ -127,11 +127,11 @@ method must be called to advance the enumerator to the first element of the collection before reading the value of the property; otherwise, returns `null` or throws an exception. + After an enumerator is created, the method must be called to advance the enumerator to the first element of the collection before reading the value of the property; otherwise, returns `null` or throws an exception. - also returns `null` or throws an exception if the last call to returns `false`, which indicates that the end of the collection has been reached. + also returns `null` or throws an exception if the last call to returns `false`, which indicates that the end of the collection has been reached. - does not move the position of the enumerator, and consecutive calls to return the same object until is called. + does not move the position of the enumerator, and consecutive calls to return the same object until is called. @@ -196,11 +196,11 @@ method moves the enumerator over the first element of the collection. Subsequent calls to advance the enumerator past subsequent elements. + After an enumerator is created, it is positioned before the first element of the collection, and the first call to the method moves the enumerator over the first element of the collection. Subsequent calls to advance the enumerator past subsequent elements. - After the end of the collection is passed, calls to return `false`. + After the end of the collection is passed, calls to return `false`. - An enumerator is valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator becomes invalid and the next call to can throw an . + An enumerator is valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator becomes invalid and the next call to can throw an . @@ -264,7 +264,7 @@ object. An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator becomes invalid, and the next call to the method throws an . + The initial position of an enumerator is before the first element in the object. An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator becomes invalid, and the next call to the method throws an . diff --git a/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml b/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml index d1451ca7c45..dfa31362709 100644 --- a/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml +++ b/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml @@ -202,14 +202,14 @@ method. + This method is a simple call to the method. Calling `Dispose` allows the resources used by the class to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). ## Examples - The following code example demonstrates how to call the method to release the resources of the current `customCrypto` object. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the method to release the resources of the current `customCrypto` object. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.vb" id="Snippet1"::: @@ -294,7 +294,7 @@ This method is obsolete in .NET 5 and later versions. ## Example - The following code example demonstrates how to implement the method in an extended class. This code example is part of a larger example provided for the class. + The following code example demonstrates how to implement the method in an extended class. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.vb" id="Snippet11"::: @@ -406,7 +406,7 @@ This method is obsolete in .NET 5 and later versions. method in an extended class. This code example is part of a larger example provided for the class. + The following code example demonstrates how to implement the method in an extended class. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.cs" id="Snippet12"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.vb" id="Snippet12"::: @@ -1022,7 +1022,7 @@ This method is obsolete in .NET 5 and later versions. method to parse the specified XML string to populate the current object. This code example is part of a larger example provided for the class. + The following code example demonstrates how to implement the method to parse the specified XML string to populate the current object. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.vb" id="Snippet4"::: @@ -1082,7 +1082,7 @@ This method is obsolete in .NET 5 and later versions. This method only supports the binary (BER/CER/DER) encoding of EncryptedPrivateKeyInfo. If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method. - Because algorithm-specific support is required to interpret the contents of this data format, throws a by default. + Because algorithm-specific support is required to interpret the contents of this data format, throws a by default. ]]> @@ -1160,7 +1160,7 @@ The algorithm-specific key import failed. This method only supports the binary (BER/CER/DER) encoding of EncryptedPrivateKeyInfo. If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method. - Because algorithm-specific support is required to interpret the contents of this data format, throws a by default. + Because algorithm-specific support is required to interpret the contents of this data format, throws a by default. ]]> @@ -1442,7 +1442,7 @@ Because each algorithm may have algorithm-specific PEM labels, the default behav This method only supports the binary (BER/CER/DER) encoding of PrivateKeyInfo. If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method. - Because algorithm-specific support is required to interpret the contents of this data format, throws a by default. + Because algorithm-specific support is required to interpret the contents of this data format, throws a by default. ]]> @@ -1508,7 +1508,7 @@ The algorithm-specific key import failed. This method only supports the binary (DER) encoding of SubjectPublicKeyInfo. If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method. - Because algorithm-specific support is required to interpret the contents of this data format, throws a by default. + Because algorithm-specific support is required to interpret the contents of this data format, throws a by default. ]]> The contents of do not represent an ASN.1-DER-encoded X.509 SubjectPublicKeyInfo structure. @@ -1770,7 +1770,7 @@ The algorithm-specific key import failed. ## Examples - The following code example demonstrates how to call the property to retrieve the , , and properties. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the property to retrieve the , , and properties. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.vb" id="Snippet10"::: @@ -2009,7 +2009,7 @@ This member is an explicit interface member implementation. It can be used only method to create an XML representation of the parameters in the current object. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the method to create an XML representation of the parameters in the current object. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.vb" id="Snippet5"::: @@ -2077,7 +2077,7 @@ This member is an explicit interface member implementation. It can be used only The password bytes are passed directly into the Key Derivation Function (KDF) used by the algorithm indicated by `pbeParameters`. This enables compatibility with other systems which use a text encoding other than UTF-8 when processing passwords with PBKDF2 (Password-Based Key Derivation Function 2). - Because algorithm-specific support is required to produce this data format, throws a by default. + Because algorithm-specific support is required to produce this data format, throws a by default. ]]> @@ -2148,7 +2148,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks When `pbeParameters` indicates an algorithm that uses PBKDF2 (Password-Based Key Derivation Function 2), the password is converted to bytes via the UTF-8 encoding. - Because algorithm-specific support is required to produce this data format, throws a by default. + Because algorithm-specific support is required to produce this data format, throws a by default. ]]> @@ -2327,7 +2327,7 @@ This member is an explicit interface member implementation. It can be used only throws a by default. + Because algorithm-specific support is required to produce this data format, throws a by default. ]]> @@ -2434,7 +2434,7 @@ This member is an explicit interface member implementation. It can be used only throws a by default. + Because algorithm-specific support is required to produce this data format, throws a by default. ]]> diff --git a/xml/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter.xml b/xml/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter.xml index 64c823efa5a..22efe6c980d 100644 --- a/xml/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter.xml +++ b/xml/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter.xml @@ -138,7 +138,7 @@ ## Remarks You cannot create an instance of an abstract class. Application code will create a new instance of a derived class. - Use an implementation of to establish the key before calling an implementation of . + Use an implementation of to establish the key before calling an implementation of . ]]> @@ -200,7 +200,7 @@ ## Examples - The following code example demonstrates how to override the method to create an encrypted key exchange for the specified input data. This code example is part of a larger example provided for the class. + The following code example demonstrates how to override the method to create an encrypted key exchange for the specified input data. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter/Overview/contosodeformatter.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter/Overview/contosodeformatter.vb" id="Snippet4"::: @@ -316,12 +316,12 @@ implementation. + You must set a key before calling a implementation. ## Examples - The following code example demonstrates how to override the to set the public key for encryption operations. This code example is part of a larger example provided for the class. + The following code example demonstrates how to override the to set the public key for encryption operations. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter/Overview/contosodeformatter.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter/Overview/contosodeformatter.vb" id="Snippet5"::: diff --git a/xml/System.Security.Cryptography/AsymmetricKeyExchangeFormatter.xml b/xml/System.Security.Cryptography/AsymmetricKeyExchangeFormatter.xml index e67694890bc..35be70b92ae 100644 --- a/xml/System.Security.Cryptography/AsymmetricKeyExchangeFormatter.xml +++ b/xml/System.Security.Cryptography/AsymmetricKeyExchangeFormatter.xml @@ -68,16 +68,16 @@ Represents the base class from which all asymmetric key exchange formatters derive. - [!CAUTION] -> It is highly recommended that you not attempt to create your own key exchange method from the basic functionality provided, because many details of the operation must be performed carefully in order for the key exchange to be successful. - +> It is highly recommended that you not attempt to create your own key exchange method from the basic functionality provided, because many details of the operation must be performed carefully in order for the key exchange to be successful. + ]]> Cryptographic Services @@ -126,13 +126,13 @@ Initializes a new instance of . - to set the key before calling . - + to set the key before calling . + ]]> Cryptographic Services @@ -195,11 +195,11 @@ When overridden in a derived class, creates the encrypted key exchange data from the specified input data. The encrypted key exchange data to be sent to the intended recipient. - Cryptographic Services @@ -262,11 +262,11 @@ When overridden in a derived class, creates the encrypted key exchange data from the specified input data. The encrypted key exchange data to be sent to the intended recipient. - Cryptographic Services @@ -371,11 +371,11 @@ The instance of the implementation of that holds the public key. When overridden in a derived class, sets the public key to use for encrypting the secret information. - implementation. - + implementation. + ]]> Cryptographic Services diff --git a/xml/System.Security.Cryptography/AsymmetricSignatureDeformatter.xml b/xml/System.Security.Cryptography/AsymmetricSignatureDeformatter.xml index 5fbce3c1990..14ee8c10104 100644 --- a/xml/System.Security.Cryptography/AsymmetricSignatureDeformatter.xml +++ b/xml/System.Security.Cryptography/AsymmetricSignatureDeformatter.xml @@ -68,11 +68,11 @@ Represents the abstract base class from which all implementations of asymmetric signature deformatters derive. - . - + . + ]]> Cryptographic Services @@ -121,13 +121,13 @@ Initializes a new instance of . - and to set the key and hash algorithm before calling an implementation of . - + and to set the key and hash algorithm before calling an implementation of . + ]]> Cryptographic Services @@ -179,11 +179,11 @@ The name of the hash algorithm to use for verifying the signature. When overridden in a derived class, sets the hash algorithm to use for verifying the signature. - . - + . + ]]> Cryptographic Services @@ -235,11 +235,11 @@ The instance of an implementation of that holds the public key. When overridden in a derived class, sets the public key to use for verifying the signature. - . - + . + ]]> Cryptographic Services @@ -305,11 +305,11 @@ if matches the signature computed using the specified hash algorithm and key on ; otherwise, . - Cryptographic Services @@ -365,11 +365,11 @@ if the signature is valid for the hash; otherwise, . - The parameter is . diff --git a/xml/System.Security.Cryptography/AsymmetricSignatureFormatter.xml b/xml/System.Security.Cryptography/AsymmetricSignatureFormatter.xml index 02c25f39e5d..9c96e9509ac 100644 --- a/xml/System.Security.Cryptography/AsymmetricSignatureFormatter.xml +++ b/xml/System.Security.Cryptography/AsymmetricSignatureFormatter.xml @@ -68,11 +68,11 @@ Represents the base class from which all implementations of asymmetric signature formatters derive. - . - + . + ]]> Cryptographic Services @@ -121,13 +121,13 @@ Initializes a new instance of . - and to set the key and hash algorithm before calling an implementation of . - + and to set the key and hash algorithm before calling an implementation of . + ]]> Cryptographic Services @@ -190,11 +190,11 @@ When overridden in a derived class, creates the signature for the specified data. The digital signature for the parameter. - Cryptographic Services @@ -247,11 +247,11 @@ Creates the signature from the specified hash value. The signature for the specified hash value. - The parameter is . @@ -304,11 +304,11 @@ The name of the hash algorithm to use for creating the signature. When overridden in a derived class, sets the hash algorithm to use for creating the signature. - . - + . + ]]> Cryptographic Services @@ -360,11 +360,11 @@ The instance of the implementation of to use to create the signature. When overridden in a derived class, sets the asymmetric algorithm to use to create the signature. - . - + . + ]]> Cryptographic Services diff --git a/xml/System.Security.Cryptography/CngKey.xml b/xml/System.Security.Cryptography/CngKey.xml index b1cfe8c7a79..280b9404fe9 100644 --- a/xml/System.Security.Cryptography/CngKey.xml +++ b/xml/System.Security.Cryptography/CngKey.xml @@ -488,9 +488,9 @@ ## Remarks -- When you call the method on an ephemeral key, it closes the handle to the key. +- When you call the method on an ephemeral key, it closes the handle to the key. - When you call the method on a named key, the object can no longer be used after the named key is deleted. + When you call the method on a named key, the object can no longer be used after the named key is deleted. ]]> @@ -556,10 +556,10 @@ 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). + 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. ]]> @@ -630,7 +630,7 @@ . + The default KSP is . ]]> @@ -702,7 +702,7 @@ . + Use this overload to check for the existence of a key in a KSP other than the default KSP, which is . ]]> @@ -780,7 +780,7 @@ , and to specify key open options. + Use this overload to check for the existence of a key in a KSP other than the default , and to specify key open options. ]]> @@ -849,7 +849,7 @@ ) only allows export of private keys in the , , and formats. This restriction is controlled by the underlying KSP. If you use a different KSP, other formats may apply. + Cryptography Next Generation (CNG) allows export in any format that the underlying key storage provider (KSP) supports. For example, on Windows Vista,the default KSP (which is ) only allows export of private keys in the , , and formats. This restriction is controlled by the underlying KSP. If you use a different KSP, other formats may apply. ]]> @@ -980,7 +980,7 @@ class. provides wrappers for several, but not all, properties. The method is primarily used to access the value of a property that is not wrapped. + The purpose of this method is to return the value of an arbitrary property of the key. The typical way to retrieve properties is by using the property accessors provided by the class. provides wrappers for several, but not all, properties. The method is primarily used to access the value of a property that is not wrapped. This method is useful in the following cases: @@ -996,7 +996,7 @@ These options must match the value that the property was set with, or the property will not be found. - is thrown if the property cannot be found. You should call the method first to avoid the exception instead of wrapping the method call in a `try/catch` block. + is thrown if the property cannot be found. You should call the method first to avoid the exception instead of wrapping the method call in a `try/catch` block. ]]> @@ -1208,7 +1208,7 @@ . + The default KSP is . > [!IMPORTANT] > On Windows operating systems before Windows 7 and Windows Server 2008 R2, some CNG key binary large object (BLOB) formats are not supported. @@ -1364,9 +1364,9 @@ The return value depends on the method that is used to obtain the key: -- If the key was not opened by the method overload, the common language runtime (CLR) is managing the key and can determine whether it is ephemeral. +- If the key was not opened by the method overload, the common language runtime (CLR) is managing the key and can determine whether it is ephemeral. -- If the key was opened by the method overload, the CLR cannot determine whether it is ephemeral. Therefore, the key is assumed to be persisted. However, if this method is used to open a handle to a key that is created by the CLR, the CLR will be able to determine whether it is ephemeral. +- If the key was opened by the method overload, the CLR cannot determine whether it is ephemeral. Therefore, the key is assumed to be persisted. However, if this method is used to open a handle to a key that is created by the CLR, the CLR will be able to determine whether it is ephemeral. This property does not have a public setter; it is read-only. @@ -1662,7 +1662,7 @@ ## Remarks This overload uses the following defaults: -- Key storage provider (KSP): . Use the overload if you want to specify another KSP. +- Key storage provider (KSP): . Use the overload if you want to specify another KSP. - Key open options: . @@ -1737,7 +1737,7 @@ ## Remarks This overload enables advanced users to use the CNG classes even if they rely on platform invoke or the managed interop capability of C++. For example, if you have a native library that returns the key as an NCRYPT_KEY_HANDLE, this overload lets you create a managed wrapper around the key and use the CNG classes to manipulate it. - When you open a key by using its handle, you cannot determine the key's ephemeral state and must specify it yourself. Several properties of the class rely on this value to be correct. Therefore, make sure that you pass the correct flag value to the methods. + When you open a key by using its handle, you cannot determine the key's ephemeral state and must specify it yourself. Several properties of the class rely on this value to be correct. Therefore, make sure that you pass the correct flag value to the methods. ]]> @@ -1810,7 +1810,7 @@ method overload, this overload lets you specify the provider. In addition, a default value of is created and bound to the key. + Unlike the method overload, this overload lets you specify the provider. In addition, a default value of is created and bound to the key. ]]> @@ -1887,7 +1887,7 @@ method overload, this overload lets you specify both the provider and the key open options. + Unlike the method overload, this overload lets you specify both the provider and the key open options. ]]> @@ -2144,7 +2144,7 @@ object. The options set on the object must exactly match the options in the call. Otherwise, the property will not be found. + This method enables you to add a new custom property to an existing key by using a object. The options set on the object must exactly match the options in the call. Otherwise, the property will not be found. ]]> @@ -2271,7 +2271,7 @@ property will return the file name of the key as this property. The name returned by the is implementation-dependent. + This property gets an alternate name that can be used when accessing the key. You can use this property if the original key name does not uniquely identify the persisted key. The property will return the file name of the key as this property. The name returned by the is implementation-dependent. ]]> diff --git a/xml/System.Security.Cryptography/CngKeyCreationParameters.xml b/xml/System.Security.Cryptography/CngKeyCreationParameters.xml index 6618ab556f3..4d8e1619c1f 100644 --- a/xml/System.Security.Cryptography/CngKeyCreationParameters.xml +++ b/xml/System.Security.Cryptography/CngKeyCreationParameters.xml @@ -59,11 +59,11 @@ ## Remarks objects contain properties. Some properties must be added to a key when it is created. Other properties can be added after the key is created. - The class enables you to add properties to a key as it is being created. You can do this by passing a object that contains standard key properties, such as key storage provider (KSP), export policy, key usage, user interface (UI) policy, and parent window handle, to the method. The object that is being created will be initialized with these values before it is finalized. + The class enables you to add properties to a key as it is being created. You can do this by passing a object that contains standard key properties, such as key storage provider (KSP), export policy, key usage, user interface (UI) policy, and parent window handle, to the method. The object that is being created will be initialized with these values before it is finalized. You can also add non-standard properties to a key by using the property. - If you need to add properties after a key is created, use the method. + If you need to add properties after a key is created, use the method. > [!NOTE] > CNG classes don't work on non-Windows platforms. @@ -358,7 +358,7 @@ 3. Add the objects to the object. -4. Call the method overload and pass the initialized object to it. +4. Call the method overload and pass the initialized object to it. ]]> diff --git a/xml/System.Security.Cryptography/CngKeyHandleOpenOptions.xml b/xml/System.Security.Cryptography/CngKeyHandleOpenOptions.xml index 85220690354..d0093982909 100644 --- a/xml/System.Security.Cryptography/CngKeyHandleOpenOptions.xml +++ b/xml/System.Security.Cryptography/CngKeyHandleOpenOptions.xml @@ -53,11 +53,11 @@ Specifies options for opening key handles. - method. - + method. + ]]> diff --git a/xml/System.Security.Cryptography/CngProperty.xml b/xml/System.Security.Cryptography/CngProperty.xml index df10f95b4ed..fe23a6d8375 100644 --- a/xml/System.Security.Cryptography/CngProperty.xml +++ b/xml/System.Security.Cryptography/CngProperty.xml @@ -58,13 +58,13 @@ Encapsulates a property of a Cryptography Next Generation (CNG) key or provider. - flag, accessor properties, and comparison and hashing functions. - - This struct is used with the and methods. - + flag, accessor properties, and comparison and hashing functions. + + This struct is used with the and methods. + ]]> @@ -123,11 +123,11 @@ A bitwise combination of the enumeration values that specify how the property is stored. Initializes a new instance of the struct. - flags require the same set of flags when they are retrieved. - + flags require the same set of flags when they are retrieved. + ]]> @@ -142,11 +142,11 @@ Compares two objects. - objects are considered equal if their names, values, and options are equivalent. Name comparison is performed in a case-sensitive manner. - + objects are considered equal if their names, values, and options are equivalent. Name comparison is performed in a case-sensitive manner. + ]]> @@ -206,11 +206,11 @@ if the parameter is a object that specifies the same property as the current object; otherwise, . - objects are considered equal if their names, values, and options are equivalent. Name comparison is performed in a case-sensitive manner. - + objects are considered equal if their names, values, and options are equivalent. Name comparison is performed in a case-sensitive manner. + ]]> @@ -265,11 +265,11 @@ if the parameter represents the same property as the current object; otherwise, . - objects are considered equal if their names, values, and options are equivalent. Name comparison is performed in a case-sensitive manner. - + objects are considered equal if their names, values, and options are equivalent. Name comparison is performed in a case-sensitive manner. + ]]> @@ -468,12 +468,12 @@ if the two objects specify the same property; otherwise, . - objects are considered equal if their names, values, and options are equivalent. Name comparison is performed in a case-sensitive manner. - - The equivalent method for this operator is .]]> + objects are considered equal if their names, values, and options are equivalent. Name comparison is performed in a case-sensitive manner. + + The equivalent method for this operator is .]]> @@ -526,12 +526,12 @@ if the two objects do not specify the same property; otherwise, . - objects are considered equal if their names, values, and options are equivalent. Name comparison is performed in a case-sensitive manner. - - The equivalent method for this operator is .]]> + objects are considered equal if their names, values, and options are equivalent. Name comparison is performed in a case-sensitive manner. + + The equivalent method for this operator is .]]> @@ -587,11 +587,11 @@ Gets the property options that the current object specifies. An object that specifies the options that are set in the current object. - objects contain objects, which contain the that the property was stored with. - + objects contain objects, which contain the that the property was stored with. + ]]> diff --git a/xml/System.Security.Cryptography/CngPropertyOptions.xml b/xml/System.Security.Cryptography/CngPropertyOptions.xml index a85ce995fe9..5fb3d4856c5 100644 --- a/xml/System.Security.Cryptography/CngPropertyOptions.xml +++ b/xml/System.Security.Cryptography/CngPropertyOptions.xml @@ -53,13 +53,13 @@ Specifies Cryptography Next Generation (CNG) key property options. - objects, which are then used in calls. You also use these options when you query for the value of properties with the method. - - Properties must be queried with the they are stored with. Otherwise, they will not be found. - + objects, which are then used in calls. You also use these options when you query for the value of properties with the method. + + Properties must be queried with the they are stored with. Otherwise, they will not be found. + ]]> diff --git a/xml/System.Security.Cryptography/CryptoAPITransform.xml b/xml/System.Security.Cryptography/CryptoAPITransform.xml index ecc8cfd6ee5..faf4e946f08 100644 --- a/xml/System.Security.Cryptography/CryptoAPITransform.xml +++ b/xml/System.Security.Cryptography/CryptoAPITransform.xml @@ -153,14 +153,14 @@ . + This method is a simple call to . Calling `Dispose` allows the resources used by the to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). ## Examples - The following code example demonstrates how to call the method to release the resources used by the current transform. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the method to release the resources used by the current transform. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.CryptoAPITransform/CPP/members.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptoAPITransform/Overview/members.cs" id="Snippet7"::: @@ -372,7 +372,7 @@ method is called automatically when you call TransformFinalBlock. The `Reset` method is not called when, for example, the encrypted input data is garbage and cannot be decrypted. In this case, an exception is thrown and `Reset` is not called. You can choose to manually call the `Reset` method in this case. + The method is called automatically when you call TransformFinalBlock. The `Reset` method is not called when, for example, the encrypted input data is garbage and cannot be decrypted. In this case, an exception is thrown and `Reset` is not called. You can choose to manually call the `Reset` method in this case. ]]> @@ -458,7 +458,7 @@ This member is an explicit interface member implementation. It can be used only method to transform the bytes from `currentPosition` in the `sourceBytes` array, writing the bytes to the `targetBytes` array. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the method to transform the bytes from `currentPosition` in the `sourceBytes` array, writing the bytes to the `targetBytes` array. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.CryptoAPITransform/CPP/members.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptoAPITransform/Overview/members.cs" id="Snippet8"::: @@ -518,7 +518,7 @@ This member is an explicit interface member implementation. It can be used only method to transform the final block of bytes. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the method to transform the final block of bytes. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.CryptoAPITransform/CPP/members.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptoAPITransform/Overview/members.cs" id="Snippet9"::: diff --git a/xml/System.Security.Cryptography/CryptoConfig.xml b/xml/System.Security.Cryptography/CryptoConfig.xml index 95899c8c046..2e84b9b2f6c 100644 --- a/xml/System.Security.Cryptography/CryptoConfig.xml +++ b/xml/System.Security.Cryptography/CryptoConfig.xml @@ -458,7 +458,7 @@ For a list of simple names recognized by this class, see . ## Examples - The following code example demonstrates how to call the method to create a new SHA-1 provider. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the method to create a new SHA-1 provider. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptoConfig/Overview/members.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoConfig/Overview/members.vb" id="Snippet4"::: @@ -555,7 +555,7 @@ ## Examples - The following code example demonstrates how to call the method to initialize a new RSA provider instance accessing the `TestContainer` key container. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the method to initialize a new RSA provider instance accessing the `TestContainer` key container. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptoConfig/Overview/members.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoConfig/Overview/members.vb" id="Snippet5"::: @@ -631,7 +631,7 @@ method to encode the specified object identifier. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the method to encode the specified object identifier. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptoConfig/Overview/members.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoConfig/Overview/members.vb" id="Snippet6"::: @@ -713,7 +713,7 @@ For a list of simple names recognized by this class, see . ## Examples - The following code example demonstrates how to call the method to retrieve an object identifier (OID) from the string name of the SHA-1 algorithm. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the method to retrieve an object identifier (OID) from the string name of the SHA-1 algorithm. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptoConfig/Overview/members.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoConfig/Overview/members.vb" id="Snippet3"::: diff --git a/xml/System.Security.Cryptography/CryptoStream.xml b/xml/System.Security.Cryptography/CryptoStream.xml index 0cd889e0440..9d53736ce54 100644 --- a/xml/System.Security.Cryptography/CryptoStream.xml +++ b/xml/System.Security.Cryptography/CryptoStream.xml @@ -76,13 +76,13 @@ The common language runtime uses a stream-oriented design for cryptography. The > [!IMPORTANT] > In .NET 6 and later versions, when `Stream.Read` or `Stream.ReadAsync` is called with a buffer of length `N`, the operation completes when either at least 1 byte has been read from the stream, or the underlying stream that it wraps returns 0 from a call to `Read`, indicating no more data is available. Prior to .NET 6, `Stream.Read` and `Stream.ReadAsync` did not return until all `N` bytes had been read from the stream or the underlying stream returned 0 from a call to `Read`. If your code assumes the `Read` methods won't return until all `N` bytes have been read, it could fail to read all the content. For more information, see [Partial and zero-byte reads in streams](/dotnet/core/compatibility/core-libraries/6.0/partial-byte-reads-in-streams). -You should always explicitly close your object after you're finished using it by calling the method. Doing so flushes the underlying stream and causes all remaining blocks of data to be processed by the object. However, if an exception occurs before you call the method, the object might not be closed. To ensure that the method always gets called, place your call to the method within the `finally` block of a `try`/`catch` statement. +You should always explicitly close your object after you're finished using it by calling the method. Doing so flushes the underlying stream and causes all remaining blocks of data to be processed by the object. However, if an exception occurs before you call the method, the object might not be closed. To ensure that the method always gets called, place your call to the method within the `finally` block of a `try`/`catch` statement. -This type implements the interface. When you've finished using the type, you should dispose of it either directly or indirectly by calling its method, which in turn calls its implementation. 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). +This type implements the interface. When you've finished using the type, you should dispose of it either directly or indirectly by calling its method, which in turn calls its implementation. 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). ## Examples -The following example demonstrates how to use a to encrypt a string. This method uses the class with the specified and initialization vector (). +The following example demonstrates how to use a to encrypt a string. This method uses the class with the specified and initialization vector (). :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptoStream/Overview/CryptoStream.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoStream/Overview/CryptoStream.vb" id="Snippet1"::: @@ -268,9 +268,9 @@ Any object that derives from can be passed into the `str > [!IMPORTANT] > Starting in .NET 6, this method might not read as many bytes as were requested. For more information, see [Partial and zero-byte reads in DeflateStream, GZipStream, and CryptoStream](/dotnet/core/compatibility/core-libraries/6.0/partial-byte-reads-in-streams). -In .NET Framework 4 and earlier versions, you have to use methods such as and to implement asynchronous I/O operations. These methods are still available in current versions to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. +In .NET Framework 4 and earlier versions, you have to use methods such as and to implement asynchronous I/O operations. These methods are still available in current versions to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. -Pass the `IAsyncResult` return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. must be called once for every call to . You can do this either by using the same code that called `BeginRead` or in a callback passed to `BeginRead`. +Pass the `IAsyncResult` return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. must be called once for every call to . You can do this either by using the same code that called `BeginRead` or in a callback passed to `BeginRead`. The current position in the stream is updated when the asynchronous read or write is issued, not when the I/O operation completes. @@ -351,9 +351,9 @@ If a stream is closed or you pass an invalid argument, exceptions are thrown imm and to implement asynchronous I/O operations. These methods are still available in current versions to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. +In .NET Framework 4 and earlier versions, you have to use methods such as and to implement asynchronous I/O operations. These methods are still available in current versions to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. -Pass the `IAsyncResult` returned by the current method to to ensure that the write completes and frees resources appropriately. must be called once for every call to . You can do this either by using the same code that called `BeginWrite` or in a callback passed to `BeginWrite`. If an error occurs during an asynchronous write, an exception will not be thrown until `EndWrite` is called with the `IAsyncResult` returned by this method. +Pass the `IAsyncResult` returned by the current method to to ensure that the write completes and frees resources appropriately. must be called once for every call to . You can do this either by using the same code that called `BeginWrite` or in a callback passed to `BeginWrite`. If an error occurs during an asynchronous write, an exception will not be thrown until `EndWrite` is called with the `IAsyncResult` returned by this method. If a stream is writable, writing at the end of the stream expands the stream. @@ -565,7 +565,7 @@ Seeking is not enabled in a , so implementation. +This method wraps a call to the type's implementation. Calling `Dispose` allows the resources used by the to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). @@ -824,7 +824,7 @@ For more information about and method enables you to perform a resource-intensive dispose operation without blocking the main thread. This performance consideration is particularly important in desktop apps where a time-consuming stream operation can block the UI thread and make the app appear as if it's not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. +The method enables you to perform a resource-intensive dispose operation without blocking the main thread. This performance consideration is particularly important in desktop apps where a time-consuming stream operation can block the UI thread and make the app appear as if it's not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. This method disposes the stream by writing any changes to the backing store and closing the stream to release resources. @@ -874,11 +874,11 @@ Calling `DisposeAsync` allows the resources used by the and to implement asynchronous I/O operations. These methods are still available in current versions to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. +In .NET Framework 4 and earlier versions, you have to use methods such as and to implement asynchronous I/O operations. These methods are still available in current versions to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. Call `EndRead` to determine how many bytes were read from the stream. -`EndRead` can be called once on every from . +`EndRead` can be called once on every from . This method blocks until the I/O operation has completed. @@ -935,9 +935,9 @@ This method blocks until the I/O operation has completed. and to implement asynchronous I/O operations. These methods are still available in current versions to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. +In .NET Framework 4 and earlier versions, you have to use methods such as and to implement asynchronous I/O operations. These methods are still available in current versions to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. -`EndWrite` must be called exactly once on every from . +`EndWrite` must be called exactly once on every from . This method blocks until the I/O operation has completed. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and become visible upon a call to `EndWrite`. Exceptions thrown by the thread pool thread will not be visible when calling `EndWrite`. @@ -1031,10 +1031,10 @@ This method blocks until the I/O operation has completed. Errors that occur duri or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. +Flushing the stream will not flush its underlying encoder unless you explicitly call or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. > [!NOTE] -> You should call either the method or the method to complete flushing the buffer. +> You should call either the method or the method to complete flushing the buffer. ]]> @@ -1089,7 +1089,7 @@ Flushing the stream will not flush its underlying encoder unless you explicitly with the `await` (C#) or `Await` (Visual Basic) operator to suspend execution of the method until the task is complete. For more information, see [Asynchronous programming (C#)](/dotnet/csharp/async) or [Asynchronous programming with Async and Await (Visual Basic)](/dotnet/visual-basic/programming-guide/concepts/async/). +You must preface your call to with the `await` (C#) or `Await` (Visual Basic) operator to suspend execution of the method until the task is complete. For more information, see [Asynchronous programming (C#)](/dotnet/csharp/async) or [Asynchronous programming with Async and Await (Visual Basic)](/dotnet/visual-basic/programming-guide/concepts/async/). If the operation is canceled before it completes, the returned task contains the value for the property. @@ -1147,7 +1147,7 @@ This method stores in the task it returns all non-usage exceptions that the meth method will call . If you do not call , call to complete flushing the buffer. Call only when all stream activity is complete. +Calling the method will call . If you do not call , call to complete flushing the buffer. Call only when all stream activity is complete. ]]> @@ -1242,7 +1242,7 @@ Calling the method will call method is called. +This property is set `true` when the method is called. ]]> @@ -1519,7 +1519,7 @@ This property exists only to support inheritance from , a > [!IMPORTANT] > Starting in .NET 6, this method might not read as many bytes as were requested. For more information, see [Partial and zero-byte reads in DeflateStream, GZipStream, and CryptoStream](/dotnet/core/compatibility/core-libraries/6.0/partial-byte-reads-in-streams). -You must preface your call to with the `await` (C#) or `Await` (Visual Basic) operator to suspend execution of the method until the task is complete. For more information, see [Asynchronous programming (C#)](/dotnet/csharp/async) or [Asynchronous programming with Async and Await (Visual Basic)](/dotnet/visual-basic/programming-guide/concepts/async/). +You must preface your call to with the `await` (C#) or `Await` (Visual Basic) operator to suspend execution of the method until the task is complete. For more information, see [Asynchronous programming (C#)](/dotnet/csharp/async) or [Asynchronous programming with Async and Await (Visual Basic)](/dotnet/visual-basic/programming-guide/concepts/async/). If the operation is canceled before it completes, the returned task contains the value for the property. @@ -1902,7 +1902,7 @@ This member is an explicit interface member implementation. It can be used only with the `await` (C#) or `Await` (Visual Basic) operator to suspend execution of the method until the task is complete. For more information, see [Asynchronous programming (C#)](/dotnet/csharp/async) or [Asynchronous programming with Async and Await (Visual Basic)](/dotnet/visual-basic/programming-guide/concepts/async/). +You must preface your call to with the `await` (C#) or `Await` (Visual Basic) operator to suspend execution of the method until the task is complete. For more information, see [Asynchronous programming (C#)](/dotnet/csharp/async) or [Asynchronous programming with Async and Await (Visual Basic)](/dotnet/visual-basic/programming-guide/concepts/async/). If the operation is canceled before it completes, the returned task contains the value for the property. diff --git a/xml/System.Security.Cryptography/CryptographicAttributeObjectCollection.xml b/xml/System.Security.Cryptography/CryptographicAttributeObjectCollection.xml index 8290fa7c081..510ac3e8558 100644 --- a/xml/System.Security.Cryptography/CryptographicAttributeObjectCollection.xml +++ b/xml/System.Security.Cryptography/CryptographicAttributeObjectCollection.xml @@ -232,7 +232,7 @@ + ]]> diff --git a/xml/System.Security.Cryptography/CryptographicException.xml b/xml/System.Security.Cryptography/CryptographicException.xml index 3cbe8808325..665405e00fd 100644 --- a/xml/System.Security.Cryptography/CryptographicException.xml +++ b/xml/System.Security.Cryptography/CryptographicException.xml @@ -159,8 +159,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The localized error message string.| +||`null`.| +||The localized error message string.| @@ -227,14 +227,14 @@ constructor accepts a system `HRESULT` error code and sets the property to a localized message that corresponds to the `HRESULT`. + The constructor accepts a system `HRESULT` error code and sets the property to a localized message that corresponds to the `HRESULT`. The following table shows the initial property values for an instance of . |Property|Value| |--------------|-----------| -||`null`.| -||The localized error message string.| +||`null`.| +||The localized error message string.| @@ -300,8 +300,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string.| +||`null`.| +||The error message string.| @@ -439,8 +439,8 @@ |Property|Value| |--------------|-----------| -||The inner exception reference.| -||The error message string.| +||The inner exception reference.| +||The error message string.| @@ -524,8 +524,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string.| +||`null`.| +||The error message string.| diff --git a/xml/System.Security.Cryptography/CryptographicUnexpectedOperationException.xml b/xml/System.Security.Cryptography/CryptographicUnexpectedOperationException.xml index 3fdac4bc6dd..68ca0bca354 100644 --- a/xml/System.Security.Cryptography/CryptographicUnexpectedOperationException.xml +++ b/xml/System.Security.Cryptography/CryptographicUnexpectedOperationException.xml @@ -147,8 +147,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The localized error message string.| +||`null`.| +||The localized error message string.| @@ -213,8 +213,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string.| +||`null`.| +||The error message string.| @@ -351,8 +351,8 @@ |Property|Value| |--------------|-----------| -||The inner exception reference.| -||The error message string.| +||The inner exception reference.| +||The error message string.| @@ -428,8 +428,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string.| +||`null`.| +||The error message string.| diff --git a/xml/System.Security.Cryptography/CspParameters.xml b/xml/System.Security.Cryptography/CspParameters.xml index 2905e86fd2a..5655dfcc5d9 100644 --- a/xml/System.Security.Cryptography/CspParameters.xml +++ b/xml/System.Security.Cryptography/CspParameters.xml @@ -154,7 +154,7 @@ initializes the field to a value of `24`, which specifies the PROV_RSA_AES provider. This default provider is compatible with the algorithm. + This form of initializes the field to a value of `24`, which specifies the PROV_RSA_AES provider. This default provider is compatible with the algorithm. For information about other provider types, see the field. @@ -218,7 +218,7 @@ constructor to specify a provider type by passing a numeric value that represents that provider. The numeric values that represent the default provider types are defined in the WinCrypt.h header file: + Use the constructor to specify a provider type by passing a numeric value that represents that provider. The numeric values that represent the default provider types are defined in the WinCrypt.h header file: - To specify a provider compatible with the algorithm, pass a value of `1` to the `dwTypeIn` parameter. @@ -281,7 +281,7 @@ constructor to specify a provider type and name. + Use the constructor to specify a provider type and name. Specify a provider type by passing a numeric value that represents the desired provider type. The numeric values that represent the default provider types are defined in the WinCrypt.h header file: @@ -356,7 +356,7 @@ constructor to specify a provider type, a provider name, and a container name. + Use the constructor to specify a provider type, a provider name, and a container name. You can use the container name to retrieve a key within that container. diff --git a/xml/System.Security.Cryptography/DES.xml b/xml/System.Security.Cryptography/DES.xml index 4c3d76441a0..b9a8967540d 100644 --- a/xml/System.Security.Cryptography/DES.xml +++ b/xml/System.Security.Cryptography/DES.xml @@ -219,7 +219,7 @@ ## Examples The following code example shows how to create and use a object to encrypt and decrypt data in a file. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/DES/Create/fileexample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/DES/Create/fileexample.vb" id="Snippet1"::: @@ -357,7 +357,7 @@ ## Remarks Semi-weak keys are pairs of keys that result in ciphers that are easy to break. If text is encrypted with a semi-weak key, encrypting the resulting cipher with the partner of that semi-weak key returns the original text. There are six known semi-weak key pairs for the Data Encryption Standard () algorithm; this method checks for those semi-weak keys. - Attempting to set a semi-weak key results in a . When is called to create a random key, a semi-weak key will never be returned. + Attempting to set a semi-weak key results in a . When is called to create a random key, a semi-weak key will never be returned. ]]> @@ -418,7 +418,7 @@ ## Remarks Weak keys are keys that result in ciphers that are easy to break. If text is encrypted with a weak key, encrypting the resulting cipher again with the same weak key returns the original text. There are four known weak keys for the Data Encryption Standard () algorithm; this method checks for those weak keys. - Attempting to set a weak key results in a . When is called to create a random key, a weak key will never be returned. + Attempting to set a weak key results in a . When is called to create a random key, a weak key will never be returned. ]]> @@ -472,7 +472,7 @@ is called to create a new random value. + If this property is `null` when it is used, is called to create a new random value. The length of the key must be equal to . diff --git a/xml/System.Security.Cryptography/DESCryptoServiceProvider.xml b/xml/System.Security.Cryptography/DESCryptoServiceProvider.xml index 048c9b15eca..1e0a567483e 100644 --- a/xml/System.Security.Cryptography/DESCryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/DESCryptoServiceProvider.xml @@ -82,12 +82,12 @@ > A newer symmetric encryption algorithm, Advanced Encryption Standard (AES), is available. Consider using the class instead of the class. Use only for compatibility with legacy applications and data. ## Examples - The following code example uses (an implementation of ) with the specified key () and initialization vector () to encrypt a file specified by `inName`. It then outputs the encrypted result to the file specified by `outName`. + The following code example uses (an implementation of ) with the specified key () and initialization vector () to encrypt a file specified by `inName`. It then outputs the encrypted result to the file specified by `outName`. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/DESCryptoServiceProvider/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/DESCryptoServiceProvider/Overview/source.vb" id="Snippet1"::: - Decryption can be handled in the same way; use instead of . The same key () and initialization vector () used to encrypt the file must be used to decrypt it. + Decryption can be handled in the same way; use instead of . The same key () and initialization vector () used to encrypt the file must be used to decrypt it. ]]> @@ -142,12 +142,12 @@ (an implementation of ) with the specified key () and initialization vector () to encrypt a file specified by `inName`. It then outputs the encrypted result to the file specified by `outName`. + The following code example uses (an implementation of ) with the specified key () and initialization vector () to encrypt a file specified by `inName`. It then outputs the encrypted result to the file specified by `outName`. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/DESCryptoServiceProvider/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/DESCryptoServiceProvider/Overview/source.vb" id="Snippet1"::: - Decryption can be handled in the same way; use instead of . The same key () and initialization vector () used to encrypt the file must be used to decrypt it. + Decryption can be handled in the same way; use instead of . The same key () and initialization vector () used to encrypt the file must be used to decrypt it. ]]> @@ -194,7 +194,7 @@ overload with the same signature. + This method decrypts an encrypted message created using the overload with the same signature. ]]> @@ -266,7 +266,7 @@ overload with the same parameters. + This method decrypts an encrypted message that was created using the overload with the same parameters. ]]> @@ -334,9 +334,9 @@ property is `null`, the method is called to create a new random . If the current property is `null`, the method is called to create a new random . + If the current property is `null`, the method is called to create a new random . If the current property is `null`, the method is called to create a new random . - Use the overload with the same signature to decrypt the result of this method. + Use the overload with the same signature to decrypt the result of this method. ]]> @@ -408,7 +408,7 @@ overload with the same parameters to decrypt the result of this method. + Use the overload with the same parameters to decrypt the result of this method. @@ -487,7 +487,7 @@ when none is specified. + Use this method to generate a random when none is specified. ]]> @@ -540,7 +540,7 @@ ) or a semi-weak key (see ). + Use this method to generate a random key when none is specified. This method will never return a weak key (see ) or a semi-weak key (see ). This algorithm supports a key length of 64 bits. diff --git a/xml/System.Security.Cryptography/DSACng.xml b/xml/System.Security.Cryptography/DSACng.xml index 6b8458290ca..a6423a2724c 100644 --- a/xml/System.Security.Cryptography/DSACng.xml +++ b/xml/System.Security.Cryptography/DSACng.xml @@ -200,7 +200,7 @@ Valid key sizes range from 512 to 3,072 bits, in increments of 64. We recommend of `key` must be . + The of `key` must be . This constructor creates a copy of the key. Even if `key` is disposed, the copy of this key object in DSA remains alive. @@ -674,9 +674,9 @@ An error occurred during signature creation. object is disposed if the key is reset, for instance by changing the property, by using the method to create a new key, or by disposing the parent object. Therefore, you should ensure that the key object is no longer used in these cases. + The object is disposed if the key is reset, for instance by changing the property, by using the method to create a new key, or by disposing the parent object. Therefore, you should ensure that the key object is no longer used in these cases. - This object is not the same as the object passed to the constructor, if that constructor was used. However, it will point to the same CNG key. + This object is not the same as the object passed to the constructor, if that constructor was used. However, it will point to the same CNG key. ]]> diff --git a/xml/System.Security.Cryptography/DSACryptoServiceProvider.xml b/xml/System.Security.Cryptography/DSACryptoServiceProvider.xml index d029767d022..d23158b5e55 100644 --- a/xml/System.Security.Cryptography/DSACryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/DSACryptoServiceProvider.xml @@ -448,7 +448,7 @@ ## Remarks Use the property to retrieve additional information about a cryptographic key pair. The returned object describes whether the key is exportable, and specifies the key container name, information about the provider, and other information. - In cases where a random key is generated, a key container will not be created until you call a method that uses the key. Some properties of the object returned by the property will throw a if a key container has not been created. To make sure that a key container has been created, call a method such as , , , , and so on, before you call the property. + In cases where a random key is generated, a key container will not be created until you call a method that uses the key. Some properties of the object returned by the property will throw a if a key container has not been created. To make sure that a key container has been created, call a method such as , , , , and so on, before you call the property. ]]> @@ -573,7 +573,7 @@ method returns a blob containing key information that is compatible with the unmanaged Microsoft Cryptographic API (CAPI). + The method returns a blob containing key information that is compatible with the unmanaged Microsoft Cryptographic API (CAPI). ]]> @@ -827,7 +827,7 @@ method initializes the key data of a object using a blob that is compatible with the unmanaged Microsoft Cryptographic API (CAPI). + The method initializes the key data of a object using a blob that is compatible with the unmanaged Microsoft Cryptographic API (CAPI). ]]> @@ -1377,7 +1377,7 @@ This algorithm supports key lengths from 512 bits to 1024 bits in increments of method. + This method creates a digital signature that is verified using the method. uses the hash algorithm. @@ -1511,7 +1511,7 @@ This algorithm supports key lengths from 512 bits to 1024 bits in increments of method. + This method creates a digital signature that is verified using the method. uses the hash algorithm. @@ -1586,7 +1586,7 @@ This algorithm supports key lengths from 512 bits to 1024 bits in increments of method. + This method creates a digital signature that is verified using the method. uses the hash algorithm. @@ -1648,7 +1648,7 @@ This algorithm supports key lengths from 512 bits to 1024 bits in increments of flag to a object. The property applies to all code in the current application domain, while the object applies only to classes that explicitly reference it. These settings are useful when impersonating or running under an account whose user profile is not loaded. + Setting this property to true is equivalent to passing the flag to a object. The property applies to all code in the current application domain, while the object applies only to classes that explicitly reference it. These settings are useful when impersonating or running under an account whose user profile is not loaded. ]]> @@ -1725,7 +1725,7 @@ This algorithm supports key lengths from 512 bits to 1024 bits in increments of digital signature produced by . + This method verifies the digital signature produced by . uses the hash algorithm. @@ -1803,7 +1803,7 @@ This algorithm supports key lengths from 512 bits to 1024 bits in increments of digital signature produced by . + This method verifies the digital signature produced by . If the `str` parameter is `null`, the default hash algorithm (SHA-1) is used. diff --git a/xml/System.Security.Cryptography/DSAOpenSsl.xml b/xml/System.Security.Cryptography/DSAOpenSsl.xml index 08ee378d015..983a0b658df 100644 --- a/xml/System.Security.Cryptography/DSAOpenSsl.xml +++ b/xml/System.Security.Cryptography/DSAOpenSsl.xml @@ -47,7 +47,7 @@ ## Remarks -This class should only be used directly when doing platform interop with the system OpenSSL library. When platform interop is not needed, you should use the factory methods instead of a specific derived implementation. +This class should only be used directly when doing platform interop with the system OpenSSL library. When platform interop is not needed, you should use the factory methods instead of a specific derived implementation. > [!IMPORTANT] > The creators of the DSA algorithm have withdrawn their support for it. Consider using the class or the class instead of the class. Use only for compatibility with legacy applications and data. @@ -109,7 +109,7 @@ DSAOpenSSL provides the FIPS 186-3 version of DSA. ## Remarks This constructor does not generate a new DSA public/private keypair immediately, it just sets the size that will be used to generate a key when one is needed. -If key is loaded via the method, or other key import method, the key size from this constructor has no meaning. +If key is loaded via the method, or other key import method, the key size from this constructor has no meaning. ]]> @@ -171,7 +171,7 @@ If key is loaded via the method, or other key import method, the `keySize` provided to this constructor has no meaning. +If key is loaded via the method, or other key import method, the `keySize` provided to this constructor has no meaning. ]]> diff --git a/xml/System.Security.Cryptography/DSASignatureFormatter.xml b/xml/System.Security.Cryptography/DSASignatureFormatter.xml index 1d9e93f2b43..29e71b4c348 100644 --- a/xml/System.Security.Cryptography/DSASignatureFormatter.xml +++ b/xml/System.Security.Cryptography/DSASignatureFormatter.xml @@ -242,7 +242,7 @@ . + The resulting signature data can be verified by using . diff --git a/xml/System.Security.Cryptography/DataProtectionScope.xml b/xml/System.Security.Cryptography/DataProtectionScope.xml index 519e57949c2..e17751ac9cd 100644 --- a/xml/System.Security.Cryptography/DataProtectionScope.xml +++ b/xml/System.Security.Cryptography/DataProtectionScope.xml @@ -37,7 +37,7 @@ and methods to protect data through encryption. + This enumeration is used with the and methods to protect data through encryption. **Caution** The LocalMachine enumeration value allows multiple accounts to unprotect data. Use this value only when you trust every account on a computer. For most situations, you should use the CurrentUser value. @@ -45,7 +45,7 @@ ## Examples The following code example shows how to use data protection. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/DataProtectionScope/Overview/dataprotectionsample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/DataProtectionScope/Overview/dataprotectionsample.vb" id="Snippet1"::: diff --git a/xml/System.Security.Cryptography/DataProtector.xml b/xml/System.Security.Cryptography/DataProtector.xml index ac5f95ef40b..9ea0b92312f 100644 --- a/xml/System.Security.Cryptography/DataProtector.xml +++ b/xml/System.Security.Cryptography/DataProtector.xml @@ -16,26 +16,26 @@ Provides the base class for data protectors. - and methods, which the base class calls back into. They must also override the method, which can always return `true` with a potential small loss of efficiency when applications refresh their database of stored cipher text. Derived classes should provide a constructor that calls the base class constructor, which sets the , , and properties. - - - -## Examples - The following example demonstrates how to create a data protector that uses a protection class with an option for extra entropy. By default, the class prepends the hash of the purpose properties to the data to be encrypted. You can turn that functionality off and use the hashed purpose as extra entropy when calling a data protector with an extra entropy option. - + and methods, which the base class calls back into. They must also override the method, which can always return `true` with a potential small loss of efficiency when applications refresh their database of stored cipher text. Derived classes should provide a constructor that calls the base class constructor, which sets the , , and properties. + + + +## Examples + The following example demonstrates how to create a data protector that uses a protection class with an option for extra entropy. By default, the class prepends the hash of the purpose properties to the data to be encrypted. You can turn that functionality off and use the hashed purpose as extra entropy when calling a data protector with an extra entropy option. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/DataProtector/Overview/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/DataProtector/Overview/class1.vb" id="Snippet1"::: - - The following example demonstrates a simple data protector that uses the functionality of the class. - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/DataProtector/Overview/class1.vb" id="Snippet1"::: + + The following example demonstrates a simple data protector that uses the functionality of the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/DataProtector/Overview/class11.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/DataProtector/Overview/class11.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/DataProtector/Overview/class11.vb" id="Snippet1"::: + ]]> @@ -63,22 +63,22 @@ The specific purposes for the protected data. Creates a new instance of the class by using the provided application name, primary purpose, and specific purposes. - , , and properties. The combination of these three properties must uniquely identify the data you are protecting. If the data is not uniquely identified, you might inadvertently read the wrong data, or other data might be substituted for yours. Examples of primary and specific purpose pairs are "invoice" and invoice number, "gift card" and gift card number, "password" and URL string. - + , , and properties. The combination of these three properties must uniquely identify the data you are protecting. If the data is not uniquely identified, you might inadvertently read the wrong data, or other data might be substituted for yours. Examples of primary and specific purpose pairs are "invoice" and invoice number, "gift card" and gift card number, "password" and URL string. + ]]> - is an empty string or . - - -or- - - is an empty string or . - - -or- - + is an empty string or . + + -or- + + is an empty string or . + + -or- + contains an empty string or . @@ -163,19 +163,19 @@ Creates a hash of the property values specified by the constructor. An array of bytes that contain the hash of the , , and properties. - computes the hash of the application name and the full purpose. The full purpose is a concatenation of all the and properties. Each of the three parts is prefaced with its length so the hash can be reversed. - - - -## Examples - The following example shows how to use the method to hash the purpose properties for use as extra entropy. It is part of a larger code example for the class. - + computes the hash of the application name and the full purpose. The full purpose is a concatenation of all the and properties. Each of the three parts is prefaced with its length so the hash can be reversed. + + + +## Examples + The following example shows how to use the method to hash the purpose properties for use as extra entropy. It is part of a larger code example for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/DataProtector/Overview/class1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/DataProtector/Overview/class1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/DataProtector/Overview/class1.vb" id="Snippet3"::: + ]]> @@ -225,11 +225,11 @@ Specifies whether the hash is prepended to the text array before encryption. Always . - , , and properties to the plain text before encryption, and will check and verify the hash during decryption. If a derived class wants to specify the prepended data on its own (for example as an optional entropy value), this property can be overridden and set to return `false`. If is `false`, and passes directly through to the and overrides without altering the byte array. - + , , and properties to the plain text before encryption, and will check and verify the hash during decryption. If a derived class wants to specify the prepended data on its own (for example as an optional entropy value), this property can be overridden and set to return `false`. If is `false`, and passes directly through to the and overrides without altering the byte array. + ]]> @@ -305,14 +305,14 @@ Specifies the delegate method in the derived class that the method in the base class calls back into. A byte array that contains the encrypted data. - method. It is part of a larger code example for the class. - + method. It is part of a larger code example for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/DataProtector/Overview/class11.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/DataProtector/Overview/class11.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/DataProtector/Overview/class11.vb" id="Snippet3"::: + ]]> @@ -340,14 +340,14 @@ Specifies the delegate method in the derived class that the method in the base class calls back into. The unencrypted data. - method. It is part of a larger code example for the class. - + method. It is part of a larger code example for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/DataProtector/Overview/class11.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/DataProtector/Overview/class11.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/DataProtector/Overview/class11.vb" id="Snippet4"::: + ]]> diff --git a/xml/System.Security.Cryptography/DpapiDataProtector.xml b/xml/System.Security.Cryptography/DpapiDataProtector.xml index 1637ef8a0de..a5ada56f6c7 100644 --- a/xml/System.Security.Cryptography/DpapiDataProtector.xml +++ b/xml/System.Security.Cryptography/DpapiDataProtector.xml @@ -19,11 +19,11 @@ class provides a structured way to protect data by using the class. The class constructor has purpose parameters that serve like a password to identify the protected data. All three parameters are hashed and included as part of the encrypted data string. You must know the purpose parameters to unprotect the data. The method that is called to encrypt the data has an `optionalEntropy` parameter that allows you to add qualifying information to encrypt the data more securely. The hash of the purpose parameters is used for optional entropy. Because you do not need a key to decrypt the data, carefully choosing the purpose data adds another level of security to data protection. + The class provides a structured way to protect data by using the class. The class constructor has purpose parameters that serve like a password to identify the protected data. All three parameters are hashed and included as part of the encrypted data string. You must know the purpose parameters to unprotect the data. The method that is called to encrypt the data has an `optionalEntropy` parameter that allows you to add qualifying information to encrypt the data more securely. The hash of the purpose parameters is used for optional entropy. Because you do not need a key to decrypt the data, carefully choosing the purpose data adds another level of security to data protection. - If you use a setting of , only a user with logon credentials that match those of the user who encrypted the data can decrypt the data. In addition, decryption usually can be done only on the computer where the data was encrypted. The Windows function that encrypts the data creates a session key to perform the encryption. The session key is derived again when the data is to be decrypted. For a detailed description of how data is protected by using session keys, see [Windows Data Protection](https://go.microsoft.com/fwlink/?LinkId=224686). + If you use a setting of , only a user with logon credentials that match those of the user who encrypted the data can decrypt the data. In addition, decryption usually can be done only on the computer where the data was encrypted. The Windows function that encrypts the data creates a session key to perform the encryption. The session key is derived again when the data is to be decrypted. For a detailed description of how data is protected by using session keys, see [Windows Data Protection](https://go.microsoft.com/fwlink/?LinkId=224686). - If you use a setting of when protecting the data and do not carefully identify the purpose parameters, any other application on that computer that knows the purposes can access and unprotect the data. + If you use a setting of when protecting the data and do not carefully identify the purpose parameters, any other application on that computer that knows the purposes can access and unprotect the data. ]]> @@ -222,7 +222,7 @@ to , only applications running on your credentials can unprotect the data; however, that means that any application running on your credentials can access the protected data. If you set the to , any full-trust application on the computer can unprotect, access, and modify the data if it knows the application name, the primary purpose, and the specific purpose. + Data protection encrypts the data on the disk so it cannot be read by other programs. You do not need a key to protect or unprotect the data. If you set the to , only applications running on your credentials can unprotect the data; however, that means that any application running on your credentials can access the protected data. If you set the to , any full-trust application on the computer can unprotect, access, and modify the data if it knows the application name, the primary purpose, and the specific purpose. ]]> diff --git a/xml/System.Security.Cryptography/ECCurve.xml b/xml/System.Security.Cryptography/ECCurve.xml index e9259eab443..0851b95d599 100644 --- a/xml/System.Security.Cryptography/ECCurve.xml +++ b/xml/System.Security.Cryptography/ECCurve.xml @@ -716,7 +716,7 @@ property directly. Instead, to create a named curve, use the , the , or the methods. + You cannot set a value for the property directly. Instead, to create a named curve, use the , the , or the methods. On some systems, the property is the primary referenced identifier, while on others it's the property. Manually creating an object with mismatched values may produce undesirable results. diff --git a/xml/System.Security.Cryptography/ECDiffieHellman.xml b/xml/System.Security.Cryptography/ECDiffieHellman.xml index 3bed7dec0e9..fdc4bbd737a 100644 --- a/xml/System.Security.Cryptography/ECDiffieHellman.xml +++ b/xml/System.Security.Cryptography/ECDiffieHellman.xml @@ -66,11 +66,11 @@ Provides an abstract base class that Elliptic Curve Diffie-Hellman (ECDH) algorithm implementations can derive from. This class provides the basic set of operations that all ECDH implementations must support. - @@ -116,11 +116,11 @@ Initializes a new instance of the class. - class. The class is the only implementation that is currently included in the .NET Framework. For information about how to create a new implementation of the Elliptic Curve Diffie-Hellman (ECDH) algorithm, see the method. - + class. The class is the only implementation that is currently included in the .NET Framework. For information about how to create a new implementation of the Elliptic Curve Diffie-Hellman (ECDH) algorithm, see the method. + ]]> @@ -230,13 +230,13 @@ Creates a new instance of the default implementation of the Elliptic Curve Diffie-Hellman (ECDH) algorithm with a new public/private key-pair generated over the specified curve. A new instance of the default implementation of the Elliptic Curve Diffie-Hellman (ECDH) algorithm. - method. - - Characteristic-2 curves are not supported on Windows. - + method. + + Characteristic-2 curves are not supported on Windows. + ]]> @@ -292,13 +292,13 @@ Creates a new instance of the default implementation of the Elliptic Curve Diffie-Hellman (ECDH) algorithm with the key described by the specified object. A new instance of the default implementation of the Elliptic Curve Diffie-Hellman (ECDH) algorithm. - method. Parameters over implicit curves are not supported. - - Characteristic-2 curves are not supported on Windows. - + method. Parameters over implicit curves are not supported. + + Characteristic-2 curves are not supported on Windows. + ]]> @@ -366,23 +366,23 @@ Creates a new instance of the specified implementation of the Elliptic Curve Diffie-Hellman (ECDH) algorithm. A new instance of the specified implementation of this class. If the specified algorithm name does not map to an ECDH implementation, this method returns . - object, you can use the method overload to create a custom `algorithm` string that specifies your implementation. - - The `algorithm` parameter specifies the name of an implementation of the ECDH algorithm. The following strings all refer to the same implementation, which is the only implementation currently supported in the .NET Framework: - -- "ECDH" - -- "ECDiffieHellman" - -- "ECDiffieHellmanCng" - -- "System.Security.Cryptography.ECDiffieHellmanCng" - - You can also provide the name of a custom ECDH implementation for the `algorithm` parameter. If you do that, the object will use it to determine whether an ECDH object can be created. - + object, you can use the method overload to create a custom `algorithm` string that specifies your implementation. + + The `algorithm` parameter specifies the name of an implementation of the ECDH algorithm. The following strings all refer to the same implementation, which is the only implementation currently supported in the .NET Framework: + +- "ECDH" + +- "ECDiffieHellman" + +- "ECDiffieHellmanCng" + +- "System.Security.Cryptography.ECDiffieHellmanCng" + + You can also provide the name of a custom ECDH implementation for the `algorithm` parameter. If you do that, the object will use it to determine whether an ECDH object can be created. + ]]> The parameter is . @@ -441,25 +441,25 @@ Performs key derivation using a specified hash algorithm. The hash of the shared secret. - method passing `null` as the prepend and append values. - + method passing `null` as the prepend and append values. + ]]> - The curve used by has a different size than the curve from this key. - --or- - -The parameter does not specify a hash. + The curve used by has a different size than the curve from this key. + +-or- + +The parameter does not specify a hash. is . - The curve used by is different than the curve from this key. - --or- - + The curve used by is different than the curve from this key. + +-or- + This instance represents only a public key. @@ -526,30 +526,30 @@ This instance represents only a public key. When implemented in a derived class, performs key derivation using a specified hash algorithm with optional prepended or appended data. The hash of the shared secret after prepending or appending data as requested. - A derived class must override this method. - The curve used by has a different size than the curve from this key. - --or- - -The parameter does not specify a hash. + The curve used by has a different size than the curve from this key. + +-or- + +The parameter does not specify a hash. is . - The curve used by is different than the curve from this key. - --or- - + The curve used by is different than the curve from this key. + +-or- + This instance represents only a public key. @@ -616,25 +616,25 @@ This instance represents only a public key. Performs key derivation using a specified HMAC (Hash-based Message Authentication Code) algorithm. The HMAC of the shared secret. - method passing `null` as the prepend and append values. - + method passing `null` as the prepend and append values. + ]]> - The curve used by has a different size than the curve from this key. - --or- - -The parameter does not specify a hash. + The curve used by has a different size than the curve from this key. + +-or- + +The parameter does not specify a hash. is . - The curve used by is different than the curve from this key. - --or- - + The curve used by is different than the curve from this key. + +-or- + This instance represents only a public key. @@ -702,31 +702,31 @@ This instance represents only a public key. When implemented in a derived class, performs key derivation using a specified HMAC (Hash-based Message Authentication Code) algorithm with optional prepended or appended data. The HMAC of the shared secret after prepending or appending data as requested. - A derived class must override this method. - The curve used by has a different size than the curve from this key. - --or- - -The parameter does not specify a hash. + The curve used by has a different size than the curve from this key. + +-or- + +The parameter does not specify a hash. is . - The curve used by is different than the curve from this key. - --or- - + The curve used by is different than the curve from this key. + +-or- + This instance represents only a public key. @@ -777,23 +777,23 @@ This instance represents only a public key. When implemented in a derived class, performs a key derivation on the shared secret. The result of the key derivation function, using the shared secret as an input. - specifying SHA-256 as the hash algorithm with no prepend or append values. -Some implementations allow the behavior of this method to be changed, -and callers are advised to call whichever method explicitly says it performs the key derivation they need. - + specifying SHA-256 as the hash algorithm with no prepend or append values. +Some implementations allow the behavior of this method to be changed, +and callers are advised to call whichever method explicitly says it performs the key derivation they need. + ]]> The curve used by has a different size than the curve from this key. is . - The curve used by is different than the curve from this key. - --or- - + The curve used by is different than the curve from this key. + +-or- + This instance represents only a public key. @@ -843,17 +843,17 @@ This instance represents only a public key. When implemented in a derived class, performs key derivation using the TLS (Transport Layer Security) 1.1 PRF (Pseudo-Random Function). The first 48 bytes from the TLS 1.1 PRF, using the shared secret as the key. - A derived class must override this method. @@ -861,14 +861,14 @@ For more information, see [IETF RFC 4346, section 5](https://tools.ietf.org/html , or is . - is not exactly 64 bytes in length. - --or- - -The curve used by is different than the curve from this key. - --or- - + is not exactly 64 bytes in length. + +-or- + +The curve used by is different than the curve from this key. + +-or- + This instance represents only a public key. @@ -1026,11 +1026,11 @@ This instance represents only a public key. When overridden in a derived class, exports either the public or the public and private key information from a working key to an structure so that it can be passed to the method. An object that represents the point on the curve for this key. It can be passed to the method. - property contains named curve parameters; otherwise, it will contain explicit parameters. - + property contains named curve parameters; otherwise, it will contain explicit parameters. + ]]> A derived class must override this method. @@ -1112,13 +1112,13 @@ This instance represents only a public key. The curve used to generate an ephemeral public/private key pair. When overridden in a derived class, generates a new ephemeral public/private key pair for the specified curve. - method) and must not be implicit. - - Characteristic-2 curves are not supported on Windows. - + method) and must not be implicit. + + Characteristic-2 curves are not supported on Windows. + ]]> @@ -1160,20 +1160,20 @@ This instance represents only a public key. When this method returns, contains a value that indicates the number of bytes read from . This parameter is treated as uninitialized. Imports the public/private keypair from an ECPrivateKey structure, replacing the keys for this object. - - The contents of do not represent an ASN.1-BER-encoded PKCS#8 ECPrivateKey structure. - --or- - -The key import failed. + The contents of do not represent an ASN.1-BER-encoded PKCS#8 ECPrivateKey structure. + +-or- + +The key import failed. @@ -1212,37 +1212,37 @@ The key import failed. When this method returns, contains a value that indicates the number of bytes read from . This parameter is treated as uninitialized. Imports the public/private keypair from a PKCS#8 EncryptedPrivateKeyInfo structure after decrypting with a byte-based password, replacing the keys for this object. - - The password is incorrect. - --or- - -The contents of indicate the Key Derivation Function (KDF) to apply is the legacy PKCS#12 KDF, which requires -based passwords. - --or- - -The contents of do not represent an ASN.1-BER-encoded PKCS#8 EncryptedPrivateKeyInfo structure. - --or- - -The contents of indicate the key is for an algorithm other than the algorithm represented by this instance. - --or- - -The contents of represent the key in a format that is not supported. - --or- - + The password is incorrect. + +-or- + +The contents of indicate the Key Derivation Function (KDF) to apply is the legacy PKCS#12 KDF, which requires -based passwords. + +-or- + +The contents of do not represent an ASN.1-BER-encoded PKCS#8 EncryptedPrivateKeyInfo structure. + +-or- + +The contents of indicate the key is for an algorithm other than the algorithm represented by this instance. + +-or- + +The contents of represent the key in a format that is not supported. + +-or- + The algorithm-specific key import failed. @@ -1281,31 +1281,31 @@ The algorithm-specific key import failed. When this method returns, contains a value that indicates the number of bytes read from . This parameter is treated as uninitialized. Imports the public/private keypair from a PKCS#8 EncryptedPrivateKeyInfo structure after decrypting with a char-based password, replacing the keys for this object. - - The password is incorrect. - --or- - -The contents of do not represent an ASN.1-BER-encoded PKCS#8 EncryptedPrivateKeyInfo structure. - --or- - -The contents of indicate the key is for an algorithm other than the algorithm represented by this instance. - --or- - -The contents of represent the key in a format that is not supported. - --or- - + The password is incorrect. + +-or- + +The contents of do not represent an ASN.1-BER-encoded PKCS#8 EncryptedPrivateKeyInfo structure. + +-or- + +The contents of indicate the key is for an algorithm other than the algorithm represented by this instance. + +-or- + +The contents of represent the key in a format that is not supported. + +-or- + The algorithm-specific key import failed. @@ -1340,47 +1340,47 @@ The algorithm-specific key import failed. The bytes to use as a password when decrypting the key material. Imports an encrypted RFC 7468 PEM-encoded private key, replacing the keys for this object. - - does not contain a PEM-encoded key with a recognized label. - --or- - - contains multiple PEM-encoded keys with a recognized label. + does not contain a PEM-encoded key with a recognized label. + +-or- + + contains multiple PEM-encoded keys with a recognized label. - -The password is incorrect. - --or- - -The base-64 decoded contents of the PEM text from do not represent an ASN.1-BER-encoded PKCS#8 EncryptedPrivateKeyInfo structure. - --or- - -The base-64 decoded contents of the PEM text from indicate the key is for an algorithm other than the algorithm represented by this instance. - --or- - -The base-64 decoded contents of the PEM text from represent the key in a format that is not supported. - --or- - -The algorithm-specific key import failed. + +The password is incorrect. + +-or- + +The base-64 decoded contents of the PEM text from do not represent an ASN.1-BER-encoded PKCS#8 EncryptedPrivateKeyInfo structure. + +-or- + +The base-64 decoded contents of the PEM text from indicate the key is for an algorithm other than the algorithm represented by this instance. + +-or- + +The base-64 decoded contents of the PEM text from represent the key in a format that is not supported. + +-or- + +The algorithm-specific key import failed. @@ -1415,47 +1415,47 @@ The algorithm-specific key import failed. The password to use for decrypting the key material. Imports an encrypted RFC 7468 PEM-encoded private key, replacing the keys for this object. - - does not contain a PEM-encoded key with a recognized label. - --or- - - contains multiple PEM-encoded keys with a recognized label. + does not contain a PEM-encoded key with a recognized label. + +-or- + + contains multiple PEM-encoded keys with a recognized label. - -The password is incorrect. - --or- - -The base-64 decoded contents of the PEM text from do not represent an ASN.1-BER-encoded PKCS#8 EncryptedPrivateKeyInfo structure. - --or- - -The base-64 decoded contents of the PEM text from indicate the key is for an algorithm other than the algorithm represented by this instance. - --or- - -The base-64 decoded contents of the PEM text from represent the key in a format that is not supported. - --or- - -The algorithm-specific key import failed. + +The password is incorrect. + +-or- + +The base-64 decoded contents of the PEM text from do not represent an ASN.1-BER-encoded PKCS#8 EncryptedPrivateKeyInfo structure. + +-or- + +The base-64 decoded contents of the PEM text from indicate the key is for an algorithm other than the algorithm represented by this instance. + +-or- + +The base-64 decoded contents of the PEM text from represent the key in a format that is not supported. + +-or- + +The algorithm-specific key import failed. @@ -1488,32 +1488,32 @@ The algorithm-specific key import failed. The PEM text of the key to import. Imports an RFC 7468 PEM-encoded key, replacing the keys for this object. - - does not contain a PEM-encoded key with a recognized label. - --or- - - contains multiple PEM-encoded keys with a recognized label. - --or- - - contains an encrypted PEM-encoded key. + does not contain a PEM-encoded key with a recognized label. + +-or- + + contains multiple PEM-encoded keys with a recognized label. + +-or- + + contains an encrypted PEM-encoded key. @@ -1553,13 +1553,13 @@ The algorithm-specific key import failed. The curve's parameters to import. When overridden in a derived class, imports the specified parameters for an as an ephemeral key into the current object. - method. Parameters over implicit curves are not supported. - - Characteristic-2 curves are not supported on Windows. - + method. Parameters over implicit curves are not supported. + + Characteristic-2 curves are not supported on Windows. + ]]> @@ -1600,26 +1600,26 @@ The algorithm-specific key import failed. When this method returns, contains a value that indicates the number of bytes read from . This parameter is treated as uninitialized. Imports the public/private keypair from a PKCS#8 PrivateKeyInfo structure after decryption, replacing the keys for this object. - - The contents of do not represent an ASN.1-BER-encoded PKCS#8 PrivateKeyInfo structure. - --or- - -The contents of indicate the key is for an algorithm other than the algorithm represented by this instance. - --or- - -The contents of represent the key in a format that is not supported. - --or- - + The contents of do not represent an ASN.1-BER-encoded PKCS#8 PrivateKeyInfo structure. + +-or- + +The contents of indicate the key is for an algorithm other than the algorithm represented by this instance. + +-or- + +The contents of represent the key in a format that is not supported. + +-or- + The algorithm-specific key import failed. @@ -1656,26 +1656,26 @@ The algorithm-specific key import failed. When this method returns, contains a value that indicates the number of bytes read from . This parameter is treated as uninitialized. Imports the public key from an X.509 SubjectPublicKeyInfo structure after decryption, replacing the keys for this object. - - The contents of do not represent an ASN.1-DER-encoded X.509 SubjectPublicKeyInfo structure. - --or- - -The contents of indicate the key is for an algorithm other than the algorithm represented by this instance. - --or- - -The contents of represent the key in a format that is not supported. - --or- - + The contents of do not represent an ASN.1-DER-encoded X.509 SubjectPublicKeyInfo structure. + +-or- + +The contents of indicate the key is for an algorithm other than the algorithm represented by this instance. + +-or- + +The contents of represent the key in a format that is not supported. + +-or- + The algorithm-specific key import failed. @@ -1718,13 +1718,13 @@ The algorithm-specific key import failed. Gets the name of the key exchange algorithm. The name of the key exchange algorithm. - base class. - + base class. + ]]> @@ -1816,13 +1816,13 @@ The algorithm-specific key import failed. Gets the name of the signature algorithm. Always . - base class. - - The Elliptic Curve Diffie-Hellman (ECDH) algorithm is used for key derivation, not digital signature generation. Therefore, this property returns `null`. - + base class. + + The Elliptic Curve Diffie-Hellman (ECDH) algorithm is used for key derivation, not digital signature generation. Therefore, this property returns `null`. + ]]> @@ -1948,18 +1948,18 @@ The algorithm-specific key import failed. if is big enough to receive the output; otherwise, . - - The key could not be exported. - --or- - + The key could not be exported. + +-or- + indicates that should be used, which requires -based passwords. @@ -2003,11 +2003,11 @@ The algorithm-specific key import failed. if is big enough to receive the output; otherwise, . - The key could not be exported. diff --git a/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml b/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml index a0c47b16c03..b2884ff3228 100644 --- a/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml +++ b/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml @@ -54,9 +54,9 @@ |Key derivation function|Properties| |-----------------------------|----------------| -|| - The hash algorithm that is used to process the secret agreement.

- An optional byte array to prepend to the secret agreement before hashing it.

- An optional byte array to append to the secret agreement before hashing it.| -|| - The hash algorithm that is used to process the secret agreement.

- An optional byte array to prepend to the secret agreement before hashing it.

- An optional byte array to append to the secret agreement before hashing it.| -|| - The label for key derivation.

- The seed for key derivation.| +|| - The hash algorithm that is used to process the secret agreement.

- An optional byte array to prepend to the secret agreement before hashing it.

- An optional byte array to append to the secret agreement before hashing it.| +|| - The hash algorithm that is used to process the secret agreement.

- An optional byte array to prepend to the secret agreement before hashing it.

- An optional byte array to append to the secret agreement before hashing it.| +|| - The label for key derivation.

- The seed for key derivation.| The result of passing the secret agreement through the key derivation function is a byte array that may be used as key material for your application. The number of bytes of key material generated is dependent on the key derivation function; for example, SHA-256 will generate 256 bits of key material, whereas SHA-512 will generate 512 bits of key material. The basic flow of an ECDH key exchange is as follows: @@ -297,7 +297,7 @@ method and must be either a named or explicit prime. + `curve` must validate (that is, it must return `true`) when passed to the method and must be either a named or explicit prime. ]]> @@ -678,7 +678,7 @@ This instance represents only a public key. method overloads are for advanced users who need a handle to the raw secret agreement instead of the key material. The secret agreement handle can be used in platform invoke calls to perform any work that is not wrapped by the class. + The method overloads are for advanced users who need a handle to the raw secret agreement instead of the key material. The secret agreement handle can be used in platform invoke calls to perform any work that is not wrapped by the class. ]]> @@ -1039,7 +1039,7 @@ This instance represents only a public key. overload instead. + To deserialize an XML key, use the overload instead. ]]> @@ -1142,7 +1142,7 @@ This instance represents only a public key. method) and must not be implicit. + `curve` must validate (that is, it must return true when passed to the method) and must not be implicit. Characteristic-2 curves are not supported on Windows. @@ -1198,11 +1198,11 @@ This instance represents only a public key. ## Remarks This property is used by Cryptography Next Generation (CNG) objects only if the or value is set in the property. - This property accepts the following algorithms: , , , , and . + This property accepts the following algorithms: , , , , and . Other custom hash algorithms may also be used. - Due to collision problems with MD5 and SHA-1, Microsoft recommends . The default algorithm is . + Due to collision problems with MD5 and SHA-1, Microsoft recommends . The default algorithm is . ]]> @@ -1380,7 +1380,7 @@ This instance represents only a public key. method replaces the existing key that this object is working with by creating a new object. If `parameters` contains only the field, then only a public key is imported. If `parameters` also contains , then a full key pair is be imported. The `parameter` value specifies the type of the curve to import. + The method replaces the existing key that this object is working with by creating a new object. If `parameters` contains only the field, then only a public key is imported. If `parameters` also contains , then a full key pair is be imported. The `parameter` value specifies the type of the curve to import. ]]> @@ -1550,7 +1550,7 @@ This instance represents only a public key. Setting this property to its current value has no visible effect. Setting this property to a new legal value discards the current key, but defers creation of a new key until one is needed. -Because key sizes do not uniquely identify elliptic curves, the use of the property setter is discouraged. To generate a new key on a specific curve, use the method. +Because key sizes do not uniquely identify elliptic curves, the use of the property setter is discouraged. To generate a new key on a specific curve, use the method. ]]> @@ -1916,7 +1916,7 @@ Because key sizes do not uniquely identify elliptic curves, the use of the prope overload instead. + To convert the current key to an XML representation, use the overload instead. ]]> diff --git a/xml/System.Security.Cryptography/ECDiffieHellmanKeyDerivationFunction.xml b/xml/System.Security.Cryptography/ECDiffieHellmanKeyDerivationFunction.xml index 629cf2a4a0a..b00921d7709 100644 --- a/xml/System.Security.Cryptography/ECDiffieHellmanKeyDerivationFunction.xml +++ b/xml/System.Security.Cryptography/ECDiffieHellmanKeyDerivationFunction.xml @@ -43,7 +43,7 @@ method. + The `ECDiffieHellmanKeyDerivationFunction` enumeration defines the type of algorithm that will be used to transform a raw secret agreement into key material. The secret agreement is the value that is generated from a private key and the other party's public key, as part of the key exchange. It is the seed value for the key material that is generated by the method. The property uses this enumeration to get the key derivation function for the class. diff --git a/xml/System.Security.Cryptography/ECDiffieHellmanOpenSsl.xml b/xml/System.Security.Cryptography/ECDiffieHellmanOpenSsl.xml index cbc385a0db8..123b6858ee6 100644 --- a/xml/System.Security.Cryptography/ECDiffieHellmanOpenSsl.xml +++ b/xml/System.Security.Cryptography/ECDiffieHellmanOpenSsl.xml @@ -46,7 +46,7 @@ ## Remarks -This class should only be used directly when doing platform interop with the system OpenSSL library. When platform interop is not needed, you should use the factory methods instead of a specific derived implementation. +This class should only be used directly when doing platform interop with the system OpenSSL library. When platform interop is not needed, you should use the factory methods instead of a specific derived implementation. ]]> @@ -102,7 +102,7 @@ This class should only be used directly when doing platform interop with the sys ## Remarks This constructor does not generate a new public/private keypair immediately, it just sets the size that will be used to generate a key when one is needed. -If key is loaded via the method, or other key import method, the key size from this constructor has no meaning. +If key is loaded via the method, or other key import method, the key size from this constructor has no meaning. ]]> @@ -167,7 +167,7 @@ To generate keys For any other curve, use the method. This constructor does not generate a new public/private keypair immediately, it just sets the size that will be used to generate a key when one is needed. -If key is loaded via the method, or other key import method, the key size from this constructor has no meaning. +If key is loaded via the method, or other key import method, the key size from this constructor has no meaning. ]]> @@ -721,7 +721,7 @@ The objects returned by this method can safely be used even after this method replaces the existing key that this object is working with by creating a new object. If `parameters` contains only the field, then only a public key is imported. If `parameters` also contains , then a full key pair is be imported. The `parameter` value specifies the type of the curve to import. + The method replaces the existing key that this object is working with by creating a new object. If `parameters` contains only the field, then only a public key is imported. If `parameters` also contains , then a full key pair is be imported. The `parameter` value specifies the type of the curve to import. ]]> diff --git a/xml/System.Security.Cryptography/ECDiffieHellmanPublicKey.xml b/xml/System.Security.Cryptography/ECDiffieHellmanPublicKey.xml index a1832a826d4..1826a454000 100644 --- a/xml/System.Security.Cryptography/ECDiffieHellmanPublicKey.xml +++ b/xml/System.Security.Cryptography/ECDiffieHellmanPublicKey.xml @@ -229,7 +229,7 @@ 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. + 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). diff --git a/xml/System.Security.Cryptography/ECDsa.xml b/xml/System.Security.Cryptography/ECDsa.xml index ee1b3b1066d..fade004c2b5 100644 --- a/xml/System.Security.Cryptography/ECDsa.xml +++ b/xml/System.Security.Cryptography/ECDsa.xml @@ -389,7 +389,7 @@ object, you can use the method overload to create a custom `algorithm` string that specifies your implementation. + If you develop your own implementation of an object, you can use the method overload to create a custom `algorithm` string that specifies your implementation. If you specify a custom value for the `algorithm` parameter, the object will use it to determine whether an ECDSA object can be created. diff --git a/xml/System.Security.Cryptography/ECDsaCng.xml b/xml/System.Security.Cryptography/ECDsaCng.xml index 9cbaaf90a56..dc12a67206c 100644 --- a/xml/System.Security.Cryptography/ECDsaCng.xml +++ b/xml/System.Security.Cryptography/ECDsaCng.xml @@ -58,7 +58,7 @@ ## Remarks This class should only be used directly when doing platform interop with the Windows CNG library. -When platform interop is not needed, you should use the factory methods instead of a specific derived implementation. +When platform interop is not needed, you should use the factory methods instead of a specific derived implementation. @@ -135,7 +135,7 @@ When platform interop is not needed, you should use the property to 521 and when a key is needed the saved size is used to identify the target curve. -If a key is loaded via the method, or other key import method, the key size from this constructor has no meaning. +If a key is loaded via the method, or other key import method, the key size from this constructor has no meaning. ]]> @@ -201,7 +201,7 @@ If a key is loaded via the property to the provided value and when a key is needed the saved size is used to identify the target curve. -If a key is loaded via the method, or other key import method, the key size from this constructor has no meaning. +If a key is loaded via the method, or other key import method, the key size from this constructor has no meaning. ]]> @@ -325,7 +325,7 @@ If a key is loaded via the method and must be either a named or explicit prime. + `curve` must validate (that is, it must return `true`) when passed to the method and must be either a named or explicit prime. ]]> @@ -605,7 +605,7 @@ If a key is loaded via the overload instead. + To deserialize an XML key, use the overload instead. ]]> @@ -758,11 +758,11 @@ If a key is loaded via the , , , , and . + This property accepts the following algorithms: , , , , and . Other custom hash algorithms may also be used. - Due to collision problems with MD5 and SHA-1, Microsoft recommends . The default algorithm is . + Due to collision problems with MD5 and SHA-1, Microsoft recommends . The default algorithm is . This property is not used if you are signing or verifying data that is already hashed. @@ -1112,7 +1112,7 @@ If a key is loaded via the method. +Because key sizes do not uniquely identify elliptic curves, the use of the property setter is discouraged. To generate a new key on a specific curve, use the method. ]]> @@ -1486,7 +1486,7 @@ but that is not reflected in this property. overload instead. + To convert the current key to an XML representation, use the overload instead. ]]> diff --git a/xml/System.Security.Cryptography/ECDsaOpenSsl.xml b/xml/System.Security.Cryptography/ECDsaOpenSsl.xml index 084505e1aa5..a6dd14b99e5 100644 --- a/xml/System.Security.Cryptography/ECDsaOpenSsl.xml +++ b/xml/System.Security.Cryptography/ECDsaOpenSsl.xml @@ -47,7 +47,7 @@ factory methods instead of a specific derived implementation. +This class should only be used directly when doing platform interop with the system OpenSSL library. When platform interop isn't needed, you should use the factory methods instead of a specific derived implementation. ]]> @@ -106,7 +106,7 @@ This class should only be used directly when doing platform interop with the sys This constructor does not generate a new public/private keypair immediately. This constructor sets the property to 521 and when a key is needed, the saved size is used to identify the target curve. -If a key is loaded via the method or another key import method, the key size from this constructor has no meaning. +If a key is loaded via the method or another key import method, the key size from this constructor has no meaning. ]]> @@ -170,7 +170,7 @@ If a key is loaded via the property to the provided value and when a key is needed, the saved size is used to identify the target curve. -If a key is loaded via the method or another key import method, the key size from this constructor has no meaning. +If a key is loaded via the method or another key import method, the key size from this constructor has no meaning. ]]> @@ -671,7 +671,7 @@ Each call to this method produces a new method. +Because key sizes do not uniquely identify elliptic curves, the use of the property setter is discouraged. To generate a new key on a specific curve, use the method. ]]> diff --git a/xml/System.Security.Cryptography/ECParameters.xml b/xml/System.Security.Cryptography/ECParameters.xml index 1337b950326..ec58d1038f8 100644 --- a/xml/System.Security.Cryptography/ECParameters.xml +++ b/xml/System.Security.Cryptography/ECParameters.xml @@ -250,7 +250,7 @@ method checks the integrity of the structure, throwing a when it is not valid. The following are the requirements: + The method checks the integrity of the structure, throwing a when it is not valid. The following are the requirements: - . and . are required fields and must have the same length. @@ -258,7 +258,7 @@ - If the curve is a named curve, is required and must have the same length as . and .. -- . must also succeed. +- . must also succeed. ]]> diff --git a/xml/System.Security.Cryptography/FromBase64Transform.xml b/xml/System.Security.Cryptography/FromBase64Transform.xml index 838e24c7023..f5f161fdb38 100644 --- a/xml/System.Security.Cryptography/FromBase64Transform.xml +++ b/xml/System.Security.Cryptography/FromBase64Transform.xml @@ -357,7 +357,7 @@ . + This method is a simple call to . Calling `Dispose` allows the resources used by the to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). diff --git a/xml/System.Security.Cryptography/FromBase64TransformMode.xml b/xml/System.Security.Cryptography/FromBase64TransformMode.xml index 7eb6b984f11..9a32ad806a3 100644 --- a/xml/System.Security.Cryptography/FromBase64TransformMode.xml +++ b/xml/System.Security.Cryptography/FromBase64TransformMode.xml @@ -64,11 +64,11 @@ Specifies whether white space should be ignored in the base 64 transformation. - method. - + method. + ]]> Cryptographic Services diff --git a/xml/System.Security.Cryptography/HMAC.xml b/xml/System.Security.Cryptography/HMAC.xml index 76fb91ce628..4a40b32c414 100644 --- a/xml/System.Security.Cryptography/HMAC.xml +++ b/xml/System.Security.Cryptography/HMAC.xml @@ -166,7 +166,7 @@ is the byte size of such a block. Its value is 64 bytes. + A Hash-based Message Authentication Code (HMAC) uses a hash function where data is hashed by iterating a basic compression function on blocks of data. is the byte size of such a block. Its value is 64 bytes. ]]> @@ -245,7 +245,7 @@ This method is obsolete in .NET 5 and later versions. - By default, this overload uses the SHA-1 implementation of HMAC. If you want to specify a different implementation, use the overload, which lets you specify an algorithm name, instead. + By default, this overload uses the SHA-1 implementation of HMAC. If you want to specify a different implementation, use the overload, which lets you specify an algorithm name, instead. Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better. diff --git a/xml/System.Security.Cryptography/HMACSHA384.xml b/xml/System.Security.Cryptography/HMACSHA384.xml index 63fde6687f6..b50010079a6 100644 --- a/xml/System.Security.Cryptography/HMACSHA384.xml +++ b/xml/System.Security.Cryptography/HMACSHA384.xml @@ -1056,7 +1056,7 @@ Boolean property is to enable .NET Framework 2.0 Service Pack 1 applications to interact with .NET Framework 2.0 applications. When you set this property to `true`, the object produces values that match the values produced by .NET Framework 2.0. You should set this property only once after you create your HMAC object. You will need to reset your key afterwards, as shown in the following example. + The purpose of the Boolean property is to enable .NET Framework 2.0 Service Pack 1 applications to interact with .NET Framework 2.0 applications. When you set this property to `true`, the object produces values that match the values produced by .NET Framework 2.0. You should set this property only once after you create your HMAC object. You will need to reset your key afterwards, as shown in the following example. ```csharp public static void Test() diff --git a/xml/System.Security.Cryptography/HMACSHA512.xml b/xml/System.Security.Cryptography/HMACSHA512.xml index 9133025f291..b04205e4f04 100644 --- a/xml/System.Security.Cryptography/HMACSHA512.xml +++ b/xml/System.Security.Cryptography/HMACSHA512.xml @@ -1056,7 +1056,7 @@ Boolean property is to enable .NET Framework 2.0 Service Pack 1 applications to interact with .NET Framework 2.0 applications. When you set this property to `true`, the object produces values that match the values produced by .NET Framework 2.0. You should set this property only once after you create your HMAC object. You will need to reset your key afterwards, as shown in the following example. + The purpose of the Boolean property is to enable .NET Framework 2.0 Service Pack 1 applications to interact with .NET Framework 2.0 applications. When you set this property to `true`, the object produces values that match the values produced by .NET Framework 2.0. You should set this property only once after you create your HMAC object. You will need to reset your key afterwards, as shown in the following example. ```csharp public static void Test() diff --git a/xml/System.Security.Cryptography/HashAlgorithm.xml b/xml/System.Security.Cryptography/HashAlgorithm.xml index b34716be923..0fc48ce6c56 100644 --- a/xml/System.Security.Cryptography/HashAlgorithm.xml +++ b/xml/System.Security.Cryptography/HashAlgorithm.xml @@ -296,7 +296,7 @@ method. + This method is a simple call to the method. Calling `Dispose` allows the resources used by the class to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). @@ -617,7 +617,7 @@ The following example calculates the This method is obsolete in .NET 5 and later versions. - By default, this overload uses the implementation of a hash algorithm. If you want to specify a different implementation, use the overload, which lets you specify an algorithm name, instead. The cryptography configuration system defines the default implementation of . + By default, this overload uses the implementation of a hash algorithm. If you want to specify a different implementation, use the overload, which lets you specify an algorithm name, instead. The cryptography configuration system defines the default implementation of . Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better. @@ -925,7 +925,7 @@ This method is obsolete in .NET 5 and later versions. property is a byte array; the property is a value that represent bits. Therefore, the number of elements in is one-eighth the size of . + The property is a byte array; the property is a value that represent bits. Therefore, the number of elements in is one-eighth the size of . ]]> @@ -1591,16 +1591,16 @@ For more information about Dispose and Finalize, see [Cleaning Up Unmanaged Reso method before calling the method. You must call both methods before you retrieve the final hash value. + You must call the method before calling the method. You must call both methods before you retrieve the final hash value. - To retrieve the final hash value after calling the method, get the byte array contained within the property. + To retrieve the final hash value after calling the method, get the byte array contained within the property. - Calling the method with different input and output arrays results in an . + Calling the method with different input and output arrays results in an . ## Examples - The following code examples use the method with the method to hash a string. + The following code examples use the method with the method to hash a string. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/HashAlgorithm/TransformBlock/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/HashAlgorithm/TransformBlock/sample.vb" id="Snippet1"::: @@ -1683,14 +1683,14 @@ For more information about Dispose and Finalize, see [Cleaning Up Unmanaged Reso method after calling the method but before you retrieve the final hash value. + You must call the method after calling the method but before you retrieve the final hash value. - Note that the return value of this method is not the hash value, but only a copy of the hashed part of the input data. To retrieve the final hashed value after calling the method, get the byte array contained in the property. + Note that the return value of this method is not the hash value, but only a copy of the hashed part of the input data. To retrieve the final hashed value after calling the method, get the byte array contained in the property. ## Examples - The following code examples use the method with the method to hash a string. + The following code examples use the method with the method to hash a string. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/HashAlgorithm/TransformBlock/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/HashAlgorithm/TransformBlock/sample.vb" id="Snippet1"::: diff --git a/xml/System.Security.Cryptography/HashAlgorithmName.xml b/xml/System.Security.Cryptography/HashAlgorithmName.xml index 94a08fb73fa..fc6155d3747 100644 --- a/xml/System.Security.Cryptography/HashAlgorithmName.xml +++ b/xml/System.Security.Cryptography/HashAlgorithmName.xml @@ -492,7 +492,7 @@ May be `null` or empty to indicate that no hash algorithm is applicable. method defines the operation of the equality operator for values. + The method defines the operation of the equality operator for values. ]]> @@ -550,7 +550,7 @@ May be `null` or empty to indicate that no hash algorithm is applicable. method defines the operation of the inequality operator for values. + The method defines the operation of the inequality operator for values. ]]> @@ -868,7 +868,7 @@ May be `null` or empty to indicate that no hash algorithm is applicable. method returns the property, if it has been assigned. Otherwise, it returns . + The method returns the property, if it has been assigned. Otherwise, it returns . ]]> diff --git a/xml/System.Security.Cryptography/ICryptoTransform.xml b/xml/System.Security.Cryptography/ICryptoTransform.xml index 07e939af800..a9fdf412f8d 100644 --- a/xml/System.Security.Cryptography/ICryptoTransform.xml +++ b/xml/System.Security.Cryptography/ICryptoTransform.xml @@ -63,11 +63,11 @@ Defines the basic operations of cryptographic transformations. - ). - + ). + ]]> Cryptographic Services @@ -319,11 +319,11 @@ Transforms the specified region of the input byte array and copies the resulting transform to the specified region of the output byte array. The number of bytes written. - is the number of bytes returned to `outputBuffer` and is always less than or equal to . If is `true`, then `inputCount` must be any positive multiple of . - + is the number of bytes returned to `outputBuffer` and is always less than or equal to . If is `true`, then `inputCount` must be any positive multiple of . + ]]> Cryptographic Services @@ -381,11 +381,11 @@ The return value of Transforms the specified region of the specified byte array. The computed transform. - is a special function for transforming the last block or a partial block in the stream. It returns a new array that contains the remaining transformed bytes. A new array is returned, because the amount of information returned at the end might be larger than a single block when padding is added. - + is a special function for transforming the last block or a partial block in the stream. It returns a new array that contains the remaining transformed bytes. A new array is returned, because the amount of information returned at the end might be larger than a single block when padding is added. + ]]> Cryptographic Services diff --git a/xml/System.Security.Cryptography/ICspAsymmetricAlgorithm.xml b/xml/System.Security.Cryptography/ICspAsymmetricAlgorithm.xml index 74157046b79..0378d7ceece 100644 --- a/xml/System.Security.Cryptography/ICspAsymmetricAlgorithm.xml +++ b/xml/System.Security.Cryptography/ICspAsymmetricAlgorithm.xml @@ -59,11 +59,11 @@ Defines methods that allow an class to enumerate key container information, and import and export Microsoft Cryptographic API (CAPI)-compatible key blobs. - class should implement the interface to enumerate key container information using a object, and to import and export Microsoft Cryptographic API (CAPI)-compatible key blobs. - + class should implement the interface to enumerate key container information using a object, and to import and export Microsoft Cryptographic API (CAPI)-compatible key blobs. + ]]> @@ -111,11 +111,11 @@ Gets a object that describes additional information about a cryptographic key pair. A object that describes additional information about a cryptographic key pair. - object specifies whether the key is exportable, and provides the key container name, information about the provider, and other information. - + object specifies whether the key is exportable, and provides the key container name, information about the provider, and other information. + ]]> @@ -168,11 +168,11 @@ Exports a blob that contains the key information associated with an object. A byte array that contains the key information associated with an object. - method returns a blob that contains key information that is compatible with the unmanaged Microsoft Cryptographic API (CAPI). - + method returns a blob that contains key information that is compatible with the unmanaged Microsoft Cryptographic API (CAPI). + ]]> @@ -223,11 +223,11 @@ A byte array that represents an asymmetric key blob. Imports a blob that represents asymmetric key information. - method initializes the key data of an object using a blob that is compatible with the unmanaged Microsoft Cryptographic API (CAPI). - + method initializes the key data of an object using a blob that is compatible with the unmanaged Microsoft Cryptographic API (CAPI). + ]]> diff --git a/xml/System.Security.Cryptography/KeySizes.xml b/xml/System.Security.Cryptography/KeySizes.xml index 6dcb64b9964..00edbdae59e 100644 --- a/xml/System.Security.Cryptography/KeySizes.xml +++ b/xml/System.Security.Cryptography/KeySizes.xml @@ -125,7 +125,7 @@ constructor. This code example is part of a larger example provided for the class. + The following code shows the use of the constructor. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/KeySizes/Overview/members.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/KeySizes/Overview/members.vb" id="Snippet2"::: diff --git a/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml b/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml index a067b333aaa..d1233818120 100644 --- a/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml +++ b/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml @@ -208,7 +208,7 @@ implementation of a keyed hash algorithm. If you want to specify a different implementation, use the overload, which lets you specify an algorithm name, instead. The cryptography configuration system defines the default implementation of the class. + By default, this overload uses the implementation of a keyed hash algorithm. If you want to specify a different implementation, use the overload, which lets you specify an algorithm name, instead. The cryptography configuration system defines the default implementation of the class. Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better. diff --git a/xml/System.Security.Cryptography/MD5.xml b/xml/System.Security.Cryptography/MD5.xml index f42f5b90419..8bf41fc57ef 100644 --- a/xml/System.Security.Cryptography/MD5.xml +++ b/xml/System.Security.Cryptography/MD5.xml @@ -74,7 +74,7 @@ The hash size for the algorithm is 128 bits. - The methods of the class return the hash as an array of 16 bytes. Note that some MD5 implementations produce a 32-character, hexadecimal-formatted hash. To interoperate with such implementations, format the return value of the methods as a hexadecimal value. + The methods of the class return the hash as an array of 16 bytes. Note that some MD5 implementations produce a 32-character, hexadecimal-formatted hash. To interoperate with such implementations, format the return value of the methods as a hexadecimal value. > [!NOTE] > Due to collision problems with MD5/SHA-1, Microsoft recommends SHA-256 or SHA-512. Consider using the class or the class instead of the class. Use only for compatibility with legacy applications and data. @@ -129,7 +129,7 @@ class, use the method. + To create an instance of the class, use the method. ]]> diff --git a/xml/System.Security.Cryptography/MD5CryptoServiceProvider.xml b/xml/System.Security.Cryptography/MD5CryptoServiceProvider.xml index 2d6fe193b25..ccc3984d43e 100644 --- a/xml/System.Security.Cryptography/MD5CryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/MD5CryptoServiceProvider.xml @@ -69,18 +69,18 @@ Computes the hash value for the input data using the implementation provided by the cryptographic service provider (CSP). This class cannot be inherited. - [!NOTE] -> Newer hash functions such as the Secure Hash Algorithms SHA-256 and SHA-512 are available. Consider using the class or the class instead of the class. Use only for compatibility with legacy applications and data. - - The hash size for the class is 128 bits. - - The methods of the class return the hash as an array of 16 bytes. Note that some MD5 implementations produce a 32-character, hexadecimal-formatted hash. To interoperate with such implementations, format the return value of the methods as a hexadecimal value. - +> Newer hash functions such as the Secure Hash Algorithms SHA-256 and SHA-512 are available. Consider using the class or the class instead of the class. Use only for compatibility with legacy applications and data. + + The hash size for the class is 128 bits. + + The methods of the class return the hash as an array of 16 bytes. Note that some MD5 implementations produce a 32-character, hexadecimal-formatted hash. To interoperate with such implementations, format the return value of the methods as a hexadecimal value. + ]]> Cryptographic Services diff --git a/xml/System.Security.Cryptography/ManifestSignatureInformation.xml b/xml/System.Security.Cryptography/ManifestSignatureInformation.xml index 384cc75c5c9..dcd84f87fab 100644 --- a/xml/System.Security.Cryptography/ManifestSignatureInformation.xml +++ b/xml/System.Security.Cryptography/ManifestSignatureInformation.xml @@ -17,11 +17,11 @@ Provides information for a manifest signature. - method to obtain a object that can be use to examine the signature information. - + method to obtain a object that can be use to examine the signature information. + ]]> diff --git a/xml/System.Security.Cryptography/ManifestSignatureInformationCollection.xml b/xml/System.Security.Cryptography/ManifestSignatureInformationCollection.xml index 16d034cfd29..4b2e65e967e 100644 --- a/xml/System.Security.Cryptography/ManifestSignatureInformationCollection.xml +++ b/xml/System.Security.Cryptography/ManifestSignatureInformationCollection.xml @@ -20,13 +20,13 @@ Represents a read-only collection of objects. - collection, call one of the method overloads. - - Each collection contains a object for each manifest that was verified by the method. - + collection, call one of the method overloads. + + Each collection contains a object for each manifest that was verified by the method. + ]]> diff --git a/xml/System.Security.Cryptography/MaskGenerationMethod.xml b/xml/System.Security.Cryptography/MaskGenerationMethod.xml index 148e39d10e3..5760ab1cf54 100644 --- a/xml/System.Security.Cryptography/MaskGenerationMethod.xml +++ b/xml/System.Security.Cryptography/MaskGenerationMethod.xml @@ -75,7 +75,7 @@ ## Examples The following code example demonstrates how to derive from the class. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/MaskGenerationMethod/Overview/maskgenerator.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/MaskGenerationMethod/Overview/maskgenerator.vb" id="Snippet1"::: @@ -182,7 +182,7 @@ to create and return a mask using the specified seed. This code example is part of a larger example provided for the class. + The following code example demonstrates how to override the to create and return a mask using the specified seed. This code example is part of a larger example provided for the class. System.Security.Cryptography.MaskGenerationMethod#3 diff --git a/xml/System.Security.Cryptography/MemoryProtectionScope.xml b/xml/System.Security.Cryptography/MemoryProtectionScope.xml index 72713c5106a..b3e31d6d17e 100644 --- a/xml/System.Security.Cryptography/MemoryProtectionScope.xml +++ b/xml/System.Security.Cryptography/MemoryProtectionScope.xml @@ -16,20 +16,20 @@ Specifies the scope of memory protection to be applied by the method. - and methods to protect data in memory. - - - -## Examples - The following code example shows how to use data protection. - + and methods to protect data in memory. + + + +## Examples + The following code example shows how to use data protection. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.MemoryProtectionSample/CPP/memoryprotectionsample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/MemoryProtectionScope/Overview/memoryprotectionsample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/MemoryProtectionScope/Overview/memoryprotectionsample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/MemoryProtectionScope/Overview/memoryprotectionsample.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Security.Cryptography/OidCollection.xml b/xml/System.Security.Cryptography/OidCollection.xml index 9cb77e50e2d..a107b555c2f 100644 --- a/xml/System.Security.Cryptography/OidCollection.xml +++ b/xml/System.Security.Cryptography/OidCollection.xml @@ -582,7 +582,7 @@ object from an object if you know the value of the or property of the object. You can use the property to retrieve an object if you know its location in the collection. + Use this property to retrieve an object from an object if you know the value of the or property of the object. You can use the property to retrieve an object if you know its location in the collection. diff --git a/xml/System.Security.Cryptography/OidEnumerator.xml b/xml/System.Security.Cryptography/OidEnumerator.xml index 3801ef4a637..31eb19fb88b 100644 --- a/xml/System.Security.Cryptography/OidEnumerator.xml +++ b/xml/System.Security.Cryptography/OidEnumerator.xml @@ -127,11 +127,11 @@ method must be called to advance the enumerator to the first element of the collection before reading the value of the property; otherwise, returns `null` or throws an exception. + After an enumerator is created, the method must be called to advance the enumerator to the first element of the collection before reading the value of the property; otherwise, returns `null` or throws an exception. - also returns `null` or throws an exception if the last call to returns `false`, which indicates that the end of the collection has been reached. + also returns `null` or throws an exception if the last call to returns `false`, which indicates that the end of the collection has been reached. - does not move the position of the enumerator, and consecutive calls to return the same object, until is called. + does not move the position of the enumerator, and consecutive calls to return the same object, until is called. @@ -196,11 +196,11 @@ method moves the enumerator over the first element of the collection. Subsequent calls to advances the enumerator past subsequent items in the collection. + After an enumerator is created, it is positioned before the first element of the collection, and the first call to the method moves the enumerator over the first element of the collection. Subsequent calls to advances the enumerator past subsequent items in the collection. - After the end of the collection is passed, calls to return `false`. + After the end of the collection is passed, calls to return `false`. - An enumerator is valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator becomes invalid and the next call to throws an . + An enumerator is valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator becomes invalid and the next call to throws an . @@ -264,7 +264,7 @@ object. An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator becomes invalid and the next call to the method throws an . + The initial position of an enumerator is before the first element in the object. An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator becomes invalid and the next call to the method throws an . diff --git a/xml/System.Security.Cryptography/OidGroup.xml b/xml/System.Security.Cryptography/OidGroup.xml index fa2ab9033dc..5457174e800 100644 --- a/xml/System.Security.Cryptography/OidGroup.xml +++ b/xml/System.Security.Cryptography/OidGroup.xml @@ -52,11 +52,11 @@ Identifies Windows cryptographic object identifier (OID) groups. - method. - + method. + ]]> diff --git a/xml/System.Security.Cryptography/PKCS1MaskGenerationMethod.xml b/xml/System.Security.Cryptography/PKCS1MaskGenerationMethod.xml index 805bb0b3960..9c0239310d4 100644 --- a/xml/System.Security.Cryptography/PKCS1MaskGenerationMethod.xml +++ b/xml/System.Security.Cryptography/PKCS1MaskGenerationMethod.xml @@ -130,7 +130,7 @@ to the default hash algorithm name (SHA1). + This constructor sets to the default hash algorithm name (SHA1). Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better. diff --git a/xml/System.Security.Cryptography/ProtectedData.xml b/xml/System.Security.Cryptography/ProtectedData.xml index 13f326943d8..4fd9a9e840f 100644 --- a/xml/System.Security.Cryptography/ProtectedData.xml +++ b/xml/System.Security.Cryptography/ProtectedData.xml @@ -54,13 +54,13 @@ This class provides access to the Data Protection API (DPAPI) available in Windo > [!IMPORTANT] > Because it depends on DPAPI, the `ProtectedData` class is supported on the Windows platform only. Its use on .NET Core on platforms other than Windows throws a . -The class consists of two wrappers for the unmanaged DPAPI, and . These two methods can be used to encrypt and decrypt data such as passwords, keys, and connection strings. +The class consists of two wrappers for the unmanaged DPAPI, and . These two methods can be used to encrypt and decrypt data such as passwords, keys, and connection strings. If you use these methods during impersonation, you may receive the following error: "Key not valid for use in specified state." This occurs because the DPAPI stores the key data in user profiles. If the profile is not loaded, DPAPI won't be able to perform the decryption. To prevent this error, load the profile of the user you want to impersonate before calling either method. Using DPAPI with impersonation can incur significant complication and requires careful design choices. ## Examples The following example shows how to use data protection. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/DataProtectionScope/Overview/dataprotectionsample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/DataProtectionScope/Overview/dataprotectionsample.vb" id="Snippet1"::: @@ -127,7 +127,7 @@ If you use these methods during impersonation, you may receive the following err method. + This method can be used to encrypt data such as passwords, keys, or connection strings. The `optionalEntropy` parameter enables you to add data to increase the complexity of the encryption; specify `null` for no additional complexity. If provided, this information must also be used when decrypting the data using the method. > [!NOTE] > If you use this method during impersonation, you may receive the following error: "Key not valid for use in specified state." To prevent this error, load the profile of the user you want to impersonate before calling the method. @@ -389,7 +389,7 @@ If you use these methods during impersonation, you may receive the following err method. If the `optionalEntropy` parameter was used during encryption, it must be supplied to unencrypt the data. + This method can be used to unprotect data that was encrypted using the method. If the `optionalEntropy` parameter was used during encryption, it must be supplied to unencrypt the data. > [!NOTE] > If you use this method during impersonation, you may receive the following error: "Key not valid for use in specified state." To prevent this error, load the profile of the user you want to impersonate before calling the method. diff --git a/xml/System.Security.Cryptography/ProtectedMemory.xml b/xml/System.Security.Cryptography/ProtectedMemory.xml index 54604ec9b23..e2fd23da7c5 100644 --- a/xml/System.Security.Cryptography/ProtectedMemory.xml +++ b/xml/System.Security.Cryptography/ProtectedMemory.xml @@ -21,22 +21,22 @@ Provides methods for protecting and unprotecting memory. This class cannot be inherited. - and . These two methods can be used to encrypt and decrypt data in memory. - - - -## Examples - The following example shows how to use data protection. - + and . These two methods can be used to encrypt and decrypt data in memory. + + + +## Examples + The following example shows how to use data protection. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.MemoryProtectionSample/CPP/memoryprotectionsample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/MemoryProtectionScope/Overview/memoryprotectionsample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/MemoryProtectionScope/Overview/memoryprotectionsample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/MemoryProtectionScope/Overview/memoryprotectionsample.vb" id="Snippet1"::: + ]]> @@ -72,22 +72,22 @@ One of the enumeration values that specifies the scope of memory protection. Protects the specified data. - @@ -128,36 +128,36 @@ One of the enumeration values that specifies the scope of memory protection. Unprotects data in memory that was protected using the method. - method. - - Support for this method is available in the Windows XP and later operating systems. - - - -## Examples - The following example shows how to use data protection. - + method. + + Support for this method is available in the Windows XP and later operating systems. + + + +## Examples + The following example shows how to use data protection. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.MemoryProtectionSample/CPP/memoryprotectionsample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/MemoryProtectionScope/Overview/memoryprotectionsample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/MemoryProtectionScope/Overview/memoryprotectionsample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/MemoryProtectionScope/Overview/memoryprotectionsample.vb" id="Snippet1"::: + ]]> The operating system does not support this method. This method can be used only with the Windows 2000 or later operating systems. is . - is empty. - - -or- - - This call was not implemented. - - -or- - + is empty. + + -or- + + This call was not implemented. + + -or- + NTSTATUS contains an error. diff --git a/xml/System.Security.Cryptography/RC2CryptoServiceProvider.xml b/xml/System.Security.Cryptography/RC2CryptoServiceProvider.xml index d42738d34a2..01db77041b1 100644 --- a/xml/System.Security.Cryptography/RC2CryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/RC2CryptoServiceProvider.xml @@ -242,7 +242,7 @@ overload with the same parameters. + This method is used to decrypt an encrypted message created using the overload with the same parameters. @@ -346,7 +346,7 @@ overload with the same parameters to decrypt the result of this method. + Use the overload with the same parameters to decrypt the result of this method. @@ -467,7 +467,7 @@ when none is specified. + Use this method to generate a random when none is specified. diff --git a/xml/System.Security.Cryptography/RNGCryptoServiceProvider.xml b/xml/System.Security.Cryptography/RNGCryptoServiceProvider.xml index a0078741784..a45994adf28 100644 --- a/xml/System.Security.Cryptography/RNGCryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/RNGCryptoServiceProvider.xml @@ -78,13 +78,13 @@ ## 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 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. ## Examples The following code example shows how to create a random number with the class. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RNGCryptoServiceProvider/Overview/rngcsp.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RNGCryptoServiceProvider/Overview/rngcsp.vb" id="Snippet1"::: @@ -214,7 +214,7 @@ class. Calling this method is equivalent to calling the constructor and passing `null`. + This method does not directly initialize the class. Calling this method is equivalent to calling the constructor and passing `null`. ]]> @@ -326,7 +326,7 @@ class. Calling this method is equivalent to calling the constructor and passing `null`. + This method does not directly initialize the class. Calling this method is equivalent to calling the constructor and passing `null`. ]]> diff --git a/xml/System.Security.Cryptography/RSA.xml b/xml/System.Security.Cryptography/RSA.xml index 85082a43820..e04a2b2fc7a 100644 --- a/xml/System.Security.Cryptography/RSA.xml +++ b/xml/System.Security.Cryptography/RSA.xml @@ -643,7 +643,7 @@ The decryption operation failed. , also threw a exception. + In the .NET Framework 4.5.2 and earlier versions of the .NET Framework, this method was `abstract`. However, the only implementation by a derived class, , also threw a exception. ]]> @@ -911,7 +911,7 @@ The encryption operation failed. , also threw a exception. + In the .NET Framework 4.5.2 and earlier versions of the .NET Framework, this method was `abstract`. However, the only implementation by a derived class, , also threw a exception. ]]> @@ -1199,9 +1199,9 @@ The encryption operation failed. ## Remarks - The initializes an RSA object using key information in an XML string that was generated using the method. The method accepts either an XML string containing a public key or an XML string containing a public and private key. + The initializes an RSA object using key information in an XML string that was generated using the method. The method accepts either an XML string containing a public key or an XML string containing a public and private key. - Use the method to conveniently initialize key information. + Use the method to conveniently initialize key information. > [!CAUTION] > Persisting an XML string containing a private key to an insecure location is a security threat. The security of your application can be compromised if a malicious third party can access your private key. To safely persist a private key, use a secure key container. For more information about persisting private keys in a key container, see [How to: Store Asymmetric Keys in a Key Container](/dotnet/standard/security/how-to-store-asymmetric-keys-in-a-key-container). @@ -2756,14 +2756,14 @@ An error occurred creating the signature. ## Remarks - The method creates an XML string that contains either the public and private key of the current object or contains only the public key of the current object. + The method creates an XML string that contains either the public and private key of the current object or contains only the public key of the current object. - Use the method whenever you need to conveniently persist RSA key information. To initialize an object with the key in an XML string, use the method. + Use the method whenever you need to conveniently persist RSA key information. To initialize an object with the key in an XML string, use the method. > [!CAUTION] > Persisting an XML string containing a private key to an insecure location is a security threat. The security of your application can be compromised if a malicious third party can access your private key. To safely persist a private key, use a secure key container. For more information about persisting private keys in a key container, see [How to: Store Asymmetric Keys in a Key Container](/dotnet/standard/security/how-to-store-asymmetric-keys-in-a-key-container). - When you pass `true` to the method, the resulting XML string takes the following form: + When you pass `true` to the method, the resulting XML string takes the following form: ```xml @@ -2778,7 +2778,7 @@ An error occurred creating the signature. ``` - When you pass `false` to the method, the resulting XML string takes the following form: + When you pass `false` to the method, the resulting XML string takes the following form: ```xml diff --git a/xml/System.Security.Cryptography/RSACng.xml b/xml/System.Security.Cryptography/RSACng.xml index 0815a34d09e..ff91069ba75 100644 --- a/xml/System.Security.Cryptography/RSACng.xml +++ b/xml/System.Security.Cryptography/RSACng.xml @@ -59,7 +59,7 @@ - performs such operations as signing and verifying signatures by using properties of the object, just as uses its object properties to control signing and verification operations. > [!NOTE] -> The class is an implementation of the RSA algorithm using the Windows CNG libraries and isn't available on operating systems other than Windows. For applications which aren't doing Windows interop, you're encouraged to use instead of referencing this type directly. +> The class is an implementation of the RSA algorithm using the Windows CNG libraries and isn't available on operating systems other than Windows. For applications which aren't doing Windows interop, you're encouraged to use instead of referencing this type directly. ]]> @@ -123,7 +123,7 @@ This constructor does not generate a new public/private keypair immediately. This constructor sets the property to 2048 and when a key is needed one is generated using the property value. -If a key is loaded via the method, or other key import method, the key size from this constructor has no meaning. +If a key is loaded via the method, or other key import method, the key size from this constructor has no meaning. ]]> @@ -183,7 +183,7 @@ Valid key sizes range from 384 to 16,384 bits, in increments of 8. We recommend This constructor does not generate a new public/private keypair immediately. This constructor sets the property to `keySize` and when a key is needed one is generated using the property value. -If a key is loaded via the method, or other key import method, the key size from this constructor has no meaning. +If a key is loaded via the method, or other key import method, the key size from this constructor has no meaning. ]]> @@ -245,7 +245,7 @@ If a key is loaded via the of `key` must be . + The of `key` must be . This constructor creates a copy of the key. Even if `key` is disposed, the copy of this key object in RSA remains alive. @@ -949,9 +949,9 @@ any already open key is unaffected by this method. object is disposed if the key is reset, for instance by changing the property, by using the to create a new key, or by disposing of the parent object. Therefore, you should ensure that the key object is no longer used in these cases. + The returned object is disposed if the key is reset, for instance by changing the property, by using the to create a new key, or by disposing of the parent object. Therefore, you should ensure that the key object is no longer used in these cases. - This object is not the same as the object passed to the constructor, if that constructor was used. However, it will point to the same CNG key. + This object is not the same as the object passed to the constructor, if that constructor was used. However, it will point to the same CNG key. ]]> diff --git a/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml b/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml index 14e7e087531..484af122ed4 100644 --- a/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml @@ -158,7 +158,7 @@ The following code example exports the key information created using the key pair suitable to encrypt session keys so that they can be safely stored and exchanged with other users. The generated key corresponds to a key generated using the `AT_KEYEXCHANGE` value used in the unmanaged Microsoft Cryptographic API (CAPI). This constructor does not generate a new public/private keypair immediately. -If no key is loaded via the method, or any other key import method, before a key is needed then a 1024-bit ephemeral key is created on demand. +If no key is loaded via the method, or any other key import method, before a key is needed then a 1024-bit ephemeral key is created on demand. ## Examples @@ -234,7 +234,7 @@ If no key is loaded via the key pair suitable to encrypt session keys so that they can be safely stored and exchanged with other users. The generated key corresponds to a key generated using the `AT_KEYEXCHANGE` value used in the unmanaged Microsoft Cryptographic API (CAPI). This constructor does not generate a new public/private keypair immediately. -If no key is loaded via the method, or any other key import method, before a key is needed then a `dwKeySize`-bit ephemeral key is created on demand. +If no key is loaded via the method, or any other key import method, before a key is needed then a `dwKeySize`-bit ephemeral key is created on demand. ## Examples @@ -484,7 +484,7 @@ If no key is loaded via the property to retrieve additional information about a cryptographic key pair. The returned object describes whether the key is exportable, and specifies the key container name, information about the provider, and other information. - In cases where a random key is generated, a key container will not be created until you call a method that uses the key. Some properties of the object returned by the property will throw a if a key container has not been created. To make sure that a key container has been created, call a method such as , , , , and so on, before you call the property. + In cases where a random key is generated, a key container will not be created until you call a method that uses the key. Some properties of the object returned by the property will throw a if a key container has not been created. To make sure that a key container has been created, call a method such as , , , , and so on, before you call the property. @@ -570,7 +570,7 @@ If no key is loaded via the to encrypt data for decryption with this method. + Use to encrypt data for decryption with this method. @@ -650,7 +650,7 @@ If no key is loaded via the or . + `padding` must be either or . ]]> @@ -858,7 +858,7 @@ If no key is loaded via the to decrypt the results of this method. + Use to decrypt the results of this method. @@ -932,7 +932,7 @@ If no key is loaded via the or . + `padding` must be either or . ]]> @@ -1070,7 +1070,7 @@ If no key is loaded via the method returns a blob containing key information that is compatible with the unmanaged Microsoft Cryptographic API (CAPI). + The method returns a blob containing key information that is compatible with the unmanaged Microsoft Cryptographic API (CAPI). ]]> @@ -1346,7 +1346,7 @@ If no key is loaded via the method initializes the key data of an object using a blob that is compatible with the unmanaged Microsoft Cryptographic API (CAPI). + The method initializes the key data of an object using a blob that is compatible with the unmanaged Microsoft Cryptographic API (CAPI). ]]> @@ -1936,7 +1936,7 @@ The supported RSA key sizes depend on the available cryptographic service provid method. + This method creates a digital signature that is verified using the method. The `halg` parameter can accept a , a , or a . @@ -2098,7 +2098,7 @@ The supported RSA key sizes depend on the available cryptographic service provid method. + This method creates a digital signature that is verified using the method. The `halg` parameter can accept a , a , or a . The string value can be one of the following: @@ -2202,9 +2202,9 @@ The supported RSA key sizes depend on the available cryptographic service provid method. + This method creates a digital signature that is verified using the method. - The valid hash algorithms are and . The algorithm identifier can be derived from the hash name by using the method. + The valid hash algorithms are and . The algorithm identifier can be derived from the hash name by using the method. Due to collision problems with SHA-1 and MD5, Microsoft recommends a security model based on SHA-256 or better. @@ -2336,7 +2336,7 @@ The supported RSA key sizes depend on the available cryptographic service provid flag to a object. The property applies to all code in the current application domain, whereas the object applies only to classes that explicitly reference it. These settings are useful when impersonating or running under an account whose user profile is not loaded. Setting affects the key store location only if is initialized with no parameters. + Setting this property to `true` is equivalent to passing the flag to a object. The property applies to all code in the current application domain, whereas the object applies only to classes that explicitly reference it. These settings are useful when impersonating or running under an account whose user profile is not loaded. Setting affects the key store location only if is initialized with no parameters. @@ -2424,14 +2424,14 @@ The supported RSA key sizes depend on the available cryptographic service provid digital signature produced by the method. The signature is verified by obtaining the hash value from the signature using the public key it was signed with, and comparing that value to the hash value of the provided data. + This method verifies the digital signature produced by the method. The signature is verified by obtaining the hash value from the signature using the public key it was signed with, and comparing that value to the hash value of the provided data. The `halg` parameter can accept a , a , or a . ## Examples - The following example shows how to use the method to verify a signature. This code example is part of a larger example provided for the method. + The following example shows how to use the method to verify a signature. This code example is part of a larger example provided for the method. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSACryptoServiceProvider/SignHash/class1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSACryptoServiceProvider/SignHash/class1.vb" id="Snippet2"::: @@ -2517,14 +2517,14 @@ The supported RSA key sizes depend on the available cryptographic service provid digital signature produced by the method. The signature is verified by obtaining the hash value from the signature using the public key it was signed with, and comparing that value to the hash value of the provided data. + This method verifies the digital signature produced by the method. The signature is verified by obtaining the hash value from the signature using the public key it was signed with, and comparing that value to the hash value of the provided data. - The valid hash algorithms are and . The algorithm identifier can be derived from the hash name by using the method. + The valid hash algorithms are and . The algorithm identifier can be derived from the hash name by using the method. Due to collision problems with SHA-1 and MD5, Microsoft recommends a security model based on SHA-256 or better. ## Examples - The following example shows how to use the method to verify a signature. This code example is part of a larger example provided for the method. + The following example shows how to use the method to verify a signature. This code example is part of a larger example provided for the method. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSACryptoServiceProvider/SignHash/class1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSACryptoServiceProvider/SignHash/class1.vb" id="Snippet2"::: diff --git a/xml/System.Security.Cryptography/RSAEncryptionPadding.xml b/xml/System.Security.Cryptography/RSAEncryptionPadding.xml index 1659a6997cf..3355165868f 100644 --- a/xml/System.Security.Cryptography/RSAEncryptionPadding.xml +++ b/xml/System.Security.Cryptography/RSAEncryptionPadding.xml @@ -194,7 +194,7 @@ object and the two objects have identical and property values. + `obj` is equal to the current instance if it is a object and the two objects have identical and property values. ]]> @@ -263,7 +263,7 @@ and property values. + `instance` and the current instance are equal if they have identical and property values. ]]> @@ -748,7 +748,7 @@ If the value of the objects are equal if their and property values are equal. + Two objects are equal if their and property values are equal. ]]> @@ -809,7 +809,7 @@ If the value of the objects are not equal if their and property values are not equal. + Two objects are not equal if their and property values are not equal. ]]> @@ -909,7 +909,7 @@ If the value of the object is the concatenation of its and `OaepHashAlgorithm.Name` properties. + The string representation of a object is the concatenation of its and `OaepHashAlgorithm.Name` properties. ]]> diff --git a/xml/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter.xml b/xml/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter.xml index ad53e4c7601..19ea577a12b 100644 --- a/xml/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter.xml +++ b/xml/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter.xml @@ -143,7 +143,7 @@ to establish the key before calling . + Use to establish the key before calling . ]]> @@ -259,7 +259,7 @@ ## Examples - The following example shows how to use the method to recreate an exchange key from a message sender. This code example is part of a larger example provided for the class. + The following example shows how to use the method to recreate an exchange key from a message sender. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter/Overview/program.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter/Overview/program.vb" id="Snippet3"::: @@ -383,7 +383,7 @@ . + You must set a key before calling . ]]> diff --git a/xml/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter.xml b/xml/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter.xml index c7556d68ef8..3a91c09242a 100644 --- a/xml/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter.xml +++ b/xml/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter.xml @@ -143,7 +143,7 @@ to set the key before calling . + Use to set the key before calling . ]]> @@ -337,7 +337,7 @@ ## Examples - The following example shows how to use the method to create an exchange key for a message recipient. This code example is part of a larger example provided for the class + The following example shows how to use the method to create an exchange key for a message recipient. This code example is part of a larger example provided for the class :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter/CreateKeyExchange/program.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter/CreateKeyExchange/program.vb" id="Snippet2"::: @@ -572,12 +572,12 @@ . + You must set the key before calling . ## Examples - The following code example demonstrates how to use the method to set an key for decryption. This code example is part of a larger example provided for the class. + The following code example demonstrates how to use the method to set an key for decryption. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter/Parameters/rsaencoder.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter/Parameters/rsaencoder.vb" id="Snippet5"::: diff --git a/xml/System.Security.Cryptography/RSAOpenSsl.xml b/xml/System.Security.Cryptography/RSAOpenSsl.xml index 7c1a519fe9d..de47d4ac067 100644 --- a/xml/System.Security.Cryptography/RSAOpenSsl.xml +++ b/xml/System.Security.Cryptography/RSAOpenSsl.xml @@ -48,7 +48,7 @@ ## Remarks > [!NOTE] -> The class is an implementation of the RSA algorithm using OpenSSL. It isn't available on Windows and is only available on other operating systems when OpenSSL is installed. For applications that aren't doing OpenSSL-specific interop, it's recommended to use instead of referencing this type directly. +> The class is an implementation of the RSA algorithm using OpenSSL. It isn't available on Windows and is only available on other operating systems when OpenSSL is installed. For applications that aren't doing OpenSSL-specific interop, it's recommended to use instead of referencing this type directly. ]]> @@ -107,7 +107,7 @@ This constructor does not generate a new public/private keypair immediately. This constructor sets the property to 2048 and when a key is needed, one is generated using the property value. -If a key is loaded via the method or another key import method, the key size from this constructor has no meaning. +If a key is loaded via the method or another key import method, the key size from this constructor has no meaning. ]]> @@ -170,7 +170,7 @@ If a key is loaded via the property to `keySize` and when a key is needed, one is generated using the property value. -If a key is loaded via the method or another key import method, the key size from this constructor has no meaning. +If a key is loaded via the method or another key import method, the key size from this constructor has no meaning. ]]> @@ -299,7 +299,7 @@ If a key is loaded via the . +This constructor is equivalent to using the default constructor and calling . ]]> diff --git a/xml/System.Security.Cryptography/RSAPKCS1KeyExchangeDeformatter.xml b/xml/System.Security.Cryptography/RSAPKCS1KeyExchangeDeformatter.xml index 604a58dc2b0..b5e2a953329 100644 --- a/xml/System.Security.Cryptography/RSAPKCS1KeyExchangeDeformatter.xml +++ b/xml/System.Security.Cryptography/RSAPKCS1KeyExchangeDeformatter.xml @@ -68,24 +68,24 @@ Decrypts the PKCS #1 key exchange data. - to create the key exchange message using the algorithm. - + to create the key exchange message using the algorithm. + > [!CAUTION] -> It is highly recommended that you not attempt to create your own key exchange method from the basic functionality provided, because many details of the operation must be performed carefully in order for the key exchange to be successful. - - - -## Examples - The following example shows how to use the class to recreate an exchange key to be used to decrypt a message. - +> It is highly recommended that you not attempt to create your own key exchange method from the basic functionality provided, because many details of the operation must be performed carefully in order for the key exchange to be successful. + + + +## Examples + The following example shows how to use the class to recreate an exchange key to be used to decrypt a message. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter/CreateKeyExchange/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter/CreateKeyExchange/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter/CreateKeyExchange/program.vb" id="Snippet1"::: + ]]> Cryptographic Services @@ -140,11 +140,11 @@ Initializes a new instance of the class. - to establish the key before calling . - + to establish the key before calling . + ]]> Cryptographic Services @@ -251,19 +251,19 @@ Extracts secret information from the encrypted key exchange data. The secret information derived from the key exchange data. - method to recreate an exchange key from a message sender. This code example is part of a larger example provided for the class. - + method to recreate an exchange key from a message sender. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter/CreateKeyExchange/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter/CreateKeyExchange/program.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter/CreateKeyExchange/program.vb" id="Snippet3"::: + ]]> The key is missing. @@ -410,11 +410,11 @@ The instance of the algorithm that holds the private key. Sets the private key to use for decrypting the secret information. - . - + . + ]]> diff --git a/xml/System.Security.Cryptography/RSAPKCS1KeyExchangeFormatter.xml b/xml/System.Security.Cryptography/RSAPKCS1KeyExchangeFormatter.xml index d125f98c080..c39e8824a03 100644 --- a/xml/System.Security.Cryptography/RSAPKCS1KeyExchangeFormatter.xml +++ b/xml/System.Security.Cryptography/RSAPKCS1KeyExchangeFormatter.xml @@ -143,7 +143,7 @@ method to set the key to be used for key exchange before calling . + Use method to set the key to be used for key exchange before calling . ]]> @@ -339,7 +339,7 @@ ## Examples - The following example shows how to use the method to create an exchange key for a message recipient. This code example is part of a larger example provided for the class. + The following example shows how to use the method to create an exchange key for a message recipient. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter/CreateKeyExchange/program.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter/CreateKeyExchange/program.vb" id="Snippet2"::: @@ -511,7 +511,7 @@ . + You must set the key before calling . ]]> diff --git a/xml/System.Security.Cryptography/RSAPKCS1SignatureDeformatter.xml b/xml/System.Security.Cryptography/RSAPKCS1SignatureDeformatter.xml index 25a1a385725..40f4532f947 100644 --- a/xml/System.Security.Cryptography/RSAPKCS1SignatureDeformatter.xml +++ b/xml/System.Security.Cryptography/RSAPKCS1SignatureDeformatter.xml @@ -68,21 +68,21 @@ Verifies an PKCS #1 version 1.5 signature. - algorithm. - - Use to create digital signatures with the algorithm. - - - -## Examples - The following example demonstrates how to use the method to verify a signature. - + algorithm. + + Use to create digital signatures with the algorithm. + + + +## Examples + The following example demonstrates how to use the method to verify a signature. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSAPKCS1SignatureDeformatter/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAPKCS1SignatureDeformatter/Overview/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAPKCS1SignatureDeformatter/Overview/program.vb" id="Snippet1"::: + ]]> Cryptographic Services @@ -137,11 +137,11 @@ Initializes a new instance of the class. - and to set the key and hash algorithm before calling . - + and to set the key and hash algorithm before calling . + ]]> Cryptographic Services @@ -190,11 +190,11 @@ The instance of that holds the public key. Initializes a new instance of the class with the specified key. - to set the hash algorithm before calling . - + to set the hash algorithm before calling . + ]]> @@ -248,11 +248,11 @@ The name of the hash algorithm to use for verifying the signature. Sets the hash algorithm to use for verifying the signature. - . - + . + ]]> Cryptographic Services @@ -304,11 +304,11 @@ The instance of that holds the public key. Sets the public key to use for verifying the signature. - . - + . + ]]> @@ -372,30 +372,30 @@ if matches the signature computed using the specified hash algorithm and key on ; otherwise, . - method to verify a signature. - + method to verify a signature. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSAPKCS1SignatureDeformatter/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAPKCS1SignatureDeformatter/Overview/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAPKCS1SignatureDeformatter/Overview/program.vb" id="Snippet1"::: + ]]> - The key is . - - -or- - + The key is . + + -or- + The hash algorithm is . - The parameter is . - - -or- - + The parameter is . + + -or- + The parameter is . Cryptographic Services diff --git a/xml/System.Security.Cryptography/RSAPKCS1SignatureFormatter.xml b/xml/System.Security.Cryptography/RSAPKCS1SignatureFormatter.xml index ad843abb0c4..8be9ca25daa 100644 --- a/xml/System.Security.Cryptography/RSAPKCS1SignatureFormatter.xml +++ b/xml/System.Security.Cryptography/RSAPKCS1SignatureFormatter.xml @@ -68,21 +68,21 @@ Creates an PKCS #1 version 1.5 signature. - algorithm. - - Use to verify digital signatures with the algorithm. - - - -## Examples - The following example demonstrates how to create a PKCS #1 version 1.5 signature. - + algorithm. + + Use to verify digital signatures with the algorithm. + + + +## Examples + The following example demonstrates how to create a PKCS #1 version 1.5 signature. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSAPKCS1SignatureFormatter/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAPKCS1SignatureFormatter/Overview/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAPKCS1SignatureFormatter/Overview/program.vb" id="Snippet1"::: + ]]> Cryptographic Services @@ -137,11 +137,11 @@ Initializes a new instance of the class. - and to set the key and hash algorithm before calling . - + and to set the key and hash algorithm before calling . + ]]> Cryptographic Services @@ -190,11 +190,11 @@ The instance of the algorithm that holds the private key. Initializes a new instance of the class with the specified key. - to set the hash algorithm before calling . - + to set the hash algorithm before calling . + ]]> @@ -255,25 +255,25 @@ Creates the PKCS #1 signature for the specified data. The digital signature for . - - The key is . - - -or- - + The key is . + + -or- + The hash algorithm is . The parameter is . Cryptographic Services @@ -325,11 +325,11 @@ The name of the hash algorithm to use for creating the signature. Sets the hash algorithm to use for creating the signature. - . - + . + ]]> Cryptographic Services @@ -381,11 +381,11 @@ The instance of the algorithm that holds the private key. Sets the private key to use for creating the signature. - . - + . + ]]> diff --git a/xml/System.Security.Cryptography/RSASignaturePadding.xml b/xml/System.Security.Cryptography/RSASignaturePadding.xml index 82de6f2b7e4..579ca9f6a4b 100644 --- a/xml/System.Security.Cryptography/RSASignaturePadding.xml +++ b/xml/System.Security.Cryptography/RSASignaturePadding.xml @@ -366,7 +366,7 @@ method defines the operation of the equality operator for values. + The method defines the operation of the equality operator for values. Two values are equal if their property values are equal. @@ -429,7 +429,7 @@ method defines the operation of the inequality operator for values. + The method defines the operation of the inequality operator for values. Two values are unequal if their property values are different. @@ -577,7 +577,7 @@ method returns the value of the `RSASignaturePadding.Mode.ToString` method. + The method returns the value of the `RSASignaturePadding.Mode.ToString` method. ]]> diff --git a/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml b/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml index 4eef4e096de..c3344a052cd 100644 --- a/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml +++ b/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml @@ -73,7 +73,7 @@ takes a password, a salt, and an iteration count, and then generates keys through calls to the method. + takes a password, a salt, and an iteration count, and then generates keys through calls to the method. RFC 2898 includes methods for creating a key and initialization vector (IV) from a password and salt. You can use PBKDF2, a password-based key derivation function, to derive keys using a pseudo-random function that allows keys of virtually unlimited length to be generated. The class can be used to produce a derived key from a base key and other parameters. In a password-based key derivation function, the base key is a password and the other parameters are a salt value and an iteration count. @@ -895,12 +895,12 @@ For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/inf class implements PBKDF2 functionality by using a pseudorandom number generator based on . The class takes a password, a salt, and an iteration count, and then generates keys through calls to the method. Repeated calls to this method will not generate the same key; instead, appending two calls of the method with a `cb` parameter value of `20` is the equivalent of calling the method once with a `cb` parameter value of `40`. + The class implements PBKDF2 functionality by using a pseudorandom number generator based on . The class takes a password, a salt, and an iteration count, and then generates keys through calls to the method. Repeated calls to this method will not generate the same key; instead, appending two calls of the method with a `cb` parameter value of `20` is the equivalent of calling the method once with a `cb` parameter value of `40`. ## Examples - The following example shows how to use the method to get the key for an instance of . This code example is part of a larger example provided for the class. + The following example shows how to use the method to get the key for an instance of . This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/Rfc2898DeriveBytes/Overview/rfc28981.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/Rfc2898DeriveBytes/Overview/rfc28981.vb" id="Snippet2"::: @@ -1428,7 +1428,7 @@ The `password` is converted to bytes using the UTF8 encoding. For other encoding ## Examples - The following example shows how to use the method. This code example is part of a larger example provided for the class. + The following example shows how to use the method. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/Rfc2898DeriveBytes/Overview/rfc28981.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/Rfc2898DeriveBytes/Overview/rfc28981.vb" id="Snippet5"::: diff --git a/xml/System.Security.Cryptography/RijndaelManaged.xml b/xml/System.Security.Cryptography/RijndaelManaged.xml index f1746426921..e8f7d282971 100644 --- a/xml/System.Security.Cryptography/RijndaelManaged.xml +++ b/xml/System.Security.Cryptography/RijndaelManaged.xml @@ -240,7 +240,7 @@ overload with the same signature. + This method decrypts an encrypted message created using the overload with the same signature. ]]> @@ -306,14 +306,14 @@ overload with the same signature. + This method decrypts an encrypted message created using the overload with the same signature. The `rgbkey` size must be 128, 192, or 256 bits. ## Examples - The following code example demonstrates how to use the method to decrypt messages encoded with the same signature parameter. + The following code example demonstrates how to use the method to decrypt messages encoded with the same signature parameter. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RijndaelManaged/Overview/class1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RijndaelManaged/Overview/class1.vb" id="Snippet1"::: @@ -368,9 +368,9 @@ property is `null`, the method is called to create a new random . If the current property is `null`, the method is called to create a new random . + If the current property is `null`, the method is called to create a new random . If the current property is `null`, the method is called to create a new random . - Use the overload with the same signature to decrypt the result of this method. + Use the overload with the same signature to decrypt the result of this method. ]]> @@ -435,7 +435,7 @@ overload with the same signature to decrypt the result of this method. + Use the overload with the same signature to decrypt the result of this method. The `rgbkey` size must be 128, 192, or 256 bits. diff --git a/xml/System.Security.Cryptography/RijndaelManagedTransform.xml b/xml/System.Security.Cryptography/RijndaelManagedTransform.xml index 80b57140de0..fe512af8849 100644 --- a/xml/System.Security.Cryptography/RijndaelManagedTransform.xml +++ b/xml/System.Security.Cryptography/RijndaelManagedTransform.xml @@ -31,17 +31,17 @@ Performs a cryptographic transformation of data using the Rijndael algorithm. This class cannot be inherited. - [!IMPORTANT] -> The class is the predecessor of the algorithm. You should use the algorithm instead of . For more information, see the entry [The Differences Between Rijndael and AES](https://learn.microsoft.com/archive/blogs/shawnfa/the-differences-between-rijndael-and-aes) in the .NET Security blog. +> The class is the predecessor of the algorithm. You should use the algorithm instead of . For more information, see the entry [The Differences Between Rijndael and AES](https://learn.microsoft.com/archive/blogs/shawnfa/the-differences-between-rijndael-and-aes) in the .NET Security blog. > -> Using this class is not recommended. If you use the `Rijndael` algorithm, a better practice is to use with a object. The object handles the padding issues that can occur when using directly. For an example, see the class. - - Both the and methods return an instance of the class that is initialized with the key information of the current object. To encrypt or decrypt data using the Rijndael algorithm, pass the object returned by these methods to a object. - +> Using this class is not recommended. If you use the `Rijndael` algorithm, a better practice is to use with a object. The object handles the padding issues that can occur when using directly. For an example, see the class. + + Both the and methods return an instance of the class that is initialized with the key information of the current object. To encrypt or decrypt data using the Rijndael algorithm, pass the object returned by these methods to a object. + ]]> Cryptographic Services @@ -143,13 +143,13 @@ Releases all resources used by the class. - class. - - Calling `Dispose` allows the resources used by the to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - + class. + + Calling `Dispose` allows the resources used by the to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + ]]> Cryptographic Services @@ -177,16 +177,16 @@ Releases all resources used by the current instance of the class. - . 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 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). - + . 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 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 `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. + ]]> @@ -269,11 +269,11 @@ Resets the internal state of so it can be used again to do a different encryption or decryption. - method is called automatically when you call . The method is not called when, for example, the encrypted input data is garbage and cannot be decrypted. In this case, an exception is thrown and is not called. You can choose to manually call the method in this case. - + method is called automatically when you call . The method is not called when, for example, the encrypted input data is garbage and cannot be decrypted. In this case, an exception is thrown and is not called. You can choose to manually call the method in this case. + ]]> Cryptographic Services @@ -354,23 +354,23 @@ This member is an explicit interface member implementation. It can be used only Computes the transformation for the specified region of the input byte array and copies the resulting transformation to the specified region of the output byte array. The number of bytes written. To be added. - The parameter is . - - -or- - + The parameter is . + + -or- + The parameter is . - The length of the input buffer is less than the sum of the input offset and the input count. - - -or- - - The value of the parameter is less than or equal to 0. - - -or- - - The value of the parameter is greater than the length of the parameter. - - -or- - + The length of the input buffer is less than the sum of the input offset and the input count. + + -or- + + The value of the parameter is less than or equal to 0. + + -or- + + The value of the parameter is greater than the length of the parameter. + + -or- + The length of the parameter is not evenly devisable by input block size. The value of the parameter is negative. Cryptographic Services @@ -414,10 +414,10 @@ This member is an explicit interface member implementation. It can be used only The computed transformation. To be added. The parameter is . - The value of the parameter is less than 0. - - -or- - + The value of the parameter is less than 0. + + -or- + The value of the parameter is grater than the length of parameter. The value of the parameter is negative. The length of the parameter is not evenly devisable by input block size. diff --git a/xml/System.Security.Cryptography/SHA1CryptoServiceProvider.xml b/xml/System.Security.Cryptography/SHA1CryptoServiceProvider.xml index 68cb35962a5..9634b8d8e42 100644 --- a/xml/System.Security.Cryptography/SHA1CryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/SHA1CryptoServiceProvider.xml @@ -75,7 +75,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 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. Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better. diff --git a/xml/System.Security.Cryptography/StrongNameSignatureInformation.xml b/xml/System.Security.Cryptography/StrongNameSignatureInformation.xml index 47bdb9679fd..c1658b76ec2 100644 --- a/xml/System.Security.Cryptography/StrongNameSignatureInformation.xml +++ b/xml/System.Security.Cryptography/StrongNameSignatureInformation.xml @@ -121,7 +121,7 @@ is `false`. If the signature is valid, there will always be a key. + The only case that returns `null` is when is `false`. If the signature is valid, there will always be a key. ]]> diff --git a/xml/System.Security.Cryptography/SymmetricAlgorithm.xml b/xml/System.Security.Cryptography/SymmetricAlgorithm.xml index 89ac1b00764..4afc2b7a621 100644 --- a/xml/System.Security.Cryptography/SymmetricAlgorithm.xml +++ b/xml/System.Security.Cryptography/SymmetricAlgorithm.xml @@ -68,18 +68,18 @@ class use a chaining mode called cipher block chaining (CBC), which requires a key () and an initialization vector () to perform cryptographic transformations on data. To decrypt data that was encrypted using one of the classes, you must set the property and the property to the same values that were used for encryption. For a symmetric algorithm to be useful, the secret key must be known only to the sender and the receiver. + The classes that derive from the class use a chaining mode called cipher block chaining (CBC), which requires a key () and an initialization vector () to perform cryptographic transformations on data. To decrypt data that was encrypted using one of the classes, you must set the property and the property to the same values that were used for encryption. For a symmetric algorithm to be useful, the secret key must be known only to the sender and the receiver. , , , and are implementations of symmetric algorithms. - Note that when using derived classes, it is not enough, from a security perspective, to simply force a garbage collection after you have finished using the object. You must explicitly call the method on the object to zero out any sensitive data within the object before it is released. Note that garbage collection does not zero out the contents of collected objects but simply marks the memory as available for reallocation. Thus the data contained within a garbage collected object may still be present in the memory heap in unallocated memory. In the case of cryptographic objects, this data could contain sensitive information such as key data or a block of plain text. + Note that when using derived classes, it is not enough, from a security perspective, to simply force a garbage collection after you have finished using the object. You must explicitly call the method on the object to zero out any sensitive data within the object before it is released. Note that garbage collection does not zero out the contents of collected objects but simply marks the memory as available for reallocation. Thus the data contained within a garbage collected object may still be present in the memory heap in unallocated memory. In the case of cryptographic objects, this data could contain sensitive information such as key data or a block of plain text. All cryptographic classes in the .NET Framework that hold sensitive data implement a `Clear` method. When called, the `Clear` method overwrites all sensitive data within the object with zeros and then releases the object so that it can be safely garbage collected. When the object has been zeroed and released, you should then call the `Dispose` method with the `disposing` parameter set to `True` to dispose of all managed and unmanaged resources associated with the object. ## Examples - The following code example uses the class with the specified property and initialization vector () to encrypt a file specified by `inName`, and outputs the encrypted result to the file specified by `outName`. The `desKey` and `desIV` parameters to the method are 8-byte arrays. You must have the high encryption pack installed to run this example. + The following code example uses the class with the specified property and initialization vector () to encrypt a file specified by `inName`, and outputs the encrypted result to the file specified by `outName`. The `desKey` and `desIV` parameters to the method are 8-byte arrays. You must have the high encryption pack installed to run this example. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/SymmetricAlgorithm/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/SymmetricAlgorithm/Overview/source.vb" id="Snippet1"::: @@ -303,7 +303,7 @@ method on the object to zero out any sensitive data within the object before it is released. Note that garbage collection does not zero out the contents of collected objects but simply marks the memory as available for reallocation. Thus the data contained within a garbage collected object may still be present in the memory heap in unallocated memory. In the case of cryptographic objects, this data could contain sensitive information such as key data or a block of plain text. + Note that when using derived classes, it is not enough, from a security perspective, to simply force a garbage collection after you have finished using the object. You must explicitly call the method on the object to zero out any sensitive data within the object before it is released. Note that garbage collection does not zero out the contents of collected objects but simply marks the memory as available for reallocation. Thus the data contained within a garbage collected object may still be present in the memory heap in unallocated memory. In the case of cryptographic objects, this data could contain sensitive information such as key data or a block of plain text. All cryptographic classes in the .NET Framework that hold sensitive data implement a `Clear` method. When called, the `Clear` method overwrites all sensitive data within the object with zeros and then releases the object so that it can be safely garbage collected. When the object has been zeroed and released, you should then call the `Dispose` method with the `disposing` parameter set to `True` to dispose of all managed and unmanaged resources associated with the object. @@ -523,7 +523,7 @@ We recommend that you specify the algorithm by calling the overload with the same signature. + This method decrypts an encrypted message created using the overload with the same signature. ]]> @@ -591,7 +591,7 @@ We recommend that you specify the algorithm by calling the overload with the same parameters. + This method decrypts an encrypted message created using the overload with the same parameters. ]]> @@ -656,14 +656,14 @@ We recommend that you specify the algorithm by calling the property is `null`, the method is called to create a new random . If the current property is `null`, the method is called to create a new random . + If the current property is `null`, the method is called to create a new random . If the current property is `null`, the method is called to create a new random . - Use the overload with the same signature to decrypt the result of this method. + Use the overload with the same signature to decrypt the result of this method. ## Examples - The following example encrypts a string using the transform object returned from the method. + The following example encrypts a string using the transform object returned from the method. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/SymmetricAlgorithm/CreateEncryptor/encryptor.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/SymmetricAlgorithm/CreateEncryptor/encryptor.vb" id="Snippet1"::: @@ -734,7 +734,7 @@ We recommend that you specify the algorithm by calling the overload with the same parameters to decrypt the result of this method. + Use the overload with the same parameters to decrypt the result of this method. ]]> @@ -2115,7 +2115,7 @@ Allows an to attempt to free resources and perfor method to reuse a symmetric algorithm instance with a different initialization vector. + In general, there is no reason to use this method, because `CreateEncryptor()` or `CreateEncryptor(null, null)` automatically generates both an initialization vector and a key. However, you may want to use the method to reuse a symmetric algorithm instance with a different initialization vector. ]]> @@ -2169,7 +2169,7 @@ Allows an to attempt to free resources and perfor method to reuse a symmetric algorithm instance with a different key. + In general, there is no reason to use this method, because `CreateEncryptor()` or `CreateEncryptor(null, null)` automatically generates both an initialization vector and a key. However, you may want to use the method to reuse a symmetric algorithm instance with a different key. ]]> @@ -2405,7 +2405,7 @@ Allows an to attempt to free resources and perfor property is automatically set to a new random value whenever you create a new instance of one of the classes or when you manually call the method. The size of the property must be the same as the property divided by 8. + The property is automatically set to a new random value whenever you create a new instance of one of the classes or when you manually call the method. The size of the property must be the same as the property divided by 8. The classes that derive from the class use a chaining mode called cipher block chaining (CBC), which requires a key and an initialization vector to perform cryptographic transformations on data. To decrypt data that was encrypted using one of the classes, you must set the property and property to the same values that were used for encryption. @@ -2533,7 +2533,7 @@ Allows an to attempt to free resources and perfor ## Remarks The secret key is used both for encryption and for decryption. For a symmetric algorithm to be successful, the secret key must be known only to the sender and the receiver. The valid key sizes are specified by the particular symmetric algorithm implementation and are listed in the property. - If this property is `null` when it is used, the method is called to create a new random value. + If this property is `null` when it is used, the method is called to create a new random value. ]]> @@ -2774,7 +2774,7 @@ Allows an to attempt to free resources and perfor ## Examples - The following example shows the value of for the symmetric algorithms. + The following example shows the value of for the symmetric algorithms. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/SymmetricAlgorithm/LegalBlockSizes/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/SymmetricAlgorithm/LegalBlockSizes/program.vb" id="Snippet1"::: @@ -2907,7 +2907,7 @@ Allows an to attempt to free resources and perfor ## Examples - The following example shows the value of for the AES symmetric algorithm. + The following example shows the value of for the AES symmetric algorithm. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/SymmetricAlgorithm/LegalBlockSizes/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/SymmetricAlgorithm/LegalBlockSizes/program.vb" id="Snippet1"::: diff --git a/xml/System.Security.Cryptography/ToBase64Transform.xml b/xml/System.Security.Cryptography/ToBase64Transform.xml index 909427b638f..6304ee417ac 100644 --- a/xml/System.Security.Cryptography/ToBase64Transform.xml +++ b/xml/System.Security.Cryptography/ToBase64Transform.xml @@ -240,7 +240,7 @@ method to verify that multiple blocks can be transformed. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the method to verify that multiple blocks can be transformed. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/ToBase64Transform/Overview/members.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/ToBase64Transform/Overview/members.vb" id="Snippet4"::: @@ -296,14 +296,14 @@ . + This method is a simple call to . Calling `Dispose` allows the resources used by the to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). ## Examples - The following code example demonstrates how to call the method to free up unused resources by the current transform. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the method to free up unused resources by the current transform. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/ToBase64Transform/Overview/members.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/ToBase64Transform/Overview/members.vb" id="Snippet7"::: @@ -731,12 +731,12 @@ For more information about `Dispose` and `Finalize`, see [Cleaning Up Unmanaged class is a block algorithm that processes input blocks of 3 bytes and creates output blocks of 4 bytes. The method transforms an input block of 24 bits into 32 bits of character data. You must maintain 3 byte input boundaries to 4 byte output boundaries in order to match the block transform. + The class is a block algorithm that processes input blocks of 3 bytes and creates output blocks of 4 bytes. The method transforms an input block of 24 bits into 32 bits of character data. You must maintain 3 byte input boundaries to 4 byte output boundaries in order to match the block transform. ## Examples - The following code example demonstrates how to call the method to iterate through `inputBytes` transforming by `blockSize`. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the method to iterate through `inputBytes` transforming by `blockSize`. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/ToBase64Transform/Overview/members.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/ToBase64Transform/Overview/members.vb" id="Snippet8"::: @@ -812,7 +812,7 @@ For more information about `Dispose` and `Finalize`, see [Cleaning Up Unmanaged method to transform the final block of data. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the method to transform the final block of data. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/ToBase64Transform/Overview/members.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/ToBase64Transform/Overview/members.vb" id="Snippet9"::: diff --git a/xml/System.Security.Cryptography/TripleDES.xml b/xml/System.Security.Cryptography/TripleDES.xml index d8e0a2a30b1..2dec3ba6983 100644 --- a/xml/System.Security.Cryptography/TripleDES.xml +++ b/xml/System.Security.Cryptography/TripleDES.xml @@ -243,7 +243,7 @@ ## Examples The following code example shows how to create and use a object to encrypt and decrypt data in a file. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/TripleDES/Create/fileexample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/TripleDES/Overview/fileexample.vb" id="Snippet1"::: @@ -384,7 +384,7 @@ ## Remarks Weak keys are keys that result in ciphers that are easy to break. If text is encrypted with a weak key, encrypting the resulting cipher again with the same weak key returns the original text. In 128-bit mode, if the first 64 bits are the same as the last 64 bits, the key is weak. In 192-bit mode, if the first 64 bits are the same as the second 64 bits or if the second 64 bits are the same as the last 64 bits, the key is weak. - Attempting to set a weak key results in a . When is called to create a random key, a weak key will never be returned. + Attempting to set a weak key results in a . When is called to create a random key, a weak key will never be returned. ]]> diff --git a/xml/System.Security.Cryptography/TripleDESCng.xml b/xml/System.Security.Cryptography/TripleDESCng.xml index 9f364faea4f..1c155e97312 100644 --- a/xml/System.Security.Cryptography/TripleDESCng.xml +++ b/xml/System.Security.Cryptography/TripleDESCng.xml @@ -168,7 +168,7 @@ value of and as the default key storage provider (KSP) to open the key. + This constructor uses a default value of and as the default key storage provider (KSP) to open the key. ]]> @@ -427,7 +427,7 @@ overload with the same signature. + This method decrypts an encrypted message created using the overload with the same signature. > [!NOTE] > If you've created the object using an existing persisted key and you want to make use of that key when decrypting the message, you want to set the property and then call the parameterless overload instead; otherwise, using this method will create an ephemeral key as specified by the `rgbKey` parameter. @@ -504,7 +504,7 @@ overload with the same signature to decrypt the result of this method. + Use this method to encrypt a message and then use the overload with the same signature to decrypt the result of this method. ]]> @@ -569,7 +569,7 @@ overload with the same signature to decrypt the result of this method. + Use this method to encrypt a message and then use the overload with the same signature to decrypt the result of this method. > [!NOTE] > If you've created the object using an existing persisted key and you want to make use of that key when encrypting the message, you want to set the property and then call the parameterless overload instead; otherwise, using this method will create an ephemeral key as specified by the `rgbKey` parameter. diff --git a/xml/System.Security.Cryptography/TripleDESCryptoServiceProvider.xml b/xml/System.Security.Cryptography/TripleDESCryptoServiceProvider.xml index 135b62472ee..695d33f5f65 100644 --- a/xml/System.Security.Cryptography/TripleDESCryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/TripleDESCryptoServiceProvider.xml @@ -225,7 +225,7 @@ overload with the same signature. + This method decrypts an encrypted message created using the overload with the same signature. ]]> @@ -297,7 +297,7 @@ overload with the same parameters. + This method decrypts an encrypted message created using the overload with the same parameters. ]]> @@ -365,9 +365,9 @@ property is `null`, the method is called to create a new random . If the current property is `null`, the method is called to create a new random . + If the current property is `null`, the method is called to create a new random . If the current property is `null`, the method is called to create a new random . - Use the overload with the same signature to decrypt the result of this method. + Use the overload with the same signature to decrypt the result of this method. ]]> @@ -440,7 +440,7 @@ overload with the same parameters to decrypt the result of this method. + Use the overload with the same parameters to decrypt the result of this method. ]]> @@ -638,7 +638,7 @@ ). + Use this method to generate a random key when none is specified. This method will never return a weak key (see ). This algorithm supports key lengths from 128 bits to 192 bits in increments of 64 bits. @@ -685,7 +685,7 @@ property is automatically set to a new random value whenever you create a new instance of one of the classes or when you manually call the method. The size of the property must be the same as the property divided by 8. + The property is automatically set to a new random value whenever you create a new instance of one of the classes or when you manually call the method. The size of the property must be the same as the property divided by 8. The classes that derive from the class use a chaining mode called cipher block chaining (CBC), which requires a key and an initialization vector to perform cryptographic transformations on data. To decrypt data that was encrypted using one of the classes, you must set the property and property to the same values that were used for encryption. diff --git a/xml/System.Security.Permissions/DataProtectionPermission.xml b/xml/System.Security.Permissions/DataProtectionPermission.xml index 42ae4b65963..c46a9dfc494 100644 --- a/xml/System.Security.Permissions/DataProtectionPermission.xml +++ b/xml/System.Security.Permissions/DataProtectionPermission.xml @@ -273,7 +273,7 @@ method reconstructs a object from an XML encoding defined by the class. Use the method to XML-encode the , including state information. + The method reconstructs a object from an XML encoding defined by the class. Use the method to XML-encode the , including state information. ]]> @@ -464,7 +464,7 @@ method to restore the state information from a . + Use the method to restore the state information from a . ]]> @@ -509,7 +509,7 @@ is a permission that represents all operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. + The result of a call to is a permission that represents all operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. ]]> diff --git a/xml/System.Security.Permissions/DataProtectionPermissionAttribute.xml b/xml/System.Security.Permissions/DataProtectionPermissionAttribute.xml index d1eeba43435..696bf57f1e7 100644 --- a/xml/System.Security.Permissions/DataProtectionPermissionAttribute.xml +++ b/xml/System.Security.Permissions/DataProtectionPermissionAttribute.xml @@ -47,16 +47,16 @@ Allows security actions for to be applied to code using declarative security. This class cannot be inherited. - value that is used. - - The security information declared by a security attribute is stored in the metadata of the attribute target and is accessed by the system at run time. is used only for declarative security. For imperative security, use the class. - + The scope of the declaration that is allowed depends on the value that is used. + + The security information declared by a security attribute is stored in the metadata of the attribute target and is accessed by the system at run time. is used only for declarative security. For imperative security, use the class. + ]]> @@ -128,13 +128,13 @@ Creates and returns a new . A that corresponds to the attribute. - @@ -206,11 +206,11 @@ if data can be encrypted; otherwise, . - occurs when the method is called. - + occurs when the method is called. + ]]> @@ -248,11 +248,11 @@ if memory can be encrypted; otherwise, . - occurs when the method is called. - + occurs when the method is called. + ]]> @@ -290,11 +290,11 @@ if data can be unencrypted; otherwise, . - occurs when the method is called. - + occurs when the method is called. + ]]> @@ -332,11 +332,11 @@ if memory can be unencrypted; otherwise, . - occurs when the method is called. - + occurs when the method is called. + ]]> diff --git a/xml/System.Security.Permissions/EnvironmentPermission.xml b/xml/System.Security.Permissions/EnvironmentPermission.xml index c1f217c2c84..2ce765e9aa8 100644 --- a/xml/System.Security.Permissions/EnvironmentPermission.xml +++ b/xml/System.Security.Permissions/EnvironmentPermission.xml @@ -63,7 +63,7 @@ Environment variable names are designated by one or more case-insensitive name lists separated by semicolons, with separate lists for read and write access to the named variables. Write access includes the ability to create and delete environment variables as well as to change existing values. > [!NOTE] -> In versions of .NET Framework before .NET Framework 4, you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](/dotnet/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox). +> In versions of .NET Framework before .NET Framework 4, you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](/dotnet/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox). ]]> @@ -170,7 +170,7 @@ values to be specified. This access applies to all listed environment variables. Use to define complex permissions. + This constructor allows only one of the values to be specified. This access applies to all listed environment variables. Use to define complex permissions. ]]> @@ -682,7 +682,7 @@ is a permission that represents all the states represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. + The result of a call to is a permission that represents all the states represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. ]]> diff --git a/xml/System.Security.Permissions/EnvironmentPermissionAccess.xml b/xml/System.Security.Permissions/EnvironmentPermissionAccess.xml index 41f13fab16c..ef898f0da01 100644 --- a/xml/System.Security.Permissions/EnvironmentPermissionAccess.xml +++ b/xml/System.Security.Permissions/EnvironmentPermissionAccess.xml @@ -53,17 +53,17 @@ Specifies access to environment variables. - . - + This enumeration is used by . + > [!NOTE] -> Although `NoAccess` and `AllAccess` appear in `EnvironmentPermissionAccess`, they are not valid for use as the parameter for because they describe no environment variable access types or all environment variable access types, respectively, and expects a single environment variable access type. - +> Although `NoAccess` and `AllAccess` appear in `EnvironmentPermissionAccess`, they are not valid for use as the parameter for because they describe no environment variable access types or all environment variable access types, respectively, and expects a single environment variable access type. + ]]> diff --git a/xml/System.Security.Permissions/FileDialogPermission.xml b/xml/System.Security.Permissions/FileDialogPermission.xml index 2014568f866..a7efd551232 100644 --- a/xml/System.Security.Permissions/FileDialogPermission.xml +++ b/xml/System.Security.Permissions/FileDialogPermission.xml @@ -542,7 +542,7 @@ is a permission that represents all operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. + The result of a call to is a permission that represents all operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. ]]> diff --git a/xml/System.Security.Permissions/FileIOPermission.xml b/xml/System.Security.Permissions/FileIOPermission.xml index 94c7d4f1238..7cfbde3d60b 100644 --- a/xml/System.Security.Permissions/FileIOPermission.xml +++ b/xml/System.Security.Permissions/FileIOPermission.xml @@ -82,7 +82,7 @@ Access to a folder implies access to all the files it contains, as well as access to all the files and folders in its subfolders. For example, `Read` access to C:\folder1\ implies `Read` access to C:\folder1\file1.txt, C:\folder1\folder2\\, C:\folder1\folder2\file2.txt, and so on. > [!NOTE] -> In versions of the .NET Framework before the .NET Framework 4, you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](/dotnet/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox). +> In versions of the .NET Framework before the .NET Framework 4, you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](/dotnet/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox). ]]> @@ -189,7 +189,7 @@ values to be specified for the specified file or directory. Use the method to define complex permissions. + This constructor allows only one of the values to be specified for the specified file or directory. Use the method to define complex permissions. ]]> @@ -249,7 +249,7 @@ value to be specified for the specified files and directories. Use the method to define complex permissions. + This constructor allows only one value to be specified for the specified files and directories. Use the method to define complex permissions. ]]> @@ -313,7 +313,7 @@ value to be specified for the specified file or directories. Use the method to define complex permissions. + This constructor allows only one value to be specified for the specified file or directories. Use the method to define complex permissions. The `control` parameter specifies whether the access control list (ACL) for the file or directory specified by `path` can be changed, viewed, or cannot be accessed. @@ -386,7 +386,7 @@ value to be specified for the specified files and directories. Use the method to define complex permissions. + This constructor allows only one value to be specified for the specified files and directories. Use the method to define complex permissions. The `control` parameter specifies whether the access control list (ACL) for the file or directory specified by `path` can be changed, viewed, or cannot be accessed. @@ -726,7 +726,7 @@ . + For more information, see . ]]> @@ -1223,7 +1223,7 @@ is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. + The result of a call to is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. ]]> diff --git a/xml/System.Security.Permissions/FileIOPermissionAccess.xml b/xml/System.Security.Permissions/FileIOPermissionAccess.xml index a881830e47f..3b1808be4ee 100644 --- a/xml/System.Security.Permissions/FileIOPermissionAccess.xml +++ b/xml/System.Security.Permissions/FileIOPermissionAccess.xml @@ -53,8 +53,8 @@ Specifies the type of file access requested. - class. > [!NOTE] -> Giving `Write` access to an assembly is similar to granting it Full Trust. If an application should not write to the file system, it should not have Write access. +> Giving `Write` access to an assembly is similar to granting it Full Trust. If an application should not write to the file system, it should not have Write access. -Although `NoAccess` and `AllAccess` are members of `FileIOPermissionAccess`, they are not valid for use as the parameter for because they describe no file access types or all file access types, respectively. expects a single file access type. +Although `NoAccess` and `AllAccess` are members of `FileIOPermissionAccess`, they are not valid for use as the parameter for because they describe no file access types or all file access types, respectively. expects a single file access type. ]]> diff --git a/xml/System.Security.Permissions/FileIOPermissionAttribute.xml b/xml/System.Security.Permissions/FileIOPermissionAttribute.xml index 85ebfc3aef1..e732a4559ca 100644 --- a/xml/System.Security.Permissions/FileIOPermissionAttribute.xml +++ b/xml/System.Security.Permissions/FileIOPermissionAttribute.xml @@ -67,7 +67,7 @@ The security information declared by a security attribute is stored in the metadata of the attribute target and is accessed by the system at run time. Security attributes are used only for declarative security. For imperative security, use the corresponding permission class. > [!CAUTION] -> `Unrestricted` grants permission for all paths within a file system, including multiple pathnames that can be used to access a single given file. To access to a file, you must `Deny` all possible paths to the file. For example, if \\\server\share is mapped to the network drive X, to `Deny` access to \\\server\share\file, you must `Deny` \\\server\share\file, X:\file and any other path that you can use to access the file. +> `Unrestricted` grants permission for all paths within a file system, including multiple pathnames that can be used to access a single given file. To access to a file, you must `Deny` all possible paths to the file. For example, if \\\server\share is mapped to the network drive X, to `Deny` access to \\\server\share\file, you must `Deny` \\\server\share\file, X:\file and any other path that you can use to access the file. ]]> @@ -430,7 +430,7 @@ Path discovery controls access to the information in the path itself. This helps protect sensitive information in the path, such as user names, as well as information about the directory structure revealed in the path. This value does not grant access to files or folders represented by the path. > [!NOTE] -> For performance reasons, should be granted only to directories, not to files. For example, permission should be granted to paths such as C:\test and C:\test\\, not to files such as C:\test\example.txt. +> For performance reasons, should be granted only to directories, not to files. For example, permission should be granted to paths such as C:\test and C:\test\\, not to files such as C:\test\example.txt. This property sets access for a single file or directory. Use additional attributes to specify additional files and directories. @@ -562,7 +562,7 @@ , , , and properties for a single file or directory. Use additional attributes to specify additional files and directories. The access rights are for file data only; they do not include the access control properties and . + This property sets the , , , and properties for a single file or directory. Use additional attributes to specify additional files and directories. The access rights are for file data only; they do not include the access control properties and . > [!NOTE] > The `get` accessor is provided for C# compiler compatibility. The C# compiler requires attribute properties to be read/write. diff --git a/xml/System.Security.Permissions/GacIdentityPermission.xml b/xml/System.Security.Permissions/GacIdentityPermission.xml index ddc2e5ea8ea..43c0fb6acfb 100644 --- a/xml/System.Security.Permissions/GacIdentityPermission.xml +++ b/xml/System.Security.Permissions/GacIdentityPermission.xml @@ -242,7 +242,7 @@ method creates a from an XML encoding defined by a object. Use the method to XML-encode the , including state information. + The method creates a from an XML encoding defined by a object. Use the method to XML-encode the , including state information. ]]> @@ -298,7 +298,7 @@ ## Remarks The intersection of two permissions is a permission that describes the set of operations they both describe in common. Only a demand that passes both original permissions will pass the intersection. - A only supports set operations (the , , and methods) when the current permission is equal to the specified permission. + A only supports set operations (the , , and methods) when the current permission is equal to the specified permission. ]]> @@ -349,7 +349,7 @@ ## Remarks The current permission is a subset of the specified permission if the current permission represents a set of operations that is wholly contained by the specified permission. If this method returns `true`, the current permission represents no more access to the protected resource than does the specified permission. - A only supports set operations (the , , and methods) when the current permission is equal to the specified permission. + A only supports set operations (the , , and methods) when the current permission is equal to the specified permission. ]]> @@ -394,7 +394,7 @@ method to create a from a . + Use the method to create a from a . ]]> @@ -440,9 +440,9 @@ method is a permission that includes all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. + The result of a call to the method is a permission that includes all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. - A only supports set operations (the , , and methods) when the current permission is equal to the specified permission. + A only supports set operations (the , , and methods) when the current permission is equal to the specified permission. ]]> diff --git a/xml/System.Security.Permissions/HostProtectionAttribute.xml b/xml/System.Security.Permissions/HostProtectionAttribute.xml index 8379870c08d..fbf42eef1be 100644 --- a/xml/System.Security.Permissions/HostProtectionAttribute.xml +++ b/xml/System.Security.Permissions/HostProtectionAttribute.xml @@ -577,7 +577,7 @@ is `true`, it indicates that a state is exposed that might be shared between threads. + When is `true`, it indicates that a state is exposed that might be shared between threads. ]]> diff --git a/xml/System.Security.Permissions/IsolatedStorageFilePermission.xml b/xml/System.Security.Permissions/IsolatedStorageFilePermission.xml index 07ebdd421a1..e828068ca16 100644 --- a/xml/System.Security.Permissions/IsolatedStorageFilePermission.xml +++ b/xml/System.Security.Permissions/IsolatedStorageFilePermission.xml @@ -50,19 +50,19 @@ Specifies the allowed usage of a private virtual file system. This class cannot be inherited. - [!NOTE] -> There is no effect if you use , , or to add stack modifiers for usage or quota. Usage and quota are determined from evidence and a stack walk is not performed for demands, making the above operations ineffective. - +> There is no effect if you use , , or to add stack modifiers for usage or quota. Usage and quota are determined from evidence and a stack walk is not performed for demands, making the above operations ineffective. + ]]> @@ -105,11 +105,11 @@ One of the values. Initializes a new instance of the class with either fully restricted or unrestricted permission as specified. - The parameter is not a valid value of . @@ -150,11 +150,11 @@ Creates and returns an identical copy of the current permission. A copy of the current permission. - @@ -197,11 +197,11 @@ Creates and returns a permission that is the intersection of the current permission and the specified permission. A new permission that represents the intersection of the current permission and the specified permission. This new permission is if the intersection is empty. - The parameter is not and is not of the same type as the current permission. @@ -246,11 +246,11 @@ if the current permission is a subset of the specified permission; otherwise, . - The parameter is not and is not of the same type as the current permission. @@ -296,11 +296,11 @@ Creates an XML encoding of the permission and its current state. An XML encoding of the permission, including any state information. - method enables the to be XML-encoded for security purposes. - + method enables the to be XML-encoded for security purposes. + ]]> @@ -343,11 +343,11 @@ Creates a permission that is the union of the current permission and the specified permission. A new permission that represents the union of the current permission and the specified permission. - is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. - + is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. + ]]> The parameter is not and is not of the same type as the current permission. diff --git a/xml/System.Security.Permissions/KeyContainerPermission.xml b/xml/System.Security.Permissions/KeyContainerPermission.xml index ae384ebca30..4ed20b8f1d4 100644 --- a/xml/System.Security.Permissions/KeyContainerPermission.xml +++ b/xml/System.Security.Permissions/KeyContainerPermission.xml @@ -365,7 +365,7 @@ method reconstructs a object from an XML encoding defined by the class. Use the method to XML-encode the , including state information. + The method reconstructs a object from an XML encoding defined by the class. Use the method to XML-encode the , including state information. ]]> @@ -560,7 +560,7 @@ method to restore the state information from a . + Use the method to restore the state information from a . ]]> @@ -606,7 +606,7 @@ is a permission that represents all operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. + The result of a call to is a permission that represents all operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. ]]> diff --git a/xml/System.Security.Permissions/KeyContainerPermissionAccessEntry.xml b/xml/System.Security.Permissions/KeyContainerPermissionAccessEntry.xml index 182f9bbc627..47a1bf4164e 100644 --- a/xml/System.Security.Permissions/KeyContainerPermissionAccessEntry.xml +++ b/xml/System.Security.Permissions/KeyContainerPermissionAccessEntry.xml @@ -255,7 +255,7 @@ method compares the properties of the two objects to determine if they are equal. + The method compares the properties of the two objects to determine if they are equal. ]]> diff --git a/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryCollection.xml b/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryCollection.xml index c79fdff744b..dfa80b701e2 100644 --- a/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryCollection.xml +++ b/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryCollection.xml @@ -367,12 +367,12 @@ Use the property of the enumerator to get the item currently pointed to in the collection. - Use the method of the enumerator to move to the next item in the collection. + Use the method of the enumerator to move to the next item in the collection. - Use the method of the enumerator to move to the initial position. + Use the method of the enumerator to move to the initial position. > [!NOTE] -> After you create a object or use the method to move the enumerator to the first item in the collection, you must call the method. Otherwise, the item represented by the property is undefined. +> After you create a object or use the method to move the enumerator to the first item in the collection, you must call the method. Otherwise, the item represented by the property is undefined. ]]> @@ -563,7 +563,7 @@ method. + When you remove an item from the collection, the index values change for subsequent items in the collection. All information about the removed item is deleted. Use this method when you want to remove a specific item by specifying the actual item to remove. To remove all items from the list, use the method. ]]> diff --git a/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryEnumerator.xml b/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryEnumerator.xml index 626d11f5850..faf5b2aeba0 100644 --- a/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryEnumerator.xml +++ b/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryEnumerator.xml @@ -61,13 +61,13 @@ Enumerators allow only reading the data in the collection. Enumerators cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. The method also brings the enumerator back to this position. At this position, calling the property throws an exception. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. + Initially, the enumerator is positioned before the first element in the collection. The method also brings the enumerator back to this position. At this position, calling the property throws an exception. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. - returns the same object until either or is called. sets to the next element. + returns the same object until either or is called. sets to the next element. - After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling returns `false`. If the last call to returned `false`, calling throws an exception. To reset to the first element of the collection, call followed by a call to . + After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling returns `false`. If the last call to returned `false`, calling throws an exception. To reset to the first element of the collection, call followed by a call to . - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . If the collection is modified between calling and , returns the element to which it is currently set, even if the enumerator is already invalidated. + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . If the collection is modified between calling and , returns the element to which it is currently set, even if the enumerator is already invalidated. The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. @@ -139,9 +139,9 @@ property is not valid and will throw an exception if it is accessed. You must first call the method to position the cursor at the first object in the collection. + When the enumerator is created, it does not point to an object, so the property is not valid and will throw an exception if it is accessed. You must first call the method to position the cursor at the first object in the collection. - Getting the property multiple times with no intervening calls to will return the same object each time. + Getting the property multiple times with no intervening calls to will return the same object each time. ]]> @@ -193,11 +193,11 @@ method returns `false` immediately if there are no objects in the collection. + The method returns `false` immediately if there are no objects in the collection. - returns `true` until it has reached the end of the collection. It then returns `false` for each successive call. However, once has returned `false`, accessing the property throws an exception. + returns `true` until it has reached the end of the collection. It then returns `false` for each successive call. However, once has returned `false`, accessing the property throws an exception. - Upon creation, an enumerator is positioned before the first object in the collection, and the first call to positions the enumerator to the first object in the collection. + Upon creation, an enumerator is positioned before the first object in the collection, and the first call to positions the enumerator to the first object in the collection. ]]> @@ -244,7 +244,7 @@ ## Remarks An enumerator moves in a forward-only direction. Use this method to return to the beginning of the collection. - The method positions the cursor at the first object in the collection. After calling , you do not need to call to move the cursor forward to the first object. + The method positions the cursor at the first object in the collection. After calling , you do not need to call to move the cursor forward to the first object. ]]> diff --git a/xml/System.Security.Permissions/PermissionSetAttribute.xml b/xml/System.Security.Permissions/PermissionSetAttribute.xml index e416b3c60c9..7693ddde6a2 100644 --- a/xml/System.Security.Permissions/PermissionSetAttribute.xml +++ b/xml/System.Security.Permissions/PermissionSetAttribute.xml @@ -60,7 +60,7 @@ [!INCLUDE[cas-deprecated](~/includes/cas-deprecated.md)] - The properties , , and are mutually exclusive, meaning that a permission set can have as its source only one of the following: a named permission set, a file containing an XML representation of a permission set, or a string containing an XML representation of a permission set. + The properties , , and are mutually exclusive, meaning that a permission set can have as its source only one of the following: a named permission set, a file containing an XML representation of a permission set, or a string containing an XML representation of a permission set. The scope of the declaration that is allowed depends on the that is used. A performed on a is the equivalent of performing that action on each of the permissions within the set. @@ -366,7 +366,7 @@ ## Remarks If this property is not set, the file is assumed to be ASCII. - If is `null` this property is not used. + If is `null` this property is not used. ]]> diff --git a/xml/System.Security.Permissions/PrincipalPermission.xml b/xml/System.Security.Permissions/PrincipalPermission.xml index 3db5964a1a2..5ee98ed2f28 100644 --- a/xml/System.Security.Permissions/PrincipalPermission.xml +++ b/xml/System.Security.Permissions/PrincipalPermission.xml @@ -71,7 +71,7 @@ To match the active and associated , both the specified identity and role must match. If `null` identity string is used, it is interpreted as a request to match any identity. Use of `null` role string will match any role. By implication, passing `null` parameter for `name` or `role` to will match the identity and roles in any . It is also possible to construct a that only determines whether the represents an authenticated or unauthenticated entity. In this case, `name` and `role` are ignored. - Unlike most other permissions, does not extend . It does, however, implement the interface. This is because is not a code access permission; that is, it is not granted based on the identity of the executing assembly. Instead, it allows code to perform actions (, , , and so on) against the current user identity in a manner consistent with the way those actions are performed for code access and code identity permissions. + Unlike most other permissions, does not extend . It does, however, implement the interface. This is because is not a code access permission; that is, it is not granted based on the identity of the executing assembly. Instead, it allows code to perform actions (, , , and so on) against the current user identity in a manner consistent with the way those actions are performed for code access and code identity permissions. > [!IMPORTANT] > Prior to a demand for principal permission it is necessary to set the current application domain's principal policy to the enumeration value . By default, the principal policy is set to . If you do not set the principal policy to , a demand for principal permission will fail. The following code should be executed before the principal permission is demanded: @@ -130,7 +130,7 @@ is the empty string (""), no , is `false`). `Unrestricted` matches all principals ( is `null`, is `null`). + `None` matches only the unauthenticated principal ( is the empty string (""), no , is `false`). `Unrestricted` matches all principals ( is `null`, is `null`). > [!NOTE] > This constructor is included for consistency with the design of other permissions, but is not useful in practice. @@ -326,12 +326,12 @@ is raised, succeeds. + If no is raised, succeeds. This method acts against the principal attached to the calling thread. > [!IMPORTANT] -> Prior to calling the method, it is necessary to set the current application domain's principal policy to the enumeration value . By default the principal policy is set to . If you do not set the principal policy to , a demand for principal permission will fail. The following code should be executed before the demand for principal permission occurs: +> Prior to calling the method, it is necessary to set the current application domain's principal policy to the enumeration value . By default the principal policy is set to . If you do not set the principal policy to , a demand for principal permission will fail. The following code should be executed before the demand for principal permission occurs: > > `AppDomain.CurrentDomain.SetPrincipalPolicy(PrincipalPolicy.WindowsPrincipal).` @@ -398,7 +398,7 @@ . + For more information, see . ]]> diff --git a/xml/System.Security.Permissions/PrincipalPermissionAttribute.xml b/xml/System.Security.Permissions/PrincipalPermissionAttribute.xml index 91205d4226e..659bb516868 100644 --- a/xml/System.Security.Permissions/PrincipalPermissionAttribute.xml +++ b/xml/System.Security.Permissions/PrincipalPermissionAttribute.xml @@ -60,7 +60,7 @@ [!INCLUDE[cas-deprecated](~/includes/cas-deprecated.md)] - can be used to declaratively demand that users running your code belong to a specified role or have been authenticated. Use of creates a with set to `true` and and set to `null`. + can be used to declaratively demand that users running your code belong to a specified role or have been authenticated. Use of creates a with set to `true` and and set to `null`. The scope of the declaration that is allowed depends on the that is used. cannot be applied at the assembly level. @@ -244,7 +244,7 @@ is the same as the user's Windows NT login name (in the form "DomainName\UserName"). Check the documentation of your host to determine which authentication provider it uses and how it determines the identity of the current principal. + If the authentication provider is Windows NT, is the same as the user's Windows NT login name (in the form "DomainName\UserName"). Check the documentation of your host to determine which authentication provider it uses and how it determines the identity of the current principal. ]]> diff --git a/xml/System.Security.Permissions/PublisherIdentityPermission.xml b/xml/System.Security.Permissions/PublisherIdentityPermission.xml index e1f54f84d58..5ae5929b5a2 100644 --- a/xml/System.Security.Permissions/PublisherIdentityPermission.xml +++ b/xml/System.Security.Permissions/PublisherIdentityPermission.xml @@ -348,7 +348,7 @@ ## Remarks The intersection of two permissions is a permission that describes the set of operations they both describe in common. Only a demand that passes both original permissions will pass the intersection. - only supports set operations (, , and ) when the current permission is equal to the specified permission. + only supports set operations (, , and ) when the current permission is equal to the specified permission. ]]> @@ -399,7 +399,7 @@ ## Remarks The current permission is a subset of the specified permission if the two permissions are equal. If this method returns `true`, the current permission represents the same access to the protected resource as the specified permission. - supports set operations (, , and ) only when the current permission is equal to the specified permission. + supports set operations (, , and ) only when the current permission is equal to the specified permission. ]]> @@ -484,9 +484,9 @@ method is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. + The result of a call to the method is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. - The class only supports set operations (, , and ) when the current permission is equal to the specified permission. + The class only supports set operations (, , and ) when the current permission is equal to the specified permission. ]]> diff --git a/xml/System.Security.Permissions/PublisherIdentityPermissionAttribute.xml b/xml/System.Security.Permissions/PublisherIdentityPermissionAttribute.xml index 28578ca0866..0c82345f3bb 100644 --- a/xml/System.Security.Permissions/PublisherIdentityPermissionAttribute.xml +++ b/xml/System.Security.Permissions/PublisherIdentityPermissionAttribute.xml @@ -54,26 +54,26 @@ Allows security actions for to be applied to code using declarative security. This class cannot be inherited. - that is used. - - The properties , , and are mutually exclusive. - - The security information declared by a security attribute is stored in the metadata of the attribute target and is accessed by the system at run time. Security attributes are used only for declarative security. For imperative security, use the corresponding permission class. - + The scope of the declaration that is allowed depends on the that is used. + + The properties , , and are mutually exclusive. + + The security information declared by a security attribute is stored in the metadata of the attribute target and is accessed by the system at run time. Security attributes are used only for declarative security. For imperative security, use the corresponding permission class. + > [!IMPORTANT] -> Starting with the .NET Framework 4, identity permissions are not used. -> -> In the .NET Framework versions 1.0 and 1.1, identity permissions cannot have an permission state value. Starting with the .NET Framework version 2.0, identity permissions can have any permission state value. This means that in 2.0 and later versions, identity permissions have the same behavior as permissions that implement the interface. - +> Starting with the .NET Framework 4, identity permissions are not used. +> +> In the .NET Framework versions 1.0 and 1.1, identity permissions cannot have an permission state value. Starting with the .NET Framework version 2.0, identity permissions can have any permission state value. This means that in 2.0 and later versions, identity permissions have the same behavior as permissions that implement the interface. + > [!NOTE] -> By default, code access security does not check for evidence. Unless your computer has a custom code group based on the class, you can improve performance by bypassing Authenticode signature verification. This is accomplished by configuring the runtime to not provide evidence for code access security. For more information about how to configure this option and which applications can use it, see the [<generatePublisherEvidence>](/dotnet/framework/configure-apps/file-schema/runtime/generatepublisherevidence-element) element. - +> By default, code access security does not check for evidence. Unless your computer has a custom code group based on the class, you can improve performance by bypassing Authenticode signature verification. This is accomplished by configuring the runtime to not provide evidence for code access security. For more information about how to configure this option and which applications can use it, see the [<generatePublisherEvidence>](/dotnet/framework/configure-apps/file-schema/runtime/generatepublisherevidence-element) element. + ]]> Extending Metadata Using Attributes @@ -149,11 +149,11 @@ Gets or sets a certification file containing an Authenticode X.509v3 certificate. The file path of an X.509 certificate file (usually has the extension.cer). - is set, this property is ignored. - + is set, this property is ignored. + ]]> @@ -199,13 +199,13 @@ Creates and returns a new instance of . A that corresponds to this attribute. - @@ -244,11 +244,11 @@ Gets or sets a signed file from which to extract an Authenticode X.509v3 certificate. The file path of a file signed with the Authenticode signature. - or is set, this property is ignored. - + or is set, this property is ignored. + ]]> @@ -287,13 +287,13 @@ Gets or sets an Authenticode X.509v3 certificate that identifies the publisher of the calling code. A hexadecimal representation of the X.509 certificate. - and are ignored. - - You can obtain the hexadecimal representation by running the Strong Name tool (Sn.exe) with the token and public key options (**Sn** **-tp** *keyfile*`)` against a file that has an Authenticode signature. For more information, see [Sn.exe (Strong Name Tool)](/dotnet/framework/tools/sn-exe-strong-name-tool). - + and are ignored. + + You can obtain the hexadecimal representation by running the Strong Name tool (Sn.exe) with the token and public key options (**Sn** **-tp** *keyfile*`)` against a file that has an Authenticode signature. For more information, see [Sn.exe (Strong Name Tool)](/dotnet/framework/tools/sn-exe-strong-name-tool). + ]]> diff --git a/xml/System.Security.Permissions/ReflectionPermission.xml b/xml/System.Security.Permissions/ReflectionPermission.xml index 95e728c05fa..a0dacbe5eb0 100644 --- a/xml/System.Security.Permissions/ReflectionPermission.xml +++ b/xml/System.Security.Permissions/ReflectionPermission.xml @@ -517,7 +517,7 @@ is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. + The result of a call to is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. ]]> diff --git a/xml/System.Security.Permissions/RegistryPermission.xml b/xml/System.Security.Permissions/RegistryPermission.xml index 6b91b428532..29c29aa210a 100644 --- a/xml/System.Security.Permissions/RegistryPermission.xml +++ b/xml/System.Security.Permissions/RegistryPermission.xml @@ -67,7 +67,7 @@ Registry permission is defined in terms of canonical absolute paths; checks should always be made with canonical pathnames. Key access implies access to all values it contains and all variables under it. > [!NOTE] -> In versions of .NET Framework before .NET Framework 4, you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](/dotnet/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox). +> In versions of .NET Framework before .NET Framework 4, you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](/dotnet/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox). ]]> @@ -174,7 +174,7 @@ values to be specified. This access applies to all listed registry variables. Use to define more complicated permissions. + This constructor allows only one of the values to be specified. This access applies to all listed registry variables. Use to define more complicated permissions. ]]> @@ -231,7 +231,7 @@ values to be specified. This access applies to all listed registry variables. Use to define more complicated permissions. + This constructor allows only one of the values to be specified. This access applies to all listed registry variables. Use to define more complicated permissions. The `control` parameter specifies whether the access control list (ACL) for the registry keys specified by `pathList` can be changed, viewed, or cannot be accessed. @@ -866,7 +866,7 @@ is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. + The result of a call to is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. ]]> diff --git a/xml/System.Security.Permissions/RegistryPermissionAccess.xml b/xml/System.Security.Permissions/RegistryPermissionAccess.xml index e359361c359..1aa7960552a 100644 --- a/xml/System.Security.Permissions/RegistryPermissionAccess.xml +++ b/xml/System.Security.Permissions/RegistryPermissionAccess.xml @@ -53,17 +53,17 @@ Specifies the permitted access to registry keys and values. - values are independent; rights to one type of access do not imply rights to another. For instance, `Write` permission does not imply permission to `Read` or `Create`. - + values are independent; rights to one type of access do not imply rights to another. For instance, `Write` permission does not imply permission to `Read` or `Create`. + > [!NOTE] -> Although `NoAccess` and `AllAccess` appear in `RegistryPermissionAccess`, they are not valid for use as the parameter for because they describe no registry variable access types or all registry variable access types, respectively, and expects a single registry variable access type. - +> Although `NoAccess` and `AllAccess` appear in `RegistryPermissionAccess`, they are not valid for use as the parameter for because they describe no registry variable access types or all registry variable access types, respectively, and expects a single registry variable access type. + ]]> diff --git a/xml/System.Security.Permissions/RegistryPermissionAttribute.xml b/xml/System.Security.Permissions/RegistryPermissionAttribute.xml index 33c030b44e0..e40bbd9620f 100644 --- a/xml/System.Security.Permissions/RegistryPermissionAttribute.xml +++ b/xml/System.Security.Permissions/RegistryPermissionAttribute.xml @@ -54,16 +54,16 @@ Allows security actions for to be applied to code using declarative security. This class cannot be inherited. - that is used. - - The security information declared by a security attribute is stored in the metadata of the attribute target and is accessed by the system at run time. Security attributes are used only for declarative security. For imperative security, use the corresponding permission class. - + The scope of the declaration that is allowed depends on the that is used. + + The security information declared by a security attribute is stored in the metadata of the attribute target and is accessed by the system at run time. Security attributes are used only for declarative security. For imperative security, use the corresponding permission class. + ]]> @@ -156,11 +156,11 @@ Gets or sets full access for the specified registry keys. A semicolon-separated list of registry key paths, for full access. - The get accessor is called; it is only provided for C# compiler compatibility. @@ -199,14 +199,14 @@ Gets or sets change access control for the specified registry keys. A semicolon-separated list of registry key paths, for change access control. . - [!IMPORTANT] -> An access control list (ACL) describes individuals or groups who have, or do not have, rights to specific actions for the given registry keys. The ability to change an ACL is an important permission and should be granted with caution. - +> An access control list (ACL) describes individuals or groups who have, or do not have, rights to specific actions for the given registry keys. The ability to change an ACL is an important permission and should be granted with caution. + ]]> @@ -245,11 +245,11 @@ Gets or sets create-level access for the specified registry keys. A semicolon-separated list of registry key paths, for create-level access. - @@ -295,13 +295,13 @@ Creates and returns a new . A that corresponds to this attribute. - @@ -340,11 +340,11 @@ Gets or sets read access for the specified registry keys. A semicolon-separated list of registry key paths, for read access. - @@ -382,14 +382,14 @@ Gets or sets view access control for the specified registry keys. A semicolon-separated list of registry key paths, for view access control. - [!IMPORTANT] -> An access control list (ACL) describes individuals or groups who have, or do not have, rights to specific actions for the given registry keys. The ability to view an ACL is an important permission and should be granted with caution. - +> An access control list (ACL) describes individuals or groups who have, or do not have, rights to specific actions for the given registry keys. The ability to view an ACL is an important permission and should be granted with caution. + ]]> @@ -427,16 +427,16 @@ Gets or sets a specified set of registry keys that can be viewed and modified. A semicolon-separated list of registry key paths, for create, read, and write access. - , , and access rights for the specified keys and their values. The access rights are for registry data only; they do not include the access control rights or . - + , , and access rights for the specified keys and their values. The access rights are for registry data only; they do not include the access control rights or . + > [!NOTE] -> The get accessor is provided for C# compiler compatibility. The C# compiler requires attribute properties to be read/write. - +> The get accessor is provided for C# compiler compatibility. The C# compiler requires attribute properties to be read/write. + ]]> The get accessor is called; it is only provided for C# compiler compatibility. @@ -476,11 +476,11 @@ Gets or sets write access for the specified registry keys. A semicolon-separated list of registry key paths, for write access. - diff --git a/xml/System.Security.Permissions/ResourcePermissionBase.xml b/xml/System.Security.Permissions/ResourcePermissionBase.xml index e06f4299926..7143ba7b131 100644 --- a/xml/System.Security.Permissions/ResourcePermissionBase.xml +++ b/xml/System.Security.Permissions/ResourcePermissionBase.xml @@ -386,7 +386,7 @@ and to add and remove permission entries to this permission. + Use and to add and remove permission entries to this permission. ]]> @@ -792,7 +792,7 @@ is a permission that represents all the operations represented by both the current permission object and the specified permission object. Any demand that passes either permission passes their union. + The result of a call to is a permission that represents all the operations represented by both the current permission object and the specified permission object. Any demand that passes either permission passes their union. ]]> diff --git a/xml/System.Security.Permissions/ResourcePermissionBaseEntry.xml b/xml/System.Security.Permissions/ResourcePermissionBaseEntry.xml index 203bb73d2ad..8988684a896 100644 --- a/xml/System.Security.Permissions/ResourcePermissionBaseEntry.xml +++ b/xml/System.Security.Permissions/ResourcePermissionBaseEntry.xml @@ -223,7 +223,7 @@ has two properties, and . The for returns + "\\\\" + . For example, "myMachine\\\myCategory". + has two properties, and . The for returns + "\\\\" + . For example, "myMachine\\\myCategory". ]]> diff --git a/xml/System.Security.Permissions/SecurityPermission.xml b/xml/System.Security.Permissions/SecurityPermission.xml index ac3e4eca31a..92ed75b502f 100644 --- a/xml/System.Security.Permissions/SecurityPermission.xml +++ b/xml/System.Security.Permissions/SecurityPermission.xml @@ -515,7 +515,7 @@ is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. + The result of a call to is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. ]]> diff --git a/xml/System.Security.Permissions/SiteIdentityPermission.xml b/xml/System.Security.Permissions/SiteIdentityPermission.xml index d3469b6608d..396f854c3ed 100644 --- a/xml/System.Security.Permissions/SiteIdentityPermission.xml +++ b/xml/System.Security.Permissions/SiteIdentityPermission.xml @@ -50,27 +50,27 @@ Defines the identity permission for the Web site from which the code originates. This class cannot be inherited. - [!IMPORTANT] -> Starting with the .NET Framework 4, identity permissions are not used. -> -> In the .NET Framework versions 1.0 and 1.1, demands on the identity permissions are effective, even when the calling assembly is fully trusted. That is, although the calling assembly has full trust, a demand for an identity permission fails if the assembly does not meet the demanded criteria. Starting with the .NET Framework version 2.0, demands for identity permissions are ineffective if the calling assembly has full trust. This assures consistency for all permissions, eliminating the treatment of identity permissions as a special case. - +> Starting with the .NET Framework 4, identity permissions are not used. +> +> In the .NET Framework versions 1.0 and 1.1, demands on the identity permissions are effective, even when the calling assembly is fully trusted. That is, although the calling assembly has full trust, a demand for an identity permission fails if the assembly does not meet the demanded criteria. Starting with the .NET Framework version 2.0, demands for identity permissions are ineffective if the calling assembly has full trust. This assures consistency for all permissions, eliminating the treatment of identity permissions as a special case. + > [!NOTE] -> In versions of the .NET Framework before the .NET Framework 4, you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](/dotnet/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox). - +> In versions of the .NET Framework before the .NET Framework 4, you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](/dotnet/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox). + > [!NOTE] -> In the .NET Framework versions 1.0 and 1.1, identity permissions cannot have an permission state value. Starting with the .NET Framework version 2.0, identity permissions can have any permission state value. This means that in 2.0 and later versions, identity permissions have the same behavior as permissions that implement the interface. - +> In the .NET Framework versions 1.0 and 1.1, identity permissions cannot have an permission state value. Starting with the .NET Framework version 2.0, identity permissions can have any permission state value. This means that in 2.0 and later versions, identity permissions have the same behavior as permissions that implement the interface. + ]]> @@ -122,16 +122,16 @@ One of the values. Initializes a new instance of the class with the specified . - matches no sites. This constructor is included for consistency with the design of other permissions, but is not useful in practice. - + matches no sites. This constructor is included for consistency with the design of other permissions, but is not useful in practice. + > [!NOTE] -> In the .NET Framework versions 1.0 and 1.1, identity permissions cannot have an permission state value. Starting with the .NET Framework version 2.0, identity permissions can have any permission state value. This means that in 2.0 and later versions, identity permissions have the same behavior as permissions that implement the interface. That is, a demand for an identity always succeeds, regardless of the identity of the assembly, if the assembly has been granted full trust. - - In the .NET Framework versions 1.0 and 1.1, demands on the identity permissions are effective, even when the calling assembly is fully trusted. That is, although the calling assembly has full trust, a demand for an identity permission fails if the assembly does not meet the demanded criteria. Starting with the .NET Framework version 2.0, demands for identity permissions are ineffective if the calling assembly has full trust. This assures consistency for all permissions, eliminating the treatment of identity permissions as a special case. - +> In the .NET Framework versions 1.0 and 1.1, identity permissions cannot have an permission state value. Starting with the .NET Framework version 2.0, identity permissions can have any permission state value. This means that in 2.0 and later versions, identity permissions have the same behavior as permissions that implement the interface. That is, a demand for an identity always succeeds, regardless of the identity of the assembly, if the assembly has been granted full trust. + + In the .NET Framework versions 1.0 and 1.1, demands on the identity permissions are effective, even when the calling assembly is fully trusted. That is, although the calling assembly has full trust, a demand for an identity permission fails if the assembly does not meet the demanded criteria. Starting with the .NET Framework version 2.0, demands for identity permissions are ineffective if the calling assembly has full trust. This assures consistency for all permissions, eliminating the treatment of identity permissions as a special case. + ]]> The parameter is not a valid value of . @@ -171,13 +171,13 @@ The site name or wildcard expression. Initializes a new instance of the class to represent the specified site identity. - The parameter is not a valid string, or does not match a valid wildcard site name. @@ -218,11 +218,11 @@ Creates and returns an identical copy of the current permission. A copy of the current permission. - @@ -265,10 +265,10 @@ Reconstructs a permission with a specified state from an XML encoding. To be added. The parameter is . - The parameter is not a valid permission element. - - -or- - + The parameter is not a valid permission element. + + -or- + The parameter's version number is not valid. @@ -310,13 +310,13 @@ Creates and returns a permission that is the intersection of the current permission and the specified permission. A new permission that represents the intersection of the current permission and the specified permission. This new permission is if the intersection is empty. - The parameter is not and is not of the same type as the current permission. @@ -361,25 +361,25 @@ if the current permission is a subset of the specified permission; otherwise, . - for a range of values of the current permission and the specified permission. - -|Current Permission|Specified Permission|IsSubsetOf| -|------------------------|--------------------------|----------------| -|`www.fourthcoffee.com`|`www.fourthcoffee.com`|`true`| -|`www.fourthcoffee.com`|`www.tailspintoys.com`|`false`| -|`www.fourthcoffee.com`|`*.fourthcoffee.com`|`true`| -|`www.fourthcoffee.com`|`*.com`|`true`| -|`*.fourthcoffee.com`|`www.fourthcoffee.com`|`false`| -|`*.fourthcoffee.com`|`*.fourthcoffee.com`|`true`| -|`*.fourthcoffee.com`|`*.com`|`true`| -|Anything except `None`|`*`|`true`| -|`None`|Anything|`true`| - + for a range of values of the current permission and the specified permission. + +|Current Permission|Specified Permission|IsSubsetOf| +|------------------------|--------------------------|----------------| +|`www.fourthcoffee.com`|`www.fourthcoffee.com`|`true`| +|`www.fourthcoffee.com`|`www.tailspintoys.com`|`false`| +|`www.fourthcoffee.com`|`*.fourthcoffee.com`|`true`| +|`www.fourthcoffee.com`|`*.com`|`true`| +|`*.fourthcoffee.com`|`www.fourthcoffee.com`|`false`| +|`*.fourthcoffee.com`|`*.fourthcoffee.com`|`true`| +|`*.fourthcoffee.com`|`*.com`|`true`| +|Anything except `None`|`*`|`true`| +|`None`|Anything|`true`| + ]]> The parameter is not and is not of the same type as the current permission. @@ -419,13 +419,13 @@ Gets or sets the current site. The current site. - The site identity cannot be retrieved because it has an ambiguous identity. @@ -506,19 +506,19 @@ Creates a permission that is the union of the current permission and the specified permission. A new permission that represents the union of the current permission and the specified permission. - is a permission that represents all the sites represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. For example, the union of a permission that represents access to `www.fourthcoffee.com` and one that represents access to `*.fourthcoffee.com` is a permission that represents access to `*.fourthcoffee.com`. - - The union of a permission and `null` is the permission that is not `null`. The union of a permission and a subset of that permission is the permission that contains the subset. Any other combination results in an being thrown. For example, the union of the site identity `www.fourthcoffee.com` and the site identity `www.tailspintoys.com` results in an exception because neither is a subset of the other. - + is a permission that represents all the sites represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. For example, the union of a permission that represents access to `www.fourthcoffee.com` and one that represents access to `*.fourthcoffee.com` is a permission that represents access to `*.fourthcoffee.com`. + + The union of a permission and `null` is the permission that is not `null`. The union of a permission and a subset of that permission is the permission that contains the subset. Any other combination results in an being thrown. For example, the union of the site identity `www.fourthcoffee.com` and the site identity `www.tailspintoys.com` results in an exception because neither is a subset of the other. + ]]> - The parameter is not and is not of the same type as the current permission. - - -or- - + The parameter is not and is not of the same type as the current permission. + + -or- + The permissions are not equal and one is not a subset of the other. diff --git a/xml/System.Security.Permissions/StorePermission.xml b/xml/System.Security.Permissions/StorePermission.xml index ede523526b0..f57ead23948 100644 --- a/xml/System.Security.Permissions/StorePermission.xml +++ b/xml/System.Security.Permissions/StorePermission.xml @@ -285,7 +285,7 @@ method reconstructs a object from an XML encoding defined by the class. Use the method to XML-encode the , including state information. + The method reconstructs a object from an XML encoding defined by the class. Use the method to XML-encode the , including state information. ]]> @@ -476,7 +476,7 @@ method to restore the state information from a . + Use the method to restore the state information from a . ]]> @@ -521,7 +521,7 @@ is a permission that represents all operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. + The result of a call to is a permission that represents all operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. ]]> diff --git a/xml/System.Security.Permissions/StorePermissionAttribute.xml b/xml/System.Security.Permissions/StorePermissionAttribute.xml index dfec06c1ab3..105b7b84a8b 100644 --- a/xml/System.Security.Permissions/StorePermissionAttribute.xml +++ b/xml/System.Security.Permissions/StorePermissionAttribute.xml @@ -48,16 +48,16 @@ Allows security actions for to be applied to code using declarative security. This class cannot be inherited. - value that is used. - - The security information declared by a security attribute is stored in the metadata of the attribute target and is accessed by the system at run time. The attribute is used only for declarative security. For imperative security, use the class. - + The scope of the declaration that is allowed depends on the value that is used. + + The security information declared by a security attribute is stored in the metadata of the attribute target and is accessed by the system at run time. The attribute is used only for declarative security. For imperative security, use the class. + ]]> @@ -138,11 +138,11 @@ if the ability to add to a store is allowed; otherwise, . - @@ -180,13 +180,13 @@ Creates and returns a new . A that corresponds to the attribute. - @@ -224,11 +224,11 @@ if the ability to create a store is allowed; otherwise, . - method. - + method. + ]]> @@ -266,11 +266,11 @@ if the ability to delete a store is allowed; otherwise, . - class. - + class. + ]]> @@ -308,11 +308,11 @@ if the ability to enumerate certificates is allowed; otherwise, . - @@ -350,11 +350,11 @@ if the ability to enumerate stores is allowed; otherwise, . - class. - + class. + ]]> @@ -397,15 +397,15 @@ Gets or sets the store permissions. A bitwise combination of the values. The default is . - [!CAUTION] -> Many of these flags are powerful and permit access to stores that should be granted only to highly trusted code. - - The most powerful of the flags are , , , and . For specific threats posed by the use of these flags, see individual flag descriptions. - +> Many of these flags are powerful and permit access to stores that should be granted only to highly trusted code. + + The most powerful of the flags are , , , and . For specific threats posed by the use of these flags, see individual flag descriptions. + ]]> @@ -443,11 +443,11 @@ if the ability to open a store is allowed; otherwise, . - @@ -485,11 +485,11 @@ if the ability to remove a certificate from a store is allowed; otherwise, . - diff --git a/xml/System.Security.Permissions/StrongNameIdentityPermission.xml b/xml/System.Security.Permissions/StrongNameIdentityPermission.xml index d73e0fb3145..f31b9c80640 100644 --- a/xml/System.Security.Permissions/StrongNameIdentityPermission.xml +++ b/xml/System.Security.Permissions/StrongNameIdentityPermission.xml @@ -137,7 +137,7 @@ In the .NET Framework versions 1.0 and 1.1, demands on the identity permissions are effective, even when the calling assembly is fully trusted. That is, although the calling assembly has full trust, a demand for an identity permission fails if the assembly does not meet the demanded criteria. In the .NET Framework version 2.0 and later, demands for identity permissions are ineffective if the calling assembly has full trust. This assures consistency for all permissions, eliminating the treatment of identity permissions as a special case. - Use this constructor with a permission state value of to create an identity permission that matches no strong names. If you subsequently set the and properties, a specific strong name identity can be represented by the permission. + Use this constructor with a permission state value of to create an identity permission that matches no strong names. If you subsequently set the and properties, a specific strong name identity can be represented by the permission. ]]> @@ -558,7 +558,7 @@ is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. + The result of a call to is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. The union of a permission and `null` is the permission that is not `null`. The union of a permission and a subset of that permission is the permission that contains the other. Any other combination results in an exception being thrown. diff --git a/xml/System.Security.Permissions/TypeDescriptorPermission.xml b/xml/System.Security.Permissions/TypeDescriptorPermission.xml index b7fffa50116..d7aa021784c 100644 --- a/xml/System.Security.Permissions/TypeDescriptorPermission.xml +++ b/xml/System.Security.Permissions/TypeDescriptorPermission.xml @@ -48,22 +48,22 @@ Defines partial-trust access to the class. - class defines access to the following methods on the class. - -- - -- - -- - -- - + The class defines access to the following methods on the class. + +- + +- + +- + +- + ]]> diff --git a/xml/System.Security.Permissions/UIPermission.xml b/xml/System.Security.Permissions/UIPermission.xml index cad4fdba35e..5236d35b219 100644 --- a/xml/System.Security.Permissions/UIPermission.xml +++ b/xml/System.Security.Permissions/UIPermission.xml @@ -473,7 +473,7 @@ to return `true`, both the and values of the current permission must be equal to or less permissive than the values of the specified permission. + The current permission is a subset of the specified permission if all demands that succeed for the current permission also succeed for the specified permission. That is, the specified permission contains at least the permissions contained in the subset. For to return `true`, both the and values of the current permission must be equal to or less permissive than the values of the specified permission. ]]> @@ -606,7 +606,7 @@ is a permission that represents all the operations represented by the current permission as well as all the operations represented by the specified permission. Specifically, it represents the most permissive values of and from those in the current permission and the specified permission. + The result of a call to is a permission that represents all the operations represented by the current permission as well as all the operations represented by the specified permission. Specifically, it represents the most permissive values of and from those in the current permission and the specified permission. ]]> diff --git a/xml/System.Security.Permissions/UIPermissionWindow.xml b/xml/System.Security.Permissions/UIPermissionWindow.xml index 1a2d416b388..73f2949a65a 100644 --- a/xml/System.Security.Permissions/UIPermissionWindow.xml +++ b/xml/System.Security.Permissions/UIPermissionWindow.xml @@ -73,7 +73,7 @@ When an application runs under the `SafeTopLevelWindows` permission, it: - Cannot use the property to make its windows less than 50% transparent. -- Must use only rectangular windows, and must include the window frame. Windows Forms will not honor setting to . +- Must use only rectangular windows, and must include the window frame. Windows Forms will not honor setting to . - Cannot make windows invisible. Any attempt by the application to set the property to `False` will be ignored. @@ -81,7 +81,7 @@ When an application runs under the `SafeTopLevelWindows` permission, it: - Has its controls prohibited from accessing the property. By implication, controls will also be barred from accessing siblings - that is, other controls at the same level of nesting. -- Cannot control focus using the method. +- Cannot control focus using the method. - Has restricted keyboard input access, so that a form or control can only access keyboard events for itself and its children. @@ -89,7 +89,7 @@ When an application runs under the `SafeTopLevelWindows` permission, it: - Cannot set the property. -- Cannot control the z-order of controls on the form using the and methods. +- Cannot control the z-order of controls on the form using the and methods. These restrictions help prevent potentially harmful code from spoofing attacks, such as imitating trusted system dialogs. diff --git a/xml/System.Security.Permissions/UrlIdentityPermission.xml b/xml/System.Security.Permissions/UrlIdentityPermission.xml index ad91d5240e4..6571e52bd81 100644 --- a/xml/System.Security.Permissions/UrlIdentityPermission.xml +++ b/xml/System.Security.Permissions/UrlIdentityPermission.xml @@ -66,7 +66,7 @@ > In the .NET Framework versions 1.0 and 1.1, demands on the identity permissions are effective even when the calling assembly is fully trusted. That is, although the calling assembly has full trust, a demand for an identity permission fails if the assembly does not meet the demanded criteria. Starting with the .NET Framework version 2.0, demands for identity permissions are ineffective if the calling assembly has full trust. That is, a demand for an identity always succeeds, regardless of the identity of the assembly, if the assembly has been granted full trust. This assures consistency for all permissions, eliminating the treatment of identity permissions as a special case. > [!NOTE] -> In versions of the .NET Framework before the .NET Framework 4, you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](/dotnet/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox). +> In versions of the .NET Framework before the .NET Framework 4, you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](/dotnet/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox). > [!NOTE] > In the .NET Framework versions 1.0 and 1.1, identity permissions cannot have an permission state value. Starting with the .NET Framework version 2.0, identity permissions can have any permission state value. This means that in 2.0 and later versions, identity permissions have the same behavior as permissions that implement the interface. @@ -179,7 +179,7 @@ URLs can be matched exactly or by a wildcard in the final position, for example: `http://www.fourthcoffee.com/process/*`. URLs can also contain a wildcard ("\*") prefix at the dot delimiter. For example, the URL name string `http://www.fourthcoffee.com/process/grind.htm/` is a subset of `http://*.fourthcoffee.com/process/grind.htm/` and `http://*.com/process/grind.htm/`. > [!NOTE] -> Starting with the .NET Framework version 2.0, for performance reasons, an invalid URL does not cause an argument exception at the time the new class instance is created. The argument exception will occur when one of the set operations (Union, Intersect, or IsSubsetOf) is executed. A demand on the permission causes to be called by the security infrastructure. The demand will fail because of the argument exception, resulting in a being thrown. In this case, the original exception will not be seen. +> Starting with the .NET Framework version 2.0, for performance reasons, an invalid URL does not cause an argument exception at the time the new class instance is created. The argument exception will occur when one of the set operations (Union, Intersect, or IsSubsetOf) is executed. A demand on the permission causes to be called by the security infrastructure. The demand will fail because of the argument exception, resulting in a being thrown. In this case, the original exception will not be seen. ]]> @@ -320,7 +320,7 @@ ## Remarks The intersection of two permissions is a permission that describes access to the URLs they both describe in common. Only a demand that passes both original permissions will pass the intersection. For example, the intersection of a permission that represents access to `http://www.fourthcoffee.com/process/grind.htm` and a permission that represents access to `http://www.fourthcoffee.com/*` is a permission that represents access to `http://www.fourthcoffee.com/process/grind.htm`. - supports set operations (, , and ) only when the current permission is equal to the specified permission object or when one of the permissions uses the wildcard operator ("\*"). + supports set operations (, , and ) only when the current permission is equal to the specified permission object or when one of the permissions uses the wildcard operator ("\*"). ]]> @@ -375,7 +375,7 @@ ## Remarks The current permission is a subset of the specified permission if the current permission identifies access to a URL that is wholly contained by the specified permission. For example, a permission that represents access to `http://www.fourthcoffee.com/process/grind.htm` is a subset of a permission that represents access to `http://www.fourthcoffee.com/*`. If this method returns `true`, the current permission represents no more access to the protected resource than does the specified permission. - supports set operations (, , and ) only when the current permission is equal to the specified permission or when one of the permissions uses the wildcard operator ("\*"). + supports set operations (, , and ) only when the current permission is equal to the specified permission or when one of the permissions uses the wildcard operator ("\*"). ]]> @@ -464,9 +464,9 @@ method is a permission that represents access to the URL as represented by the current permission, as well as access to the URL as represented by the specified permission. + The result of a call to the method is a permission that represents access to the URL as represented by the current permission, as well as access to the URL as represented by the specified permission. - The class supports set operations , , and ) only when the current permission is equal to the specified permission, or when one of the permissions uses the wildcard operator ("\*") and one is a subset of the other. + The class supports set operations , , and ) only when the current permission is equal to the specified permission, or when one of the permissions uses the wildcard operator ("\*") and one is a subset of the other. ]]> diff --git a/xml/System.Security.Permissions/WebBrowserPermissionAttribute.xml b/xml/System.Security.Permissions/WebBrowserPermissionAttribute.xml index 5d5a27e83d2..3707dec5983 100644 --- a/xml/System.Security.Permissions/WebBrowserPermissionAttribute.xml +++ b/xml/System.Security.Permissions/WebBrowserPermissionAttribute.xml @@ -142,9 +142,9 @@ This class is not typically used in XAML. ## Remarks -The method is called by the security system, not by application code. +The method is called by the security system, not by application code. -The security information described by is stored in the metadata of the attribute target, which is the class to which is applied. The system accesses the information at run time. The system uses the returned by to convert the security information of the attribute target to a serializable form stored in metadata. +The security information described by is stored in the metadata of the attribute target, which is the class to which is applied. The system accesses the information at run time. The system uses the returned by to convert the security information of the attribute target to a serializable form stored in metadata. Members of this class are either not typically used in XAML, or cannot be used in XAML. diff --git a/xml/System.Security.Permissions/ZoneIdentityPermission.xml b/xml/System.Security.Permissions/ZoneIdentityPermission.xml index fb9788007a4..22a5d4bbc0e 100644 --- a/xml/System.Security.Permissions/ZoneIdentityPermission.xml +++ b/xml/System.Security.Permissions/ZoneIdentityPermission.xml @@ -476,7 +476,7 @@ is a permission that represents the security zone represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. The union of two identical objects is the same permission. The union of a null permission and a permission is the permission that is not null. + The result of a call to is a permission that represents the security zone represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. The union of two identical objects is the same permission. The union of a null permission and a permission is the permission that is not null. Note that a object representing a security zone is treated as a null permission and handled as a special case. The union of a object representing the security zone and a null permission is null. The union of two different zone identity permissions results in an exception being thrown when neither of the two permissions represents the security zone. diff --git a/xml/System.Security.Policy/AllMembershipCondition.xml b/xml/System.Security.Policy/AllMembershipCondition.xml index 7e63ba21f94..b604189ceb8 100644 --- a/xml/System.Security.Policy/AllMembershipCondition.xml +++ b/xml/System.Security.Policy/AllMembershipCondition.xml @@ -63,11 +63,11 @@ Represents a membership condition that matches all code. This class cannot be inherited. - @@ -145,11 +145,11 @@ Determines whether the specified evidence satisfies the membership condition. Always . - , so always returns `true`. - + , so always returns `true`. + ]]> diff --git a/xml/System.Security.Policy/ApplicationSecurityManager.xml b/xml/System.Security.Policy/ApplicationSecurityManager.xml index 5df45c87904..12fe8894305 100644 --- a/xml/System.Security.Policy/ApplicationSecurityManager.xml +++ b/xml/System.Security.Policy/ApplicationSecurityManager.xml @@ -28,7 +28,7 @@ class provides essential information for the execution of a manifest-based application. The property identifies the trust manager responsible for determining whether an application is trusted. The method calls the application trust manager to determine whether an application is trusted. The property contains the cached trust decisions for the user. + The class provides essential information for the execution of a manifest-based application. The property identifies the trust manager responsible for determining whether an application is trusted. The method calls the application trust manager to determine whether an application is trusted. The property contains the cached trust decisions for the user. ]]> @@ -106,7 +106,7 @@ uses the configured property to determine whether to allow execution of the specified application with the permission set requested in the application manifest. The trust manager's behavior is dependent on the trust manager implementation and the information passed in the `context` parameter. The default behavior of the trust manager is to establish a user interface (UI) dialog box to determine the user's approval. However, a trust manager can also determine an application's trust status based on other criteria, such as decisions provided by a corporate database. The trust decision can be persisted, depending upon the `context` parameters properties and the trust manager implementation. If the trust for the application is persisted for a decision based on a user dialog box, future calls to the will not present the UI dialog box for every request for that application. is called after the manifest, but before the application has been downloaded to the local system. + uses the configured property to determine whether to allow execution of the specified application with the permission set requested in the application manifest. The trust manager's behavior is dependent on the trust manager implementation and the information passed in the `context` parameter. The default behavior of the trust manager is to establish a user interface (UI) dialog box to determine the user's approval. However, a trust manager can also determine an application's trust status based on other criteria, such as decisions provided by a corporate database. The trust decision can be persisted, depending upon the `context` parameters properties and the trust manager implementation. If the trust for the application is persisted for a decision based on a user dialog box, future calls to the will not present the UI dialog box for every request for that application. is called after the manifest, but before the application has been downloaded to the local system. ]]> @@ -142,7 +142,7 @@ method or the method. + The trust decisions in the collection are maintained using the methods of the collection, such as the method or the method. ]]> diff --git a/xml/System.Security.Policy/ApplicationTrust.xml b/xml/System.Security.Policy/ApplicationTrust.xml index eefee171a7d..234af8f3cb6 100644 --- a/xml/System.Security.Policy/ApplicationTrust.xml +++ b/xml/System.Security.Policy/ApplicationTrust.xml @@ -58,7 +58,7 @@ object is returned by a trust manager's method. + An object is returned by a trust manager's method. ]]> @@ -207,7 +207,7 @@ [!INCLUDE[cas-deprecated](~/includes/cas-deprecated.md)] - `fullTrustAssemblies` identifies strong-named assemblies within the that are to be granted full trust. This constructor is called by the method to create an that will be used as a sandbox. For more information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](/dotnet/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox). + `fullTrustAssemblies` identifies strong-named assemblies within the that are to be granted full trust. This constructor is called by the method to create an that will be used as a sandbox. For more information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](/dotnet/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox). ]]> @@ -422,7 +422,7 @@ [!INCLUDE [untrusted-data-method-note](~/includes/untrusted-data-method-note.md)] -The and methods are implemented to make objects XML-encodable for security policy use. +The and methods are implemented to make objects XML-encodable for security policy use. ]]> @@ -607,7 +607,7 @@ The and and methods are implemented to make objects XML-encodable for security policy use. + The and methods are implemented to make objects XML-encodable for security policy use. ]]> diff --git a/xml/System.Security.Policy/ApplicationTrustCollection.xml b/xml/System.Security.Policy/ApplicationTrustCollection.xml index fa9125331e7..4594efc0e6c 100644 --- a/xml/System.Security.Policy/ApplicationTrustCollection.xml +++ b/xml/System.Security.Policy/ApplicationTrustCollection.xml @@ -106,7 +106,7 @@ object is added to the end of the collection. To remove an application trust that you previously added, use the method. + The object is added to the end of the collection. To remove an application trust that you previously added, use the method. ]]> @@ -172,7 +172,7 @@ ## Remarks The objects contained in the `trusts` array are appended to the end of the collection. - To remove a range of application trusts that you previously added, use the method. + To remove a range of application trusts that you previously added, use the method. ]]> @@ -228,9 +228,9 @@ ## Remarks The objects contained in `trusts` are appended to the end of the collection. - You can use the method to quickly add another collection of application trust objects to the collection instead of manually adding each application trust to the collection using the method. + You can use the method to quickly add another collection of application trust objects to the collection instead of manually adding each application trust to the collection using the method. - To remove a range of application trusts that you previously added, use the method. + To remove a range of application trusts that you previously added, use the method. ]]> @@ -486,12 +486,12 @@ Use the property to get the item currently pointed to in the collection. - Use the method to move to the next item in the collection. + Use the method to move to the next item in the collection. - Use the method to move the enumerator to its initial position. + Use the method to move the enumerator to its initial position. > [!NOTE] -> After you create the enumerator, or use the method to reposition the enumerator to the start of the collection, you must then call the method to position the enumerator to the first item. Otherwise, the item represented by the property is undefined. +> After you create the enumerator, or use the method to reposition the enumerator to the start of the collection, you must then call the method to position the enumerator to the first item. Otherwise, the item represented by the property is undefined. ]]> @@ -773,7 +773,7 @@ method is used to locate all matching application trusts, and the matching items are removed from the collection. + The application trust can be identified by an exact version match, dependent upon the value of the `versionMatch` parameter. The method is used to locate all matching application trusts, and the matching items are removed from the collection. The objects that follow the removed objects move up to occupy the vacated positions. The indexes of the objects that are moved are also updated. diff --git a/xml/System.Security.Policy/ApplicationTrustEnumerator.xml b/xml/System.Security.Policy/ApplicationTrustEnumerator.xml index 93c673b6583..e408190decc 100644 --- a/xml/System.Security.Policy/ApplicationTrustEnumerator.xml +++ b/xml/System.Security.Policy/ApplicationTrustEnumerator.xml @@ -49,13 +49,13 @@ ## Remarks Enumerators only allow reading the data in the collection. Enumerators cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. The method also brings the enumerator back to this position. At this position, calling the property throws an exception. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. + Initially, the enumerator is positioned before the first element in the collection. The method also brings the enumerator back to this position. At this position, calling the property throws an exception. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. - returns the same object until either or is called. sets to the next element. + returns the same object until either or is called. sets to the next element. - After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling returns `false`. If the last call to returned `false`, calling throws an exception. To reset to the first element of the collection, call followed by a call to . + After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling returns `false`. If the last call to returned `false`, calling throws an exception. To reset to the first element of the collection, call followed by a call to . - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an exception. If the collection is modified between calling and , returns the element to which it is currently set, even if the enumerator is already invalidated. + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an exception. If the collection is modified between calling and , returns the element to which it is currently set, even if the enumerator is already invalidated. The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. @@ -105,9 +105,9 @@ property is not valid and will throw an exception if it is accessed. You must first call the method to position the cursor at the first object in the collection. + When the enumerator is created, it does not point to an object, so the property is not valid and will throw an exception if it is accessed. You must first call the method to position the cursor at the first object in the collection. - Multiple calls to with no intervening calls to will return the same object. + Multiple calls to with no intervening calls to will return the same object. ]]> @@ -160,11 +160,11 @@ method immediately returns `false` if there are no objects in the collection. + The method immediately returns `false` if there are no objects in the collection. - will return `true` until it has reached the end of the collection. It will then return `false` for each successive call. However, after has returned `false`, accessing the property will throw an exception. + will return `true` until it has reached the end of the collection. It will then return `false` for each successive call. However, after has returned `false`, accessing the property will throw an exception. - Upon creation, an enumerator is positioned before the first object in the collection, and the first call to positions the enumerator at the first object in the collection. + Upon creation, an enumerator is positioned before the first object in the collection, and the first call to positions the enumerator at the first object in the collection. ]]> @@ -211,7 +211,7 @@ ## Remarks An enumerator moves in a forward-only direction. Use this method to return the enumerator to the beginning of the collection of objects. - The method positions the cursor at the first object in the collection. After calling , you do not need to call the method to move the cursor forward to the first object. + The method positions the cursor at the first object in the collection. After calling , you do not need to call the method to move the cursor forward to the first object. ]]> diff --git a/xml/System.Security.Policy/ApplicationVersionMatch.xml b/xml/System.Security.Policy/ApplicationVersionMatch.xml index 05e88c5d5b4..adc3ace97fe 100644 --- a/xml/System.Security.Policy/ApplicationVersionMatch.xml +++ b/xml/System.Security.Policy/ApplicationVersionMatch.xml @@ -39,11 +39,11 @@ Specifies how to match versions when locating application trusts in a collection. - and methods of an can act either on all versions of an application or on the exact version. The enumeration allows the caller to specify the desired behavior. - + and methods of an can act either on all versions of an application or on the exact version. The enumeration allows the caller to specify the desired behavior. + ]]> diff --git a/xml/System.Security.Policy/CodeConnectAccess.xml b/xml/System.Security.Policy/CodeConnectAccess.xml index 96e150af40a..3ed7c517880 100644 --- a/xml/System.Security.Policy/CodeConnectAccess.xml +++ b/xml/System.Security.Policy/CodeConnectAccess.xml @@ -50,9 +50,9 @@ ## Remarks This class is used in conjunction with the class to control how executing code can connect back to the site it was downloaded from. These classes provide programmatic control of the granted to executing code that controls what schemes and ports the code can use access its origin site. You can specify scheme and port pairs that are permitted based on the scheme in the URL where the code originates. - To create a object based on the code's origin scheme, use the method. + To create a object based on the code's origin scheme, use the method. - To create a object that can use any scheme but is restricted by port, use the method. + To create a object that can use any scheme but is restricted by port, use the method. @@ -104,9 +104,9 @@ property is set using the `allowScheme` parameter. The scheme is converted to lowercase. The value of controls the scheme that executing code can use to connect to a network resource. + The property is set using the `allowScheme` parameter. The scheme is converted to lowercase. The value of controls the scheme that executing code can use to connect to a network resource. - The property is set using the `allowPort` parameter. The value of controls the port that executing code can use to connect to a network resource. + The property is set using the `allowPort` parameter. The value of controls the port that executing code can use to connect to a network resource. @@ -173,7 +173,7 @@ object using this value, you can call the method to obtain a object that represents a specified port and any scheme. + As an alternative to constructing a object using this value, you can call the method to obtain a object that represents a specified port and any scheme. The value of this field is "*". @@ -344,7 +344,7 @@ object that has the default port for a specified scheme, use this field as the `allowPort` parameter of the constructor. + To create a object that has the default port for a specified scheme, use this field as the `allowPort` parameter of the constructor. The value of this field is -3. @@ -401,7 +401,7 @@ objects are equal if their and property values are equal. + Two objects are equal if their and property values are equal. ]]> @@ -479,7 +479,7 @@ object that has the same port as the port in the executing code's URL evidence, use this field as the `allowPort` parameter of the constructor. + To create a object that has the same port as the port in the executing code's URL evidence, use this field as the `allowPort` parameter of the constructor. The value of this field is -4. @@ -530,7 +530,7 @@ constructor. Instead, use the method. + Do not use this field with the constructor. Instead, use the method. The value of this field is "$origin". diff --git a/xml/System.Security.Policy/CodeGroup.xml b/xml/System.Security.Policy/CodeGroup.xml index 4f67f6615c4..95379b1c973 100644 --- a/xml/System.Security.Policy/CodeGroup.xml +++ b/xml/System.Security.Policy/CodeGroup.xml @@ -46,13 +46,13 @@ Represents the abstract base class from which all implementations of code groups must derive. - @@ -97,18 +97,18 @@ The policy statement for the code group in the form of a permission set and attributes to grant code that matches the membership condition. Initializes a new instance of . - method. - + method. + ]]> The parameter is . - The type of the parameter is not valid. - - -or- - + The type of the parameter is not valid. + + -or- + The type of the parameter is not valid. @@ -199,11 +199,11 @@ Gets a string representation of the attributes of the policy statement for the code group. A string representation of the attributes of the policy statement for the code group. - @@ -248,14 +248,14 @@ Gets or sets an ordered list of the child code groups of a code group. A list of child code groups. - [!NOTE] -> The return value is a copy of the child code list. Do not use the returned list to add a child code group; instead, use the method. - +> The return value is a copy of the child code list. Do not use the returned list to add a child code group; instead, use the method. + ]]> An attempt is made to set this property to . @@ -297,11 +297,11 @@ When overridden in a derived class, makes a deep copy of the current code group. An equivalent copy of the current code group, including its membership conditions and child code groups. - @@ -345,13 +345,13 @@ The policy level within which the code group exists. When overridden in a derived class, serializes properties and internal state specific to a derived code group and adds the serialization to the specified . - cannot be overridden. If you need to serialize members specific to a particular implementation of , you must override and serialize your members there. When the code group is serialized, calls and adds your serialization to the created by . - - The XML created using this method is deserialized by the method. - + cannot be overridden. If you need to serialize members specific to a particular implementation of , you must override and serialize your members there. When the code group is serialized, calls and adds your serialization to the created by . + + The XML created using this method is deserialized by the method. + ]]> @@ -451,13 +451,13 @@ if the specified code group is equivalent to the current code group; otherwise, . - , , and . - - This method tests the top-level code group only, not its child code groups. - + , , and . + + This method tests the top-level code group only, not its child code groups. + ]]> @@ -510,13 +510,13 @@ if the specified code group is equivalent to the current code group; otherwise, . - , , and . - - If the `compareChildren` parameter is `true`, this method will only return `true` if the current code group and all its child code groups are equivalent to the specified code group and all its child code groups. - + , , and . + + If the `compareChildren` parameter is `true`, this method will only return `true` if the current code group and all its child code groups are equivalent to the specified code group and all its child code groups. + ]]> @@ -614,11 +614,11 @@ The policy level within which the code group exists. Reconstructs a security object with a given state and policy level from an XML encoding. - The parameter is . @@ -711,11 +711,11 @@ Gets or sets the code group's membership condition. The membership condition that determines to which evidence the code group is applicable. - An attempt is made to set this parameter to . @@ -835,13 +835,13 @@ The policy level within which the code group exists. When overridden in a derived class, reconstructs properties and internal state specific to a derived code group from the specified . - cannot be overridden. If you need to deserialize members specific to a particular implementation of , you must override and deserialize your members there. When the code group is deserialized, calls and reconstructs your members from the . - - This method deserializes XML created using . - + cannot be overridden. If you need to deserialize members specific to a particular implementation of , you must override and deserialize your members there. When the code group is deserialized, calls and reconstructs your members from the . + + This method deserializes XML created using . + ]]> @@ -890,11 +890,11 @@ Gets the name of the named permission set for the code group. The name of a named permission set of the policy level. - @@ -939,22 +939,22 @@ Gets or sets the policy statement associated with the code group. The policy statement for the code group. - for a code group. - + for a code group. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic CodeGroup.PolicyStatement Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/CodeGroup/PolicyStatement/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/CodeGroup/PolicyStatement/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/CodeGroup/PolicyStatement/source.vb" id="Snippet1"::: + ]]> @@ -1002,11 +1002,11 @@ The code group to be removed as a child. Removes the specified child code group. - The parameter is not an immediate child code group of the current code group. @@ -1050,15 +1050,15 @@ When overridden in a derived class, resolves policy for the code group and its descendants for a set of evidence. A policy statement that consists of the permissions granted by the code group with optional attributes, or if the code group does not apply (the membership condition does not match the specified evidence). - , all child code groups whose membership condition match the specified evidence are also resolved, and all resulting policy statements are combined with the policy statement of the parent union code group. Each child code group type determines how all child groups under it are applied, depending on how the methods of these child groups work. - - The .NET Framework security system uses on the policy levels to determine which permissions to grant to loaded code from the resulting policy statements and the code request on the assembly. - + , all child code groups whose membership condition match the specified evidence are also resolved, and all resulting policy statements are combined with the policy statement of the parent union code group. Each child code group type determines how all child groups under it are applied, depending on how the methods of these child groups work. + + The .NET Framework security system uses on the policy levels to determine which permissions to grant to loaded code from the resulting policy statements and the code request on the assembly. + ]]> @@ -1101,11 +1101,11 @@ When overridden in a derived class, resolves matching code groups. A that is the root of the tree of matching code groups. - . The code group that is returned contains child code groups, which in turn can have child code groups as necessary to reflect the complete set of code groups that were matched by the evidence provided. - + . The code group that is returned contains child code groups, which in turn can have child code groups as necessary to reflect the complete set of code groups that were matched by the evidence provided. + ]]> @@ -1211,11 +1211,11 @@ Creates an XML encoding of the security object, its current state, and the policy level within which the code exists. An XML encoding of the security object, including any state information. - diff --git a/xml/System.Security.Policy/Evidence.xml b/xml/System.Security.Policy/Evidence.xml index 43ac404f185..cbb9b7bd72e 100644 --- a/xml/System.Security.Policy/Evidence.xml +++ b/xml/System.Security.Policy/Evidence.xml @@ -191,7 +191,7 @@ constructor. This example is part of a larger example provided for the class. + The following code example shows the use of the constructor. This example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Policy.Evidence/CPP/evidence_evidence.cpp" id="Snippet12"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/Evidence/Overview/evidence_evidence.cs" id="Snippet12"::: @@ -640,12 +640,12 @@ removes the evidence in the host and assembly enumerations, setting both to `null`. + removes the evidence in the host and assembly enumerations, setting both to `null`. ## Examples - The following code example shows the use of the method. This example is part of a larger example provided for the class. + The following code example shows the use of the method. This example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Policy.Evidence/CPP/evidence_evidence.cpp" id="Snippet13"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/Evidence/Overview/evidence_evidence.cs" id="Snippet13"::: @@ -870,7 +870,7 @@ . +For more information, see . ## Examples The following code example shows the use of the Equals method. This example is part of a larger example provided for the class. @@ -942,7 +942,7 @@ Console::WriteLine( "Does the copy equal the current evidence? {0}", myEvidence- method. This example is part of a larger example provided for the class. + The following example shows the use of the method. This example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Policy.Evidence/CPP/evidence_evidence.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/Evidence/Overview/evidence_evidence.cs" id="Snippet3"::: @@ -1177,7 +1177,7 @@ Console::WriteLine( "HashCode = {0}", myEvidence->GetHashCode() ); method. This example is part of a larger example provided for the class. + The following example shows the use of the method. This example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Policy.Evidence/CPP/evidence_evidence.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/Evidence/Overview/evidence_evidence.cs" id="Snippet2"::: @@ -1466,7 +1466,7 @@ Console::WriteLine( "HashCode = {0}", myEvidence->GetHashCode() ); ## Examples - The following code example shows the use of the method. This example is part of a larger example provided for the class. + The following code example shows the use of the method. This example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Policy.Evidence/CPP/evidence_evidence.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/Evidence/Overview/evidence_evidence.cs" id="Snippet10"::: @@ -1533,10 +1533,10 @@ Console::WriteLine( "HashCode = {0}", myEvidence->GetHashCode() ); ## Remarks -The results of executing the method can be confirmed using the method and the method. +The results of executing the method can be confirmed using the method and the method. ## Examples - The following code example shows the use of the method. This example is part of a larger example provided for the class. + The following code example shows the use of the method. This example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Policy.Evidence/CPP/evidence_evidence.cpp" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/Evidence/Overview/evidence_evidence.cs" id="Snippet11"::: diff --git a/xml/System.Security.Policy/FileCodeGroup.xml b/xml/System.Security.Policy/FileCodeGroup.xml index d42d94fd8de..53f7d977df5 100644 --- a/xml/System.Security.Policy/FileCodeGroup.xml +++ b/xml/System.Security.Policy/FileCodeGroup.xml @@ -105,7 +105,7 @@ method. + This constructor creates a basic code group. Child code groups can be added with the method. returns a permission set containing a dynamically-calculated that grants file access to the directory from which the code is run. The type of access granted is determined by the `access` parameter. @@ -162,7 +162,7 @@ does not use , so this property is always `null`. + does not use , so this property is always `null`. ]]> @@ -517,7 +517,7 @@ ## Remarks Given evidence for an assembly to be loaded, this method evaluates the code group by first checking the membership condition against the specified evidence. If there is a match, this method returns a policy statement for the code group, including evaluation of child code groups. - The .NET Framework security system uses on the policy levels to determine which permissions to grant to loaded code from the resulting policy statements and the code request on the assembly. + The .NET Framework security system uses on the policy levels to determine which permissions to grant to loaded code from the resulting policy statements and the code request on the assembly. uses union semantics and forms a permission set based on the specified by `evidence`. diff --git a/xml/System.Security.Policy/FirstMatchCodeGroup.xml b/xml/System.Security.Policy/FirstMatchCodeGroup.xml index 97bdf2762a8..3117da019de 100644 --- a/xml/System.Security.Policy/FirstMatchCodeGroup.xml +++ b/xml/System.Security.Policy/FirstMatchCodeGroup.xml @@ -109,7 +109,7 @@ method. + This constructor creates a basic code group and should be called from the constructors of custom code groups. Child code groups can be added using the method. ]]> @@ -255,9 +255,9 @@ ## Remarks Given evidence for an assembly to be loaded, this method evaluates the code group by first checking the membership condition against the specified evidence. If there is a match, this method returns a policy statement for the code group, including evaluation of child code groups. - For first-match code groups, each child code group's membership condition is tested against the evidence in the order in which they were added; only the first match is resolved with the evidence set. If there are no matches, the policy statement of the parent first-match code group applies. The matching child code group type determines how all child groups under it are applied, depending on how the methods of these child groups work. + For first-match code groups, each child code group's membership condition is tested against the evidence in the order in which they were added; only the first match is resolved with the evidence set. If there are no matches, the policy statement of the parent first-match code group applies. The matching child code group type determines how all child groups under it are applied, depending on how the methods of these child groups work. - The .NET Framework security system uses on the policy levels to determine which permissions to grant to loaded code from the resulting policy statements and the code request on the assembly. + The .NET Framework security system uses on the policy levels to determine which permissions to grant to loaded code from the resulting policy statements and the code request on the assembly. This operation of this method is as follows: @@ -318,7 +318,7 @@ ## Remarks Given evidence for an assembly to be loaded, this method evaluates the code group by first checking the membership condition against the specified evidence. If there is a match, this method returns a root code group. The code group that is returned contains child code groups, which in turn can have child code groups as necessary to reflect the complete set of code groups that were matched by the evidence provided. - For first-match code groups, each child code group's membership condition is tested against the evidence in the order in which they were added; only the first match is resolved with the evidence set. If there are no matches, the policy statement of the parent first-match code group applies. The matching child code group type determines how all child groups under it are applied, depending on how the methods of these child groups work. + For first-match code groups, each child code group's membership condition is tested against the evidence in the order in which they were added; only the first match is resolved with the evidence set. If there are no matches, the policy statement of the parent first-match code group applies. The matching child code group type determines how all child groups under it are applied, depending on how the methods of these child groups work. ]]> diff --git a/xml/System.Security.Policy/GacInstalled.xml b/xml/System.Security.Policy/GacInstalled.xml index ddb5237f1c8..235daed8627 100644 --- a/xml/System.Security.Policy/GacInstalled.xml +++ b/xml/System.Security.Policy/GacInstalled.xml @@ -65,7 +65,7 @@ [!INCLUDE[cas-deprecated](~/includes/cas-deprecated.md)] - The presence of evidence produces a in the grant set. If there is a for , the that corresponds to the evidence is compared with the demanded permission. + The presence of evidence produces a in the grant set. If there is a for , the that corresponds to the evidence is compared with the demanded permission. ]]> @@ -303,7 +303,7 @@ method returns 0 (zero) because objects have no properties to distinguish one from another. + The method returns 0 (zero) because objects have no properties to distinguish one from another. ]]> diff --git a/xml/System.Security.Policy/GacMembershipCondition.xml b/xml/System.Security.Policy/GacMembershipCondition.xml index 88791efe146..21d54c8505c 100644 --- a/xml/System.Security.Policy/GacMembershipCondition.xml +++ b/xml/System.Security.Policy/GacMembershipCondition.xml @@ -59,20 +59,20 @@ Determines whether an assembly belongs to a code group by testing its global assembly cache membership. This class cannot be inherited. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Policy.GacMembershipCondition/CPP/gacmembershipcondition.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/GacInstalled/Equals/gacmembershipcondition.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet1"::: + ]]> @@ -106,20 +106,20 @@ Initializes a new instance of the class. - constructor. This example is part of a larger example provided for the class topic. - + constructor. This example is part of a larger example provided for the class topic. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Policy.GacMembershipCondition/CPP/gacmembershipcondition.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/GacInstalled/Equals/gacmembershipcondition.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet4"::: + ]]> @@ -165,20 +165,20 @@ if the specified evidence satisfies the membership condition; otherwise, . - evidence. - - - -## Examples - The following code example shows the use of the method. This example is part of a larger example provided for the class. - + evidence. + + + +## Examples + The following code example shows the use of the method. This example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Policy.GacMembershipCondition/CPP/gacmembershipcondition.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/GacInstalled/Equals/gacmembershipcondition.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet3"::: + ]]> @@ -220,20 +220,20 @@ Creates an equivalent copy of the membership condition. A new object. - method. This example is part of a larger example provided for the class. - + method. This example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Policy.GacMembershipCondition/CPP/gacmembershipcondition.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/GacInstalled/Equals/gacmembershipcondition.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet2"::: + ]]> @@ -279,20 +279,20 @@ if is a ; otherwise, . - , then the objects being compared are equal. This method returns `false` only if `o` is `null` or if `o` is not a . - - - -## Examples - The following code example shows the use of the method. This example is part of a larger example provided for the class. - + , then the objects being compared are equal. This method returns `false` only if `o` is `null` or if `o` is not a . + + + +## Examples + The following code example shows the use of the method. This example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Policy.GacMembershipCondition/CPP/gacmembershipcondition.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/GacInstalled/Equals/gacmembershipcondition.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet5"::: + ]]> @@ -346,20 +346,20 @@ The that contains the XML encoding to use to reconstruct the security object. Uses the specified XML encoding to reconstruct a security object. - method reconstructs a from an XML encoding defined by the class. Use the method to XML-encode the including state information. - - - -## Examples - The following code example shows the use of the method. This example is part of a larger example provided for the class. - + method reconstructs a from an XML encoding defined by the class. Use the method to XML-encode the including state information. + + + +## Examples + The following code example shows the use of the method. This example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Policy.GacMembershipCondition/CPP/gacmembershipcondition.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/GacInstalled/Equals/gacmembershipcondition.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet5"::: + ]]> @@ -409,20 +409,20 @@ The context for resolving references. Uses the specified XML encoding to reconstruct a security object, using the specified policy level context. - method. This example is part of a larger example provided for the class. - + method. This example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Policy.GacMembershipCondition/CPP/gacmembershipcondition.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/GacInstalled/Equals/gacmembershipcondition.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet6"::: + ]]> @@ -465,20 +465,20 @@ Gets a hash code for the current membership condition. 0 (zero). - method returns 0 (zero) because objects have no properties to distinguish one from another. - - - -## Examples - The following code example shows the use of the method. This example is part of a larger example provided for the class. - + method returns 0 (zero) because objects have no properties to distinguish one from another. + + + +## Examples + The following code example shows the use of the method. This example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Policy.GacMembershipCondition/CPP/gacmembershipcondition.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/GacInstalled/Equals/gacmembershipcondition.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet4"::: + ]]> @@ -520,20 +520,20 @@ Returns a string representation of the membership condition. A string representation of the membership condition. - is "GAC". - - - -## Examples - The following code example shows the use of the method. This example is part of a larger example provided for the class. - + is "GAC". + + + +## Examples + The following code example shows the use of the method. This example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Policy.GacMembershipCondition/CPP/gacmembershipcondition.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/GacInstalled/Equals/gacmembershipcondition.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet5"::: + ]]> @@ -585,20 +585,20 @@ Creates an XML encoding of the security object and its current state. A that contains the XML encoding of the security object, including any state information. - method to restore the state information from a . - - - -## Examples - The following code example shows the use of the method. This example is part of a larger example provided for the class. - + method to restore the state information from a . + + + +## Examples + The following code example shows the use of the method. This example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Policy.GacMembershipCondition/CPP/gacmembershipcondition.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/GacInstalled/Equals/gacmembershipcondition.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet5"::: + ]]> @@ -643,20 +643,20 @@ Creates an XML encoding of the security object and its current state, using the specified policy level context. A that contains the XML encoding of the security object, including any state information. - method. This example is part of a larger example provided for the class. - + method. This example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Policy.GacMembershipCondition/CPP/gacmembershipcondition.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/GacInstalled/Equals/gacmembershipcondition.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/GacMembershipCondition/Overview/gacmembershipcondition.vb" id="Snippet6"::: + ]]> diff --git a/xml/System.Security.Policy/Hash.xml b/xml/System.Security.Policy/Hash.xml index dc32e465a77..2030806640e 100644 --- a/xml/System.Security.Policy/Hash.xml +++ b/xml/System.Security.Policy/Hash.xml @@ -61,7 +61,7 @@ ## Remarks A hash value represents a unique value that corresponds to a particular set of bytes. Rather than referring to an assembly by name, version, or other designation, a hash value designates the assembly without ambiguity. Names are subject to collisions in rare cases where the same name is given to completely different code. Different variations of code can accidentally be marked with the same version. However, even changing a single bit results in a very different hash value. - Hash values are a cryptographically secure way to refer to specific assemblies in policy without the use of digital signatures. A secure hash algorithm is designed so that it is computationally infeasible to construct a different assembly with the identical hash value by either an accidental or malicious attempt. By default, evidence from the and hash algorithms is supported, although any hash algorithm can be used through . + Hash values are a cryptographically secure way to refer to specific assemblies in policy without the use of digital signatures. A secure hash algorithm is designed so that it is computationally infeasible to construct a different assembly with the identical hash value by either an accidental or malicious attempt. By default, evidence from the and hash algorithms is supported, although any hash algorithm can be used through . Due to collision problems with MD5 and SHA-1, Microsoft recommends a security model based on SHA-256 or better. @@ -529,7 +529,7 @@ constructor provides the bytes for the hash computation. + The assembly that is specified in the constructor provides the bytes for the hash computation. ]]> diff --git a/xml/System.Security.Policy/IApplicationTrustManager.xml b/xml/System.Security.Policy/IApplicationTrustManager.xml index bf9a48063bb..0ad5f65bc3b 100644 --- a/xml/System.Security.Policy/IApplicationTrustManager.xml +++ b/xml/System.Security.Policy/IApplicationTrustManager.xml @@ -28,7 +28,7 @@ interface. The host calls the method to determine whether an application should be executed and which permissions should be granted to the application. + Trust managers must implement the interface. The host calls the method to determine whether an application should be executed and which permissions should be granted to the application. In the .NET Framework 4 and later, there is only one trust manager, which can be a custom implementation of the interface. The default trust manager implementation prompts the user for permission to install the application and to elevate the permissions granted to the application. Other trust manager implementations might provide different user experiences. For example, an implementation might check an enterprise list for trusted applications instead of prompting the user for that information. @@ -73,12 +73,12 @@ method is called by the host to determine whether an application should be executed and which set of permissions it should be granted. returns an object with a property that contains a permission set representing the permissions to be granted to each assembly executing within the context of the application. The granted permissions do not apply to assemblies in the global assembly cache. The object also has an property that the trust manager sets to indicate whether the application should be trusted. If the trust manager indicates that the application can be trusted, the host activates the application and grants its assemblies the set of permissions provided in the collection. + The method is called by the host to determine whether an application should be executed and which set of permissions it should be granted. returns an object with a property that contains a permission set representing the permissions to be granted to each assembly executing within the context of the application. The granted permissions do not apply to assemblies in the global assembly cache. The object also has an property that the trust manager sets to indicate whether the application should be trusted. If the trust manager indicates that the application can be trusted, the host activates the application and grants its assemblies the set of permissions provided in the collection. ## Examples - The following example shows an implementation of the method for a custom trust manager. This code example is part of a larger example provided for the interface. + The following example shows an implementation of the method for a custom trust manager. This code example is part of a larger example provided for the interface. :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/IApplicationTrustManager/Overview/customTrustManager.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/IApplicationTrustManager/Overview/customtrustmanager.vb" id="Snippet2"::: diff --git a/xml/System.Security.Policy/IIdentityPermissionFactory.xml b/xml/System.Security.Policy/IIdentityPermissionFactory.xml index f1fc55c5a86..bfb6e5a1c36 100644 --- a/xml/System.Security.Policy/IIdentityPermissionFactory.xml +++ b/xml/System.Security.Policy/IIdentityPermissionFactory.xml @@ -43,14 +43,14 @@ Defines the method that creates a new identity permission. - for an evidence object, you provide an implementation of that the .NET Framework security system can call to get an identity permission that represents that piece of evidence. During policy resolution, the security system will call that method on all evidence objects that implement and grant the resulting identity permissions to the appropriate assembly. - + Some types of evidence have a corresponding identity permission that is granted to assemblies with that evidence. This allows other code to make identity demands, so that only code with a specific piece of evidence will pass. For example, you can demand that your callers have a specific strong name; only callers with that strong name will pass the demand. By implementing for an evidence object, you provide an implementation of that the .NET Framework security system can call to get an identity permission that represents that piece of evidence. During policy resolution, the security system will call that method on all evidence objects that implement and grant the resulting identity permissions to the appropriate assembly. + ]]> diff --git a/xml/System.Security.Policy/NetCodeGroup.xml b/xml/System.Security.Policy/NetCodeGroup.xml index a47e03d6fdf..d2542ead8eb 100644 --- a/xml/System.Security.Policy/NetCodeGroup.xml +++ b/xml/System.Security.Policy/NetCodeGroup.xml @@ -61,7 +61,7 @@ |http|HTTP and HTTPS access is permitted using the origin port.| |https|HTTPS access is permitted using the origin port.| - You can control the scheme and port that code is permitted to use when connecting back to its site of origin by passing a object with the appropriate and property values to the method. You can create a connection access rule that applies when the origin scheme is not present in the evidence or is not recognized by specifying ("") as the scheme. You can also create a connection access rule that applies when there is no connection access rule with a matching scheme by specifying ("*") as the scheme. + You can control the scheme and port that code is permitted to use when connecting back to its site of origin by passing a object with the appropriate and property values to the method. You can create a connection access rule that applies when the origin scheme is not present in the evidence or is not recognized by specifying ("") as the scheme. You can also create a connection access rule that applies when there is no connection access rule with a matching scheme by specifying ("*") as the scheme. > [!NOTE] > If code does not submit the URI scheme as evidence, access is permitted using any scheme back to the origin site. @@ -172,7 +172,7 @@ method, you specify a scheme and an associated object. Any objects that you add to the using as the origin scheme are applied when the code's origin scheme is not present in its evidence, or is not a scheme recognized by the object. + When calling the method, you specify a scheme and an associated object. Any objects that you add to the using as the origin scheme are applied when the code's origin scheme is not present in its evidence, or is not a scheme recognized by the object. To specify the objects to use when the code's origin scheme does not match any of the schemes contained in the set of origin schemes added to the current object, use the value. @@ -280,7 +280,7 @@ method, you specify a scheme and an associated object. You can use the value of the field to specify the objects that should be used for any scheme that is not explicitly contained in the set of origin schemes added to the current object. + When calling the method, you specify a scheme and an associated object. You can use the value of the field to specify the objects that should be used for any scheme that is not explicitly contained in the set of origin schemes added to the current object. The objects specified with the field are only used if the code's origin scheme does not match any of the schemes contained in the set of origin schemes added to the current object. @@ -473,7 +473,7 @@ ## Remarks The following data are used to determine the equality of two objects: -- The and properties. +- The and properties. - The property. @@ -520,7 +520,7 @@ property value is the origin scheme, and the property value is the array of associated objects. If there are no associated objects, returns an empty array. + In each dictionary entry, the property value is the origin scheme, and the property value is the array of associated objects. If there are no associated objects, returns an empty array. diff --git a/xml/System.Security.Policy/PolicyException.xml b/xml/System.Security.Policy/PolicyException.xml index 3d535d83049..c7e3e84f022 100644 --- a/xml/System.Security.Policy/PolicyException.xml +++ b/xml/System.Security.Policy/PolicyException.xml @@ -113,8 +113,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The localized error message string.| +||`null`.| +||The localized error message string.| ]]> @@ -161,8 +161,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string.| +||`null`.| +||The error message string.| ]]> @@ -272,8 +272,8 @@ |Property|Value| |--------------|-----------| -||The inner exception reference.| -||The error message string.| +||The inner exception reference.| +||The error message string.| ]]> diff --git a/xml/System.Security.Policy/PolicyLevel.xml b/xml/System.Security.Policy/PolicyLevel.xml index 11b83de8a92..d308f314996 100644 --- a/xml/System.Security.Policy/PolicyLevel.xml +++ b/xml/System.Security.Policy/PolicyLevel.xml @@ -66,7 +66,7 @@ A policy level consists of a set of code groups organized into a single rooted tree (see ), a set of named permission sets that are referenced by the code groups to specify permissions to be granted to code belonging to the code group, and a list of fully-trusted assemblies. - Use to enumerate the policy levels. + Use to enumerate the policy levels. ]]> @@ -136,7 +136,7 @@ method is not supported in version 2.0 or later of the .NET Framework because the list of full trust assemblies is not used in those versions. + The method is not supported in version 2.0 or later of the .NET Framework because the list of full trust assemblies is not used in those versions. ]]> @@ -199,7 +199,7 @@ method is not supported in version 2.0 or later of the .NET Framework because the list of full trust assemblies is not used in those versions. + The method is not supported in version 2.0 or later of the .NET Framework because the list of full trust assemblies is not used in those versions. ]]> @@ -394,7 +394,7 @@ [!INCLUDE[cas-deprecated](~/includes/cas-deprecated.md)] - This method creates a new with the "AppDomain". The new will initially contain the same objects as in the default computer policy, and will have a single root code group that grants `FullTrust` to all code. + This method creates a new with the "AppDomain". The new will initially contain the same objects as in the default computer policy, and will have a single root code group that grants `FullTrust` to all code. ]]> @@ -499,7 +499,7 @@ are granted full trust during security policy evaluation of assemblies not in the list, but are not automatically granted full trust when directly evaluated by the security policy system. + are granted full trust during security policy evaluation of assemblies not in the list, but are not automatically granted full trust when directly evaluated by the security policy system. The property is not supported in version 2.0 or later of the .NET Framework because the list of full trust assemblies is not used in those versions. @@ -768,7 +768,7 @@ method is not supported in version 2.0 or later of the .NET Framework because the list of full trust assemblies is not used in those versions. + The method is not supported in version 2.0 or later of the .NET Framework because the list of full trust assemblies is not used in those versions. ]]> @@ -830,7 +830,7 @@ method is not supported in version 2.0 or later of the .NET Framework because the list of full trust assemblies is not used in those versions. + The method is not supported in version 2.0 or later of the .NET Framework because the list of full trust assemblies is not used in those versions. ]]> @@ -1069,14 +1069,14 @@ is the basic policy evaluation operation for policy levels. Given a set of evidence as input, this method tests membership conditions of code groups starting at the root and working down as matched. The combination of permissions resulting from the matching code groups produces a that is returned. + is the basic policy evaluation operation for policy levels. Given a set of evidence as input, this method tests membership conditions of code groups starting at the root and working down as matched. The combination of permissions resulting from the matching code groups produces a that is returned. In granting permissions to code, security policy uses the resolved policy statements for all applicable policy levels, together with the code request for permissions. ## Examples - The following code shows the use of the method. This code example is part of a larger example provided for the class. + The following code shows the use of the method. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.policy.policylevel/CPP/policylevel.cpp" id="Snippet13"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/PolicyLevel/Resolve/policylevel.cs" id="Snippet13"::: diff --git a/xml/System.Security.Policy/PolicyStatement.xml b/xml/System.Security.Policy/PolicyStatement.xml index 74d07ff52e4..f28ab4297e6 100644 --- a/xml/System.Security.Policy/PolicyStatement.xml +++ b/xml/System.Security.Policy/PolicyStatement.xml @@ -59,7 +59,7 @@ ## Remarks A consists of a set of granted permissions, and possible special attributes for the code group. - Policy statements are typically used as the return value of a operation on a . + Policy statements are typically used as the return value of a operation on a . ]]> @@ -342,7 +342,7 @@ method. + For more information, see the method. ]]> diff --git a/xml/System.Security.Policy/Publisher.xml b/xml/System.Security.Policy/Publisher.xml index 8f8e9f7c053..956e6bd1d40 100644 --- a/xml/System.Security.Policy/Publisher.xml +++ b/xml/System.Security.Policy/Publisher.xml @@ -60,18 +60,18 @@ Provides the Authenticode X.509v3 digital signature of a code assembly as evidence for policy evaluation. This class cannot be inherited. - evidence produces a in the grant set. If there is a for , the that corresponds to the evidence will be compared with the demanded permission. - - Publisher evidence is based on Authenticode X.509v3 signatures. - - By default, code access security (CAS) does not check for evidence. Unless your computer has a custom code group based on the class, you can improve performance by bypassing Authenticode signature verification. This is accomplished by configuring the runtime to not provide evidence for CAS. For more information about how to configure this option and which applications can use it, see the [\](/dotnet/framework/configure-apps/file-schema/runtime/generatepublisherevidence-element) element. - + The presence of evidence produces a in the grant set. If there is a for , the that corresponds to the evidence will be compared with the demanded permission. + + Publisher evidence is based on Authenticode X.509v3 signatures. + + By default, code access security (CAS) does not check for evidence. Unless your computer has a custom code group based on the class, you can improve performance by bypassing Authenticode signature verification. This is accomplished by configuring the runtime to not provide evidence for CAS. For more information about how to configure this option and which applications can use it, see the [\](/dotnet/framework/configure-apps/file-schema/runtime/generatepublisherevidence-element) element. + ]]> @@ -294,11 +294,11 @@ if the two instances of the class are equal; otherwise, . - objects are equal if they designate the same software publisher certificate. - + objects are equal if they designate the same software publisher certificate. + ]]> The parameter is not a object. diff --git a/xml/System.Security.Policy/Site.xml b/xml/System.Security.Policy/Site.xml index 1b3123ed86b..3e9ec7e95ef 100644 --- a/xml/System.Security.Policy/Site.xml +++ b/xml/System.Security.Policy/Site.xml @@ -60,16 +60,16 @@ Provides the Web site from which a code assembly originates as evidence for policy evaluation. This class cannot be inherited. - evidence produces a in the grant set. If there is a for , the that corresponds to the evidence will be compared with the demanded permission. - +The presence of evidence produces a in the grant set. If there is a for , the that corresponds to the evidence will be compared with the demanded permission. + Site identity is defined for code from URLs with any protocol except FILE. A site is the string between the "//" after the protocol of a URL and the following "/", if present. For example, `www.fourthcoffee.com` is the site identity in the URL `http://www.fourthcoffee.com/process/grind.htm`. This excludes port numbers. If a given URL is `http://www.fourthcoffee.com:8000/`, the site is `www.fourthcoffee.com`, not `www.fourthcoffee.com:8000`. - + ]]> @@ -211,10 +211,10 @@ Site identity is defined for code from URLs with any protocol except FILE. A sit Creates a new object from the specified URL. A new site object. To be added. - The parameter is not a valid URL. - - -or- - + The parameter is not a valid URL. + + -or- + The parameter is a file name. @@ -300,11 +300,11 @@ Site identity is defined for code from URLs with any protocol except FILE. A sit if the two instances of the class are equal; otherwise, . - objects are equal if they designate the same website name. - + objects are equal if they designate the same website name. + ]]> diff --git a/xml/System.Security.Policy/SiteMembershipCondition.xml b/xml/System.Security.Policy/SiteMembershipCondition.xml index 4562ef0c3e8..4c1ee8a8618 100644 --- a/xml/System.Security.Policy/SiteMembershipCondition.xml +++ b/xml/System.Security.Policy/SiteMembershipCondition.xml @@ -63,14 +63,14 @@ Determines whether an assembly belongs to a code group by testing the site from which it originated. This class cannot be inherited. - . Site identity is defined for code from URLs with any protocol except FILE. A site is the string between the "//" after the protocol of a URL and the following "/", if present. For example, `www.fourthcoffee.com` is the site identity in the URL `http://www.fourthcoffee.com/process/grind.htm`. This excludes port numbers. If a given URL is `http://www.fourthcoffee.com:8000/`, the site is `www.fourthcoffee.com`, not `www.fourthcoffee.com:8000`. -A code assembly satisfies a site membership condition if that code originates from the Web site specified by . Site identity is defined for code from URLs with any protocol except FILE. A site is the string between the "//" after the protocol of a URL and the following "/", if present. For example, `www.fourthcoffee.com` is the site identity in the URL `http://www.fourthcoffee.com/process/grind.htm`. This excludes port numbers. If a given URL is `http://www.fourthcoffee.com:8000/`, the site is `www.fourthcoffee.com`, not `www.fourthcoffee.com:8000`. - Sites can be matched exactly, or by a wildcard ("\*") prefix at the dot delimiter. For example, the site name `*.fourthcoffee.com` matches `fourthcoffee.com` as well as `www.fourthcoffee.com`. Without a wildcard, the site name must be a precise match. The site name \* will match any site, but will not match code that has no site evidence. - + ]]> @@ -109,11 +109,11 @@ Sites can be matched exactly, or by a wildcard ("\*") prefix at the dot delimite The site name or wildcard expression. Initializes a new instance of the class with name of the site that determines membership. - . - + . + ]]> The parameter is . @@ -162,11 +162,11 @@ Sites can be matched exactly, or by a wildcard ("\*") prefix at the dot delimite if the specified evidence satisfies the membership condition; otherwise, . - evidence. - + evidence. + ]]> The property is . @@ -430,11 +430,11 @@ Sites can be matched exactly, or by a wildcard ("\*") prefix at the dot delimite Gets or sets the site for which the membership condition tests. The site for which the membership condition tests. - An attempt is made to set to . diff --git a/xml/System.Security.Policy/StrongNameMembershipCondition.xml b/xml/System.Security.Policy/StrongNameMembershipCondition.xml index 1acc0b244af..b4311e220d8 100644 --- a/xml/System.Security.Policy/StrongNameMembershipCondition.xml +++ b/xml/System.Security.Policy/StrongNameMembershipCondition.xml @@ -122,7 +122,7 @@ ## Remarks Strong names are well suited to specifying code assemblies to which you give a rich set of powerful permissions. Since strong names are cryptographically verified, attackers cannot impersonate rightful assemblies and use their permissions. - The `name` and `version` parameters are optional. For example, you can create a that checks for and (but not ) by passing `null` into the `version` parameter. If `name` is an empty string (""), an is thrown. + The `name` and `version` parameters are optional. For example, you can create a that checks for and (but not ) by passing `null` into the `version` parameter. If `name` is an empty string (""), an is thrown. ]]> diff --git a/xml/System.Security.Policy/TrustManagerContext.xml b/xml/System.Security.Policy/TrustManagerContext.xml index e3e1d092ffb..03bc9f416e6 100644 --- a/xml/System.Security.Policy/TrustManagerContext.xml +++ b/xml/System.Security.Policy/TrustManagerContext.xml @@ -95,12 +95,12 @@ |Property|Initial value| |--------------|-------------------| -||`false`| -||`false`| -||`false`| -||`true`| -||`null`| -||| +||`false`| +||`false`| +||`false`| +||`true`| +||`null`| +||| ]]> @@ -228,7 +228,7 @@ method. This property is set to `false` if the host does not expect to call the trust manager again for the current . + This flag is set to `true` if the host might call the trust manager numerous times for trust decisions for this application. If `true`, the trust manager should cache any state that might improve the speed of future calls to the method. This property is set to `false` if the host does not expect to call the trust manager again for the current . ]]> diff --git a/xml/System.Security.Policy/UnionCodeGroup.xml b/xml/System.Security.Policy/UnionCodeGroup.xml index e3a7cb0e4dc..06728ad730c 100644 --- a/xml/System.Security.Policy/UnionCodeGroup.xml +++ b/xml/System.Security.Policy/UnionCodeGroup.xml @@ -54,18 +54,18 @@ Represents a code group whose policy statement is the union of the current code group's policy statement and the policy statement of all its matching child code groups. This class cannot be inherited. - is the most common type of code group; the policy statement of all matching child code groups (and by extension their child code groups) are combined with the permission set of the matching parent code group. Thus, if its membership condition matches, this code group forms the union of its policy statement and those of all its child code groups that also match the evidence. - - code groups are the code groups created by the CASPOL utility (see [Caspol.exe (Code Access Security Policy Tool)](/dotnet/framework/tools/caspol-exe-code-access-security-policy-tool)). - + Code groups are the building blocks of code access security policy. Each policy level consists of a root code group that can have child code groups (and so on), forming a tree. Each code group has a membership condition that determines if a given assembly belongs to it or not, based on the evidence for that assembly. Only code groups whose membership conditions match a given assembly and their child code groups apply policy. + + is the most common type of code group; the policy statement of all matching child code groups (and by extension their child code groups) are combined with the permission set of the matching parent code group. Thus, if its membership condition matches, this code group forms the union of its policy statement and those of all its child code groups that also match the evidence. + + code groups are the code groups created by the CASPOL utility (see [Caspol.exe (Code Access Security Policy Tool)](/dotnet/framework/tools/caspol-exe-code-access-security-policy-tool)). + ]]> @@ -106,17 +106,17 @@ The policy statement for the code group in the form of a permission set and attributes to grant code that matches the membership condition. Initializes a new instance of the class. - method. - + method. + ]]> - The type of the parameter is not valid. - - -or- - + The type of the parameter is not valid. + + -or- + The type of the parameter is not valid. @@ -161,11 +161,11 @@ Makes a deep copy of the current code group. An equivalent copy of the current code group, including its membership conditions and child code groups. - @@ -250,17 +250,17 @@ Resolves policy for the code group and its descendants for a set of evidence. A policy statement consisting of the permissions granted by the code group with optional attributes, or if the code group does not apply (the membership condition does not match the specified evidence). - methods work. - - The .NET Framework security system uses on the policy levels to determine which permissions to grant to loaded code from the resulting policy statements and the code request on the assembly. - - If the membership condition does not match the specified evidence, this method returns `null`; otherwise, it sets the permission set to be returned (P) equal to the code group's policy statement, and then continues. For each child code group, the method resolves the code group with the same evidence; if the result is not `null`, it sets P equal to the union of P and the child code group's policy statement. It then returns P, which is now the union of the current code group's policy statement and all child group policy statements. - + methods work. + + The .NET Framework security system uses on the policy levels to determine which permissions to grant to loaded code from the resulting policy statements and the code request on the assembly. + + If the membership condition does not match the specified evidence, this method returns `null`; otherwise, it sets the permission set to be returned (P) equal to the code group's policy statement, and then continues. For each child code group, the method resolves the code group with the same evidence; if the result is not `null`, it sets P equal to the union of P and the child code group's policy statement. It then returns P, which is now the union of the current code group's policy statement and all child group policy statements. + ]]> The parameter is . @@ -311,11 +311,11 @@ Resolves matching code groups. The complete set of code groups that were matched by the evidence. - The parameter is . diff --git a/xml/System.Security.Policy/Url.xml b/xml/System.Security.Policy/Url.xml index 24934a474ba..9b23143f984 100644 --- a/xml/System.Security.Policy/Url.xml +++ b/xml/System.Security.Policy/Url.xml @@ -60,18 +60,18 @@ Provides the URL from which a code assembly originates as evidence for policy evaluation. This class cannot be inherited. - evidence produces a in the grant set. If there is a for , the that corresponds to the evidence is compared to the demanded permission. - - The complete URL is considered, including the protocol (HTTP, HTTPS, FTP) and the file. For example, `http://www.fourthcoffee.com/process/grind.htm` is a complete URL. - - URLs can be matched exactly or by a wildcard in the final position. For example, `http://www.fourthcoffee.com/process/*` is a wildcard URL. - + The presence of evidence produces a in the grant set. If there is a for , the that corresponds to the evidence is compared to the demanded permission. + + The complete URL is considered, including the protocol (HTTP, HTTPS, FTP) and the file. For example, `http://www.fourthcoffee.com/process/grind.htm` is a complete URL. + + URLs can be matched exactly or by a wildcard in the final position. For example, `http://www.fourthcoffee.com/process/*` is a wildcard URL. + ]]> diff --git a/xml/System.Security.Policy/Zone.xml b/xml/System.Security.Policy/Zone.xml index ccb9e9fac0a..c1e88eabbcf 100644 --- a/xml/System.Security.Policy/Zone.xml +++ b/xml/System.Security.Policy/Zone.xml @@ -60,16 +60,16 @@ Provides the security zone of a code assembly as evidence for policy evaluation. This class cannot be inherited. - evidence produces a in the grant set. If there is a for , the that corresponds to the evidence will be compared with the demanded permission. - - Zones are defined by the enumeration. - + The presence of evidence produces a in the grant set. If there is a for , the that corresponds to the evidence will be compared with the demanded permission. + + Zones are defined by the enumeration. + ]]> @@ -211,11 +211,11 @@ Creates a new zone with the specified URL. A new zone with the specified URL. - The parameter is . @@ -303,11 +303,11 @@ if the two objects are equal; otherwise, . - objects are equal if they designate the same . - + objects are equal if they designate the same . + ]]> The parameter is not a object. diff --git a/xml/System.Security.Principal/GenericIdentity.xml b/xml/System.Security.Principal/GenericIdentity.xml index 543aaad2597..0e0578c92e1 100644 --- a/xml/System.Security.Principal/GenericIdentity.xml +++ b/xml/System.Security.Principal/GenericIdentity.xml @@ -194,7 +194,7 @@ constructor. This code example is part of a larger example provided for the class. + The following code shows the use of the constructor. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.GenericIdentity2/CPP/genericidentitymembers.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/GenericIdentity/Overview/genericidentitymembers.cs" id="Snippet2"::: @@ -258,7 +258,7 @@ constructor. This code example is part of a larger example provided for the class. + The following code shows the use of the constructor. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.GenericIdentity2/CPP/genericidentitymembers.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/GenericIdentity/Overview/genericidentitymembers.cs" id="Snippet3"::: diff --git a/xml/System.Security.Principal/GenericPrincipal.xml b/xml/System.Security.Principal/GenericPrincipal.xml index dd13f9f569a..44550fd5c3b 100644 --- a/xml/System.Security.Principal/GenericPrincipal.xml +++ b/xml/System.Security.Principal/GenericPrincipal.xml @@ -146,7 +146,7 @@ constructor. This code example is part of a larger example provided for the class. + The following code shows the use of the constructor. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.GenericPrincipal2/CPP/genericprincipalmembers.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/GenericPrincipal/Overview/genericprincipalmembers.cs" id="Snippet2"::: @@ -283,7 +283,7 @@ method. This code example is part of a larger example provided for the class. + The following code shows the use of the method. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.GenericPrincipal2/CPP/genericprincipalmembers.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/GenericPrincipal/Overview/genericprincipalmembers.cs" id="Snippet4"::: diff --git a/xml/System.Security.Principal/IIdentity.xml b/xml/System.Security.Principal/IIdentity.xml index 573ce4db967..299c8186d94 100644 --- a/xml/System.Security.Principal/IIdentity.xml +++ b/xml/System.Security.Principal/IIdentity.xml @@ -62,11 +62,11 @@ Defines the basic functionality of an identity object. - and classes. - + and classes. + ]]> @@ -116,11 +116,11 @@ Gets the type of authentication used. The type of authentication used to identify the user. - @@ -170,11 +170,11 @@ if the user was authenticated; otherwise, . - @@ -224,13 +224,13 @@ Gets the name of the current user. The name of the user on whose behalf the code is running. - is typically set to an empty string ("") for an unauthenticated entity, but can take other values. - + is typically set to an empty string ("") for an unauthenticated entity, but can take other values. + ]]> diff --git a/xml/System.Security.Principal/IdentityReference.xml b/xml/System.Security.Principal/IdentityReference.xml index c1416cd9037..8d746f4b4a9 100644 --- a/xml/System.Security.Principal/IdentityReference.xml +++ b/xml/System.Security.Principal/IdentityReference.xml @@ -152,8 +152,8 @@ - The type being queried for validity to serve as a conversion from . The following target types are valid: - + The type being queried for validity to serve as a conversion from . The following target types are valid: + . Returns a value that indicates whether the specified type is a valid translation type for the class. @@ -202,7 +202,7 @@ if and are equal; otherwise, . - .]]> + .]]> @@ -247,7 +247,7 @@ if and are not equal; otherwise, . - .]]> + .]]> diff --git a/xml/System.Security.Principal/PrincipalPolicy.xml b/xml/System.Security.Principal/PrincipalPolicy.xml index 22e1cf42f3d..4d5c67e19ba 100644 --- a/xml/System.Security.Principal/PrincipalPolicy.xml +++ b/xml/System.Security.Principal/PrincipalPolicy.xml @@ -66,13 +66,13 @@ Specifies how principal and identity objects should be created for an application domain. The default is . - method of an . - + method of an . + ]]> diff --git a/xml/System.Security.Principal/WindowsAccountType.xml b/xml/System.Security.Principal/WindowsAccountType.xml index eafa3410ad7..97cdf030fd5 100644 --- a/xml/System.Security.Principal/WindowsAccountType.xml +++ b/xml/System.Security.Principal/WindowsAccountType.xml @@ -40,20 +40,20 @@ Specifies the type of Windows account used. - enumeration is used by the class. - - - -## Examples - The following example shows how to use the constructor to create a new instance of the class for the user represented by the specified Windows account token, the specified authentication type, and the specified Windows account type. This code example is part of a larger example provided for the class. - + enumeration is used by the class. + + + +## Examples + The following example shows how to use the constructor to create a new instance of the class for the user represented by the specified Windows account token, the specified authentication type, and the specified Windows account type. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsAccountType/Overview/Form1.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsAccountType/Overview/Form1.vb" id="Snippet7"::: + ]]> diff --git a/xml/System.Security.Principal/WindowsBuiltInRole.xml b/xml/System.Security.Principal/WindowsBuiltInRole.xml index 8db1276d6b7..a25c6717b43 100644 --- a/xml/System.Security.Principal/WindowsBuiltInRole.xml +++ b/xml/System.Security.Principal/WindowsBuiltInRole.xml @@ -41,23 +41,23 @@ Specifies common roles to be used with . - [!NOTE] -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator. - - - -## Examples - The following example shows the use of the enumeration. - +> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator. + + + +## Examples + The following example shows the use of the enumeration. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsBuiltInRole Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsBuiltInRole/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsBuiltInRole/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsBuiltInRole/Overview/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Security.Principal/WindowsIdentity.xml b/xml/System.Security.Principal/WindowsIdentity.xml index cb52580748c..c4fb0558c0e 100644 --- a/xml/System.Security.Principal/WindowsIdentity.xml +++ b/xml/System.Security.Principal/WindowsIdentity.xml @@ -80,10 +80,10 @@ method to create a object that represents the current user. + 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 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. @@ -154,9 +154,9 @@ |Property|Initial value| |--------------|-------------------| -||`Negotiate`| +||`Negotiate`| ||`Normal`| -||`false`| +||`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). @@ -331,9 +331,9 @@ |Property|Initial value| |--------------|-------------------| ||`Normal`| -||`false`| +||`false`| - 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. + 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). @@ -341,7 +341,7 @@ ## Examples - The following code shows the use of the constructor to create a new instance of the class for the user represented by the specified Windows account token and the specified authentication type. This code example is part of a larger example provided for the class. + The following code shows the use of the constructor to create a new instance of the class for the user represented by the specified Windows account token and the specified authentication type. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet4"::: @@ -462,7 +462,7 @@ 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. + 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. 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. @@ -538,9 +538,9 @@ |Property|Initial Value| |--------------|-------------------| -||`false`| +||`false`| - 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. + 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). @@ -548,7 +548,7 @@ ## Examples - The following code shows the use of the constructor to create a new instance of the class for the user represented by the specified Windows account token, the specified authentication type, and the specified Windows account type. This code example is part of a larger example provided for the class. + The following code shows the use of the constructor to create a new instance of the class for the user represented by the specified Windows account token, the specified authentication type, and the specified Windows account type. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet7"::: @@ -618,14 +618,14 @@ 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. + 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. 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). ## Examples - The following code shows the use of the constructor to create a new instance of the class for the user represented by the specified Windows account token, the specified authentication type, the specified Windows account type, and the specified authentication status. This code example is part of a larger example provided for the class. + The following code shows the use of the constructor to create a new instance of the class for the user represented by the specified Windows account token, the specified authentication type, the specified Windows account type, and the specified authentication status. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet17"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet17"::: @@ -963,10 +963,10 @@ 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). + 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. ]]> @@ -1066,7 +1066,7 @@ > This member is removed in the .NET Framework version 2.0 and subsequent versions. -Application code does not call this method; it is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled. For more information, see and . This method overrides . +Application code does not call this method; it is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled. For more information, see and . This method overrides . ]]> @@ -1116,14 +1116,14 @@ Application code does not call this method; it is automatically invoked during g object that enables you to treat operations as anonymous. The property value does not correspond to a Windows anonymous user and cannot be used for impersonation. Also, note that the identity returned by this property is not static; each call to returns a different anonymous identity. + This property returns an empty object that enables you to treat operations as anonymous. The property value does not correspond to a Windows anonymous user and cannot be used for impersonation. Also, note that the identity returned by this property is not static; each call to returns a different anonymous identity. - You can use the property to detect the return value from . However, detects both the Windows anonymous identity and the anonymous identity returned by this method. To use the latter identity, cache the return value instead of relying on the property. + You can use the property to detect the return value from . However, detects both the Windows anonymous identity and the anonymous identity returned by this method. To use the latter identity, cache the return value instead of relying on the property. ## Examples - The following code shows the use of the method to return a object that represents an anonymous Windows user. This code example is part of a larger example provided for the class. + The following code shows the use of the method to return a object that represents an anonymous Windows user. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet15"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet15"::: @@ -1186,7 +1186,7 @@ Application code does not call this method; it is automatically invoked during g method to return a object that represents the current Windows user. This code example is part of a larger example provided for the class. + The following code shows the use of the method to return a object that represents the current Windows user. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet13"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet13"::: @@ -1466,7 +1466,7 @@ Application code does not call this method; it is automatically invoked during g On Windows NT platforms, the current user must have sufficient rights to allow impersonation. > [!NOTE] -> Calling the method with a `userToken` value of is equivalent to calling the Win32 `RevertToSelf` function. If another user is currently being impersonated, control reverts to the original user. +> Calling the method with a `userToken` value of is equivalent to calling the Win32 `RevertToSelf` function. If another user is currently being impersonated, control reverts to the original user. For more information about calls to unmanaged code, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). @@ -1595,7 +1595,7 @@ Application code does not call this method; it is automatically invoked during g property detects both the Windows anonymous identity and the anonymous identity that is returned by the method. + The property detects both the Windows anonymous identity and the anonymous identity that is returned by the method. Anonymous accounts are typically only encountered only from within ASP.NET-based applications when anonymous access is allowed by Internet Information Services (IIS). @@ -2386,7 +2386,7 @@ public class ImpersonationDemo property. The token is released by the method, which you can call in code. is also automatically called by the garbage collector. + Do not explicitly release the account token that is returned by the property. The token is released by the method, which you can call in code. is also automatically called by the garbage collector. > [!NOTE] > The account token that is returned by the property is a duplicate of the Windows token that is used to create the object and is automatically released by the .NET Framework. This is different from the account token (the `userToken` parameter for the constructor), which is used to create the object. `userToken` is a Windows account token that is created by a call to `LogonUser` and must be closed to avoid a memory leak. @@ -2458,7 +2458,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.Principal/WindowsImpersonationContext.xml b/xml/System.Security.Principal/WindowsImpersonationContext.xml index 2ca682166b4..208f8158499 100644 --- a/xml/System.Security.Principal/WindowsImpersonationContext.xml +++ b/xml/System.Security.Principal/WindowsImpersonationContext.xml @@ -40,7 +40,7 @@ This class reverts a user's identity after the user impersonates another 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 have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. @@ -101,10 +101,10 @@ 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). + 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. ]]> @@ -189,7 +189,7 @@ > This member is removed in the .NET Framework version 2.0 and subsequent versions. -Application code does not call this method; it is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled. For more information, see and . This method overrides . +Application code does not call this method; it is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled. For more information, see and . This method overrides . ]]> diff --git a/xml/System.Security.Principal/WindowsPrincipal.xml b/xml/System.Security.Principal/WindowsPrincipal.xml index 04637ce18e9..827bb40fa89 100644 --- a/xml/System.Security.Principal/WindowsPrincipal.xml +++ b/xml/System.Security.Principal/WindowsPrincipal.xml @@ -59,12 +59,12 @@ class is primarily used to check the role of a Windows user. The method overloads let you check the user role by using different role contexts. + The class is primarily used to check the role of a Windows user. The method overloads let you check the user role by using different role contexts. ## Examples - The following example demonstrates how to use the method overloads. The enumeration is used as the source for the relative identifiers (RIDs) that identify the built-in roles. The RIDs are used to determine the roles of the current principal. + The following example demonstrates how to use the method overloads. The enumeration is used as the source for the relative identifiers (RIDs) that identify the built-in roles. The RIDs are used to determine the roles of the current principal. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsBuiltInRole Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsBuiltInRole/Overview/source.cs" id="Snippet1"::: @@ -228,7 +228,7 @@ overload is strongly recommended. + There are four overloads for this method. For performance reasons, the overload is strongly recommended. ]]> @@ -277,16 +277,16 @@ test to return `false`. + When testing for newly created role information, such as a new user or a new group, it is important to log out and log in to force the propagation of role information within the domain. Not doing so can cause the test to return `false`. - For performance reasons, the overload is recommended as the preferable overload for determining the user's role. + For performance reasons, the overload is recommended as the preferable overload for determining the user's role. > [!NOTE] -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator. +> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator. Relative identifiers (RIDs) are components of a Windows user group's security identifier (SID) and are supported to help prevent cross-platform localization issues. Many user accounts, local groups, and global groups have a default RID value that is constant across all versions of Windows. - For example, the RID for the BUILTIN\Administrators role is 0x220. Using 0x220 as the input parameter for the method results in `true` being returned if the current principal is an administrator. + For example, the RID for the BUILTIN\Administrators role is 0x220. Using 0x220 as the input parameter for the method results in `true` being returned if the current principal is an administrator. The following tables list the default RID values. @@ -315,7 +315,7 @@ ## Examples - The following code example demonstrates the use of the methods. The enumeration is used as the source for the RIDs that identify the built-in roles. The RIDs are used to determine the roles of the current principal. + The following code example demonstrates the use of the methods. The enumeration is used as the source for the RIDs that identify the built-in roles. The RIDs are used to determine the roles of the current principal. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsBuiltInRole Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsBuiltInRole/Overview/source.cs" id="Snippet1"::: @@ -377,15 +377,15 @@ uniquely identifies a user or group on Windows. When testing for newly created role information, such as a new user or a new group, it is important to log out and log in to force the propagation of role information within the domain. Not doing so can cause the test to return `false`. + The uniquely identifies a user or group on Windows. When testing for newly created role information, such as a new user or a new group, it is important to log out and log in to force the propagation of role information within the domain. Not doing so can cause the test to return `false`. > [!NOTE] -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator. +> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator. For performance reasons, this is the preferable overload to determine a user's role. ## Examples - The following code example demonstrates the use of the method. The enumeration value is used to determine whether the current principal is an administrator. For the full code example, see the method. + The following code example demonstrates the use of the method. The enumeration value is used to determine whether the current principal is an administrator. For the full code example, see the method. :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsBuiltInRole/Overview/source.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsBuiltInRole/Overview/source.vb" id="Snippet5"::: @@ -440,17 +440,17 @@ test to return `false`. + When testing for newly created role information, such as a new user or a new group, it is important to log out and log in to force the propagation of role information within the domain. Not doing so can cause the test to return `false`. - For performance reasons, the overload is recommended as the preferable overload for determining the user's role. + For performance reasons, the overload is recommended as the preferable overload for determining the user's role. > [!NOTE] -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator. +> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator. ## Examples - The following example uses the enumeration is used to determine whether the current principal is an . For the full code example, see the method. + The following example uses the enumeration is used to determine whether the current principal is an . For the full code example, see the method. :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsBuiltInRole/Overview/source.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsBuiltInRole/Overview/source.vb" id="Snippet4"::: @@ -517,12 +517,12 @@ test to return `false`. + When testing for newly created role information, such as a new user or a new group, it is important to log out and log in to force the propagation of role information within the domain. Not doing so can cause the test to return `false`. - For performance reasons, the overload is recommended as the preferable overload for determining the user's role. + For performance reasons, the overload is recommended as the preferable overload for determining the user's role. > [!NOTE] -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator. +> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator. For built-in roles, the `role` string should be in the form "BUILTIN\\*RoleNameHere*". For example, to test for membership in the Windows administrator role, the string representing the role should be "BUILTIN\Administrators". Note that the backslash might need to be escaped. The following table lists the built-in roles. @@ -550,9 +550,9 @@ ## Examples - The following code example demonstrates the use of the method. + The following code example demonstrates the use of the method. - The strings `BUILTIN\Administrators` and `BUILTIN\Users` are used to determine whether the current principal is an administrator or a user. For the full code example, see the method. + The strings `BUILTIN\Administrators` and `BUILTIN\Users` are used to determine whether the current principal is an administrator or a user. For the full code example, see the method. :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsBuiltInRole/Overview/source.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsBuiltInRole/Overview/source.vb" id="Snippet3"::: diff --git a/xml/System.Security.RightsManagement/ContentGrant.xml b/xml/System.Security.RightsManagement/ContentGrant.xml index 851bb0ae08f..11afd40dc90 100644 --- a/xml/System.Security.RightsManagement/ContentGrant.xml +++ b/xml/System.Security.RightsManagement/ContentGrant.xml @@ -90,7 +90,7 @@ - The property is set to ., which indicates there is no ending limitation. - Use the alternate constructor to create an instance with date and time limitations. + Use the alternate constructor to create an instance with date and time limitations. ]]> diff --git a/xml/System.Security.RightsManagement/ContentUser.xml b/xml/System.Security.RightsManagement/ContentUser.xml index 9a57ab386ca..1986194ddff 100644 --- a/xml/System.Security.RightsManagement/ContentUser.xml +++ b/xml/System.Security.RightsManagement/ContentUser.xml @@ -123,9 +123,9 @@ has "Internal" and "Anyone". + has "Internal" and "Anyone". - If "Internal" with "Anyone" is granted rights during publishing, the authentication server will issue a to any request and will attach the license to the requesting user. + If "Internal" with "Anyone" is granted rights during publishing, the authentication server will issue a to any request and will attach the license to the requesting user. ]]> @@ -257,9 +257,9 @@ is authenticated based on the given . + The given user is authenticated based on the given . - After a user has been authenticated and is `true`, the user dialog and prompt to confirm authentication is no longer displayed when creating a . + After a user has been authenticated and is `true`, the user dialog and prompt to confirm authentication is no longer displayed when creating a . ]]> @@ -324,9 +324,9 @@ has "Internal" and "Owner". + has "Internal" and "Owner". - is used by the server-side templates to give special rights to the content author or publisher when the protected document is created. + is used by the server-side templates to give special rights to the content author or publisher when the protected document is created. ]]> diff --git a/xml/System.Security.RightsManagement/CryptoProvider.xml b/xml/System.Security.RightsManagement/CryptoProvider.xml index 4bffa9f0d91..f660f4a8112 100644 --- a/xml/System.Security.RightsManagement/CryptoProvider.xml +++ b/xml/System.Security.RightsManagement/CryptoProvider.xml @@ -37,7 +37,7 @@ is created as a result of the method when binding a rights managed to a . + is created as a result of the method when binding a rights managed to a . As with other types, is only usable in full trust applications. @@ -85,13 +85,13 @@ and must be n* bytes in length, where 'n' is an integer greater than or equal to 1. + The `clearText` and `cipherText` buffers passed to and must be n* bytes in length, where 'n' is an integer greater than or equal to 1. - If is `false`, buffers passed to must be the same length as the buffers passed to . + If is `false`, buffers passed to must be the same length as the buffers passed to . - If is `true`, buffers passed to can be a different length from the buffers passed to (all buffer sizes must still always be a multiple of bytes in length). + If is `true`, buffers passed to can be a different length from the buffers passed to (all buffer sizes must still always be a multiple of bytes in length). - A of 1 indicates that the cipher is a stream cipher; a of 2 or greater indicates a block cipher. + A of 1 indicates that the cipher is a stream cipher; a of 2 or greater indicates a block cipher. @@ -175,7 +175,7 @@ returns `true` if the bound to this grants the user read access rights such as View, Edit, Print, or Owner. + returns `true` if the bound to this grants the user read access rights such as View, Edit, Print, or Owner. @@ -222,7 +222,7 @@ returns `true` if the bound to this grants the user write access rights such as Edit or Owner. + returns `true` if the bound to this grants the user write access rights such as Edit or Owner. ]]> @@ -261,11 +261,11 @@ and must be n* bytes in length, where 'n' is an integer greater than or equal to 1. + The `clearText` and `cipherText` buffers passed to and must be n* bytes in length, where 'n' is an integer greater than or equal to 1. - If is `false`, buffers passed to must be the same length as the buffers passed to . + If is `false`, buffers passed to must be the same length as the buffers passed to . - If is `true`, buffers passed to can be a different length from the buffers passed to (all buffer sizes must still always be a multiple of bytes in length). + If is `true`, buffers passed to can be a different length from the buffers passed to (all buffer sizes must still always be a multiple of bytes in length). ]]> @@ -305,7 +305,7 @@ method to convert encrypted data to unencrypted data. + The following example shows how to use the method to convert encrypted data to unencrypted data. :::code language="csharp" source="~/snippets/csharp/System.Security.RightsManagement/CryptoProvider/BoundGrants/Window1.xaml.cs" id="Snippetrmcontviewdecrypt"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.RightsManagement/CryptoProvider/BoundGrants/window1.xaml.vb" id="Snippetrmcontviewdecrypt"::: @@ -361,12 +361,12 @@ performs (`true`). + performs (`true`). - 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). + 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. ]]> @@ -461,7 +461,7 @@ ## Examples - The following example shows how to use the method to convert clear-text data to encrypted-text data. + The following example shows how to use the method to convert clear-text data to encrypted-text data. :::code language="csharp" source="~/snippets/csharp/System.Security.RightsManagement/CryptoProvider/BlockSize/Window1.xaml.cs" id="Snippetrmcontpubencrypt"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.RightsManagement/CryptoProvider/BlockSize/window1.xaml.vb" id="Snippetrmcontpubencrypt"::: @@ -505,9 +505,9 @@ performs (`false`). + performs (`false`). - This method overrides . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + This method overrides . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. For more information, see [Finalize Methods and Destructors](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/0s71x931(v%3dvs.100)), [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged), and [Overriding the Finalize Method](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/ddae83kx(v=vs.100)). diff --git a/xml/System.Security.RightsManagement/LocalizedNameDescriptionPair.xml b/xml/System.Security.RightsManagement/LocalizedNameDescriptionPair.xml index ed0420d7911..a1a45ccbe7c 100644 --- a/xml/System.Security.RightsManagement/LocalizedNameDescriptionPair.xml +++ b/xml/System.Security.RightsManagement/LocalizedNameDescriptionPair.xml @@ -103,7 +103,7 @@ property is set as a parameter to the constructor. + The property is set as a parameter to the constructor. ]]> @@ -204,7 +204,7 @@ property is set as a parameter to the constructor. + The property is set as a parameter to the constructor. ]]> diff --git a/xml/System.Security.RightsManagement/PublishLicense.xml b/xml/System.Security.RightsManagement/PublishLicense.xml index 2998a30d283..1ed9db24342 100644 --- a/xml/System.Security.RightsManagement/PublishLicense.xml +++ b/xml/System.Security.RightsManagement/PublishLicense.xml @@ -35,14 +35,14 @@ ## Remarks defines security data about rights, users, and other security-related information. The license defines how a specific user on a specific computer can use specified rights managed content. - The publishing process begins with the document author, who defines rights information in an . Next, the author creates a signed by calling the method of the . The serialized form of the signed can then be provided to end users who can use it to acquire a by calling the method of the . The returned then allows the client application to exercise the rights that were granted to the user. + The publishing process begins with the document author, who defines rights information in an . Next, the author creates a signed by calling the method of the . The serialized form of the signed can then be provided to end users who can use it to acquire a by calling the method of the . The returned then allows the client application to exercise the rights that were granted to the user. As with other types, is only usable in full trust applications. ## Examples - The following example shows how to initialize a by using the method. + The following example shows how to initialize a by using the method. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubencrypt"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: @@ -156,7 +156,7 @@ method suppresses the Windows network authentication dialog box. If the license request is denied because the user does not have permission, prevents the network authentication dialog box from displaying. Use silent acquisition when attempting to obtain licenses in a background task or in a non-user interface that might display confusing dialog boxes. + The method suppresses the Windows network authentication dialog box. If the license request is denied because the user does not have permission, prevents the network authentication dialog box from displaying. Use silent acquisition when attempting to obtain licenses in a background task or in a non-user interface that might display confusing dialog boxes. ]]> @@ -196,7 +196,7 @@ to identify the protected content. + Publishers create a to identify the protected content. ]]> @@ -236,7 +236,7 @@ method allows the license owner and users who were granted to extract the original information that was encrypted when the was created. + The method allows the license owner and users who were granted to extract the original information that was encrypted when the was created. ]]> @@ -379,7 +379,7 @@ property is used by the method when a user acquires a . + The property is used by the method when a user acquires a . ]]> diff --git a/xml/System.Security.RightsManagement/RightsManagementException.xml b/xml/System.Security.RightsManagement/RightsManagementException.xml index 59981272310..f3df5be852e 100644 --- a/xml/System.Security.RightsManagement/RightsManagementException.xml +++ b/xml/System.Security.RightsManagement/RightsManagementException.xml @@ -247,7 +247,7 @@ and properties to create an error message for the user. + The following example shows use of the and properties to create an error message for the user. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgbldsecenv"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: @@ -294,7 +294,7 @@ and properties to create an error message for the user. + The following example shows use of the and properties to create an error message for the user. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgbldsecenv"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: @@ -390,7 +390,7 @@ and properties to create an error message for the user. + The following example shows use of the and properties to create an error message for the user. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgbldsecenv"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: @@ -435,7 +435,7 @@ and properties to create an error message for the user. + The following example shows use of the and properties to create an error message for the user. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgbldsecenv"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: diff --git a/xml/System.Security.RightsManagement/RightsManagementFailureCode.xml b/xml/System.Security.RightsManagement/RightsManagementFailureCode.xml index 49b45c40eef..e39d7d111ba 100644 --- a/xml/System.Security.RightsManagement/RightsManagementFailureCode.xml +++ b/xml/System.Security.RightsManagement/RightsManagementFailureCode.xml @@ -23,14 +23,14 @@ Specifies error conditions that can occur when performing a rights management operation. - and properties to create an error message for the user. - + and properties to create an error message for the user. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgbldsecenv"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: + ]]> diff --git a/xml/System.Security.RightsManagement/SecureEnvironment.xml b/xml/System.Security.RightsManagement/SecureEnvironment.xml index d584c52a9ea..874647361c4 100644 --- a/xml/System.Security.RightsManagement/SecureEnvironment.xml +++ b/xml/System.Security.RightsManagement/SecureEnvironment.xml @@ -81,7 +81,7 @@ method. + The following example shows use of the method. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubsecenv"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubsecenv"::: @@ -147,7 +147,7 @@ method is intended for use with users that are already activated, such as provided in the list returned from . Use the alternate method for users that are not yet activated. + This method is intended for use with users that are already activated, such as provided in the list returned from . Use the alternate method for users that are not yet activated. @@ -200,11 +200,11 @@ method is intended for new users that are not yet activated. + This method is intended for new users that are not yet activated. Activating a new user includes a roundtrip server transaction to obtain the User Certificate and Client License Certificate. - The alternate method can be used if a user is already activated, such as provided in the list returned from . + The alternate method can be used if a user is already activated, such as provided in the list returned from . @@ -263,7 +263,7 @@ The application should call when finished with the . After is called, resources allocated to the are reclaimed by the garbage collector. 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 the last reference to the is released. If is not called, resources allocated to the will not be freed until the garbage collector calls the instance's method. +> Always call before the last reference to the is released. If is not called, resources allocated to the will not be freed until the garbage collector calls the instance's method. ]]> @@ -303,7 +303,7 @@ method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` specifies the `disposing` parameter as `false`. + This method is called by the public method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` specifies the `disposing` parameter as `false`. When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose()` method of each referenced object. @@ -382,7 +382,7 @@ method to determine if given user has been authorized to access rights managed content. + The following example shows use of the method to determine if given user has been authorized to access rights managed content. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubsecenv"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubsecenv"::: diff --git a/xml/System.Security.RightsManagement/UnsignedPublishLicense.xml b/xml/System.Security.RightsManagement/UnsignedPublishLicense.xml index dd470de95c4..0d9a989d7e5 100644 --- a/xml/System.Security.RightsManagement/UnsignedPublishLicense.xml +++ b/xml/System.Security.RightsManagement/UnsignedPublishLicense.xml @@ -35,7 +35,7 @@ ## Remarks defines security data about rights, users, and other security-related information. The license defines how a specific user on a specific computer can use specified rights-managed content. - The publishing process begins with the document author, who defines rights information in an . Next, the authoring application calls the . method to create a signed . The signed can then be provided to the end-user client application which can call to request an end-user . The returned then allows the client application to exercise the rights that are granted to the user. + The publishing process begins with the document author, who defines rights information in an . Next, the authoring application calls the . method to create a signed . The signed can then be provided to the end-user client application which can call to request an end-user . The returned then allows the client application to exercise the rights that are granted to the user. The document author can use the class either to create a signed , or to build and serialize a template. @@ -116,7 +116,7 @@ ` or `` elements are ignored when the is created by the (String) constructor. To specify these values for the publish license, the properties for and must be explicitly set. The following example shows how to explicitly set the and properties. + The `publishLicenseTemplate` XrML `` or `` elements are ignored when the is created by the (String) constructor. To specify these values for the publish license, the properties for and must be explicitly set. The following example shows how to explicitly set the and properties. :::code language="csharp" source="~/snippets/csharp/System.Security.RightsManagement/UnsignedPublishLicense/.ctor/Window1.xaml.cs" id="Snippetrmpkgpubgrants"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.RightsManagement/UnsignedPublishLicense/.ctor/window1.xaml.vb" id="Snippetrmpkgpubgrants"::: @@ -163,7 +163,7 @@ to identify rights-managed content in a and a . + The publisher creates a to identify rights-managed content in a and a . ]]> @@ -257,9 +257,9 @@ specifies the user who owns the . + specifies the user who owns the . - is also associated with the Owner node in the issuance license Extensible Rights Markup Language (XrML). + is also associated with the Owner node in the issuance license Extensible Rights Markup Language (XrML). diff --git a/xml/System.Security.RightsManagement/UseLicense.xml b/xml/System.Security.RightsManagement/UseLicense.xml index 738641d494c..43c14a4f005 100644 --- a/xml/System.Security.RightsManagement/UseLicense.xml +++ b/xml/System.Security.RightsManagement/UseLicense.xml @@ -30,19 +30,19 @@ Represents a license that enables access to protected rights managed content. - types, is only usable in full trust applications. - - - -## Examples - The following example shows how to use this class to initialize a . - + types, is only usable in full trust applications. + + + +## Examples + The following example shows how to use this class to initialize a . + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubencrypt"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: + ]]> @@ -107,13 +107,13 @@ Gets the application data dictionary that contains key/value pairs passed from the publishing application to the consuming application. The application data dictionary that contains key/value pairs passed from the publishing application to the consuming application. - @@ -149,21 +149,21 @@ Binds the license to a given . A instance if the license binding succeeded; otherwise, . - instance provides decryption and access to the protected rights managed content. - - - -## Examples - The following example shows how to use this method to initialize a . - + instance provides decryption and access to the protected rights managed content. + + + +## Examples + The following example shows how to use this method to initialize a . + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubencrypt"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: + ]]> @@ -197,11 +197,11 @@ Gets the content identifier created by the publisher. The content identifier created by the publisher. - is created by the publisher and can be used to match content to a and . - + is created by the publisher and can be used to match content to a and . + ]]> @@ -238,11 +238,11 @@ if both licenses are the equivalent; otherwise, . - tests for equivalence comparing the serialized Extensible Rights Markup Language (XrML) strings specified to the constructors. - + tests for equivalence comparing the serialized Extensible Rights Markup Language (XrML) strings specified to the constructors. + ]]> @@ -276,11 +276,11 @@ Returns the hash code associated with this license. A hash code for this license. - constructor. - + constructor. + ]]> @@ -312,11 +312,11 @@ Gets the owner of the license. The owner of the license. - constructor. - + constructor. + ]]> diff --git a/xml/System.Security.RightsManagement/UserActivationMode.xml b/xml/System.Security.RightsManagement/UserActivationMode.xml index 93be2ce2446..0c40b03144e 100644 --- a/xml/System.Security.RightsManagement/UserActivationMode.xml +++ b/xml/System.Security.RightsManagement/UserActivationMode.xml @@ -23,19 +23,19 @@ Specifies the type of user Rights Account Certificate to request for rights management activation. - method of a , specifies to request either a `Temporary` or `Permanent` [Rights Account Certificate](https://go.microsoft.com/fwlink/?LinkId=74474). - - - -## Examples - The following example shows how to use this enumeration to create a . - + method of a , specifies to request either a `Temporary` or `Permanent` [Rights Account Certificate](https://go.microsoft.com/fwlink/?LinkId=74474). + + + +## Examples + The following example shows how to use this enumeration to create a . + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubsecenv"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubsecenv"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubsecenv"::: + ]]> diff --git a/xml/System.Security/CodeAccessPermission.xml b/xml/System.Security/CodeAccessPermission.xml index 1f6509861d2..59e6ee4ace7 100644 --- a/xml/System.Security/CodeAccessPermission.xml +++ b/xml/System.Security/CodeAccessPermission.xml @@ -170,14 +170,14 @@ prevents a stack walk originating lower in the call stack from proceeding up the call stack beyond the code that calls this method. Therefore, even if callers higher on the call stack do not have the requisite permissions to access a resource, they can still access it through the code that calls this method on the necessary permission. An assertion is effective only if the code that calls passes the security check for the permission that it is asserting. + The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack. Calling prevents a stack walk originating lower in the call stack from proceeding up the call stack beyond the code that calls this method. Therefore, even if callers higher on the call stack do not have the requisite permissions to access a resource, they can still access it through the code that calls this method on the necessary permission. An assertion is effective only if the code that calls passes the security check for the permission that it is asserting. - The call to is effective until the calling code returns to its caller. Only one can be active on a frame. An attempt to call when an active exists on the frame results in a . Call or to remove an active . + The call to is effective until the calling code returns to its caller. Only one can be active on a frame. An attempt to call when an active exists on the frame results in a . Call or to remove an active . - is ignored for a permission not granted because a demand for that permission will not succeed. However, if code lower on the call stack calls for that permission, a is thrown when the stack walk reaches the code that tried to call . This happens because the code that called has not been granted the permission, even though it tried to it. + is ignored for a permission not granted because a demand for that permission will not succeed. However, if code lower on the call stack calls for that permission, a is thrown when the stack walk reaches the code that tried to call . This happens because the code that called has not been granted the permission, even though it tried to it. > [!CAUTION] -> Because calling removes the requirement that all code in the call chain must be granted permission to access the specified resource, it can open up security issues if used incorrectly or inappropriately. Therefore, it should be used with great caution. +> Because calling removes the requirement that all code in the call chain must be granted permission to access the specified resource, it can open up security issues if used incorrectly or inappropriately. Therefore, it should be used with great caution. ]]> @@ -289,9 +289,9 @@ for the necessary before performing a file operation requested by the caller. + This method is typically used by secure libraries to ensure that callers have permission to access a resource. For example, a file class in a secure class library calls for the necessary before performing a file operation requested by the caller. - The permissions of the code that calls this method are not examined; the check begins from the immediate caller of that code and proceeds up the stack. The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack. succeeds only if no is raised. + The permissions of the code that calls this method are not examined; the check begins from the immediate caller of that code and proceeds up the stack. The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack. succeeds only if no is raised. ]]> @@ -361,13 +361,13 @@ ## Remarks > [!IMPORTANT] -> The method should be used only to protect resources from accidental access by fully trusted code. It should not be used to protect resources from intentional misuse by untrusted code. For example, if method `A` issues a for a permission and then calls method `B`, method `B` can overtly override the by issuing an . The called method is always higher in the stack. Therefore, if method `B` tries to access a protected resource, the security system begins checking for permissions with it because method `B` is the immediate caller, and then walks down the stack to confirm that there is no or lower in the stack. Method `B`, which is trying to access the resource, can stop the stack walk immediately by using the method. In that case, the placed on the stack by method `A` (the calling method) is never discovered. +> The method should be used only to protect resources from accidental access by fully trusted code. It should not be used to protect resources from intentional misuse by untrusted code. For example, if method `A` issues a for a permission and then calls method `B`, method `B` can overtly override the by issuing an . The called method is always higher in the stack. Therefore, if method `B` tries to access a protected resource, the security system begins checking for permissions with it because method `B` is the immediate caller, and then walks down the stack to confirm that there is no or lower in the stack. Method `B`, which is trying to access the resource, can stop the stack walk immediately by using the method. In that case, the placed on the stack by method `A` (the calling method) is never discovered. This method prevents callers higher in the call stack from accessing the protected resource through the code that calls this method, even if those callers have been granted permission to access it. The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack. - can limit the liability of the programmer or help prevent accidental security issues because it helps prevent the method that calls from being used to access the resource protected by the denied permission. If a method calls on a permission, and if a for that permission is invoked by a caller lower in the call stack, that security check will fail when it reaches the . + can limit the liability of the programmer or help prevent accidental security issues because it helps prevent the method that calls from being used to access the resource protected by the denied permission. If a method calls on a permission, and if a for that permission is invoked by a caller lower in the call stack, that security check will fail when it reaches the . - The call to is effective until the calling code returns to its caller. Only one can be active on a frame. An attempt to call when an active exists on the frame results in a . Call or to remove an active . is ignored for a permission not granted because a demand for that permission will not succeed. + The call to is effective until the calling code returns to its caller. Only one can be active on a frame. An attempt to call when an active exists on the frame results in a . Call or to remove an active . is ignored for a permission not granted because a demand for that permission will not succeed. ]]> @@ -424,7 +424,7 @@ . + For more information, see . ]]> @@ -473,7 +473,7 @@ and methods to make the objects security-encodable. + Custom code that extends security objects needs to implement the and methods to make the objects security-encodable. ]]> @@ -638,7 +638,7 @@ ## Remarks The current permission is a subset of the specified permission if the current permission specifies a set of operations that is wholly contained by the specified permission. For example, a permission that represents access to C:\example.txt is a subset of a permission that represents access to C:\\. If this method returns `true`, the current permission represents no more access to the protected resource than does the specified permission. - The following statements are required to be `true` for all overrides of the method. *X*, *Y*, and *Z* represent custom code access permission objects that are not null references, *U* represents an unrestricted code access permission, and *N* represents an empty permission with a of . + The following statements are required to be `true` for all overrides of the method. *X*, *Y*, and *Z* represent custom code access permission objects that are not null references, *U* represents an unrestricted code access permission, and *N* represents an empty permission with a of . - *X*.IsSubsetOf(*X*) returns `true`. - *X*.IsSubsetOf(*Y*) returns the same value as *Y*.IsSubsetOf(*X*) if and only if *X* and *Y* represent the same set of permissions. @@ -705,13 +705,13 @@ ## Remarks > [!IMPORTANT] -> The method should be used only to protect resources from accidental access by fully trusted code. It should not be used to protect resources from intentional misuse by untrusted code. For example, if method `A` issues a for a permission and then calls method `B`, method `B` can overtly override the by issuing an . The called method is always higher in the stack. Therefore, if method `B` tries to access a protected resource, the security system begins checking for permissions with it because method `B` is the immediate caller, and then walks down the stack to confirm that there is no or lower in the stack. Method `B`, which is trying to access the resource, can stop the stack walk immediately by using the method. In that case, the placed on the stack by method `A` (the calling method) is never discovered. +> The method should be used only to protect resources from accidental access by fully trusted code. It should not be used to protect resources from intentional misuse by untrusted code. For example, if method `A` issues a for a permission and then calls method `B`, method `B` can overtly override the by issuing an . The called method is always higher in the stack. Therefore, if method `B` tries to access a protected resource, the security system begins checking for permissions with it because method `B` is the immediate caller, and then walks down the stack to confirm that there is no or lower in the stack. Method `B`, which is trying to access the resource, can stop the stack walk immediately by using the method. In that case, the placed on the stack by method `A` (the calling method) is never discovered. - is similar to , in that both cause stack walks to fail when they would otherwise succeed. The difference is that specifies permissions that will cause the stack walk to fail, but specifies the only permissions that do not cause the stack walk to fail. + is similar to , in that both cause stack walks to fail when they would otherwise succeed. The difference is that specifies permissions that will cause the stack walk to fail, but specifies the only permissions that do not cause the stack walk to fail. - Call this method to ensure that your code can be used to access only the specified resources. The call to is effective until the calling code returns to its caller. Only one can be active on a frame. An attempt to call when an active exists on the frame results in a . Call or to remove an active . + Call this method to ensure that your code can be used to access only the specified resources. The call to is effective until the calling code returns to its caller. Only one can be active on a frame. An attempt to call when an active exists on the frame results in a . Call or to remove an active . - is ignored for a permission not granted because a demand for that permission will not succeed. However, if code lower on the call stack later calls for that permission, a is thrown when the stack walk reaches the code that tried to call . This is because the code that called has not been granted the permission, even though it called for that permission. The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack. + is ignored for a permission not granted because a demand for that permission will not succeed. However, if code lower on the call stack later calls for that permission, a is thrown when the stack walk reaches the code that tried to call . This is because the code that called has not been granted the permission, even though it called for that permission. The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack. ]]> @@ -764,7 +764,7 @@ , , or ) for the current frame, an is thrown. + If there are no overrides (, , or ) for the current frame, an is thrown. ]]> @@ -814,7 +814,7 @@ for the current frame, an is thrown. + If there is no for the current frame, an is thrown. ]]> @@ -872,7 +872,7 @@ for the current frame, an is thrown. + If there is no for the current frame, an is thrown. ]]> @@ -922,7 +922,7 @@ for the current frame, an is thrown. + If there is no for the current frame, an is thrown. ]]> @@ -1014,7 +1014,7 @@ and methods to make the objects security-encodable. + Custom code that extends security objects needs to implement the and methods to make the objects security-encodable. ]]> @@ -1067,7 +1067,7 @@ is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. + The result of a call to is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. ]]> diff --git a/xml/System.Security/HostProtectionException.xml b/xml/System.Security/HostProtectionException.xml index 3e846380d2b..e5d41ffd7da 100644 --- a/xml/System.Security/HostProtectionException.xml +++ b/xml/System.Security/HostProtectionException.xml @@ -114,8 +114,8 @@ |Property|Value| |--------------|-----------| -||| -||| +||| +||| ]]> @@ -402,7 +402,7 @@ method sets a object with all the exception object data targeted for serialization. During deserialization, the exception is reconstructed from the transmitted over the stream. + The method sets a object with all the exception object data targeted for serialization. During deserialization, the exception is reconstructed from the transmitted over the stream. ]]> diff --git a/xml/System.Security/HostSecurityManager.xml b/xml/System.Security/HostSecurityManager.xml index 0ea86b5b70c..063f6d33a02 100644 --- a/xml/System.Security/HostSecurityManager.xml +++ b/xml/System.Security/HostSecurityManager.xml @@ -160,7 +160,7 @@ ## Examples - The following example shows how to override the method for a custom host security manager. This example is part of a larger example provided for the class. + The following example shows how to override the method for a custom host security manager. This example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/HostSecurityManager/Overview/customsecuritymanager.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/HostSecurityManager/Overview/customsecuritymanager.vb" id="Snippet3"::: @@ -329,20 +329,20 @@ ## Remarks This method can be overridden by a derived class. The base implementation returns `null`. - The common language runtime calls this method when evidence of the specified type is needed for the current . The returned value is used as host-supplied evidence, and is stored in the collection of the property. You can use the method to obtain the generated evidence from the collection. + The common language runtime calls this method when evidence of the specified type is needed for the current . The returned value is used as host-supplied evidence, and is stored in the collection of the property. You can use the method to obtain the generated evidence from the collection. To get a callback to this method, hosts must specify the flag in the property. - This method of generating evidence allows hosts to delay evidence generation for an until the evidence is needed. In the .NET Framework version 3.5 and earlier versions, it was necessary to provide evidence at load time by overriding the method. We recommend that you use to provide evidence instead of overriding . + This method of generating evidence allows hosts to delay evidence generation for an until the evidence is needed. In the .NET Framework version 3.5 and earlier versions, it was necessary to provide evidence at load time by overriding the method. We recommend that you use to provide evidence instead of overriding . - The method is called back into only for types of evidence that the host has specified in the override of the method. + The method is called back into only for types of evidence that the host has specified in the override of the method. A return value of `null` indicates that the host cannot generate evidence of this specific type. ## Examples - The following example shows how to override the method for a custom host security manager. This example is part of a larger example provided for the class. + The following example shows how to override the method for a custom host security manager. This example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/HostSecurityManager/Overview/customsecuritymanager.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/HostSecurityManager/Overview/customsecuritymanager.vb" id="Snippet6"::: @@ -393,13 +393,13 @@ ## Remarks This method can be overridden by a derived class. The base implementation returns `null`. - The common language runtime calls this method when evidence of the specified type is needed for the current assembly. The returned value is used as host-supplied evidence, and is stored in the property. You can use the method to obtain the generated evidence from the property. + The common language runtime calls this method when evidence of the specified type is needed for the current assembly. The returned value is used as host-supplied evidence, and is stored in the property. You can use the method to obtain the generated evidence from the property. To get a callback to this method, hosts must specify the flag in the property. - This method of generating evidence allows hosts to delay evidence generation for an until the evidence is needed. In the .NET Framework 3.5 and earlier versions, it was necessary to provide evidence at load time by overriding the method. We recommend that you use to provide evidence instead of overriding . + This method of generating evidence allows hosts to delay evidence generation for an until the evidence is needed. In the .NET Framework 3.5 and earlier versions, it was necessary to provide evidence at load time by overriding the method. We recommend that you use to provide evidence instead of overriding . - The method is called back into only for types of evidence that the host has specified in the override of the method. + The method is called back into only for types of evidence that the host has specified in the override of the method. A return value of `null` indicates that the host cannot generate evidence of this specific type. @@ -444,7 +444,7 @@ ## Remarks This method can be overridden by a derived class. The base implementation returns `null`. - The types returned by this method determine whether the method is called back into. The presence of a type in this list does not mean that the host must be able to generate this evidence type, but that it may be able to. For that reason, it is best to over-specify rather than under-specify the types in this list. + The types returned by this method determine whether the method is called back into. The presence of a type in this list does not mean that the host must be able to generate this evidence type, but that it may be able to. For that reason, it is best to over-specify rather than under-specify the types in this list. ]]> @@ -490,7 +490,7 @@ ## Remarks This method can be overridden by a derived class. The base implementation returns `null`. - The types returned by this method determine whether the method is called back into. The presence of a type in this list does not mean that the host must be able to generate this evidence type, but that it may be able to. For that reason, it is best to over-specify rather than under-specify the types in this list. + The types returned by this method determine whether the method is called back into. The presence of a type in this list does not mean that the host must be able to generate this evidence type, but that it may be able to. For that reason, it is best to over-specify rather than under-specify the types in this list. ]]> @@ -599,7 +599,7 @@ ## Examples - The following example shows how to override the method for a custom host security manager. This example is part of a larger example provided for the class. + The following example shows how to override the method for a custom host security manager. This example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/HostSecurityManager/Overview/customsecuritymanager.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/HostSecurityManager/Overview/customsecuritymanager.vb" id="Snippet5"::: diff --git a/xml/System.Security/IPermission.xml b/xml/System.Security/IPermission.xml index 79be177dd50..4d0695685e9 100644 --- a/xml/System.Security/IPermission.xml +++ b/xml/System.Security/IPermission.xml @@ -104,7 +104,7 @@ > If you write a new permission, you must implement this interface in your class. > [!IMPORTANT] -> A permission can be accessed by multiple threads. When implementing this interface, you must guarantee that the , , , and method implementations are thread safe. +> A permission can be accessed by multiple threads. When implementing this interface, you must guarantee that the , , , and method implementations are thread safe. ]]> @@ -223,11 +223,11 @@ for the necessary before performing a file operation requested by the caller. + This method is typically used by secure libraries to ensure that callers have permission to access a resource. For example, a file class in a secure class library calls for the necessary before performing a file operation requested by the caller. - Although the majority of the classes that implement this interface method satisfy the security criteria by performing a full stack walk, a stack walk is not necessarily performed. An example of an implementation that does not perform a stack walk is . + Although the majority of the classes that implement this interface method satisfy the security criteria by performing a full stack walk, a stack walk is not necessarily performed. An example of an implementation that does not perform a stack walk is . - When a stack walk is performed, the permissions of the code that calls this method are not examined; the check begins from the immediate caller of that code and proceeds up the stack. The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack. succeeds only if no is raised. + When a stack walk is performed, the permissions of the code that calls this method are not examined; the check begins from the immediate caller of that code and proceeds up the stack. The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack. succeeds only if no is raised. ]]> @@ -293,7 +293,7 @@ ## Remarks The intersection of two permissions is a permission that describes the set of operations they both describe in common. Only a demand that passes both original permissions will pass the intersection. - The following statements are required to be true for all implementations of the method. `X` and `Y` represent object references that are not `null`. + The following statements are required to be true for all implementations of the method. `X` and `Y` represent object references that are not `null`. - `X`.Intersect(`X`) returns a value equal to `X`. - `X`.Intersect(`Y`) returns the same value as `Y`.Intersect(`X`). @@ -365,7 +365,7 @@ ## Remarks The current permission is a subset of the specified permission if the current permission specifies a set of operations that is wholly contained by the specified permission. For example, a permission that represents access to C:\example.txt is a subset of a permission that represents access to C:\\. If this method returns `true`, the current permission represents no more access to the protected resource than does the specified permission. - The following statements are required to be true for all implementations of the method. `X`, `Y`, and `Z` represent objects that are not `null`. + The following statements are required to be true for all implementations of the method. `X`, `Y`, and `Z` represent objects that are not `null`. - `X`.IsSubsetOf(`X`) returns `true`. - `X`.IsSubsetOf(`Y`) returns the same value as `Y`.IsSubsetOf(`X`) if and only if `X` and `Y` represent the same set of permissions. @@ -436,9 +436,9 @@ is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. + The result of a call to is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. - The following statements are required to be true for all implementations of the method. `X` and `Y` represent objects that are not `null`. + The following statements are required to be true for all implementations of the method. `X` and `Y` represent objects that are not `null`. - `X`.Union(`X`) returns an object that has the same value as `X`. - `X`.Union(`Y`) returns an object that has the same value as the object returned by `Y`.Union(`X`). diff --git a/xml/System.Security/ISecurityEncodable.xml b/xml/System.Security/ISecurityEncodable.xml index 43ea9be0cff..e8c8523db1f 100644 --- a/xml/System.Security/ISecurityEncodable.xml +++ b/xml/System.Security/ISecurityEncodable.xml @@ -91,7 +91,7 @@ ## Examples This example shows how to define a permission class for use with code access security. All of the necessary permission interfaces are implemented. - + :::code language="csharp" source="~/snippets/csharp/System.Security/IPermission/Overview/Permission.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/ISecurityEncodable/Overview/permission.vb" id="Snippet1"::: @@ -155,12 +155,12 @@ and methods to make the objects security-encodable. + Custom code that extends security objects needs to implement the and methods to make the objects security-encodable. ## Examples - The following code example demonstrates implementing the method. This code example is part of a larger example provided for the class. + The following code example demonstrates implementing the method. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/IPermission/Overview/Permission.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/ISecurityEncodable/Overview/permission.vb" id="Snippet6"::: @@ -224,12 +224,12 @@ and methods to make the objects security-encodable. + Custom code that extends security objects needs to implement the and methods to make the objects security-encodable. ## Examples - The following code example demonstrates implementing the method. This code example is part of a larger example provided for the class. + The following code example demonstrates implementing the method. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/IPermission/Overview/Permission.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/ISecurityEncodable/Overview/permission.vb" id="Snippet7"::: diff --git a/xml/System.Security/ISecurityPolicyEncodable.xml b/xml/System.Security/ISecurityPolicyEncodable.xml index 6c2ae283cfe..6078c252565 100644 --- a/xml/System.Security/ISecurityPolicyEncodable.xml +++ b/xml/System.Security/ISecurityPolicyEncodable.xml @@ -39,11 +39,11 @@ Supports the methods that convert permission object state to and from an XML element representation. - , with the exception that it includes policy-level context. Policy level is needed to resolve references to named permission sets. - + , with the exception that it includes policy-level context. Policy level is needed to resolve references to named permission sets. + ]]> @@ -87,11 +87,11 @@ The policy-level context to resolve named permission set references. Reconstructs a security object with a specified state from an XML encoding. - and methods to make the objects security-encodable. - + and methods to make the objects security-encodable. + ]]> @@ -134,13 +134,13 @@ Creates an XML encoding of the security object and its current state. The root element of the XML representation of the policy object. - and methods to make the objects security-encodable. - + and methods to make the objects security-encodable. + ]]> diff --git a/xml/System.Security/IStackWalk.xml b/xml/System.Security/IStackWalk.xml index 17596e88ec0..6c93269049d 100644 --- a/xml/System.Security/IStackWalk.xml +++ b/xml/System.Security/IStackWalk.xml @@ -73,16 +73,16 @@ Manages the stack walk that determines whether all callers in the call stack have the required permissions to access a protected resource. - @@ -135,18 +135,18 @@ Asserts that the calling code can access the resource identified by the current permission object, even if callers higher in the stack have not been granted permission to access the resource. - stops the permission check on callers higher in the call stack. Therefore, even if these callers do not have the requisite permissions, they can still access resources. An assertion is effective only if the code that calls passes the security check for the permission that it is asserting. - - A call to is effective until the calling code returns to its caller or until a subsequent call to renders the previous assertion ineffective. Also, or removes a pending . - - is ignored for a permission not granted because a demand for that permission will not succeed. However, if code lower on the call stack calls for that permission, a is thrown when the stack walk reaches the code that tried to call . This happens because the code that called has not been granted the permission, even though it tried to it. - + stops the permission check on callers higher in the call stack. Therefore, even if these callers do not have the requisite permissions, they can still access resources. An assertion is effective only if the code that calls passes the security check for the permission that it is asserting. + + A call to is effective until the calling code returns to its caller or until a subsequent call to renders the previous assertion ineffective. Also, or removes a pending . + + is ignored for a permission not granted because a demand for that permission will not succeed. However, if code lower on the call stack calls for that permission, a is thrown when the stack walk reaches the code that tried to call . This happens because the code that called has not been granted the permission, even though it tried to it. + > [!CAUTION] -> Because calling removes the requirement that all code in the call chain must be granted permission to access the specified resource, it can open up security vulnerabilities if used incorrectly or inappropriately. Therefore, it should be used with great caution. - +> Because calling removes the requirement that all code in the call chain must be granted permission to access the specified resource, it can open up security vulnerabilities if used incorrectly or inappropriately. Therefore, it should be used with great caution. + ]]> The calling code does not have . @@ -201,19 +201,19 @@ Determines at run time whether all callers in the call stack have been granted the permission specified by the current permission object. - for the necessary before performing a file operation requested by the caller. - - The permissions of the code that calls this method are not examined; the check begins from the immediate caller of that code and proceeds up the stack. succeeds only if no is raised. - + for the necessary before performing a file operation requested by the caller. + + The permissions of the code that calls this method are not examined; the check begins from the immediate caller of that code and proceeds up the stack. succeeds only if no is raised. + ]]> - A caller higher in the call stack does not have the permission specified by the current permission object. - - -or- - + A caller higher in the call stack does not have the permission specified by the current permission object. + + -or- + A caller in the call stack has called on the current permission object. @@ -265,15 +265,15 @@ Causes every for the current object that passes through the calling code to fail. - can limit the liability of the programmer or help prevent accidental security vulnerabilities because it helps prevent the method that calls from being used to access the resource protected by the denied permission. If a method calls on a permission, and if a for that permission is invoked by a caller lower in the call stack, that security check will fail when it reaches the . - - is ignored for a permission not granted because a demand for that permission will not succeed. - + can limit the liability of the programmer or help prevent accidental security vulnerabilities because it helps prevent the method that calls from being used to access the resource protected by the denied permission. If a method calls on a permission, and if a for that permission is invoked by a caller lower in the call stack, that security check will fail when it reaches the . + + is ignored for a permission not granted because a demand for that permission will not succeed. + ]]> @@ -329,13 +329,13 @@ Causes every for all objects except the current one that passes through the calling code to fail, even if code higher in the call stack has been granted permission to access other resources. - is similar to , in that both cause stack walks to fail when they would otherwise succeed. The difference is that specifies permissions that will cause the stack walk to fail, but specifies the only permissions that do not cause the stack walk to fail. Call this method to ensure that your code can be used to access only the specified resources. - - is ignored for a permission not granted because a demand for that permission will not succeed. However, if code lower on the call stack later calls for that permission, a is thrown when the stack walk reaches the code that tried to call . This is because the code that called has not been granted the permission, even though it called for that permission. The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack. - + is similar to , in that both cause stack walks to fail when they would otherwise succeed. The difference is that specifies permissions that will cause the stack walk to fail, but specifies the only permissions that do not cause the stack walk to fail. Call this method to ensure that your code can be used to access only the specified resources. + + is ignored for a permission not granted because a demand for that permission will not succeed. However, if code lower on the call stack later calls for that permission, a is thrown when the stack walk reaches the code that tried to call . This is because the code that called has not been granted the permission, even though it called for that permission. The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack. + ]]> diff --git a/xml/System.Security/ManifestKinds.xml b/xml/System.Security/ManifestKinds.xml index 51df2df911f..35d59aa9a92 100644 --- a/xml/System.Security/ManifestKinds.xml +++ b/xml/System.Security/ManifestKinds.xml @@ -27,7 +27,7 @@ ## Remarks This enumeration has two purposes: -- In the method, it specifies which manifests you want to generate signature information for. +- In the method, it specifies which manifests you want to generate signature information for. - In a object, it shows you which manifest the signature information is generated from. diff --git a/xml/System.Security/NamedPermissionSet.xml b/xml/System.Security/NamedPermissionSet.xml index faf2c024cb2..c42fd2ff7d6 100644 --- a/xml/System.Security/NamedPermissionSet.xml +++ b/xml/System.Security/NamedPermissionSet.xml @@ -50,8 +50,8 @@ Defines a permission set that has a name and description associated with it. This class cannot be inherited. - The name for the new named permission set. Initializes a new, empty instance of the class with the specified name. - permission state. A named permission set in an unrestricted state effectively contains all permissions that implement the interface. The named permission set will contain all built-in permissions as well as all custom user-defined permissions that implement . All permissions will have the equivalent of an `Unrestricted` permission state. Permissions that do not implement will be empty instances. - + permission state. A named permission set in an unrestricted state effectively contains all permissions that implement the interface. The named permission set will contain all built-in permissions as well as all custom user-defined permissions that implement . All permissions will have the equivalent of an `Unrestricted` permission state. Permissions that do not implement will be empty instances. + ]]> The parameter is or is an empty string (""). @@ -188,11 +188,11 @@ One of the values. Initializes a new instance of the class with the specified name in either an unrestricted or a fully restricted state. - interface. The named permission set will contain all built-in permissions as well as all custom permissions. All permissions will have an `Unrestricted` . Permissions that do not implement , such as identity permissions, will be empty instances. - + interface. The named permission set will contain all built-in permissions as well as all custom permissions. All permissions will have an `Unrestricted` . Permissions that do not implement , such as identity permissions, will be empty instances. + ]]> The parameter is or is an empty string (""). @@ -359,9 +359,9 @@ Gets or sets the text description of the current named permission set. A text description of the named permission set. - @@ -419,10 +419,10 @@ if the specified is equal to the current object; otherwise, . - . + . ]]> @@ -465,10 +465,10 @@ A security element containing the XML representation of the named permission set. Reconstructs a named permission set with a specified state from an XML encoding. - . + . ]]> @@ -516,11 +516,11 @@ Gets a hash code for the object that is suitable for use in hashing algorithms and data structures such as a hash table. A hash code for the current object. - objects. - + objects. + ]]> @@ -559,9 +559,9 @@ Gets or sets the name of the current named permission set. The name of the named permission set. - @@ -610,10 +610,10 @@ Creates an XML element description of the named permission set. The XML representation of the named permission set. - to recreate the state represented by the returned element. + to recreate the state represented by the returned element. ]]> diff --git a/xml/System.Security/PartialTrustVisibilityLevel.xml b/xml/System.Security/PartialTrustVisibilityLevel.xml index 5b73970f3d1..8a73f7df2fc 100644 --- a/xml/System.Security/PartialTrustVisibilityLevel.xml +++ b/xml/System.Security/PartialTrustVisibilityLevel.xml @@ -46,7 +46,7 @@ is passed as a property setting parameter to the constructor. If no parameter is passed to the constructor, the default is VisibleToAllHosts. + is passed as a property setting parameter to the constructor. If no parameter is passed to the constructor, the default is VisibleToAllHosts. You enable partially trusted assemblies that are identified as NotVisibleByDefault by adding them to the property of their application domain. If you enable an assembly that references (directly or indirectly) other partially trusted assemblies that are NotVisibleByDefault, those other assemblies should be enabled as well. diff --git a/xml/System.Security/PermissionSet.xml b/xml/System.Security/PermissionSet.xml index f54f3e2f938..9376d556123 100644 --- a/xml/System.Security/PermissionSet.xml +++ b/xml/System.Security/PermissionSet.xml @@ -176,7 +176,7 @@ ## Remarks The `Unrestricted` state allows all permissions that implement the interface, while `None` allows no permissions. - Use on an empty to define the set in greater detail. + Use on an empty to define the set in greater detail. ]]> @@ -238,7 +238,7 @@ The new contains copies of the permissions contained in the specified . > [!NOTE] -> This is equivalent to when the `permSet` parameter is not `null`. +> This is equivalent to when the `permSet` parameter is not `null`. ]]> @@ -374,7 +374,7 @@ method is the implementation for the method. + The method is the implementation for the method. If a permission of the same type as the added permission already exists in the , the new permission is the union of the existing permission object and the specified permission object. For example, if a permission that implements is added to an , the resulting union is the original `Unrestricted` . @@ -445,10 +445,10 @@ can be active on a frame. is only effective for granted permissions. Call the or method to cancel an active . + This is the only way to assert multiple permissions at the same time within a frame because only one can be active on a frame. is only effective for granted permissions. Call the or method to cancel an active . > [!CAUTION] -> Because calling the method removes the requirement that all code in the call chain must be granted permission to access the specified resource, it can open up security vulnerabilities if used incorrectly or inappropriately. Therefore, it should be used with great caution. +> Because calling the method removes the requirement that all code in the call chain must be granted permission to access the specified resource, it can open up security vulnerabilities if used incorrectly or inappropriately. Therefore, it should be used with great caution. ]]> @@ -835,9 +835,9 @@ on a to ensure that all callers have all permissions in the set with one operation. + Use on a to ensure that all callers have all permissions in the set with one operation. - The permissions of the code that calls this method are not examined; the check begins from the immediate caller of that code and proceeds up the stack. The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack. succeeds only if no is thrown. + The permissions of the code that calls this method are not examined; the check begins from the immediate caller of that code and proceeds up the stack. The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack. succeeds only if no is thrown. If the contains permissions that do not inherit from , the `Demand` methods of those permissions are called as well. @@ -918,9 +918,9 @@ ## Remarks This method prevents callers higher in the call stack from accessing the protected resource through the code that calls this method, even if those callers have been granted permission to access it. The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack. - can limit the liability of the programmer or help prevent accidental security vulnerabilities because it helps prevent the method that calls from being used to access the resource protected by the denied permission. If a method calls on a permission, and if a for that permission is invoked by a caller lower in the call stack, that security check fails when it reaches the . + can limit the liability of the programmer or help prevent accidental security vulnerabilities because it helps prevent the method that calls from being used to access the resource protected by the denied permission. If a method calls on a permission, and if a for that permission is invoked by a caller lower in the call stack, that security check fails when it reaches the . - is ignored for a permission that is not granted because a demand for that permission cannot succeed. + is ignored for a permission that is not granted because a demand for that permission cannot succeed. ]]> @@ -997,7 +997,7 @@ ## Remarks Equality is determined by the permissions contained in the permission set specified by `obj`. `obj` can be either a object or a object. If `obj` is a , the name and description are ignored. - For more information, see . + For more information, see . ]]> @@ -1180,7 +1180,7 @@ method is the implementation for the method. + The method is the implementation for the method. ]]> @@ -1372,7 +1372,7 @@ method is the implementation for the method. + The method is the implementation for the method. The method returns `null` for an `Unrestricted` . Although an `Unrestricted` effectively contains all permissions, it does not have any actual instances to return. @@ -1844,9 +1844,9 @@ is similar to , in that both cause stack walks to fail when they would otherwise succeed. The difference is that specifies permissions that will cause the stack walk to fail, but specifies the only permissions that do not cause the stack walk to fail. Call this method to ensure that your code can be used to access only the specified resources. + is similar to , in that both cause stack walks to fail when they would otherwise succeed. The difference is that specifies permissions that will cause the stack walk to fail, but specifies the only permissions that do not cause the stack walk to fail. Call this method to ensure that your code can be used to access only the specified resources. - is ignored for a permission not granted because a demand for that permission cannot succeed. However, if code lower on the call stack later calls for that permission, a is thrown when the stack walk reaches the code that tried to call . This is because the code that called has not been granted the permission, even though it called for that permission. The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack. + is ignored for a permission not granted because a demand for that permission cannot succeed. However, if code lower on the call stack later calls for that permission, a is thrown when the stack walk reaches the code that tried to call . This is because the code that called has not been granted the permission, even though it called for that permission. The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack. ]]> @@ -1978,7 +1978,7 @@ method is the implementation for the method. + The method is the implementation for the method. > [!IMPORTANT] > You cannot remove permissions from an unrestricted permission set. The permission set remains unrestricted after you attempt to remove the permission, and an exception is not thrown. @@ -2044,7 +2044,7 @@ for the current frame, an is thrown. + If there is no for the current frame, an is thrown. ]]> @@ -2175,7 +2175,7 @@ method is the implementation for the method. + The method is the implementation for the method. This method removes any existing permission object of the same type from the and replaces it with the `perm` parameter. If a permission that implements is set on a that is , the resulting is no longer `Unrestricted`. @@ -2493,7 +2493,7 @@ is a that represents all the operations represented by the current as well as all the operations represented by the specified . If either set is `Unrestricted`, the union is `Unrestricted` as well. + The result of a call to is a that represents all the operations represented by the current as well as all the operations represented by the specified . If either set is `Unrestricted`, the union is `Unrestricted` as well. ]]> diff --git a/xml/System.Security/ReadOnlyPermissionSet.xml b/xml/System.Security/ReadOnlyPermissionSet.xml index 8ab3b889f30..907c300e285 100644 --- a/xml/System.Security/ReadOnlyPermissionSet.xml +++ b/xml/System.Security/ReadOnlyPermissionSet.xml @@ -22,13 +22,13 @@ Represents a read-only collection that can contain many different types of permissions. - results in an . - - Note that any permission you obtain from the is only a copy of the permission. If the copy is mutable and is changed, the permission that is in the is not changed. - + results in an . + + Note that any permission you obtain from the is only a copy of the permission. If the copy is mutable and is changed, the permission that is in the is not changed. + ]]> @@ -125,18 +125,18 @@ The XML encoding to use to reconstruct the security object. Reconstructs a security object with a specified state from an XML encoding. - is intended to be called by the base class when it is deserializing the permission set. An exception is thrown if you attempt to call directly. You cannot modify a read-only permission set with a call. - + is intended to be called by the base class when it is deserializing the permission set. An exception is thrown if you attempt to call directly. You cannot modify a read-only permission set with a call. + ]]> The parameter is . - The parameter is not a valid permission element. - - -or- - + The parameter is not a valid permission element. + + -or- + The parameter's version number is not supported. The object is not being deserialized; that is, did not call back into during deserialization. @@ -207,11 +207,11 @@ Gets a value that indicates whether the collection is read-only. Always . - is always read-only, so this value must always be `true`. - + is always read-only, so this value must always be `true`. + ]]> diff --git a/xml/System.Security/SecureString.xml b/xml/System.Security/SecureString.xml index 1c0ce98efa5..48f6ae99e77 100644 --- a/xml/System.Security/SecureString.xml +++ b/xml/System.Security/SecureString.xml @@ -135,7 +135,7 @@ The following example demonstrates how to use a object. It then calls the method to add an array of characters to it. + The following example uses the default (or parameterless) constructor to instantiate a new object. It then calls the method to add an array of characters to it. :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/Overview/Ctor2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecureString/Overview/ctor2.vb" id="Snippet2"::: @@ -295,12 +295,12 @@ The following example demonstrates how to use a , , , , and methods affect the value of a object. + The following example demonstrates how the , , , , and methods affect the value of a object. :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/AppendChar/xat.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecureString/AppendChar/xat.vb" id="Snippet1"::: - The following example demonstrates how the and methods can be used to collect the characters in a password. + The following example demonstrates how the and methods can be used to collect the characters in a password. :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/AppendChar/xchar.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecureString/AppendChar/xchar.vb" id="Snippet1"::: @@ -370,7 +370,7 @@ The following example demonstrates how to use a , , , , and methods affect the value of a object. + The following example demonstrates how the , , , , and methods affect the value of a object. :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/AppendChar/xat.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecureString/AppendChar/xat.vb" id="Snippet1"::: @@ -500,7 +500,7 @@ The following example demonstrates how to use a method writes binary zeroes to the allocated memory that contains the value of this object, then frees the allocated memory. + The method writes binary zeroes to the allocated memory that contains the value of this object, then frees the allocated memory. For more information, see [Garbage Collection](/dotnet/standard/garbage-collection/). @@ -571,12 +571,12 @@ The following example demonstrates how to use a method yields the same results as the method, which inserts a character at the end of a secure string, if the `index` parameter of is set to the length of this instance. + If the implementation uses a protection mechanism, such as encryption, the value of the secure string, if any, is unprotected; `c` is inserted at the specified index position; then the new value is re-protected. The method yields the same results as the method, which inserts a character at the end of a secure string, if the `index` parameter of is set to the length of this instance. ## Examples - The following example demonstrates how the , , , , and methods affect the value of a object. + The following example demonstrates how the , , , , and methods affect the value of a object. :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/AppendChar/xat.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecureString/AppendChar/xat.vb" id="Snippet1"::: @@ -648,7 +648,7 @@ The following example demonstrates how to use a is marked read-only by the method, any attempt to modify the value of the instance throws an . Use the method to test whether a is read-only before attempting to modify it. + After an instance of is marked read-only by the method, any attempt to modify the value of the instance throws an . Use the method to test whether a is read-only before attempting to modify it. ]]> @@ -769,16 +769,16 @@ The following example demonstrates how to use a class with the constructors, and modify the value with the , , , , and methods. + Initialize the text value of an instance of the class with the constructors, and modify the value with the , , , , and methods. - After you have made your final modifications, use the method to make the value of the instance immutable (read-only). After the value is marked as read-only, any further attempt to modify it throws an . + After you have made your final modifications, use the method to make the value of the instance immutable (read-only). After the value is marked as read-only, any further attempt to modify it throws an . - The effect of invoking is permanent because the class provides no means to make the secure string modifiable again. Use the method to test whether an instance of is read-only. + The effect of invoking is permanent because the class provides no means to make the secure string modifiable again. Use the method to test whether an instance of is read-only. ## Examples - The following example demonstrates how the and methods can be used to collect the characters in a password. After the password is collected, it is made read-only. + The following example demonstrates how the and methods can be used to collect the characters in a password. After the password is collected, it is made read-only. :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/AppendChar/xchar.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecureString/AppendChar/xchar.vb" id="Snippet1"::: @@ -855,12 +855,12 @@ The following example demonstrates how to use a , , , , and methods affect the value of a object. + The following example demonstrates how the , , , , and methods affect the value of a object. :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/AppendChar/xat.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecureString/AppendChar/xat.vb" id="Snippet1"::: - The following example demonstrates how the and methods can be used to collect the characters in a password. + The following example demonstrates how the and methods can be used to collect the characters in a password. :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/AppendChar/xchar.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecureString/AppendChar/xchar.vb" id="Snippet1"::: @@ -942,7 +942,7 @@ The following example demonstrates how to use a , , , , and methods affect the value of a object. + The following example demonstrates how the , , , , and methods affect the value of a object. :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/AppendChar/xat.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecureString/AppendChar/xat.vb" id="Snippet1"::: diff --git a/xml/System.Security/SecureStringMarshal.xml b/xml/System.Security/SecureStringMarshal.xml index 9a873f1c4ff..de85ef30812 100644 --- a/xml/System.Security/SecureStringMarshal.xml +++ b/xml/System.Security/SecureStringMarshal.xml @@ -128,11 +128,11 @@ Copies the contents of a managed object to a block of memory allocated from the unmanaged COM task allocator. The address, in unmanaged memory, where the parameter was copied to, or 0 if a null object was supplied. - method is useful for custom marshaling or when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the memory by calling . The characters of the string are copied as ANSI characters. - + method is useful for custom marshaling or when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the memory by calling . The characters of the string are copied as ANSI characters. + ]]> The parameter is . @@ -194,11 +194,11 @@ Copies the contents of a managed object to a block of memory allocated from the unmanaged COM task allocator. The address, in unmanaged memory, where the parameter was copied to, or 0 if a null object was supplied. - method is useful for custom marshaling or when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the memory by calling the method. The characters of the string are copied as Unicode characters. - + method is useful for custom marshaling or when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the memory by calling the method. The characters of the string are copied as Unicode characters. + ]]> The parameter is . @@ -260,11 +260,11 @@ Copies the contents of a managed into unmanaged memory, converting into ANSI format as it copies. The address, in unmanaged memory, to where the parameter was copied, or 0 if a null object was supplied. - method is useful for custom marshaling or when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the memory by calling the method. - + method is useful for custom marshaling or when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the memory by calling the method. + ]]> The parameter is . diff --git a/xml/System.Security/SecurityContext.xml b/xml/System.Security/SecurityContext.xml index 3917b6fbc1f..67092850850 100644 --- a/xml/System.Security/SecurityContext.xml +++ b/xml/System.Security/SecurityContext.xml @@ -67,7 +67,7 @@ The is part of the larger and flows or migrates when the flows or migrates. > [!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 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. ]]> @@ -268,7 +268,7 @@ method is used by infrastructure components to determine whether to transfer the information during asynchronous operations. + The method is used by infrastructure components to determine whether to transfer the information during asynchronous operations. ]]> @@ -313,7 +313,7 @@ method is used by infrastructure components to determine whether to transfer the Windows identity information when the migrates during asynchronous operations. + The method is used by infrastructure components to determine whether to transfer the Windows identity information when the migrates during asynchronous operations. ]]> @@ -362,7 +362,7 @@ method is called by the method to reverse the effect of a prior method call. + The method is called by the method to reverse the effect of a prior method call. ]]> @@ -483,9 +483,9 @@ The common language runtime (CLR) is only aware of the impersonation operations performed using managed code. The CLR has no knowledge of impersonation performed outside of managed code, such as platform invokes to unmanaged code that does the impersonation, or through calls to Win32 functions. To flow identity across asynchronous points you must use the managed and methods. - Use the method on the returned structure to return the object to its previous state. + Use the method on the returned structure to return the object to its previous state. - This method is protected with a for permission. A fully trusted component can call this method to suppress the flow of the information during asynchronous calls. When the flow is suppressed, the method returns `null`. + This method is protected with a for permission. A fully trusted component can call this method to suppress the flow of the information during asynchronous calls. When the flow is suppressed, the method returns `null`. ]]> @@ -537,7 +537,7 @@ ## Remarks Use this method to suppress the flow of the Windows identity when the migrates across asynchronous threads. - Use the method on the returned structure to return the object to its previous state. + Use the method on the returned structure to return the object to its previous state. > [!NOTE] > The common language runtime (CLR) is aware of impersonation operations performed using only managed code, not of impersonation performed outside of managed code, such as through platform invoke to unmanaged code or through direct calls to Win32 functions. Only managed objects can flow across asynchronous points, unless the `alwaysFlowImpersonationPolicy` element has been set to `true` (``). Setting the `alwaysFlowImpersonationPolicy` element to `true` specifies that the Windows identity always flows across asynchronous points, regardless of how impersonation was performed. For more information about flowing unmanaged impersonation across asynchronous points, see [\ Element](/dotnet/framework/configure-apps/file-schema/runtime/alwaysflowimpersonationpolicy-element). diff --git a/xml/System.Security/SecurityCriticalAttribute.xml b/xml/System.Security/SecurityCriticalAttribute.xml index 3a2edda6b42..80c26b891fe 100644 --- a/xml/System.Security/SecurityCriticalAttribute.xml +++ b/xml/System.Security/SecurityCriticalAttribute.xml @@ -66,7 +66,7 @@ > [!IMPORTANT] > Partially trusted code is no longer supported. This attribute has no effect in .NET Core. - Security-critical operations are actions that affect code access security, such as elevation of privilege through suppression of code access security checks by using the method, calling unsafe managed code, and so forth. Either the attribute or the attribute must be applied to code for the code to perform security-critical operations. + Security-critical operations are actions that affect code access security, such as elevation of privilege through suppression of code access security checks by using the method, calling unsafe managed code, and so forth. Either the attribute or the attribute must be applied to code for the code to perform security-critical operations. > [!NOTE] > The is equivalent to a link demand for full trust. A type or member marked with the can be called only by fully trusted code; it does not have to demand specific permissions. It cannot be called by partially trusted code. diff --git a/xml/System.Security/SecurityElement.xml b/xml/System.Security/SecurityElement.xml index 996fb56d3ab..42950ed6217 100644 --- a/xml/System.Security/SecurityElement.xml +++ b/xml/System.Security/SecurityElement.xml @@ -187,12 +187,12 @@ to remove invalid characters from the string. + The `tag` parameter must consist of a valid XML tag name. Use to remove invalid characters from the string. ## Examples - The following code shows the use of the constructor to create a new object. This code example is part of a larger example provided for the class. + The following code shows the use of the constructor to create a new object. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityElement/Overview/securityelementmembers.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecurityElement/Overview/Form1.vb" id="Snippet2"::: @@ -332,14 +332,14 @@ to remove invalid characters from the string. + Names and values in attributes should only contain valid XML attribute characters. XML attribute names must be unique. Use to remove invalid characters from the string. There is no support for quoted strings, so strings for name/value pairs should not contain quotes or other characters requiring quoting. ## Examples - The following code shows the use of the method to add a name/value attribute to an XML element. This code example is part of a larger example provided for the class. + The following code shows the use of the method to add a name/value attribute to an XML element. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityElement/Overview/securityelementmembers.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecurityElement/Overview/Form1.vb" id="Snippet4"::: @@ -415,7 +415,7 @@ ## Examples - The following code shows the use of the method to add a child element to the XML element. This code example is part of a larger example provided for the class. + The following code shows the use of the method to add a child element to the XML element. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityElement/Overview/securityelementmembers.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecurityElement/Overview/Form1.vb" id="Snippet5"::: @@ -498,7 +498,7 @@ ## Examples - The following code shows the use of the method to find an attribute by name. This code example is part of a larger example provided for the class. + The following code shows the use of the method to find an attribute by name. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityElement/Overview/securityelementmembers.cs" id="Snippet13"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecurityElement/Overview/Form1.vb" id="Snippet13"::: @@ -564,7 +564,7 @@ ## Remarks Each attribute is stored in the as a name/value pair. - Names and values in attributes should contain only valid XML attribute characters. Use to remove invalid characters from the string. + Names and values in attributes should contain only valid XML attribute characters. Use to remove invalid characters from the string. There is no support for quoted strings, so strings for name/value pairs should not contain quotes or other characters requiring quoting. @@ -636,7 +636,7 @@ contains both and , will appear first. + If a contains both and , will appear first. @@ -710,7 +710,7 @@ and properties. + The copy includes both the and properties. ]]> @@ -789,7 +789,7 @@ ## Examples - The following code shows the use of the method to compare two XML elements. This code example is part of a larger example provided for the class. + The following code shows the use of the method to compare two XML elements. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityElement/Overview/securityelementmembers.cs" id="Snippet22"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecurityElement/Overview/Form1.vb" id="Snippet22"::: @@ -875,7 +875,7 @@ | `&` | `&` | ## Examples - The following code shows the use of the method to replace invalid XML characters in a string with their valid XML equivalent. This code example is part of a larger example provided for the class. + The following code shows the use of the method to replace invalid XML characters in a string with their valid XML equivalent. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityElement/Overview/securityelementmembers.cs" id="Snippet19"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecurityElement/Overview/Form1.vb" id="Snippet19"::: @@ -1031,7 +1031,7 @@ ## Examples - The following code shows the use of the method to determine whether a string is a valid attribute name. This code example is part of a larger example provided for the class. + The following code shows the use of the method to determine whether a string is a valid attribute name. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityElement/Overview/securityelementmembers.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecurityElement/Overview/Form1.vb" id="Snippet6"::: @@ -1111,7 +1111,7 @@ ## Examples - The following code shows the use of the method to determine whether a string is a valid attribute value. This code example is part of a larger example provided for the class. + The following code shows the use of the method to determine whether a string is a valid attribute value. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityElement/Overview/securityelementmembers.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecurityElement/Overview/Form1.vb" id="Snippet7"::: @@ -1186,12 +1186,12 @@ before setting it. + This can be used to test a before setting it. ## Examples - The following code shows the use of the method to determine whether a string is a valid attribute tag. This code example is part of a larger example provided for the class. + The following code shows the use of the method to determine whether a string is a valid attribute tag. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityElement/Overview/securityelementmembers.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecurityElement/Overview/Form1.vb" id="Snippet10"::: @@ -1266,12 +1266,12 @@ before setting it. + This method can be used to test before setting it. ## Examples - The following code shows the use of the method to determine whether a string is valid as XML element text. This code example is part of a larger example provided for the class. + The following code shows the use of the method to determine whether a string is valid as XML element text. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityElement/Overview/securityelementmembers.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecurityElement/Overview/Form1.vb" id="Snippet9"::: @@ -1354,7 +1354,7 @@ ## Examples - The following code shows the use of the method to find a child by its tag name. This code example is part of a larger example provided for the class. + The following code shows the use of the method to find a child by its tag name. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityElement/Overview/securityelementmembers.cs" id="Snippet17"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecurityElement/Overview/Form1.vb" id="Snippet17"::: @@ -1443,7 +1443,7 @@ ## Examples - The following code shows the use of the method to find a child by its tag name and return the contained text. This code example is part of a larger example provided for the class. + The following code shows the use of the method to find a child by its tag name and return the contained text. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityElement/Overview/securityelementmembers.cs" id="Snippet18"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecurityElement/Overview/Form1.vb" id="Snippet18"::: @@ -1521,7 +1521,7 @@ If this element has child elements, the children will replace `text`. - Assign only valid XML tag strings to this property. Use to remove invalid characters from the string. + Assign only valid XML tag strings to this property. Use to remove invalid characters from the string. @@ -1591,9 +1591,9 @@ to remove invalid characters from the string. + The text should not contain XML special characters. Use to remove invalid characters from the string. - If a contains both and , will appear first. + If a contains both and , will appear first. diff --git a/xml/System.Security/SecurityException.xml b/xml/System.Security/SecurityException.xml index e291b17841f..587f86a9fbb 100644 --- a/xml/System.Security/SecurityException.xml +++ b/xml/System.Security/SecurityException.xml @@ -75,14 +75,14 @@ exception is thrown when a caller does not have the permissions required to access a resource. The following example instantiates a object that includes a object to allow access to UI objects and the Clipboard and a object to prevent registry access. The call to the method means that these permissions will apply regardless of the permissions assigned to the caller. As a result, the attempt to create a registry key throws a . + A exception is thrown when a caller does not have the permissions required to access a resource. The following example instantiates a object that includes a object to allow access to UI objects and the Clipboard and a object to prevent registry access. The call to the method means that these permissions will apply regardless of the permissions assigned to the caller. As a result, the attempt to create a registry key throws a . :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityException/Overview/se_ex1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecurityException/Overview/se_ex1.vb" id="Snippet1"::: uses the HRESULT COR_E_SECURITY, which has the value 0x8013150A. - For a list of the initial property values for an instance of the class, see a specific constructor. + For a list of the initial property values for an instance of the class, see a specific constructor. ]]> @@ -104,7 +104,7 @@ constructor, see the example provided for the constructor. + For an example of the use of a constructor, see the example provided for the constructor. ]]> @@ -157,13 +157,13 @@ |Property|Value| |--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| ## Examples - For an example of the use of a constructor, see the example provided for the constructor. + For an example of the use of a constructor, see the example provided for the constructor. ]]> @@ -221,13 +221,13 @@ |Property|Value| |--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| ## Examples - For an example of the use of a constructor, see the example provided for the constructor. + For an example of the use of a constructor, see the example provided for the constructor. ]]> @@ -296,30 +296,30 @@ This constructor sets the following property values based on the information in the `info` parameter: -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- ## Examples - For an example of the use of a constructor, see the example provided for the constructor. + For an example of the use of a constructor, see the example provided for the constructor. ]]> @@ -383,13 +383,13 @@ |Property|Value| |--------------|-----------| -||The inner exception reference.| -||The localized error message string.| +||The inner exception reference.| +||The localized error message string.| ## Examples - For an example of the use of a constructor, see the example provided for the constructor. + For an example of the use of a constructor, see the example provided for the constructor. ]]> @@ -453,13 +453,13 @@ |Property|Value| |--------------|-----------| -||The localized error message string specified by `message`.| -||The of the permission that failed, specified by `type`.| +||The localized error message string specified by `message`.| +||The of the permission that failed, specified by `type`.| ## Examples - For an example of the use of a constructor, see the example provided for the constructor. + For an example of the use of a constructor, see the example provided for the constructor. ]]> @@ -523,14 +523,14 @@ |Property|Value| |--------------|-----------| -||The localized error message string specified by `message`.| -||The of the permission that failed, specified by `type`.| -||The demanded security permission, permission set, or permission set collection that failed.| +||The localized error message string specified by `message`.| +||The of the permission that failed, specified by `type`.| +||The demanded security permission, permission set, or permission set collection that failed.| ## Examples - For an example of the use of a constructor, see the example provided for the constructor. + For an example of the use of a constructor, see the example provided for the constructor. ]]> @@ -585,22 +585,22 @@ |Property|Value| |--------------|-----------| -||The localized error message string specified by `message`.| -||The first permission in the permission set or permission set collection specified by `permThatFailed`.| -||An empty string.| -||The security permission, permission set, or permission set collection specified by `demanded`.| -||An empty string.| -||The denied security permission, permission set, or permission set collection specified by `deny`.| -||The permission, permission set, or permission set collection specified by `permitOnly`.| -||`null`.| -||The specified by `method`.| -||.| -||An empty string.| +||The localized error message string specified by `message`.| +||The first permission in the permission set or permission set collection specified by `permThatFailed`.| +||An empty string.| +||The security permission, permission set, or permission set collection specified by `demanded`.| +||An empty string.| +||The denied security permission, permission set, or permission set collection specified by `deny`.| +||The permission, permission set, or permission set collection specified by `permitOnly`.| +||`null`.| +||The specified by `method`.| +||.| +||An empty string.| ## Examples - The following code example shows the use of the constructor. + The following code example shows the use of the constructor. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.SecurityException/CPP/form1.cpp" id="Snippet16"::: :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityException/.ctor/form1.cs" id="Snippet16"::: @@ -667,17 +667,17 @@ |Property|Value| |--------------|-----------| -||The localized error message string specified by `message`.| -||The first permission in the permission set or permission set collection specified by `permThatFailed`.| -||The specified by `grant`.| -||The demanded security permission, permission set, or permission set collection that failed, specified by `demanded`.| -||The specified by `refused`.| -||An empty string.| -||An empty string.| -||The specified by `assemblyName`.| -||The specified by `method`.| -||The value from the specified by `evidence`.| -||The URL from the specified by `evidence`.| +||The localized error message string specified by `message`.| +||The first permission in the permission set or permission set collection specified by `permThatFailed`.| +||The specified by `grant`.| +||The demanded security permission, permission set, or permission set collection that failed, specified by `demanded`.| +||The specified by `refused`.| +||An empty string.| +||An empty string.| +||The specified by `assemblyName`.| +||The specified by `method`.| +||The value from the specified by `evidence`.| +||The URL from the specified by `evidence`.| ]]> @@ -864,7 +864,7 @@ because it can contain a permission, a permission set, or a permission set collection. To test the run-time type of this property, you can use the method or a specific language operator, such as the [is operator](/dotnet/csharp/language-reference/keywords/is) in C# or the [TypeOf operator](/dotnet/visual-basic/language-reference/operators/typeof-operator) in Visual Basic. + This property contains the denied permission, permission set, or permission set collection that caused the security check to fail. It is `null` for exceptions that are not caused by a Deny. The property is of type because it can contain a permission, a permission set, or a permission set collection. To test the run-time type of this property, you can use the method or a specific language operator, such as the [is operator](/dotnet/csharp/language-reference/keywords/is) in C# or the [TypeOf operator](/dotnet/visual-basic/language-reference/operators/typeof-operator) in Visual Basic. ]]> @@ -980,7 +980,7 @@ represents only the first permission that caused the exception. Additional permissions in the set or collection can also cause a demand failure. + If the demanded object is a permission set or permission set collection, the represents only the first permission that caused the exception. Additional permissions in the set or collection can also cause a demand failure. ]]> @@ -1053,7 +1053,7 @@ ## Examples - The following code shows the use of the method to display the permission state contained in the object. + The following code shows the use of the method to display the permission state contained in the object. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.SecurityException/CPP/form1.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityException/.ctor/form1.cs" id="Snippet9"::: @@ -1363,9 +1363,9 @@ property represents the permitted permission, permission set, or permission set collection contained in the stack frame that caused the security exception. For instance, when a security exception occurs because of a failure, the permitted permission appears in this property and the demanded is contained in the property. + The property represents the permitted permission, permission set, or permission set collection contained in the stack frame that caused the security exception. For instance, when a security exception occurs because of a failure, the permitted permission appears in this property and the demanded is contained in the property. - This property is of type because permissions, permission sets, or permission set collections can all be demanded and is their common base class. To test the run-time type of this property, you can use the method or a specific language operator, such as the [is operator](/dotnet/csharp/language-reference/keywords/is) in C# or the [TypeOf operator](/dotnet/visual-basic/language-reference/operators/typeof-operator) in Visual Basic. + This property is of type because permissions, permission sets, or permission set collections can all be demanded and is their common base class. To test the run-time type of this property, you can use the method or a specific language operator, such as the [is operator](/dotnet/csharp/language-reference/keywords/is) in C# or the [TypeOf operator](/dotnet/visual-basic/language-reference/operators/typeof-operator) in Visual Basic. ]]> @@ -1485,7 +1485,7 @@ method returns the full description of the . + The method returns the full description of the . ]]> diff --git a/xml/System.Security/SecurityManager.xml b/xml/System.Security/SecurityManager.xml index c45dbf12324..84e8892482f 100644 --- a/xml/System.Security/SecurityManager.xml +++ b/xml/System.Security/SecurityManager.xml @@ -111,7 +111,7 @@ ## Remarks If this property is `false`, even code without can execute. Execution checking is expensive and can eliminate the advantages of lazy policy resolution. This property is provided to disable execution checking when needed. - A change to this property is not persisted until is called. New processes will not be affected by the change until it is persisted in the registry. + A change to this property is not persisted until is called. New processes will not be affected by the change until it is persisted in the registry. ]]> @@ -161,14 +161,14 @@ method before you cache sensitive data that is obtained after successful security demands. + You can use the method before you cache sensitive data that is obtained after successful security demands. - If the method has been called higher on the stack, the data should not be cached without capturing the corresponding security context. Otherwise, sensitive data that is obtained under an may become available to code that is no longer be running with that in place. + If the method has been called higher on the stack, the data should not be cached without capturing the corresponding security context. Otherwise, sensitive data that is obtained under an may become available to code that is no longer be running with that in place. > [!IMPORTANT] > The return value is reliable only when it is `false`, which means that the thread is guaranteed not to require a security context capture. The method may return true when a security context capture is not necessary, to avoid security vulnerabilities. - is security-critical because its main use is to avoid unnecessary security context captures, which indicates that the code using it is security-sensitive and must be audited. + is security-critical because its main use is to avoid unnecessary security context captures, which indicates that the code using it is security-sensitive and must be audited. ]]> @@ -286,7 +286,7 @@ for each evidence type. The permission sets returned from the calls identify the permissions granted to the executing assembly based on its zone and URL of origin. + The recommended alternative to this method is to use the URL and Zone evidence for the executing assembly to call for each evidence type. The permission sets returned from the calls identify the permissions granted to the executing assembly based on its zone and URL of origin. > [!NOTE] > This member makes a link demand for the ECMA public key, which is not a valid cryptographic key but a pseudo key. Within the .NET Framework the link demand for the ECMA pseudo key is automatically converted to a link demand for the Microsoft public key. The security exception is based on the Microsoft public key, not the ECMA pseudo key. @@ -352,7 +352,7 @@ only tests the grant of the calling code assembly, independent of other callers on the stack. + Granting of permissions is determined by policy and is different from a demand subject to overrides, such as an assert. Also, only tests the grant of the calling code assembly, independent of other callers on the stack. ]]> @@ -931,7 +931,7 @@ , , and other classes that represent configuration of the security policy. Unless this method is called, changes made to the policy objects will not be saved and will not affect subsequent application runs. + This method saves the policy as exposed by , , and other classes that represent configuration of the security policy. Unless this method is called, changes made to the policy objects will not be saved and will not affect subsequent application runs. ]]> @@ -1057,12 +1057,12 @@ `-security` (`-s`) option to turn off code-based security. - provides a way for administrators to disable code access security. When code access security is disabled, all code access demands succeed. Effectively, this grants all code `FullTrust`. Disabling code access security bypasses the security system so that code might perform slightly better than the equivalent security policy granting `FullTrust` to all code. This property does not disable role-based security; therefore, demands are not affected. + provides a way for administrators to disable code access security. When code access security is disabled, all code access demands succeed. Effectively, this grants all code `FullTrust`. Disabling code access security bypasses the security system so that code might perform slightly better than the equivalent security policy granting `FullTrust` to all code. This property does not disable role-based security; therefore, demands are not affected. > [!CAUTION] > Disabling code access security makes the system vulnerable to attacks by malicious code such as viruses and worms. Disabling code access security does not automatically block managed code from running in any way. It only causes managed code to run without restriction by the code access security system, and should only be done with the most extreme caution. Turning off security to gain extra performance should only be done when other security measures have been taken to help protect system security. Examples of other security precautions include disconnecting from public networks, physically securing computers, and so on. - A change to this property is not persisted in the registry until is called. New processes will not be affected by the change until it is persisted in the registry. Changing the value of this property in a running process does not necessarily change the state in the expected manner. To ensure changes have taken effect, you must call and start a new process. + A change to this property is not persisted in the registry until is called. New processes will not be affected by the change until it is persisted in the registry. Changing the value of this property in a running process does not necessarily change the state in the expected manner. To ensure changes have taken effect, you must call and start a new process. ]]> diff --git a/xml/System.Security/SecurityState.xml b/xml/System.Security/SecurityState.xml index 9520f45f8d2..d724fdfb78c 100644 --- a/xml/System.Security/SecurityState.xml +++ b/xml/System.Security/SecurityState.xml @@ -40,86 +40,86 @@ Provides a base class for requesting the security status of an action from the object. - object that is instantiated from the derived class is passed to the method to determine whether the host allows that action to be performed. The default implementation of the method always returns `false`. The method must be overridden to detect the actions that are allowed. - - For example, if you want to access a Web camera in your library code, you would create a `WebcamSecurityState` object and call the method to determine whether the host allows Web camera access, as shown in the following example. (You can find the code for `WebcamSecurityState` in the "Example" section.) - + object that is instantiated from the derived class is passed to the method to determine whether the host allows that action to be performed. The default implementation of the method always returns `false`. The method must be overridden to detect the actions that are allowed. + + For example, if you want to access a Web camera in your library code, you would create a `WebcamSecurityState` object and call the method to determine whether the host allows Web camera access, as shown in the following example. (You can find the code for `WebcamSecurityState` in the "Example" section.) + ```csharp -var securityState = new WebcamSecurityState("Safe access to Webcam", WebcamSecurityOptions.SafeAccess); -try -{ - securityState.EnsureState(); - // Allocate memory. -} -catch (ApplicationException e) -{ - // Handle any exception that is thrown. - System.Diagnostics.Debug.WriteLine(e.Message); -} -``` - - To process the call the must be made aware of `WebcamSecurityState` through an override of the method, as shown in the following example. - +var securityState = new WebcamSecurityState("Safe access to Webcam", WebcamSecurityOptions.SafeAccess); +try +{ + securityState.EnsureState(); + // Allocate memory. +} +catch (ApplicationException e) +{ + // Handle any exception that is thrown. + System.Diagnostics.Debug.WriteLine(e.Message); +} +``` + + To process the call the must be made aware of `WebcamSecurityState` through an override of the method, as shown in the following example. + ```csharp -[SecurityCritical] -public override bool CheckSecuritySettings(System.Security.SecurityState securityState) -{ - switch (securityState.ToString()) - { - case "WebcamSecurityState": - { - if ((securityState as WebcamSecurityState).Options == WebcamSecurityOptions.SafeAccess) - return PromptUser((securityState as WebcamSecurityState).Description); - return false; - } - } - return false; -} -private bool PromptUser(string text) -{ - // Replace the OpenFileDialog with a custom user prompt. - OpenFileDialog o = new OpenFileDialog(); - o.Title = text; - if (o.ShowDialog() == DialogResult.OK) - return true; - else - return false; -} -``` - - - -## Examples - The following example shows how to override the class. - +[SecurityCritical] +public override bool CheckSecuritySettings(System.Security.SecurityState securityState) +{ + switch (securityState.ToString()) + { + case "WebcamSecurityState": + { + if ((securityState as WebcamSecurityState).Options == WebcamSecurityOptions.SafeAccess) + return PromptUser((securityState as WebcamSecurityState).Description); + return false; + } + } + return false; +} +private bool PromptUser(string text) +{ + // Replace the OpenFileDialog with a custom user prompt. + OpenFileDialog o = new OpenFileDialog(); + o.Title = text; + if (o.ShowDialog() == DialogResult.OK) + return true; + else + return false; +} +``` + + + +## Examples + The following example shows how to override the class. + ```csharp -[SecurityCritical] +[SecurityCritical] public enum WebcamSecurityOptions { - SafeAccess, - FullAccess -} -[SecurityCritical] -public class WebcamSecurityState : SecurityState -{ - public WebcamSecurityState(string description, WebcamSecurityOptions options) - { - Options = options; - Description = description; - } - public WebcamSecurityOptions Options { get; set; } - public string Description { get; set; } - public override void EnsureState() - { - if (!IsStateAvailable()) - throw new ApplicationException("WebcamSecurityState not available"); - } -} -``` - + SafeAccess, + FullAccess +} +[SecurityCritical] +public class WebcamSecurityState : SecurityState +{ + public WebcamSecurityState(string description, WebcamSecurityOptions options) + { + Options = options; + Description = description; + } + public WebcamSecurityOptions Options { get; set; } + public string Description { get; set; } + public override void EnsureState() + { + if (!IsStateAvailable()) + throw new ApplicationException("WebcamSecurityState not available"); + } +} +``` + ]]> @@ -188,20 +188,20 @@ public class WebcamSecurityState : SecurityState When overridden in a derived class, ensures that the state that is represented by is available on the host. - @@ -247,13 +247,13 @@ public override void EnsureState() if the state is available; otherwise, . - calls the method to determine whether the state that is represented by this class is available on the host. - - See the class for an example implementation of the method. - + calls the method to determine whether the state that is represented by this class is available on the host. + + See the class for an example implementation of the method. + ]]> diff --git a/xml/System.Security/VerificationException.xml b/xml/System.Security/VerificationException.xml index dbf57029972..212a5705046 100644 --- a/xml/System.Security/VerificationException.xml +++ b/xml/System.Security/VerificationException.xml @@ -306,8 +306,8 @@ |Property|Value| |--------------|-----------| -||The inner exception reference.| -||The error message string.| +||The inner exception reference.| +||The error message string.| ]]> diff --git a/xml/System.Security/XmlSyntaxException.xml b/xml/System.Security/XmlSyntaxException.xml index 4f86ec4e05d..f39919df8b5 100644 --- a/xml/System.Security/XmlSyntaxException.xml +++ b/xml/System.Security/XmlSyntaxException.xml @@ -53,7 +53,7 @@ uses the default implementation, which supports reference equality. + uses the default implementation, which supports reference equality. For a list of initial property values for an instance of , see the constructor. @@ -110,8 +110,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||"Invalid syntax."| +||`null`.| +||"Invalid syntax."| ]]> @@ -160,8 +160,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||"Invalid syntax on line `lineNumber`."| +||`null`.| +||"Invalid syntax on line `lineNumber`."| ]]> @@ -208,8 +208,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string.| +||`null`.| +||The error message string.| ]]> @@ -260,8 +260,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||"Invalid syntax on line `lineNumber` - `message` "| +||`null`.| +||"Invalid syntax on line `lineNumber` - `message` "| ]]> @@ -312,8 +312,8 @@ |Property|Value| |--------------|-----------| -||The inner exception reference.| -||The error message string.| +||The inner exception reference.| +||The error message string.| ]]> diff --git a/xml/System.ServiceProcess.Design/ServiceInstallerDialog.xml b/xml/System.ServiceProcess.Design/ServiceInstallerDialog.xml index 51aa88f7262..7c47441cafb 100644 --- a/xml/System.ServiceProcess.Design/ServiceInstallerDialog.xml +++ b/xml/System.ServiceProcess.Design/ServiceInstallerDialog.xml @@ -18,26 +18,26 @@ Provides a dialog box, which prompts for account information of a Windows Service application. - class directly within your code; this dialog is generally used by the installation utility for a Windows Service application. - - If a object has the set to `User`, and either the or is an empty string (""), then the installation utility uses to prompt for these values. - - derives from ; use the class methods and properties to display and manipulate the dialog. For example, use to display the form, and then check the before validating the input text for the and properties. - + class directly within your code; this dialog is generally used by the installation utility for a Windows Service application. + + If a object has the set to `User`, and either the or is an empty string (""), then the installation utility uses to prompt for these values. + + derives from ; use the class methods and properties to display and manipulate the dialog. For example, use to display the form, and then check the before validating the input text for the and properties. + > [!NOTE] -> does not check the credentials and privileges for the specified account. For example, the user might enter an invalid account name and password for the computer, or the account might not have the correct privileges to run as a service. Validate the user input to ensure that the installed service runs successfully. - - - -## Examples - The following example uses a to prompt the user for a service installation account. - +> does not check the credentials and privileges for the specified account. For example, the user might enter an invalid account name and password for the computer, or the account might not have the correct privileges to run as a service. Validate the user input to ensure that the installed service runs successfully. + + + +## Examples + The following example uses a to prompt the user for a service installation account. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ServiceInstallConfig/CPP/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess.Design/ServiceInstallerDialog/Overview/source.cs" id="Snippet1"::: - + :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess.Design/ServiceInstallerDialog/Overview/source.cs" id="Snippet1"::: + ]]> @@ -62,11 +62,11 @@ Initializes a new instance of the service account form. - form has its set to , the set to an empty string (""), and the set to an empty string. - + form has its set to , the set to an empty string (""), and the set to an empty string. + ]]> @@ -98,13 +98,13 @@ Begins running a standard application message loop and displays the service account form. - on a new form; it is typically used for testing purposes. - - Call on the form to display the dialog box in your application. - + on a new form; it is typically used for testing purposes. + + Call on the form to display the dialog box in your application. + ]]> @@ -132,11 +132,11 @@ Gets or sets the password for the service account form. A string representing the password in the service account form. The default is an empty string (""). - does not validate the and values. The dialog checks that the user confirms the password, but it does not authenticate the account credentials on the computer. - + does not validate the and values. The dialog checks that the user confirms the password, but it does not authenticate the account credentials on the computer. + ]]> @@ -162,11 +162,11 @@ Gets the dialog result for the service account form. A indicating the user response to the dialog box. The default is . - to prompt the user for the service installation account, then check the value. If the value is , verify that the input and are valid. - + to prompt the user for the service installation account, then check the value. If the value is , verify that the input and are valid. + ]]> @@ -193,11 +193,11 @@ Gets or sets the user name for the service account form. A string representing the user name in the service account form. The default is an empty string (""). - does not validate the or values. - + does not validate the or values. + ]]> diff --git a/xml/System.ServiceProcess/ServiceBase.xml b/xml/System.ServiceProcess/ServiceBase.xml index 4dd5cb4e168..be4cd5b6fc7 100644 --- a/xml/System.ServiceProcess/ServiceBase.xml +++ b/xml/System.ServiceProcess/ServiceBase.xml @@ -57,7 +57,7 @@ when defining your service class in a service application. Any useful service overrides the and methods. For additional functionality, you can override and with specific behavior in response to changes in the service state. + Derive from when defining your service class in a service application. Any useful service overrides the and methods. For additional functionality, you can override and with specific behavior in response to changes in the service state. A service is a long-running executable that does not support a user interface, and which might not run under the logged-on user account. The service can run without any user being logged on to the computer. @@ -65,20 +65,20 @@ An executable can contain more than one service but must contain a separate for each service. The instance registers the service with the system. The installer also associates each service with an event log that you can use to record service commands. The `main()` function in the executable defines which services should run. The current working directory of the service is the system directory, not the directory in which the executable is located. - When you start a service, the system locates the executable and runs the method for that service, contained within the executable. However, running the service is not the same as running the executable. The executable only loads the service. The service is accessed (for example, started and stopped) through the Service Control Manager. + When you start a service, the system locates the executable and runs the method for that service, contained within the executable. However, running the service is not the same as running the executable. The executable only loads the service. The service is accessed (for example, started and stopped) through the Service Control Manager. - The executable calls the derived class's constructor the first time you call Start on the service. The command-handling method is called immediately after the constructor executes. The constructor is not executed again after the first time the service has been loaded, so it is necessary to separate the processing performed by the constructor from that performed by . Any resources that can be released by should be created in . Creating resources in the constructor prevents them from being created properly if the service is started again after has released the resources. + The executable calls the derived class's constructor the first time you call Start on the service. The command-handling method is called immediately after the constructor executes. The constructor is not executed again after the first time the service has been loaded, so it is necessary to separate the processing performed by the constructor from that performed by . Any resources that can be released by should be created in . Creating resources in the constructor prevents them from being created properly if the service is started again after has released the resources. - The Service Control Manager (SCM) provides a way to interact with the service. You can use the SCM to pass Start, Stop, Pause, Continue, or custom commands into the service. The SCM uses the values of and to determine whether the service accepts Stop, Pause, or Continue commands. Stop, Pause, and Continue are enabled in the SCM's context menus only if the corresponding property or is `true` in the service class. If enabled, the command is passed to the service, and , , or is called. If , , or is `false`, the corresponding command-handling method (such as ) will not be processed, even if you have implemented the method. + The Service Control Manager (SCM) provides a way to interact with the service. You can use the SCM to pass Start, Stop, Pause, Continue, or custom commands into the service. The SCM uses the values of and to determine whether the service accepts Stop, Pause, or Continue commands. Stop, Pause, and Continue are enabled in the SCM's context menus only if the corresponding property or is `true` in the service class. If enabled, the command is passed to the service, and , , or is called. If , , or is `false`, the corresponding command-handling method (such as ) will not be processed, even if you have implemented the method. - You can use the class to do programmatically what the SCM does using a user interface. You can automate the tasks available in the console. If , , or is `true` but you have not implemented a corresponding command-handling method (such as ) the system throws an exception and ignores the command. + You can use the class to do programmatically what the SCM does using a user interface. You can automate the tasks available in the console. If , , or is `true` but you have not implemented a corresponding command-handling method (such as ) the system throws an exception and ignores the command. - You do not have to implement , , or any other method in . However, the service's behavior is described in , so at minimum, this member should be overridden. The `main()` function of the executable registers the service in the executable with the Service Control Manager by calling the method. The property of the object passed to the method must match the property of the service installer for that service. + You do not have to implement , , or any other method in . However, the service's behavior is described in , so at minimum, this member should be overridden. The `main()` function of the executable registers the service in the executable with the Service Control Manager by calling the method. The property of the object passed to the method must match the property of the service installer for that service. You can use the `sc create` command to install services that target modern .NET, or use `InstallUtil.exe` to install services that target .NET Framework. > [!NOTE] -> You can specify a log other than the Application event log to receive notification of service calls, but neither the nor the property can write to a custom log. Set to `false` if you do not want to use automatic logging. +> You can specify a log other than the Application event log to receive notification of service calls, but neither the nor the property can write to a custom log. Set to `false` if you do not want to use automatic logging. ]]> @@ -111,11 +111,11 @@ class. Instead, derive from and instantiate your derived class. The minimum you need to implement in the constructor for a class inherited from is to set the on your component. No other processing is specifically required in the constructor. You should handle most initialization in rather than in the constructor. Otherwise, there is no guarantee the objects will be reinitialized when you restart a service after it has been stopped. + Do not create an instance of the class. Instead, derive from and instantiate your derived class. The minimum you need to implement in the constructor for a class inherited from is to set the on your component. No other processing is specifically required in the constructor. You should handle most initialization in rather than in the constructor. Otherwise, there is no guarantee the objects will be reinitialized when you restart a service after it has been stopped. If you override the constructor in your derived class, call the base class constructor in your code. - The constructor sets to `true`. If you do not want to automatically log calls to the service from the Service Control Manager (SCM), set to `false`. + The constructor sets to `true`. If you do not want to automatically log calls to the service from the Service Control Manager (SCM), set to `false`. If the executable contains a single service, the system calls the service's constructor when Start is selected from the SCM, and runs the destructor if Stop is called. @@ -171,12 +171,12 @@ to `true` instructs the service to use the Application event log to report command failures, as well as state change information for Start, Stop, Pause, and Continue events on the service. The name of the service is used as the log's . + Setting to `true` instructs the service to use the Application event log to report command failures, as well as state change information for Start, Stop, Pause, and Continue events on the service. The name of the service is used as the log's . - To report information to a custom event log rather than the Application log, set to `false` and write instructions within the command-handling methods , , or to post to the appropriate log. + To report information to a custom event log rather than the Application log, set to `false` and write instructions within the command-handling methods , , or to post to the appropriate log. > [!NOTE] -> The , which supplies the source string for the event log, must be set before the service attempts to write to the event log. Trying to access the event log before the source name is set throws an exception. +> The , which supplies the source string for the event log, must be set before the service attempts to write to the event log. Trying to access the event log before the source name is set throws an exception. ]]> @@ -221,9 +221,9 @@ . + When the computer power status changes, the Service Control Manager (SCM) verifies whether the service accepts power event commands using the value of . - If is `true`, the command is passed to the service and the method is called if defined. If is not implemented in the derived class, the SCM handles the power event through the empty base class method. + If is `true`, the command is passed to the service and the method is called if defined. If is not implemented in the derived class, the SCM handles the power event through the empty base class method. ]]> @@ -316,13 +316,13 @@ ## Remarks Set the value of the property in the constructor for the service. - When a service is paused, it halts what it is doing. When you continue the service (either through the Service Control Manager or programmatically), runs. + When a service is paused, it halts what it is doing. When you continue the service (either through the Service Control Manager or programmatically), runs. - Sending a Pause request to the service can conserve system resources. Pause may not release all system resources, but Stop does. and are often implemented to perform less processing than and . + Sending a Pause request to the service can conserve system resources. Pause may not release all system resources, but Stop does. and are often implemented to perform less processing than and . - When is `true`, override and to specify the processing that should occur when the Service Control Manager (SCM) passes a Pause or Continue request to your service. should be implemented to undo the processing in . + When is `true`, override and to specify the processing that should occur when the Service Control Manager (SCM) passes a Pause or Continue request to your service. should be implemented to undo the processing in . - If is `false`, the SCM will not pass Pause or Continue requests to the service, so the and methods will not be called even if they are implemented. In the SCM, the `Pause` and `Continue` controls are disabled when is `false`. + If is `false`, the SCM will not pass Pause or Continue requests to the service, so the and methods will not be called even if they are implemented. In the SCM, the `Pause` and `Continue` controls are disabled when is `false`. ]]> @@ -370,10 +370,10 @@ is `true`, the service is notified when the system is shutting down. At shutdown, the method is called if it has been implemented in your derived class. + If is `true`, the service is notified when the system is shutting down. At shutdown, the method is called if it has been implemented in your derived class. > [!NOTE] -> Only the system should cause the method to execute; the service can call it, but this is not recommended. +> Only the system should cause the method to execute; the service can call it, but this is not recommended. ]]> @@ -420,9 +420,9 @@ . For most services, the value of is `true`, but some operating system services, for example, do not allow the user to stop them. + When Stop is called on a service, the Service Control Manager (SCM) verifies whether the service accepts Stop commands using the value of . For most services, the value of is `true`, but some operating system services, for example, do not allow the user to stop them. - If is `true`, the Stop command is passed to the service and the method is called if it is defined. If is not implemented in the derived class, the SCM handles the Stop command through the empty base class method. + If is `true`, the Stop command is passed to the service and the method is called if it is defined. If is not implemented in the derived class, the SCM handles the Stop command through the empty base class method. ]]> @@ -466,12 +466,12 @@ in your derived class (and through it, in the class) when you are finished using the derived class. The method leaves the derived class in an unusable state. After calling , you must release all references to the derived class and so the memory they were occupying can be reclaimed by garbage collection. + Call in your derived class (and through it, in the class) when you are finished using the derived class. The method leaves the derived class in an unusable state. After calling , you must release all references to the derived class and so the memory they were occupying can be reclaimed by garbage collection. > [!NOTE] -> Always call before you release your last reference to the class derived from . Otherwise, the resources and the derived class are using will not be freed until garbage collection calls the objects' destructors. +> Always call before you release your last reference to the class derived from . Otherwise, the resources and the derived class are using will not be freed until garbage collection calls the objects' destructors. - is often implemented to process the code in , combined with a call to . If you choose to do this in your derived class, it is customary to implement to allocate whatever released. + is often implemented to process the code in , combined with a call to . If you choose to do this in your derived class, it is customary to implement to allocate whatever released. ]]> @@ -517,11 +517,11 @@ property to an instance with the and properties set. The source is the of the service, and the log is the computer's Application log. These values are set automatically and cannot be changed for automatic logging of service commands. + The constructor initializes the property to an instance with the and properties set. The source is the of the service, and the log is the computer's Application log. These values are set automatically and cannot be changed for automatic logging of service commands. - When is `true`, Start, Stop, Pause, Continue, and custom commands are recorded automatically in the Application event log. You can use the property to write additional messages to that log as well. The component calls using this member. + When is `true`, Start, Stop, Pause, Continue, and custom commands are recorded automatically in the Application event log. You can use the property to write additional messages to that log as well. The component calls using this member. - To report information to a custom event log rather than the Application log, set to `false` and write instructions within the command-handling methods , , or to post to the appropriate log. + To report information to a custom event log rather than the Application log, set to `false` and write instructions within the command-handling methods , , or to post to the appropriate log. ]]> @@ -635,11 +635,11 @@ to mirror your application's response to . When you continue the service (either through the Services console or programmatically), the processing runs, and the service becomes active again. + Implement to mirror your application's response to . When you continue the service (either through the Services console or programmatically), the processing runs, and the service becomes active again. - is expected to be overridden when the property is `true`. + is expected to be overridden when the property is `true`. - If is `false`, the SCM will not pass Pause or Continue requests to the service, so the and methods will not be called even if they are implemented. In the SCM, the `Pause` and `Continue` controls are disabled when is `false`. + If is `false`, the SCM will not pass Pause or Continue requests to the service, so the and methods will not be called even if they are implemented. In the SCM, the `Pause` and `Continue` controls are disabled when is `false`. ]]> @@ -684,13 +684,13 @@ lets you specify additional functionality beyond starting, stopping, pausing and continuing services. + lets you specify additional functionality beyond starting, stopping, pausing and continuing services. The SCM does not examine the custom command to verify whether the service supports the `command` parameter passed in. It passes the custom command directly to the service. If the service does not recognize the `command` parameter, it does nothing. - Custom commands are raised by an statement in a component. Use a switch statement or if..then condition to handle the custom commands you define on your service. + Custom commands are raised by an statement in a component. Use a switch statement or if..then condition to handle the custom commands you define on your service. - The only values for a custom command that you can define in your application or use in are those between 128 and 255. Integers below 128 correspond to system-reserved values. + The only values for a custom command that you can define in your application or use in are those between 128 and 255. Integers below 128 correspond to system-reserved values. If the property is `true`, custom commands, like all other commands, write entries to the event log to report whether the method execution succeeded or failed. @@ -733,17 +733,17 @@ to specify the processing that occurs when the service receives a Pause command. is expected to be overridden when the property is `true`. + Use to specify the processing that occurs when the service receives a Pause command. is expected to be overridden when the property is `true`. - When you continue a paused service (either through the Services console or programmatically), the processing is run, and the service becomes active again. + When you continue a paused service (either through the Services console or programmatically), the processing is run, and the service becomes active again. - The Pause command only allows your application to react to a specific event. does nothing to the service that you do not define it to do. + The Pause command only allows your application to react to a specific event. does nothing to the service that you do not define it to do. Sending a Pause request to the service can conserve system resources because Pause need not release all system resources. For example, if threads have been opened by the process, pausing a service rather than stopping it can allow the threads to remain open, obviating the need to reallocate them when the service continues. If you define Pause to release all system resources, it behaves like a Stop command. - Set to `true`, and override and to specify the processing that should occur when the SCM passes a Pause or Continue request to your service. should be implemented to undo the processing in . + Set to `true`, and override and to specify the processing that should occur when the SCM passes a Pause or Continue request to your service. should be implemented to undo the processing in . - If is `false`, the SCM will not pass Pause or Continue requests to the service, so the and methods will not be called even if implemented. In the SCM, the `Pause` and `Continue` controls are disabled when is `false`. + If is `false`, the SCM will not pass Pause or Continue requests to the service, so the and methods will not be called even if implemented. In the SCM, the `Pause` and `Continue` controls are disabled when is `false`. ]]> @@ -789,9 +789,9 @@ to specify the processing that occurs when the system event indicated in the enumeration occurs--for example, when the computer is placed in suspended mode or indicates low battery power. + Use to specify the processing that occurs when the system event indicated in the enumeration occurs--for example, when the computer is placed in suspended mode or indicates low battery power. - is expected to be overridden when the property is `true`. + is expected to be overridden when the property is `true`. ]]> @@ -872,11 +872,11 @@ to specify the processing that occurs when the system shuts down. + Use to specify the processing that occurs when the system shuts down. This event occurs only when the operating system is shut down, not when the computer is turned off. - is expected to be overridden when the property is `true`. + is expected to be overridden when the property is `true`. ]]> @@ -921,16 +921,16 @@ to specify the processing that occurs when the service receives a Start command. is the method in which you specify the behavior of the service. can take arguments as a way to pass data, but this usage is rare. + Use to specify the processing that occurs when the service receives a Start command. is the method in which you specify the behavior of the service. can take arguments as a way to pass data, but this usage is rare. > [!CAUTION] -> Do not use the constructor to perform processing that should be in . Use to handle all initialization of your service. The constructor is called when the application's executable runs, not when the service runs. The executable runs before . When you continue, for example, the constructor is not called again because the SCM already holds the object in memory. If releases resources allocated in the constructor rather than in , the needed resources would not be created again the second time the service is called. +> Do not use the constructor to perform processing that should be in . Use to handle all initialization of your service. The constructor is called when the application's executable runs, not when the service runs. The executable runs before . When you continue, for example, the constructor is not called again because the SCM already holds the object in memory. If releases resources allocated in the constructor rather than in , the needed resources would not be created again the second time the service is called. - Services can be set to start automatically when the computer reboots by setting the on the service's installer to . In such a situation, would be called at system startup. + Services can be set to start automatically when the computer reboots by setting the on the service's installer to . In such a situation, would be called at system startup. - is expected to be overridden in the derived class. For the service to be useful, and should both be implemented in your service class. + is expected to be overridden in the derived class. For the service to be useful, and should both be implemented in your service class. - Process initialization arguments for the service in the method, not in the Main method. The arguments in the `args` parameter array can be set manually in the properties window for the service in the Services console. The arguments entered in the console are not saved; they are passed to the service on a one-time basis when the service is started from the control panel. Arguments that must be present when the service is automatically started can be placed in the ImagePath string value for the service's registry key (HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\\*\*). You can obtain the arguments from the registry using the method, for example: `string[] imagePathArgs = Environment.GetCommandLineArgs();`. + Process initialization arguments for the service in the method, not in the Main method. The arguments in the `args` parameter array can be set manually in the properties window for the service in the Services console. The arguments entered in the console are not saved; they are passed to the service on a one-time basis when the service is started from the control panel. Arguments that must be present when the service is automatically started can be placed in the ImagePath string value for the service's registry key (HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\\*\*). You can obtain the arguments from the registry using the method, for example: `string[] imagePathArgs = Environment.GetCommandLineArgs();`. ]]> @@ -971,13 +971,13 @@ to specify the processing that occurs when the service receives a Stop command. + Use to specify the processing that occurs when the service receives a Stop command. - When the SCM receives a Stop command, it uses the value of to verify whether the service accepts Stop commands. If is `true`, the Stop command is passed to the service, and the method is called if it is defined. If is not implemented in the service, the SCM handles the Stop command. + When the SCM receives a Stop command, it uses the value of to verify whether the service accepts Stop commands. If is `true`, the Stop command is passed to the service, and the method is called if it is defined. If is not implemented in the service, the SCM handles the Stop command. - If is `false`, the SCM ignores the Stop command. It is not passed to the service. The Stop command returns and throws an exception. + If is `false`, the SCM ignores the Stop command. It is not passed to the service. The Stop command returns and throws an exception. - is expected to be overridden in the derived class. For the service to be useful, and should both be implemented in your service class. + is expected to be overridden in the derived class. For the service to be useful, and should both be implemented in your service class. ]]> @@ -1027,7 +1027,7 @@ method is intended to be called by the overridden , , , or methods to request additional time for a pending operation, to prevent the Service Control Manager (SCM) from marking the service as not responding. If the pending operation is not a continue, pause, start, or stop, an is thrown. + The method is intended to be called by the overridden , , , or methods to request additional time for a pending operation, to prevent the Service Control Manager (SCM) from marking the service as not responding. If the pending operation is not a continue, pause, start, or stop, an is thrown. ]]> @@ -1106,11 +1106,11 @@ , the Service Control Manager issues a Start command, which results in a call to the method in the service. The service is not started until the Start command is executed. + Call this overload in the `main()` function of the service executable to register the service with the Service Control Manager. After you call , the Service Control Manager issues a Start command, which results in a call to the method in the service. The service is not started until the Start command is executed. - The method is called in much the same way as for Windows Forms applications. + The method is called in much the same way as for Windows Forms applications. - If is `true`, an entry is written to the event log if the service specified by the `service` parameter fails to start. + If is `true`, an entry is written to the event log if the service specified by the `service` parameter fails to start. ]]> @@ -1152,11 +1152,11 @@ , the Service Control Manager issues Start commands, which result in calls to the methods in the services. The services are not started until the Start commands are executed. + Call this overload in the `main()` function of the service executable to register the services with the Service Control Manager. After you call , the Service Control Manager issues Start commands, which result in calls to the methods in the services. The services are not started until the Start commands are executed. - The method is called in much the same way as the method for Windows Forms applications. + The method is called in much the same way as the method for Windows Forms applications. - If is `true`, an entry is written to the event log if any service in the array fails to start. + If is `true`, an entry is written to the event log if any service in the array fails to start. ]]> @@ -1294,11 +1294,11 @@ identifies the service to the Service Control Manager. The value of this property must be identical to the name recorded for the service in the property of the corresponding installer class. In code, the of the service is usually set in the `main()` function of the executable. + The identifies the service to the Service Control Manager. The value of this property must be identical to the name recorded for the service in the property of the corresponding installer class. In code, the of the service is usually set in the `main()` function of the executable. - The is also used to specify the associated with the property. This is an instance that writes service command information to the Application log. + The is also used to specify the associated with the property. This is an instance that writes service command information to the Application log. - The , which supplies the source string for the event log, must be set before the service writes to the event log. Trying to access the event log before the source name is set causes an exception to be thrown. + The , which supplies the source string for the event log, must be set before the service writes to the event log. Trying to access the event log before the source name is set causes an exception to be thrown. ]]> @@ -1336,7 +1336,7 @@ method sets the service state to indicate a stop is pending and calls the method. After the application is stopped, the service state is set to stopped. If the application is a hosted service, the application domain is unloaded. + The method sets the service state to indicate a stop is pending and calls the method. After the application is stopped, the service state is set to stopped. If the application is a hosted service, the application domain is unloaded. ]]> diff --git a/xml/System.ServiceProcess/ServiceController.xml b/xml/System.ServiceProcess/ServiceController.xml index b73be4fb11d..926ed006180 100644 --- a/xml/System.ServiceProcess/ServiceController.xml +++ b/xml/System.ServiceProcess/ServiceController.xml @@ -83,9 +83,9 @@ After you create an instance of , you must set two properties on it to identify the service with which it interacts: the computer name and the name of the service you want to control. > [!NOTE] -> By default, is set to the local computer, so you do not need to change it unless you want to set the instance to point to another computer. +> By default, is set to the local computer, so you do not need to change it unless you want to set the instance to point to another computer. - Generally, the service author writes code that customizes the action associated with a specific command. For example, a service can contain code to respond to an command. In that case, the custom processing for the task runs before the system pauses the service. + Generally, the service author writes code that customizes the action associated with a specific command. For example, a service can contain code to respond to an command. In that case, the custom processing for the task runs before the system pauses the service. The set of commands a service can process depends on its properties; for example, you can set the property for a service to `false`. This setting renders the `Stop` command unavailable on that particular service; it prevents you from stopping the service from the SCM by disabling the necessary button. If you try to stop the service from your code, the system raises an error and displays the error message "Failed to stop `servicename`." @@ -167,7 +167,7 @@ constructor to create a object that is used to control a sample service. This example is part of a larger example that is provided for the class. + The following example demonstrates the use of the constructor to create a object that is used to control a sample service. This example is part of a larger example that is provided for the class. :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/Overview/program.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/ServiceController/Overview/program.vb" id="Snippet2"::: @@ -407,7 +407,7 @@ releases all the handles associated with the instance. + releases all the handles associated with the instance. ]]> @@ -443,14 +443,14 @@ for a service, its status is first changed to `ContinuePending` and then, when the method returns, it is changed to `Running`. + When you call for a service, its status is first changed to `ContinuePending` and then, when the method returns, it is changed to `Running`. - You cannot call for the service until the service controller status is `Paused`. + You cannot call for the service until the service controller status is `Paused`. ## Examples - The following example demonstrates the use of the method to continue a paused service. This example is part of a larger example that is provided for the class. + The following example demonstrates the use of the method to continue a paused service. This example is part of a larger example that is provided for the class. :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/Overview/program.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/ServiceController/Overview/program.vb" id="Snippet5"::: @@ -504,7 +504,7 @@ array represents the services that the system stops if your application calls for this service. + The array represents the services that the system stops if your application calls for this service. @@ -569,7 +569,7 @@ to an empty string (""), but setting the property to `null` throws an exception. + You can set the to an empty string (""), but setting the property to `null` throws an exception. @@ -699,12 +699,12 @@ , the status of the service does not change. If the service was started, the status remains `Running`. If the service was stopped, the status remains `Stopped`, and so on. To process the custom command, the service must override the method and provide a handler for the command identified by the `command` parameter. + When you call , the status of the service does not change. If the service was started, the status remains `Running`. If the service was stopped, the status remains `Stopped`, and so on. To process the custom command, the service must override the method and provide a handler for the command identified by the `command` parameter. ## Examples - The following code example shows the use of the method to execute custom commands in the `SimpleService` service example. + The following code example shows the use of the method to execute custom commands in the `SimpleService` service example. :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/ExecuteCommand/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/ServiceController/ExecuteCommand/module1.vb" id="Snippet1"::: @@ -756,7 +756,7 @@ returns only the device driver services from the local computer. To retrieve the non-device driver services or services that are not drivers, call the method. Together, the two methods provide access to all the services on a computer. + returns only the device driver services from the local computer. To retrieve the non-device driver services or services that are not drivers, call the method. Together, the two methods provide access to all the services on a computer. @@ -807,7 +807,7 @@ returns only the device driver services from the specified computer. To retrieve the non-device driver services or services that are not drivers, call the method. Together, the two methods provide access to all the services on a computer. + returns only the device driver services from the specified computer. To retrieve the non-device driver services or services that are not drivers, call the method. Together, the two methods provide access to all the services on a computer. ]]> @@ -856,7 +856,7 @@ returns only the non-device driver services and the services that are not drivers from the local computer. To retrieve device driver services, call the method. Together, the two methods provide access to all the services on a computer. + returns only the non-device driver services and the services that are not drivers from the local computer. To retrieve device driver services, call the method. Together, the two methods provide access to all the services on a computer. @@ -907,7 +907,7 @@ returns only the non-device driver services and the services that are not drivers from the specified computer. To retrieve device driver services, call the method. Together, the two methods provide access to all the services on a computer. + returns only the non-device driver services and the services that are not drivers from the specified computer. To retrieve device driver services, call the method. Together, the two methods provide access to all the services on a computer. ]]> @@ -1009,12 +1009,12 @@ for the service until the service controller status is `Paused`. + You cannot call for the service until the service controller status is `Paused`. ## Examples - The following example demonstrates the use of the method to pause a service. This example is part of a larger example that is provided for the class. + The following example demonstrates the use of the method to pause a service. This example is part of a larger example that is provided for the class. :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/Overview/program.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/ServiceController/Overview/program.vb" id="Snippet4"::: @@ -1058,12 +1058,12 @@ method causes the , , and properties to be reset to their current values when they are next referenced. + The method causes the , , and properties to be reset to their current values when they are next referenced. ## Examples - The following example demonstrates the use of the method to obtain the status of a service. The code instructs a service to pause, and then waits for the status to reflect the change. This example is part of a larger example that is provided for the class. + The following example demonstrates the use of the method to obtain the status of a service. The code instructs a service to pause, and then waits for the status to reflect the change. This example is part of a larger example that is provided for the class. :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/Overview/program.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/ServiceController/Overview/program.vb" id="Snippet4"::: @@ -1171,11 +1171,11 @@ identifies the service to the Service Control Manager. Changing this property causes the instance to bind to another service, it does not change what the Service Control Manager's Microsoft Management Console snap-in displays. + The identifies the service to the Service Control Manager. Changing this property causes the instance to bind to another service, it does not change what the Service Control Manager's Microsoft Management Console snap-in displays. - When you are implementing a custom service, the value of this property must be identical to the name recorded for the service in the property of the corresponding class. In code, the is usually set in the `main()` function of the executable. + When you are implementing a custom service, the value of this property must be identical to the name recorded for the service in the property of the corresponding class. In code, the is usually set in the `main()` function of the executable. - When you reset the property, the method that sets the property sets this instance's to an empty string (""). + When you reset the property, the method that sets the property sets this instance's to an empty string (""). ]]> @@ -1224,7 +1224,7 @@ array is not running, you will not be able to start this service. + If any service in the array is not running, you will not be able to start this service. @@ -1338,7 +1338,7 @@ for the service until the service controller status is `Running`. + You cannot call for the service until the service controller status is `Running`. @@ -1390,7 +1390,7 @@ for the service until the service controller status is `Running`. + You cannot call for the service until the service controller status is `Running`. ]]> @@ -1534,7 +1534,7 @@ ## Remarks If any services depend on this service for their operation, they will be stopped before this service is stopped. The property contains the set of services that depend on this one. - If you stop a service that this service depends on, call the method on this service within the method of the parent service. The property contains the services that this service depends on. + If you stop a service that this service depends on, call the method on this service within the method of the parent service. The property contains the services that this service depends on. @@ -1634,10 +1634,10 @@ If any other services depend on this one, you need to either pass `true` for to suspend an application's processing until the service has reached the required status. + Use to suspend an application's processing until the service has reached the required status. > [!NOTE] -> The method waits approximately 250 milliseconds between each status check. cannot detect the case of the observed service changing to the `desiredStatus` and then immediately to another status in that interval. +> The method waits approximately 250 milliseconds between each status check. cannot detect the case of the observed service changing to the `desiredStatus` and then immediately to another status in that interval. @@ -1689,10 +1689,10 @@ If any other services depend on this one, you need to either pass `true` for to suspend an application's processing until the service has reached the required status. + Use to suspend an application's processing until the service has reached the required status. > [!NOTE] -> The method waits approximately 250 milliseconds between each status check. cannot detect the case of the observed service changing to the `desiredStatus` and then immediately to another status in that interval. +> The method waits approximately 250 milliseconds between each status check. cannot detect the case of the observed service changing to the `desiredStatus` and then immediately to another status in that interval. ]]> diff --git a/xml/System.ServiceProcess/ServiceInstaller.xml b/xml/System.ServiceProcess/ServiceInstaller.xml index 30734dc52af..6631214499c 100644 --- a/xml/System.ServiceProcess/ServiceInstaller.xml +++ b/xml/System.ServiceProcess/ServiceInstaller.xml @@ -23,36 +23,36 @@ ## Remarks The does work specific to the service with which it is associated. It is used by the installation utility to write registry values associated with the service to a subkey within the HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services registry key. The service is identified by its ServiceName within this subkey. The subkey also includes the name of the executable or .dll to which the service belongs. - To install a service, create a project installer class that inherits from the class, and set the attribute on the class to `true`. Within your project, create one instance per service application, and one instance for each service in the application. Within your project installer class constructor, set the installation properties for the service using the and instances, and add the instances to the collection. + To install a service, create a project installer class that inherits from the class, and set the attribute on the class to `true`. Within your project, create one instance per service application, and one instance for each service in the application. Within your project installer class constructor, set the installation properties for the service using the and instances, and add the instances to the collection. > [!NOTE] -> It is recommended that you use the constructor for adding installer instances; however, if you need to add to the collection in the method, be sure to perform the same additions to the collection in the method. +> It is recommended that you use the constructor for adding installer instances; however, if you need to add to the collection in the method, be sure to perform the same additions to the collection in the method. - For all classes deriving from the class, the state of the collection must be the same in the and methods. However, you can avoid the maintenance of the collection across the and methods if you add installer instances to the collection in your custom installer class constructor.When the install utility is called, it looks for the attribute. If the attribute is `true`, the utility installs all the services that were added to the collection that were associated with your project installer. If is `false` or does not exist, the install utility ignores the project installer. + For all classes deriving from the class, the state of the collection must be the same in the and methods. However, you can avoid the maintenance of the collection across the and methods if you add installer instances to the collection in your custom installer class constructor.When the install utility is called, it looks for the attribute. If the attribute is `true`, the utility installs all the services that were added to the collection that were associated with your project installer. If is `false` or does not exist, the install utility ignores the project installer. The associated with your project installation class installs information common to all instances in the project. If this service has anything that separates it from the other services in the installation project, that service-specific information is installed by this method. > [!NOTE] -> It is crucial that the be identical to the of the class you derived from . Normally, the value of the property for the service is set within the Main() function of the service application's executable. The Service Control Manager uses the property to locate the service within this executable. +> It is crucial that the be identical to the of the class you derived from . Normally, the value of the property for the service is set within the Main() function of the service application's executable. The Service Control Manager uses the property to locate the service within this executable. - You can modify other properties on the either before or after adding it to the collection of your project installer. For example, a service's may be set to start the service automatically at reboot or require a user to start the service manually. + You can modify other properties on the either before or after adding it to the collection of your project installer. For example, a service's may be set to start the service automatically at reboot or require a user to start the service manually. - Normally, you will not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the and methods during the installation process. It backs out failures, if necessary, by calling (or ) on all previously installed components. + Normally, you will not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the and methods during the installation process. It backs out failures, if necessary, by calling (or ) on all previously installed components. - The installation utility calls to remove the object. + The installation utility calls to remove the object. - An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information is continuously updated as the instance, and each instance is installed by the utility. It is usually unnecessary for your code to modify state information explicitly. + An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information is continuously updated as the instance, and each instance is installed by the utility. It is usually unnecessary for your code to modify state information explicitly. - When the installation is performed, it automatically creates an to install the event log source associated with the derived class. The property for this source is set by the constructor to the computer's Application log. When you set the of the (which should be identical to the of the service), the is automatically set to the same value. In an installation failure, the source's installation is rolled-back along with previously installed services. + When the installation is performed, it automatically creates an to install the event log source associated with the derived class. The property for this source is set by the constructor to the computer's Application log. When you set the of the (which should be identical to the of the service), the is automatically set to the same value. In an installation failure, the source's installation is rolled-back along with previously installed services. - The method tries to stop the service if it is running. Whether this succeeds or not, undoes the changes made by . If a new source was created for event logging, the source is deleted. + The method tries to stop the service if it is running. Whether this succeeds or not, undoes the changes made by . If a new source was created for event logging, the source is deleted. ## Examples The following example creates a project installer, called `MyProjectInstaller`, which inherits from . It is assumed there is a service executable that contains two services, "Hello-World Service 1" and "Hello-World Service 2". Within the constructor for `MyProjectInstaller` (which would be called by the install utility), objects are created for each of these services, and a is created for the executable. For the install utility to recognize `MyProjectInstaller` as a valid installer, the attribute is set to `true`. - Optional properties are set on the process installer and the service installers before the installers are added to the collection. When the install utility accesses `MyProjectInstaller`, the objects added to the collection through a call to will be installed in turn. During the process, the installer maintains state information indicating which objects have been installed, so each can be backed out in turn, if an installation failure occurs. + Optional properties are set on the process installer and the service installers before the installers are added to the collection. When the install utility accesses `MyProjectInstaller`, the objects added to the collection through a call to will be installed in turn. During the process, the installer maintains state information indicating which objects have been installed, so each can be backed out in turn, if an installation failure occurs. Normally, you would not create an instance of your project installer class explicitly. You would create it and add the attribute to the syntax, but it is the install utility that actually calls, and therefore instantiates, the class. @@ -88,11 +88,11 @@ class, and set the attribute on the class to `true`. Within your project, create one instance per service application, and one instance for each service in the application. Within your project installer class constructor, set the installation properties for the service using the and instances, and add the instances to the collection. + To install a service, create a project installer class that inherits from the class, and set the attribute on the class to `true`. Within your project, create one instance per service application, and one instance for each service in the application. Within your project installer class constructor, set the installation properties for the service using the and instances, and add the instances to the collection. - The constructor automatically generates an event log source whose property is set to the computer's Application log, and an . When you set the of the , which should be identical to the of the service, the property of the event log is automatically set to the same value. The source is deleted automatically in the case of an installation failure. + The constructor automatically generates an event log source whose property is set to the computer's Application log, and an . When you set the of the , which should be identical to the of the service, the property of the event log is automatically set to the same value. The source is deleted automatically in the case of an installation failure. - The constructor sets the property to `ServiceStartMode.Manual` to specify that a user start the service. You can reset the property to `ServiceStartMode.Automatic` to specify that the service start when the computer reboots. + The constructor sets the property to `ServiceStartMode.Manual` to specify that a user start the service. You can reset the property to `ServiceStartMode.Automatic` to specify that the service start when the computer reboots. ]]> @@ -127,9 +127,9 @@ is usually called only by designers. + This method will rarely be called within your code. is usually called only by designers. - saves the service name of the `component` parameter to the of the instance. (Because the parameter must be an instance of a class that derives from , `component` is guaranteed to have a property.) + saves the service name of the `component` parameter to the of the instance. (Because the parameter must be an instance of a class that derives from , `component` is guaranteed to have a property.) > [!NOTE] > If you are using the Visual Studio designer, this method is called at design time when the user clicks `Add Installer` on a component that specified this class as its installer. The installer takes all information it can from the live component and stores it for use at install time. @@ -227,7 +227,7 @@ ## Examples - The following code example sets the installation properties for a new Windows service application. The example sets the service name, along with the display name and description. After assigning the installation properties for the service, the example adds the object to the collection. + The following code example sets the installation properties for a new Windows service application. The example sets the service name, along with the display name and description. After assigning the installation properties for the service, the example adds the object to the collection. :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceInstaller/Description/simpleserviceinstaller.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/ServiceInstaller/Description/service1.vb" id="Snippet3"::: @@ -272,7 +272,7 @@ is used, for example, in the Service Control Manager to provide a user-readable descriptive name for the service. The is a registry value, but is never used as a registry key. Therefore, restrictions on the property value do not apply. is used as the HKEY_LOCAL_MACHINES\System\CurrentControlSet\Services registry key, so it is restricted. + The is used, for example, in the Service Control Manager to provide a user-readable descriptive name for the service. The is a registry value, but is never used as a registry key. Therefore, restrictions on the property value do not apply. is used as the HKEY_LOCAL_MACHINES\System\CurrentControlSet\Services registry key, so it is restricted. The display name is never used by the install utility to identify the service, so there are no restrictions on the choice of name, as there is for the property. @@ -309,18 +309,18 @@ within your code; they are generally called only by the install utility. The install utility automatically calls the method during installation. It backs out failures, if necessary, by calling on the object that generated the exception. + Normally, you will not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the method during installation. It backs out failures, if necessary, by calling on the object that generated the exception. - An application's install routine maintains information automatically about the components that were already installed, using the project installer's . This state information, passed into as the `stateSaver` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. + An application's install routine maintains information automatically about the components that were already installed, using the project installer's . This state information, passed into as the `stateSaver` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. The associated with your project installation class installs information common to all instances in the project. If this service has anything that separates it from the other services in the installation project, that service-specific information is installed by this method. - To install a service, create a project installer class that inherits from the class, and set the attribute on the class to `true`. Within your project, create one instance per service application, and one instance for each service in the application. Within your project installer class constructor, set the installation properties for the service using the and instances, and add the instances to the collection. + To install a service, create a project installer class that inherits from the class, and set the attribute on the class to `true`. Within your project, create one instance per service application, and one instance for each service in the application. Within your project installer class constructor, set the installation properties for the service using the and instances, and add the instances to the collection. > [!NOTE] -> It is recommended that you use the constructor for adding installer instances; however, if you need to add to the collection in the method, be sure to perform the same additions to the collection in the method. +> It is recommended that you use the constructor for adding installer instances; however, if you need to add to the collection in the method, be sure to perform the same additions to the collection in the method. - For all classes deriving from the class, the state of the collection must be the same in the and methods. However, you can avoid the maintenance of the collection across the and methods if you add installer instances to the collection in your custom installer class constructor. + For all classes deriving from the class, the state of the collection must be the same in the and methods. However, you can avoid the maintenance of the collection across the and methods if you add installer instances to the collection in your custom installer class constructor. ]]> @@ -380,7 +380,7 @@ indicates, for example, whether two installers would install the same service under the same user account. + indicates, for example, whether two installers would install the same service under the same user account. ]]> @@ -415,9 +415,9 @@ within your code; they are generally called only by the install utility. The install utility automatically calls the method during the installation process. It backs out failures, if necessary, by calling on the object that generated the exception. + Normally, you will not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the method during the installation process. It backs out failures, if necessary, by calling on the object that generated the exception. - An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information, passed into as the `savedState` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. + An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information, passed into as the `savedState` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. ]]> @@ -473,14 +473,14 @@ be identical to the of the class you derived from . Normally, the value of the property for the service is set within the Main() function of the service application's executable. The Service Control Manager uses the property to locate the service within this executable. + It is crucial that the be identical to the of the class you derived from . Normally, the value of the property for the service is set within the Main() function of the service application's executable. The Service Control Manager uses the property to locate the service within this executable. - When you set the of the service installer, the of the associated event log is set to the same value. This allows the service to automatically log service commands (such as Start and Stop) calls to the Application log on the computer. + When you set the of the service installer, the of the associated event log is set to the same value. This allows the service to automatically log service commands (such as Start and Stop) calls to the Application log on the computer. > [!NOTE] > If a source by the same name already exists on the computer, but in a log other than the Application log, an exception will be thrown. If the source exists and is associated with the Application log, that source is used to report command calls to the service, and no exception is thrown. - The cannot be `null` or have zero length. Its maximum size is 256 characters. It also cannot contain forward or backward slashes, '/' or '\\', or characters from the ASCII character set with value less than decimal value 32. + The cannot be `null` or have zero length. Its maximum size is 256 characters. It also cannot contain forward or backward slashes, '/' or '\\', or characters from the ASCII character set with value less than decimal value 32. ]]> @@ -521,7 +521,7 @@ ## Remarks A service can require other services to be running before it can start. The information from this property is written to a key in the registry. When the user (or the system, in the case of automatic startup) tries to run the service, the Service Control Manager (SCM) verifies that each of the services in the array has already been started. - If any service in the array is not running then, the SCM tries to start them. This includes services with `Manual` . + If any service in the array is not running then, the SCM tries to start them. This includes services with `Manual` . If any service upon which this service depends fails to start, this service will not start. An exception is not thrown if the system is not started because there is no exception handling at the system level to detect this. Decide how to handle service start failures and implement this in your code. Typically, a dialog appears to the user at startup if a service fails to start. @@ -568,9 +568,9 @@ to specify either that the service be started automatically after reboot or that a user must manually start the service. A service can also be disabled, specifying that it cannot be started, either manually or programmatically, until it is enabled. + Set the to specify either that the service be started automatically after reboot or that a user must manually start the service. A service can also be disabled, specifying that it cannot be started, either manually or programmatically, until it is enabled. - You cannot change property values after installation. To change the , you either have to uninstall and reinstall your service, or manually change the setting using the Service Control Manager. + You cannot change property values after installation. To change the , you either have to uninstall and reinstall your service, or manually change the setting using the Service Control Manager. ]]> @@ -609,9 +609,9 @@ Normally, you will not call the methods on within your code; they are generally called only by the install utility. InstallUtil is used to uninstall services as well as install them; uninstalling takes a switch in the command line call. - An application's uninstall routine maintains information automatically about the components being uninstalled, using the project installer's . This state information, passed into as the `savedState` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. + An application's uninstall routine maintains information automatically about the components being uninstalled, using the project installer's . This state information, passed into as the `savedState` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. - For all classes deriving from the class, the state of the collection must be the same in the and methods. However, you can avoid the maintenance of the collection across the and methods if you add installer instances to the collection in your custom installer class constructor. + For all classes deriving from the class, the state of the collection must be the same in the and methods. However, you can avoid the maintenance of the collection across the and methods if you add installer instances to the collection in your custom installer class constructor. There is no rollback mechanism for uninstalling, so if one service fails to uninstall, this does not affect the other services (usually within the same installation project) being uninstalled. diff --git a/xml/System.ServiceProcess/ServiceProcessDescriptionAttribute.xml b/xml/System.ServiceProcess/ServiceProcessDescriptionAttribute.xml index ccb383792ee..fa37408256f 100644 --- a/xml/System.ServiceProcess/ServiceProcessDescriptionAttribute.xml +++ b/xml/System.ServiceProcess/ServiceProcessDescriptionAttribute.xml @@ -90,7 +90,7 @@ constructor is displayed by a visual designer when you access the property, event, or extender to which the attribute applies. + The description you specify in the constructor is displayed by a visual designer when you access the property, event, or extender to which the attribute applies. ]]> diff --git a/xml/System.ServiceProcess/ServiceProcessInstaller.xml b/xml/System.ServiceProcess/ServiceProcessInstaller.xml index 5999a659138..d34c616362e 100644 --- a/xml/System.ServiceProcess/ServiceProcessInstaller.xml +++ b/xml/System.ServiceProcess/ServiceProcessInstaller.xml @@ -25,25 +25,25 @@ To install a service, create a project installer class that inherits from , and set the on the class to `true`. Within your project, instantiate one instance per service application, and one instance for each service in the application. Finally, add the instance and the instances to your project installer class. - When InstallUtil.exe runs, the utility looks for classes in the service assembly with the set to `true`. Add classes to the service assembly by adding them to the collection associated with your project installer. If is `false`, the install utility ignores the project installer. + When InstallUtil.exe runs, the utility looks for classes in the service assembly with the set to `true`. Add classes to the service assembly by adding them to the collection associated with your project installer. If is `false`, the install utility ignores the project installer. - For an instance of , properties you can modify include specifying that a service application run under an account other than the logged-on user. You can specify a particular and pair under which the service should run, or you can use to specify that the service run under the computer's System account, a local or network service account, or a user account. + For an instance of , properties you can modify include specifying that a service application run under an account other than the logged-on user. You can specify a particular and pair under which the service should run, or you can use to specify that the service run under the computer's System account, a local or network service account, or a user account. > [!NOTE] > The computer's System account is not the same as the Administrator account. - Normally, you do not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the and methods during the installation process. It backs out failures, if necessary, by calling (or ) on all previously installed components. + Normally, you do not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the and methods during the installation process. It backs out failures, if necessary, by calling (or ) on all previously installed components. - An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. + An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. - Instantiating a causes the base class constructor, , to be called. + Instantiating a causes the base class constructor, , to be called. ## Examples The following example creates a project installer called MyProjectInstaller, which inherits from . It is assumed there is a service executable that contains two services, "Hello-World Service 1" and "Hello-World Service 2". Within the constructor for MyProjectInstaller (which would be called by the install utility), objects are created for each service, and a is created for the executable. For the install utility to recognize MyProjectInstaller as a valid installer, the attribute is set to `true`. - Optional properties are set on the process installer and the service installers before the installers are added to the collection. When the install utility accesses MyProjectInstaller, the objects added to the collection through a call to will be installed in turn. During the process, the installer maintains state information indicating which objects have been installed, so each object can be backed out in turn in case of an installation failure. + Optional properties are set on the process installer and the service installers before the installers are added to the collection. When the install utility accesses MyProjectInstaller, the objects added to the collection through a call to will be installed in turn. During the process, the installer maintains state information indicating which objects have been installed, so each object can be backed out in turn in case of an installation failure. Normally, you would not instantiate your project installer class explicitly. You would create it and add the , but the install utility actually calls, and therefore instantiates, the class. @@ -114,9 +114,9 @@ property is `User`, the and properties are used to define an account under which the service application runs. + When the property is `User`, the and properties are used to define an account under which the service application runs. - The and pair allows the service to run under an account other than the system account. This can, for example, allow the service to start automatically at reboot, when no user is logged on. If you leave either the or empty and set to `User`, you will be prompted for a valid user name and password at installation. + The and pair allows the service to run under an account other than the system account. This can, for example, allow the service to start automatically at reboot, when no user is logged on. If you leave either the or empty and set to `User`, you will be prompted for a valid user name and password at installation. You can also specify that the service run under the local system account, or as a local or network service. See the enumeration for details on types of accounts. @@ -222,13 +222,13 @@ within your code; they are generally called only by the install utility. The install utility automatically calls the method during the installation process. It backs out failures, if necessary, by calling on all previously installed components. This method passes the installation to the base class method. + Normally, you do not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the method during the installation process. It backs out failures, if necessary, by calling on all previously installed components. This method passes the installation to the base class method. - Normally, you will not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the and methods during the installation process. It backs out failures, if necessary, by calling (or ) on all previously installed components + Normally, you will not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the and methods during the installation process. It backs out failures, if necessary, by calling (or ) on all previously installed components - An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information, passed into as the `stateSaver` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. + An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information, passed into as the `stateSaver` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. - passes to the calling method any exceptions thrown by base class methods or / event handlers. + passes to the calling method any exceptions thrown by base class methods or / event handlers. ]]> @@ -268,15 +268,15 @@ and pair allows the service to run under an account other than the system account. This can, for example, allow the service to start automatically at reboot, when no user is logged on. + The and pair allows the service to run under an account other than the system account. This can, for example, allow the service to start automatically at reboot, when no user is logged on. - and are handled in a secure manner in that they are never serialized or saved to the install state (the project installer's ) or other location with public access. + and are handled in a secure manner in that they are never serialized or saved to the install state (the project installer's ) or other location with public access. - Setting the and allows an account to be associated automatically with the service at install time. If you leave either the or empty and set to `User`, you will be prompted for a valid user name and password at installation. + Setting the and allows an account to be associated automatically with the service at install time. If you leave either the or empty and set to `User`, you will be prompted for a valid user name and password at installation. Another option for running a service under a separate account is to use the computer's System account. That account, which is distinct from the Administrator account, requires no password. The System account's privileges may exceed those of the user currently logged in. Running under the System account rather than a user account avoids problems resulting from the user lacking a permission the service requires - If is any value other than `User`, the specified account (local or network service, or local system) is used, even if the and properties are populated. + If is any value other than `User`, the specified account (local or network service, or local system) is used, even if the and properties are populated. ]]> @@ -312,11 +312,11 @@ within your code; they are generally called only by the install utility. The install utility automatically calls the method during the installation process. It backs out failures, if necessary, by calling on the object that generated the exception. + Normally, you do not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the method during the installation process. It backs out failures, if necessary, by calling on the object that generated the exception. - An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information, passed into as the `savedState` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. + An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information, passed into as the `savedState` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. - passes to the calling method any exceptions thrown by base class methods or / event handlers. + passes to the calling method any exceptions thrown by base class methods or / event handlers. ]]> @@ -371,15 +371,15 @@ and pair allows the service to run under an account other than the system account. This can, for example, allow the service to start automatically at reboot, when no user is logged on. + The and pair allows the service to run under an account other than the system account. This can, for example, allow the service to start automatically at reboot, when no user is logged on. - and are handled in a secure manner in that they are never serialized or saved to the install state (the project installer's ) or other location with public access. + and are handled in a secure manner in that they are never serialized or saved to the install state (the project installer's ) or other location with public access. - Setting the and allows an account to be associated automatically with the service at install time. If you leave either the or empty and set to `User`, you will be prompted for a valid user name and password at installation. + Setting the and allows an account to be associated automatically with the service at install time. If you leave either the or empty and set to `User`, you will be prompted for a valid user name and password at installation. Another option for running a service under a separate account is to use the computer's System account. That account, which is distinct from the Administrator account, requires no password. The System account's privileges may exceed those of the user currently logged in. Running under the System account rather than a user account avoids problems resulting from the user lacking a permission the service requires - If is any value other than `User`, the specified account (local or network service, or local system) is used, even if the and properties are populated. + If is any value other than `User`, the specified account (local or network service, or local system) is used, even if the and properties are populated. ]]> diff --git a/xml/System.ServiceProcess/SessionChangeDescription.xml b/xml/System.ServiceProcess/SessionChangeDescription.xml index 853ecd42226..2b62000dcab 100644 --- a/xml/System.ServiceProcess/SessionChangeDescription.xml +++ b/xml/System.ServiceProcess/SessionChangeDescription.xml @@ -57,7 +57,7 @@ class in an implementation of the method in a class derived from . This code example is part of a larger example provided for the class. + The following code example shows the use of the class in an implementation of the method in a class derived from . This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/SessionChangeDescription/Overview/simpleservice.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/SessionChangeDescription/Overview/simpleservice.vb" id="Snippet9"::: @@ -116,7 +116,7 @@ or if it is `null`. Equality is determined by comparing the and properties of the specified structure to the and properties of the current structure. The two structures are considered equal if their properties are equal. + The return value is `false` if `obj` is not a or if it is `null`. Equality is determined by comparing the and properties of the specified structure to the and properties of the current structure. The two structures are considered equal if their properties are equal. ]]> @@ -160,7 +160,7 @@ and properties of the specified structure to the and properties of the current structure. The two structures are considered equal if their properties are equal. + Equality is determined by comparing the and properties of the specified structure to the and properties of the current structure. The two structures are considered equal if their properties are equal. ]]> @@ -195,7 +195,7 @@ and properties. The hash code should not be used to compare instances. + The returned hash code is calculated from the values of the and properties. The hash code should not be used to compare instances. ]]> @@ -236,9 +236,9 @@ method. + This operator is implemented using the method. - The equivalent method for this operator is ]]> + The equivalent method for this operator is ]]> @@ -277,9 +277,9 @@ method. + This operator is implemented using the method. - The equivalent method for this operator is ]]> + The equivalent method for this operator is ]]> @@ -311,7 +311,7 @@ property in an implementation of the method in a class derived from . This code example is part of a larger example provided for the class. + The following code example shows the use of the property in an implementation of the method in a class derived from . This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/SessionChangeDescription/Overview/simpleservice.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/SessionChangeDescription/Overview/simpleservice.vb" id="Snippet10"::: @@ -348,7 +348,7 @@ property in an implementation of the method in a class derived from . This code example is part of a larger example provided for the class. + The following code example shows the use of the property in an implementation of the method in a class derived from . This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/SessionChangeDescription/Overview/simpleservice.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/SessionChangeDescription/Overview/simpleservice.vb" id="Snippet10"::: diff --git a/xml/System.ServiceProcess/SessionChangeReason.xml b/xml/System.ServiceProcess/SessionChangeReason.xml index df18e617141..edb8a3a8d35 100644 --- a/xml/System.ServiceProcess/SessionChangeReason.xml +++ b/xml/System.ServiceProcess/SessionChangeReason.xml @@ -38,14 +38,14 @@ Specifies the reason for a Terminal Services session change notice. - enumeration in an implementation of the method in a class derived from . This code example is part of a larger example provided for the class. - + enumeration in an implementation of the method in a class derived from . This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/SessionChangeDescription/Overview/simpleservice.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/SessionChangeDescription/Overview/simpleservice.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/SessionChangeDescription/Overview/simpleservice.vb" id="Snippet9"::: + ]]> diff --git a/xml/System.ServiceProcess/TimeoutException.xml b/xml/System.ServiceProcess/TimeoutException.xml index fc79434aa93..4a22dbffa83 100644 --- a/xml/System.ServiceProcess/TimeoutException.xml +++ b/xml/System.ServiceProcess/TimeoutException.xml @@ -63,7 +63,7 @@ ## Remarks The class can specify a message to describe the source of the exception. When a method throws this exception, the message is usually "The timeout provided has expired and the operation has not been completed." - This class is used, for example, by the class's member. The operation that can throw the exception is a change of the service's property (for example, from `Paused` to `ContinuePending`). + This class is used, for example, by the class's member. The operation that can throw the exception is a change of the service's property (for example, from `Paused` to `ContinuePending`). ]]> diff --git a/xml/System.Speech.AudioFormat/SpeechAudioFormatInfo.xml b/xml/System.Speech.AudioFormat/SpeechAudioFormatInfo.xml index 929dd87c159..bde4ed026eb 100644 --- a/xml/System.Speech.AudioFormat/SpeechAudioFormatInfo.xml +++ b/xml/System.Speech.AudioFormat/SpeechAudioFormatInfo.xml @@ -71,7 +71,7 @@ to specify the format of audio to output to a WAV file. The instance is an argument to the method. + The following example shows a typical use of to specify the format of audio to output to a WAV file. The instance is an argument to the method. ```csharp using System; diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsDocument.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsDocument.xml index b3a2c436efb..3300be69cb6 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsDocument.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsDocument.xml @@ -215,7 +215,7 @@ SrgsDocument document = new SrgsDocument(builder); of the object and sets it as the rule for the grammar. + This constructor adds the specified rule to the of the object and sets it as the rule for the grammar. @@ -601,7 +601,7 @@ if (File.Exists(srgsDocumentFile)) ## Remarks Phonetic alphabets are composed of phones, which consist of letters, numbers or characters, sometimes in combination. Each phone describes a unique sound of speech. This is in contrast to the Latin alphabet, for which any letter may represent multiple spoken sounds. Consider the different pronunciations of the letter "c" in the words "candy" and "cease", or the different pronunciations of the letter combination "th" in the words "thing" and "those". - In System.Speech, you can use any of three phonetic alphabets to specify custom pronunciations: International Phone Alphabet (IPA), Universal Phone Set (UPS), or the SAPI phone set. The specified phonetic alphabet determines which phone set will be used to define inline pronunciations for objects. The phones specified in must match the phonetic alphabet specified in . + In System.Speech, you can use any of three phonetic alphabets to specify custom pronunciations: International Phone Alphabet (IPA), Universal Phone Set (UPS), or the SAPI phone set. The specified phonetic alphabet determines which phone set will be used to define inline pronunciations for objects. The phones specified in must match the phonetic alphabet specified in . See [Lexicons and Phonetic Alphabets](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh378335(v%3doffice.14)) for more information. @@ -640,7 +640,7 @@ if (File.Exists(srgsDocumentFile)) ## Examples - The following example creates a rule named `winnerRule`, and then creates an object named `document`. The example then calls the method to add the rule to the document. Finally, the example sets the document's property to `winnerRule`, thereby making it the `root rule` for the grammar defined by the object. + The following example creates a rule named `winnerRule`, and then creates an object named `document`. The example then calls the method to add the rule to the document. Finally, the example sets the document's property to `winnerRule`, thereby making it the `root rule` for the grammar defined by the object. ```csharp SrgsRule winnerRule = new SrgsRule("WorldCupWinner"); @@ -681,12 +681,12 @@ document.Root = winnerRule; objects to the by using the method on the property. If you initialize an object and specify an object as the argument, the is automatically added to the for the . + You can add objects to the by using the method on the property. If you initialize an object and specify an object as the argument, the is automatically added to the for the . ## Examples - The following example creates a grammar that recognizes the phrase "A nation that has won the World Cup is" followed by the name of a country/region that has won the World Cup. The example creates an object, and then creates a public rule named `winnerRule`. After adding a string to the rule `winnerRule`, the example creates two more rules (`ruleEurope` and `ruleSAmerica`), each containing a list of countries/regions. Using the method, the example adds all three rules (`winnerRule`, `ruleEurope`, and `ruleSAmerica`) to the property of the . + The following example creates a grammar that recognizes the phrase "A nation that has won the World Cup is" followed by the name of a country/region that has won the World Cup. The example creates an object, and then creates a public rule named `winnerRule`. After adding a string to the rule `winnerRule`, the example creates two more rules (`ruleEurope` and `ruleSAmerica`), each containing a list of countries/regions. Using the method, the example adds all three rules (`winnerRule`, `ruleEurope`, and `ruleSAmerica`) to the property of the . ```csharp public void WorldSoccerWinners () @@ -788,7 +788,7 @@ public void WorldSoccerWinners () object, and then creates a public rule named `winnerRule`. It then creates an that consists of the string "A nation that has won the World Cup is:", and adds this item to the property of the rule. The example then creates two more rules (`ruleEurope` and `ruleSAmerica`), each of which is an object that contains three objects. After that, another object is created that contains objects that refer to `ruleEurope` and `ruleSAmerica`. The new object is then added to the property of `winnerRule`. After this, all three rules (`winnerRule`, `ruleEurope`, and `ruleSAmerica`) are added to the property of the . Finally, the example creates an empty XML file and an instance of . The method uses the instance to write the contents of the to the XML file. + The following example creates an object, and then creates a public rule named `winnerRule`. It then creates an that consists of the string "A nation that has won the World Cup is:", and adds this item to the property of the rule. The example then creates two more rules (`ruleEurope` and `ruleSAmerica`), each of which is an object that contains three objects. After that, another object is created that contains objects that refer to `ruleEurope` and `ruleSAmerica`. The new object is then added to the property of `winnerRule`. After this, all three rules (`winnerRule`, `ruleEurope`, and `ruleSAmerica`) are added to the property of the . Finally, the example creates an empty XML file and an instance of . The method uses the instance to write the contents of the to the XML file. ```csharp public void WorldSoccerWinners () @@ -864,7 +864,7 @@ public void WorldSoccerWinners () property gets a value that is used to resolve relative URIs in a object. Suppose the value for is `http://www.contoso.com/` and the contains a relative rule reference to another document, for example `SrgsRuleRef("ExternalGrammar.grxml")`. This creates the following absolute path to the external document: `http://www.contoso.com/ExternalGrammar.grxml`. + property gets a value that is used to resolve relative URIs in a object. Suppose the value for is `http://www.contoso.com/` and the contains a relative rule reference to another document, for example `SrgsRuleRef("ExternalGrammar.grxml")`. This creates the following absolute path to the external document: `http://www.contoso.com/ExternalGrammar.grxml`. [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsGrammarCompiler.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsGrammarCompiler.xml index 44ffd9d6ff5..5e3c7b47428 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsGrammarCompiler.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsGrammarCompiler.xml @@ -25,13 +25,13 @@ Compiles and XML-format grammar files into binary grammar files with the .cfg extension and sends the output to a stream. - objects and XML-format grammars to a binary format to optimize them for loading and consumption by a speech recognition engine. Compiling a speech recognition grammar using one of the methods can reduce the amount of time required to construct a object from an or an XML-format grammar. - - For more information, see [Compile SRGS Grammars](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh361674(v=office.14)). - + objects and XML-format grammars to a binary format to optimize them for loading and consumption by a speech recognition engine. Compiling a speech recognition grammar using one of the methods can reduce the amount of time required to construct a object from an or an XML-format grammar. + + For more information, see [Compile SRGS Grammars](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh361674(v=office.14)). + ]]> @@ -71,16 +71,16 @@ The stream that receives the results of compilation. Compiles an object into a binary grammar file with the .cfg extension and sends the output to a stream. - - is . - + is . + is . @@ -110,20 +110,20 @@ The stream that receives the results of compilation. Compiles an XML-format grammar file into a binary grammar file with the .cfg extension and sends the output to a stream. - - is . - + is . + is . is an empty string. @@ -155,18 +155,18 @@ The stream that will receive the results of compilation. Compiles data for an XML-format grammar file referenced by an into a binary grammar file with the .cfg extension and sends the output to a stream. - must conform to the [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://www.w3.org/TR/speech-grammar/). - - For more information, see [Compile SRGS Grammars](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh361674(v=office.14)). - + must conform to the [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://www.w3.org/TR/speech-grammar/). + + For more information, see [Compile SRGS Grammars](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh361674(v=office.14)). + ]]> - is . - + is . + is . @@ -210,8 +210,8 @@ Compiles an SRGS document into a DLL. To be added. - is . - + is . + is . is an empty string. @@ -248,12 +248,12 @@ Compiles multiple SRGS grammars into a DLL. To be added. - is . - + is . + is . - is an empty string. - + is an empty string. + Any element of the array is . @@ -288,8 +288,8 @@ Compiles an SRGS grammar into a DLL. To be added. - is . - + is . + is . is an empty string. diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsItem.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsItem.xml index ffd59cf0332..731ece08b69 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsItem.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsItem.xml @@ -45,7 +45,7 @@ ## Remarks An object can consist of phrases, entities such as objects, logical combinations of phrases and objects, and so on. You can use the property on the class to gain access to the constituents of an object. - The order in which objects appear in a given object specifies the order in which a user must speak them. By default, the contents of an must be spoken exactly once. To specify that the contents of an must be spoken repeatedly, use the constructor and set the `repeatCount` parameter. Similarly, to specify a range for the number of times that an can be spoken, create the with one of the constructors that set the property and the property. If the already exists, you can use one of the or the methods to specify repeats. + The order in which objects appear in a given object specifies the order in which a user must speak them. By default, the contents of an must be spoken exactly once. To specify that the contents of an must be spoken repeatedly, use the constructor and set the `repeatCount` parameter. Similarly, to specify a range for the number of times that an can be spoken, create the with one of the constructors that set the property and the property. If the already exists, you can use one of the or the methods to specify repeats. You can also specify the probability that an item will be repeatedly spoken by setting the value of the property. @@ -118,7 +118,7 @@ and properties of the new to the value in `repeatCount`. + This constructor sets and properties of the new to the value in `repeatCount`. ]]> @@ -314,7 +314,7 @@ method appends an element to the property. + The method appends an element to the property. ]]> @@ -377,7 +377,7 @@ method. + To set this property, use the method. This property represents a portion of the `repeat` attribute defined by the World Wide Web Consortium (W3C) [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://www.w3.org/TR/speech-grammar/). @@ -410,7 +410,7 @@ method. + To set this property, use the method. This property represents a portion of the `repeat` attribute of the World Wide Web Consortium (W3C) Speech Recognition Grammar Specification (SRGS). @@ -449,7 +449,7 @@ and properties have been explicitly set to non-default values, either by a constructor for or by the method. + The property applies only to items whose and properties have been explicitly set to non-default values, either by a constructor for or by the method. ]]> @@ -493,7 +493,7 @@ and properties to the value in `count`. + This method sets the and properties to the value in `count`. ]]> diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsNameValueTag.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsNameValueTag.xml index 1c29dc7b038..e6457765962 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsNameValueTag.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsNameValueTag.xml @@ -39,16 +39,16 @@ property of this object cannot be script. The contents of can be of the type , , , or . String values must be enclosed in double quotes. + This object is similar to the `tag` element defined by the World Wide Web Consortium (W3C) [Speech Recognition Grammar Specification (SRGS) Version 1.0.](https://go.microsoft.com/fwlink/?LinkId=201761). However, the property of this object cannot be script. The contents of can be of the type , , , or . String values must be enclosed in double quotes. To add semantics as script, use . ## Examples - The following example creates a grammar for choosing the cities for a flight. The example uses to assign a semantic value to each city, which is the code for the city's airport. + The following example creates a grammar for choosing the cities for a flight. The example uses to assign a semantic value to each city, which is the code for the city's airport. - The example constructs two instances, each of which specifies a semantic key. Both rule references target the same object, named `cities`, but tag the recognition result from the rule reference with a different semantic key. The semantic key identifies a recognized city as the departure city or the arrival city for the flight. The handler for the event uses the keys to retrieve the semantics values created using from the recognition result. + The example constructs two instances, each of which specifies a semantic key. Both rule references target the same object, named `cities`, but tag the recognition result from the rule reference with a different semantic key. The semantic key identifies a recognized city as the departure city or the arrival city for the flight. The handler for the event uses the keys to retrieve the semantics values created using from the recognition result. ``` using System; @@ -189,9 +189,9 @@ namespace SampleRecognition to assign a semantic value to each city, which is the code for the city's airport. + The following example creates a grammar for choosing the cities for a flight. The example uses to assign a semantic value to each city, which is the code for the city's airport. - The example constructs two instances, each of which specifies a semantic key. Both rule references target the same object, named `cities`, but tag the recognition result from the rule reference with a different semantic key. The semantic key identifies a recognized city as the departure city or the arrival city for the flight. The handler for the event uses the keys to retrieve the semantics values created using from the recognition result. + The example constructs two instances, each of which specifies a semantic key. Both rule references target the same object, named `cities`, but tag the recognition result from the rule reference with a different semantic key. The semantic key identifies a recognized city as the departure city or the arrival city for the flight. The handler for the event uses the keys to retrieve the semantics values created using from the recognition result. ``` using System; diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsOneOf.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsOneOf.xml index 1fabcd5c444..0956f20731f 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsOneOf.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsOneOf.xml @@ -63,7 +63,7 @@ class from an array of objects, from an array of objects, or as an empty list. Using objects instead of objects in a list of alternatives lets you apply properties of to each item in the list, such as , , , and . + You can construct an instance of the class from an array of objects, from an array of objects, or as an empty list. Using objects instead of objects in a list of alternatives lets you apply properties of to each item in the list, such as , , , and . ]]> @@ -161,7 +161,7 @@ public void WorldSoccerWinners () objects using objects that contain arrays of new objects. To see the grammar that this example generates, see . + The following example creates a grammar that recognizes the phrase "A nation that has won the World Cup is" followed by the name of a country/region that has won the World Cup. It creates a public rule named `WorldCupWinner`. It then creates two objects using objects that contain arrays of new objects. To see the grammar that this example generates, see . ```csharp public void WorldSoccerWinners () @@ -304,7 +304,7 @@ public void WorldSoccerWinners () object to build lists of acceptable country/region names from an array of objects. Using the method, the example appends an that contains the string "Italy" to the object `oneOfEurope`. + The following example creates a grammar that recognizes the phrase "A nation that has won the World Cup is" followed by the name of a country/region that has won the World Cup. The example uses the object to build lists of acceptable country/region names from an array of objects. Using the method, the example appends an that contains the string "Italy" to the object `oneOfEurope`. ```csharp public void WorldSoccerWinners () diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsPhoneticAlphabet.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsPhoneticAlphabet.xml index a95ae644c73..f34a33a9ace 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsPhoneticAlphabet.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsPhoneticAlphabet.xml @@ -24,13 +24,13 @@ Enumerates the supported phonetic alphabets. - objects. The phones specified in must match the phonetic alphabet specified in . - + objects. The phones specified in must match the phonetic alphabet specified in . + ]]> diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsRule.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsRule.xml index b95ae633d63..31ccf0fa18f 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsRule.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsRule.xml @@ -93,9 +93,9 @@ constructor initializes the property. The identifier must be unique within a given grammar. + The constructor initializes the property. The identifier must be unique within a given grammar. - The constructor throws a in the following circumstances: + The constructor throws a in the following circumstances: - `id` is not a valid XML name, as defined in [Extensible Markup Language (XML) 1.0 (Fifth Edition)](https://www.w3.org/TR/REC-xml/). To paraphrase this definition, a valid XML name must begin with a letter, an underscore ('_'), or a colon (':') and can be followed by zero or more NameChar characters (also defined in the XML specification). @@ -184,9 +184,9 @@ public void WorldSoccerWinners () constructor initializes the property. The identifier must be unique within a given grammar. + The constructor initializes the property. The identifier must be unique within a given grammar. - The constructor throws a in the following circumstances: + The constructor throws a in the following circumstances: - `id` is not a valid XML name, as defined in [Extensible Markup Language (XML) 1.0 (Fifth Edition)](https://www.w3.org/TR/REC-xml/). To paraphrase this definition, a valid XML name must begin with a letter, an underscore ('_'), or a colon (':') and can be followed by zero or more NameChar characters (also defined in the XML specification). @@ -307,7 +307,7 @@ public void WorldSoccerWinners () ## Examples - The following example creates a grammar that recognizes the phrase "A nation that has won the World Cup is" followed by the name of a country that has won the World Cup. After creating the object `winnerRule` and giving it the string identifier `WorldCupWinner`, the example uses the method to append the string "A nation that has won the World Cup is" to the rule. The example then creates two additional rules, `ruleEurope` and `ruleSAmerica`. Again using the method, the example appends an object to the `WorldCupWinner` rule that contains rule references to `ruleEurope` and `ruleSAmerica`. + The following example creates a grammar that recognizes the phrase "A nation that has won the World Cup is" followed by the name of a country that has won the World Cup. After creating the object `winnerRule` and giving it the string identifier `WorldCupWinner`, the example uses the method to append the string "A nation that has won the World Cup is" to the rule. The example then creates two additional rules, `ruleEurope` and `ruleSAmerica`. Again using the method, the example appends an object to the `WorldCupWinner` rule that contains rule references to `ruleEurope` and `ruleSAmerica`. ```csharp // Create an SrgsDocument, create a new rule @@ -446,7 +446,7 @@ document.Root = winnerRule; ## Remarks The identifier for a rule is a string that contains the name of the rule. - A value used to set must adhere to the following rules: + A value used to set must adhere to the following rules: - The value must be a valid XML name, as defined in [Extensible Markup Language (XML) 1.0 (Fifth Edition)](https://www.w3.org/TR/REC-xml/). To paraphrase this definition, a valid XML name must begin with a letter, an underscore ('_'), or a colon (':') and can be followed by zero or more NameChar characters (also defined in the XML specification). diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsRuleRef.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsRuleRef.xml index e791d300a34..34ea44bfd8b 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsRuleRef.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsRuleRef.xml @@ -97,13 +97,13 @@ ## Remarks This constructor creates a rule reference to an object within the containing grammar. To create a rule reference to a `rule` element in an external grammar file, use any of the following constructors: -- +- -- +- -- +- -- +- @@ -210,11 +210,11 @@ public void WorldSoccerWinners () ## Remarks This constructor creates a rule reference to an external grammar file. The URI may also include the identifier of a rule to reference, for example `http://www.contoso.com/ExternalGrammar.grxml#targetRule`. If the `uri` parameter does not specify a rule identifier, the rule reference points to the root rule of the target grammar. To create a rule reference to an object within the same grammar, use any of the following constructors: -- +- -- +- -- +- [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] @@ -284,18 +284,18 @@ private SrgsDocument CreateGrammarForRoute() ## Remarks This constructor creates a rule reference to an object within the containing grammar. To create a rule reference to a `rule` element in an external grammar file, use any of the following constructors: -- +- -- +- -- +- -- +- ## Examples - The following example creates a grammar for choosing the cities for a flight. The example constructs two instances, each of which specifies a semantic key. Both rule references target the same object, named `cities`, but tag the recognition result from the rule reference with a different semantic key. The semantic key identifies a recognized city as the departure city or the arrival city for the flight. The handler for the event uses the keys to retrieve the semantics values created using from the recognition result. + The following example creates a grammar for choosing the cities for a flight. The example constructs two instances, each of which specifies a semantic key. Both rule references target the same object, named `cities`, but tag the recognition result from the rule reference with a different semantic key. The semantic key identifies a recognized city as the departure city or the arrival city for the flight. The handler for the event uses the keys to retrieve the semantics values created using from the recognition result. ```csharp using System; @@ -406,11 +406,11 @@ namespace SampleRecognition ## Remarks This constructor creates a rule reference to a `rule` element in an external grammar file. To create a rule reference to an object within the same grammar, use any of the following constructors: -- +- -- +- -- +- [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] @@ -455,13 +455,13 @@ namespace SampleRecognition ## Remarks This constructor creates a rule reference to an object within the containing grammar. To create a rule reference to a `rule` element in an external grammar file, use any of the following constructors: -- +- -- +- -- +- -- +- ]]> @@ -498,11 +498,11 @@ namespace SampleRecognition ## Remarks This constructor creates a rule reference to a `rule` element in an external grammar file. To create a rule reference to an object within the same grammar, use any of the following constructors: -- +- -- +- -- +- [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] @@ -549,11 +549,11 @@ namespace SampleRecognition ## Remarks This constructor creates a rule reference to a `rule` element in an external grammar file. To create a rule reference to an object within the same grammar, use any of the following constructors: -- +- -- +- -- +- [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsRulesCollection.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsRulesCollection.xml index ad7c5ab0d17..0b13fb6e531 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsRulesCollection.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsRulesCollection.xml @@ -39,7 +39,7 @@ object, you must add it to the collection of an instance using the method. An cannot be used for recognition until it has been added to the collection of an instance. + After you define the content for an object, you must add it to the collection of an instance using the method. An cannot be used for recognition until it has been added to the collection of an instance. ]]> diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsSemanticInterpretationTag.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsSemanticInterpretationTag.xml index ae1661f6918..1cc78a96e49 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsSemanticInterpretationTag.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsSemanticInterpretationTag.xml @@ -52,7 +52,7 @@ In the code example, "out" refers to the Rule Variable of the containing . The expression "out.LeavingFrom" refers to the property named `LeavingFrom` of the Rule Variable on the rule named `bookFlight`. - The expression "rules.flightCities" refers to the Rule Variable on the rule whose is `flightCities`, and which is the target of a rule reference. In the example, the expression "out.LeavingFrom=rules.flightCities;" assigns the value from the rule whose is `flightCities` to the property named `LeavingFrom` of the Rule Variable on the rule named `bookFlight`. See [Semantic Results Content](https://msdn.microsoft.com/library/622291af-615c-4a15-9014-2933aa3f89fe), [Grammar Rule Name Referencing](https://msdn.microsoft.com/library/0777e975-8665-4cc3-957b-752743cb1bb9), and [Grammar Rule Reference Referencing](https://msdn.microsoft.com/library/dec3a809-9aa2-4139-893f-3a549ca1e03e) for more information. + The expression "rules.flightCities" refers to the Rule Variable on the rule whose is `flightCities`, and which is the target of a rule reference. In the example, the expression "out.LeavingFrom=rules.flightCities;" assigns the value from the rule whose is `flightCities` to the property named `LeavingFrom` of the Rule Variable on the rule named `bookFlight`. See [Semantic Results Content](https://msdn.microsoft.com/library/622291af-615c-4a15-9014-2933aa3f89fe), [Grammar Rule Name Referencing](https://msdn.microsoft.com/library/0777e975-8665-4cc3-957b-752743cb1bb9), and [Grammar Rule Reference Referencing](https://msdn.microsoft.com/library/dec3a809-9aa2-4139-893f-3a549ca1e03e) for more information. ```csharp using System; diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsText.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsText.xml index 0ca9eaf9823..37a1ff6e078 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsText.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsText.xml @@ -39,7 +39,7 @@ class represents the text found within a set of SRGS element tags. When an object is constructed with a parameter, a object is created with its property initialized to the value of that parameter. The object is then added to the collection on the object. + The class represents the text found within a set of SRGS element tags. When an object is constructed with a parameter, a object is created with its property initialized to the value of that parameter. The object is then added to the collection on the object. diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsToken.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsToken.xml index 2dcfe18ed43..68e4e8a13f8 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsToken.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsToken.xml @@ -39,7 +39,7 @@ class, you can specify three forms of a word: the form, the form, and a custom for the word. + Using the members of the class, you can specify three forms of a word: the form, the form, and a custom for the word. If multiple words are stored in a single object, each is treated as a different token internally and in the result. @@ -113,7 +113,7 @@ form may be different than the form for a word or phrase in a . For example, the display form may be an acronym, such as "USA", while the text that will be spoken, and to which the applies, is "United States of America". + Although they typically represent the same value, the form may be different than the form for a word or phrase in a . For example, the display form may be an acronym, such as "USA", while the text that will be spoken, and to which the applies, is "United States of America". ]]> @@ -151,13 +151,13 @@ must match the phonetic alphabet specified in . See [Lexicons and Phonetic Alphabets](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh378335(v%3doffice.14)) for more information. + Phones are letters or symbols that describe the sounds of speech. System.Speech supports three phonetic alphabets for specifying custom pronunciations: the Universal Phone Set (UPS), the Speech API (SAPI) Phone set, and the International Phonetic Alphabet (IPA). The phones specified in must match the phonetic alphabet specified in . See [Lexicons and Phonetic Alphabets](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh378335(v%3doffice.14)) for more information. - The phones specified in indicate how the contents of should be pronounced for successful recognition. The speech recognition engine uses the pronunciation specified in to match speech input and returns the string contained by in the recognition result. + The phones specified in indicate how the contents of should be pronounced for successful recognition. The speech recognition engine uses the pronunciation specified in to match speech input and returns the string contained by in the recognition result. - If the phones are not space-delimited or the specified string contains an unrecognized phone, the recognition engine does not recognize the specified pronunciation as a valid pronunciation of the word contained by . + If the phones are not space-delimited or the specified string contains an unrecognized phone, the recognition engine does not recognize the specified pronunciation as a valid pronunciation of the word contained by . - Pronunciations specified in take precedence over pronunciations specified in lexicons associated with a grammar or a recognition engine. Also, the pronunciation in the property applies only to the single occurrence of the word or phrase contained by . + Pronunciations specified in take precedence over pronunciations specified in lexicons associated with a grammar or a recognition engine. Also, the pronunciation in the property applies only to the single occurrence of the word or phrase contained by . @@ -278,7 +278,7 @@ namespace SampleRecognition form may be different than the form for a word or phrase in a . For example, the form may be an acronym, such as "USA", while the text that will be spoken, and to which the applies, is "United States of America". + Although they typically represent the same value, the form may be different than the form for a word or phrase in a . For example, the form may be an acronym, such as "USA", while the text that will be spoken, and to which the applies, is "United States of America". The default value for the property is an empty string - "". diff --git a/xml/System.Speech.Recognition/AudioSignalProblemOccurredEventArgs.xml b/xml/System.Speech.Recognition/AudioSignalProblemOccurredEventArgs.xml index 32b991ebe42..32d77dfe608 100644 --- a/xml/System.Speech.Recognition/AudioSignalProblemOccurredEventArgs.xml +++ b/xml/System.Speech.Recognition/AudioSignalProblemOccurredEventArgs.xml @@ -30,13 +30,13 @@ ## Remarks An instance of is created when the or object raises an `AudioSignalProblemOccurred` event. To obtain information related to an `AudioSignalProblemOccurred` event, access the following properties in the handler for the event: -- +- -- +- -- +- -- +- The property references the input device's position in its generated audio stream. By contrast, the property references the recognizer's position within its audio input. These positions can be different. For more information, see [Using Speech Recognition Events](https://msdn.microsoft.com/library/01c598ca-2e0e-4e89-b303-cd1cef9e8482). diff --git a/xml/System.Speech.Recognition/AudioState.xml b/xml/System.Speech.Recognition/AudioState.xml index 99f9b4356a4..b740d6c2ab9 100644 --- a/xml/System.Speech.Recognition/AudioState.xml +++ b/xml/System.Speech.Recognition/AudioState.xml @@ -24,41 +24,41 @@ Contains a list of possible states for the audio input to a speech recognition engine. - and properties. The and events are raised when the audio input state of a speech recognition engine changes. - - - -## Examples - The following example demonstrates an event handler that handles the changing audio state of a speech recognizer. - -```csharp - -private SpeechRecognitionEngine sre; - -// Initializes the speech recognition engine. -private void Initialize() -{ - sre = new SpeechRecognitionEngine(); - - // Add a handler for the AudioStateChanged event. - sre.AudioStateChanged += new EventHandler(sre_AudioStateChanged); - - // Add other initialization code here. -} - - // Handle the AudioStateChanged event. - void sre_AudioStateChanged(object sender, AudioStateChangedEventArgs e) -{ - AudioState newState = e.AudioState; - - // Handle event here. -} - -``` - + and properties. The and events are raised when the audio input state of a speech recognition engine changes. + + + +## Examples + The following example demonstrates an event handler that handles the changing audio state of a speech recognizer. + +```csharp + +private SpeechRecognitionEngine sre; + +// Initializes the speech recognition engine. +private void Initialize() +{ + sre = new SpeechRecognitionEngine(); + + // Add a handler for the AudioStateChanged event. + sre.AudioStateChanged += new EventHandler(sre_AudioStateChanged); + + // Add other initialization code here. +} + + // Handle the AudioStateChanged event. + void sre_AudioStateChanged(object sender, AudioStateChangedEventArgs e) +{ + AudioState newState = e.AudioState; + + // Handle event here. +} + +``` + ]]> diff --git a/xml/System.Speech.Recognition/Choices.xml b/xml/System.Speech.Recognition/Choices.xml index 0c30cf842ba..29736e859ee 100644 --- a/xml/System.Speech.Recognition/Choices.xml +++ b/xml/System.Speech.Recognition/Choices.xml @@ -39,7 +39,7 @@ For example, a object could represent the component *colorChoice* in the phrase, "Change the color to *colorChoice*", where acceptable values for *colorChoice* are "red", or "green", or "blue". > [!NOTE] -> To use a object as an optional component in a phrase, create the object and add it to a object with `minRepeat` and `maxRepeat` set to 0 and 1, respectively. Phrases containing optional components can be recognized whether or not the optional component is spoken. +> To use a object as an optional component in a phrase, create the object and add it to a object with `minRepeat` and `maxRepeat` set to 0 and 1, respectively. Phrases containing optional components can be recognized whether or not the optional component is spoken. The class serves the same function as the `one-of` XML element defined by the [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://www.w3.org/TR/speech-grammar/) and is similar to the class in the namespace. @@ -137,7 +137,7 @@ public GrammarBuilder ChoicesConstructor2 () methods. + This constructor returns a valid, empty set of alternatives. You can add alternatives using any of the methods. @@ -213,7 +213,7 @@ public Grammar CreatePhonePhrase() in `alternateChoices` defines one alternative. If `alternateChoices` is an empty array, the constructor returns an empty set of alternatives. You can add alternatives using any of the methods. + Each in `alternateChoices` defines one alternative. If `alternateChoices` is an empty array, the constructor returns an empty set of alternatives. You can add alternatives using any of the methods. The constructor throws an when `alternateChoices` is `null` or when any of the array elements are `null`. @@ -293,7 +293,7 @@ public Grammar CreatePhonePhrase() in `phrases` defines one alternative. The speech recognition engine can use any one of the items in the string array to match speech input. If `phrases` is an empty array, the constructor returns an empty set of alternatives. You can add alternatives using any of the methods. + Each in `phrases` defines one alternative. The speech recognition engine can use any one of the items in the string array to match speech input. If `phrases` is an empty array, the constructor returns an empty set of alternatives. You can add alternatives using any of the methods. The constructor throws an when `phrases` is `null` or any of the array elements are `null`. The constructor throws an if any element in the array is an empty string (""). @@ -387,14 +387,14 @@ public Grammar CreatePhonePhrase() If `alternateChoices` is an empty array, this method does not update the set of alternatives. - Applications can use both and to add alternatives to a object. + Applications can use both and to add alternatives to a object. This method throws an when `alternateChoices` is `null` or any of the array elements are `null`. ## Examples - The following example creates a speech recognition grammar for phrases such as "Call Anne on her cell" and "Call James on his work phone". The example uses both overloads of the method to build the grammar. + The following example creates a speech recognition grammar for phrases such as "Call Anne on her cell" and "Call James on his work phone". The example uses both overloads of the method to build the grammar. ```csharp public Grammar CreatePhonePhrase() @@ -468,7 +468,7 @@ public Grammar CreatePhonePhrase() and to add alternatives to a object. + Applications can use both and to add alternatives to a object. If `phrases` is an empty array, this method does not update the set of alternates. @@ -477,7 +477,7 @@ public Grammar CreatePhonePhrase() ## Examples - The following example creates a speech recognition grammar for phrases similar to "Call Anne on her cell" and "Call James on his work phone". The example uses both overloads of the method to build the grammar. + The following example creates a speech recognition grammar for phrases similar to "Call Anne on her cell" and "Call James on his work phone". The example uses both overloads of the method to build the grammar. ```csharp public Grammar CreatePhonePhrase() @@ -544,7 +544,7 @@ public Grammar CreatePhonePhrase() ## Remarks The returned by this method is equivalent to one returned by either of the following. -- Calling the constructor with this object as the parameter. +- Calling the constructor with this object as the parameter. - Using the implicit or explicit cast of this object to a . diff --git a/xml/System.Speech.Recognition/DictationGrammar.xml b/xml/System.Speech.Recognition/DictationGrammar.xml index eb2c3f7b0f7..220366a2ec6 100644 --- a/xml/System.Speech.Recognition/DictationGrammar.xml +++ b/xml/System.Speech.Recognition/DictationGrammar.xml @@ -28,17 +28,17 @@ objects. For information about selecting a dictation grammar, see the constructor. + This class provides applications with a predefined language model that can process spoken user input into text. This class supports both default and custom objects. For information about selecting a dictation grammar, see the constructor. - By default, the language model is context free. It does not make use of specific words or word order to identify and interpret audio input. To add context to the dictation grammar, use the method. + By default, the language model is context free. It does not make use of specific words or word order to identify and interpret audio input. To add context to the dictation grammar, use the method. > [!NOTE] -> objects do not support the property. throws a if is set. +> objects do not support the property. throws a if is set. ## Examples - The following example creates three dictation grammars, adds them to a new object, and returns the new object. The first grammar is the default dictation grammar. The second grammar is the spelling dictation grammar. The third grammar is the default dictation grammar that includes a context phrase. The method is used to associate the context phrase with the dictation grammar after it is loaded to the object. + The following example creates three dictation grammars, adds them to a new object, and returns the new object. The first grammar is the default dictation grammar. The second grammar is the spelling dictation grammar. The third grammar is the default dictation grammar that includes a context phrase. The method is used to associate the context phrase with the dictation grammar after it is loaded to the object. ```csharp @@ -178,7 +178,7 @@ private SpeechRecognitionEngine LoadDictationGrammars() By default, the dictation grammar does not make use of specific words or word order to identify and interpret audio input. When a context is added to a dictation grammar, the recognition engine uses the `precedingText` and `subsequentText` to identify when to interpret speech as dictation. > [!NOTE] -> A dictation grammar must be loaded by a or object before you can use to add a context. +> A dictation grammar must be loaded by a or object before you can use to add a context. The following table describes how the recognition engine uses the two parameters to determine when to use the dictation grammar. diff --git a/xml/System.Speech.Recognition/EmulateRecognizeCompletedEventArgs.xml b/xml/System.Speech.Recognition/EmulateRecognizeCompletedEventArgs.xml index 2e5da491f7a..08027ee87bb 100644 --- a/xml/System.Speech.Recognition/EmulateRecognizeCompletedEventArgs.xml +++ b/xml/System.Speech.Recognition/EmulateRecognizeCompletedEventArgs.xml @@ -30,7 +30,7 @@ ## Remarks An instance of is created when the object raises the event. To obtain information about the result of recognition, access the property in the handler for the event. - Emulation is the process by which text, instead of audio, is the input to a speech recognition engine. To bypass the audio inputs for a object during emulation, use the method. + Emulation is the process by which text, instead of audio, is the input to a speech recognition engine. To bypass the audio inputs for a object during emulation, use the method. If the speech recognition engine encounters an exception during the recognition operation, the property is set to the exception and the property is set to `null`. diff --git a/xml/System.Speech.Recognition/Grammar.xml b/xml/System.Speech.Recognition/Grammar.xml index 0bdc9a7088b..98d633def29 100644 --- a/xml/System.Speech.Recognition/Grammar.xml +++ b/xml/System.Speech.Recognition/Grammar.xml @@ -36,15 +36,15 @@ ## Remarks A speech recognition grammar is a set of rules or constraints that define what a speech recognition engine can recognize as meaningful input. For more information about creating and using speech recognition grammars, see [Speech Recognition](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh361633(v=office.14)), and [Create Grammars Using SrgsGrammar](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh361680(v%3doffice.14)). - After you author a grammar, you must build it into a object that a speech recognition engine can load and that your application can use at runtime to manage speech recognition. You can use a constructor to create a instance from a or a object, or from a file or a that contains a description of a grammar in a supported format. Supported formats include the following: + After you author a grammar, you must build it into a object that a speech recognition engine can load and that your application can use at runtime to manage speech recognition. You can use a constructor to create a instance from a or a object, or from a file or a that contains a description of a grammar in a supported format. Supported formats include the following: - XML-format files that conform to the W3C [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761) - Grammars that have been compiled to a binary file with a .cfg file extension - Grammar constructors that accept XML-format grammar files in their arguments compile the XML grammars to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. + Grammar constructors that accept XML-format grammar files in their arguments compile the XML grammars to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. - An application's speech recognition engine, as managed by a or object, can load multiple speech recognition grammars. The application can independently enable or disable individual grammars by setting the property, and modify recognition behavior through properties, such as the and properties. + An application's speech recognition engine, as managed by a or object, can load multiple speech recognition grammars. The application can independently enable or disable individual grammars by setting the property, and modify recognition behavior through properties, such as the and properties. The grammar's event is raised when input matches a path through the grammar. @@ -121,13 +121,13 @@ private static Grammar CreateGrammarFromFile() constructor to create a instance from a or object, or from a file or a that contains a description of a grammar in a supported format. Supported formats include the following: + You can use a constructor to create a instance from a or object, or from a file or a that contains a description of a grammar in a supported format. Supported formats include the following: - XML-format files that conform to the W3C [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761) - Grammars that have been compiled to a binary file with a .cfg file extension - Grammar constructors that accept XML-format grammar files in their arguments compile the XML grammars to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. + Grammar constructors that accept XML-format grammar files in their arguments compile the XML grammars to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. A speech recognition grammar can define a root rule. To create a object that specifies which rule to use as its root rule, use a constructor that accepts the `ruleName` parameter. @@ -194,11 +194,11 @@ private static Grammar CreateGrammarFromFile() - Grammars that have been compiled to a binary file with a .cfg file extension - This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. + This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. - An SRGS grammar can define a root rule. To create a object from a stream and specify a root rule, use the or constructor. + An SRGS grammar can define a root rule. To create a object from a stream and specify a root rule, use the or constructor. - To create a object from a stream and specify a base URI to use to resolve relative rule references, use the constructor. + To create a object from a stream and specify a base URI to use to resolve relative rule references, use the constructor. @@ -284,7 +284,7 @@ private static Grammar CreateGrammarFromStream() and objects. The constructor creates a object from the object. + The following example creates a speech recognition grammar using and objects. The constructor creates a object from the object. ```csharp // Create a grammar using a GrammarBuilder and return the new grammar. @@ -346,9 +346,9 @@ private static Grammar CreateGrammarBuilderGrammar() ## Remarks This constructor does not pass any parameters to the initialization handler, and the should not contain an initialization handler that requires arguments. - A can have a root rule. To create a object that specifies a root rule, use the or constructor. + A can have a root rule. To create a object that specifies a root rule, use the or constructor. - To create a speech recognition from an and specify a base URI to use to resolve relative rule references, use the constructor. + To create a speech recognition from an and specify a base URI to use to resolve relative rule references, use the constructor. @@ -451,11 +451,11 @@ private static Grammar CreateSrgsDocumentGrammar() - Grammars that have been compiled to a binary file with a .cfg file extension - This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. + This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. - An SRGS grammar can define a root rule. To create a object from a string and specify a root rule, use the constructor. + An SRGS grammar can define a root rule. To create a object from a string and specify a root rule, use the constructor. - To create a object that specifies a base URI to use to resolve relative rule references, open the file in a file stream and use the constructor. + To create a object that specifies a base URI to use to resolve relative rule references, open the file in a file stream and use the constructor. @@ -556,9 +556,9 @@ private static Grammar CreateGrammarFromFile() - Grammars that have been compiled to a binary file with a .cfg file extension - This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. + This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. - To create a from a stream and specify a base URI to use to resolve relative rule references, use the constructor. + To create a from a stream and specify a base URI to use to resolve relative rule references, use the constructor. @@ -653,7 +653,7 @@ private static Grammar CreateGrammarFromStream2() ## Remarks This constructor does not pass any parameters to the initialization handler, and the should not contain an initialization handler that requires arguments. - To create a object from a and specify a base URI to use to resolve relative rule references, use the constructor. + To create a object from a and specify a base URI to use to resolve relative rule references, use the constructor. @@ -792,9 +792,9 @@ namespace SampleRecognition - Grammars that have been compiled to a binary file with a .cfg file extension - This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. + This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. - To create a that specifies a base URI to use to resolve relative rule references, open a file stream for the file and use the constructor. + To create a that specifies a base URI to use to resolve relative rule references, open a file stream for the file and use the constructor. @@ -951,7 +951,7 @@ private static Grammar CreateGrammarFromFile2() - Grammars that have been compiled to a binary file with a .cfg file extension - This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. + This constructor compiles XML-format grammar files to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. This constructor does not validate `baseUri`. However, the `LoadGrammar` method of a or object throws an exception if it cannot resolve all of the rule references in the grammar description. If `baseUri` is not `null`, the `LoadGrammar` method uses the URI to resolve any rule references that it cannot otherwise resolve. If `baseUri` represents a file, then the `LoadGrammar` uses both the designated file and the file's directory when it attempts to resolve relative rule references. @@ -1489,7 +1489,7 @@ private static void DumpGrammarStatus(Grammar item) has been loaded, the values of , and cannot be changed. + Once a has been loaded, the values of , and cannot be changed. @@ -1559,7 +1559,7 @@ private static void DumpGrammarStatus(Grammar item) for more information on strongly typed grammars). If `onInitParameters` is a null reference (Nothing in Visual Basic) the localized grammar should have either no initialization method, or a method that takes no arguments. + Localized grammars obtained with `LoadLocalizedGrammarFromType` are typically strongly-typed (see for more information on strongly typed grammars). If `onInitParameters` is a null reference (Nothing in Visual Basic) the localized grammar should have either no initialization method, or a method that takes no arguments. ]]> @@ -1766,11 +1766,11 @@ recognizer.RecognizeAsync(RecognizeMode.Multiple); object and set the name for its root rule, use one of the constructors that takes the `ruleName` parameter. + To construct a object and set the name for its root rule, use one of the constructors that takes the `ruleName` parameter. If the root rule of a has no name, the property returns `null`. - The root rules of instances constructed from objects typically have no name, so returns `null`. + The root rules of instances constructed from objects typically have no name, so returns `null`. @@ -1946,7 +1946,7 @@ public partial class Form1 : Form . + Because of the complexity of a recognition engine's use of **Weight**, its effect on a particular grammar's performance is not as directly predictable as that of . Speech recognition is a weighted system. It evaluates all possible recognition paths based on a combination of the weight of the grammar, the weights defined for alternatives within the grammar, and the probabilities defined by speech models. The speech recognition engine uses the combination of these weights and probabilities to rank potential alternative recognitions. Grammars with higher weights will contribute more to the ranking of recognition alternatives than grammars with lower weights. diff --git a/xml/System.Speech.Recognition/GrammarBuilder.xml b/xml/System.Speech.Recognition/GrammarBuilder.xml index 31868c84607..8a63e17eba9 100644 --- a/xml/System.Speech.Recognition/GrammarBuilder.xml +++ b/xml/System.Speech.Recognition/GrammarBuilder.xml @@ -44,13 +44,13 @@ 2. Append constraints to the , such as objects, , , , , and other objects that define the constraints for the grammar. -3. Use one of the constructors to create a object from the completed grammar. +3. Use one of the constructors to create a object from the completed grammar. Authoring with is best suited to grammars that have a single rule containing lists, or perhaps lists of lists. To programmatically build grammars that have multiple rules, or that need to make internal rule references, use the classes of the namespace. - Instances of can also be obtained by implicit conversions from certain other classes or by combining a with a second object that contains constraints for a grammar.. For more information, see the and operators and the methods. + Instances of can also be obtained by implicit conversions from certain other classes or by combining a with a second object that contains constraints for a grammar.. For more information, see the and operators and the methods. - To add rules to an existing , use the , , , , and methods. + To add rules to an existing , use the , , , , and methods. > [!IMPORTANT] > The speech recognizer can throw an exception when using a speech recognition grammar that contains duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the value of the same semantic element. @@ -106,9 +106,9 @@ private Grammar CreateColorGrammar() object with a second object to from a new . For more information, see the and methods. + Instances of this class can also be obtained by implicit conversions from other classes or by combining a object with a second object to from a new . For more information, see the and methods. - To add constraints to an existing , use the , , , , and methods, and the operator. + To add constraints to an existing , use the , , , , and methods, and the operator. > [!IMPORTANT] > The speech recognizer can throw an exception when using a speech recognition grammar that contains duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the value of the same semantic element. @@ -143,7 +143,7 @@ private Grammar CreateColorGrammar() object, use the , , , , and methods, and the operator. + To add rules to an existing object, use the , , , , and methods, and the operator. > [!IMPORTANT] > The speech recognizer can throw an exception when using a speech recognition grammar that contains duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the value of the same semantic element. @@ -280,7 +280,7 @@ private Grammar CreateColorGrammar() instance from a object, you add semantic information to the grammar that can be returned in the recognition result. You can access the semantic information in the recognition result using the property of , which is available in the handler for the `SpeechRecognized` event. If the defines a , this can be used to retrieve the semantic information in a recognition result that is associated with the key. See the example for , and also see and . + When you create a instance from a object, you add semantic information to the grammar that can be returned in the recognition result. You can access the semantic information in the recognition result using the property of , which is available in the handler for the `SpeechRecognized` event. If the defines a , this can be used to retrieve the semantic information in a recognition result that is associated with the key. See the example for , and also see and . > [!IMPORTANT] > When you construct objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. @@ -371,7 +371,7 @@ private Grammar CreateColorGrammar() instance from a object, you add semantic information to the grammar that can be returned in the recognition result. You can access the semantic information in the recognition result using the property of , which is available in the handler for the `SpeechRecognized` event. If the defines a , this can be used to retrieve the semantic information in a recognition result that is associated with the key. See the example for , and also see and . + When you create a instance from a object, you add semantic information to the grammar that can be returned in the recognition result. You can access the semantic information in the recognition result using the property of , which is available in the handler for the `SpeechRecognized` event. If the defines a , this can be used to retrieve the semantic information in a recognition result that is associated with the key. See the example for , and also see and . > [!IMPORTANT] > When you construct objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. @@ -750,9 +750,9 @@ private static Grammar CreatePizzaGrammar() methods provide another mechanism by which you can combine various types to create diversity and flexibility in grammars built with . These methods correspond to the static methods, which are also defined on the class. The order of the parameters determines the order of the elements in the new . + The static methods provide another mechanism by which you can combine various types to create diversity and flexibility in grammars built with . These methods correspond to the static methods, which are also defined on the class. The order of the parameters determines the order of the elements in the new . - A can also be obtained from , , , and [String](https://go.microsoft.com/fwlink/?LinkId=159733) objects. For more information, see the and operators. + A can also be obtained from , , , and [String](https://go.microsoft.com/fwlink/?LinkId=159733) objects. For more information, see the and operators. > [!IMPORTANT] > The speech recognizer can throw an exception when using a speech recognition grammar that contains duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the value of the same semantic element. @@ -805,7 +805,7 @@ private static Grammar CreatePizzaGrammar() This method accepts the objects listed above for the `builder` parameter. - For more information, see the and operators. + For more information, see the and operators. > [!IMPORTANT] > When you combine and objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. For more information about building a speech recognition grammar that contains semantic information, see [Add Semantics to a GrammarBuilder Grammar](https://msdn.microsoft.com/library/hh361581.aspx). @@ -859,7 +859,7 @@ private static Grammar CreatePizzaGrammar() This method accepts the objects listed above for the `builder` parameter. - For more information, see the and operators. + For more information, see the and operators. > [!IMPORTANT] > When you combine and objects that contain or instances with other grammar elements, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. @@ -867,7 +867,7 @@ private static Grammar CreatePizzaGrammar() ## Examples - The following example creates a speech recognition grammar that can recognize the two phrases, "Make background *color*" and "Set background to *color*", where *color* is selected from a set of colors. Various types are used to build the final grammar, such as [String](https://go.microsoft.com/fwlink/?LinkId=159733), , and objects. The explicit cast operators in the calls to the methods are optional. + The following example creates a speech recognition grammar that can recognize the two phrases, "Make background *color*" and "Set background to *color*", where *color* is selected from a set of colors. Various types are used to build the final grammar, such as [String](https://go.microsoft.com/fwlink/?LinkId=159733), , and objects. The explicit cast operators in the calls to the methods are optional. ```csharp private Grammar CreateColorGrammar() @@ -942,7 +942,7 @@ private Grammar CreateColorGrammar() This method accepts the objects listed above for the `builder1` or `builder2` parameter. - For more information, see the and operators. + For more information, see the and operators. > [!IMPORTANT] > When you combine and objects that contain or instances with other grammar elements, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. @@ -950,7 +950,7 @@ private Grammar CreateColorGrammar() ## Examples - The following example creates a speech recognition grammar that can recognize the two phrases, "Make background *color*" and "Set background to *color*", where *color* is selected from a set of colors. Various types are used to build the final grammar, such as [String](https://go.microsoft.com/fwlink/?LinkId=159733), , and objects. The explicit cast operators in the calls to the methods are optional. + The following example creates a speech recognition grammar that can recognize the two phrases, "Make background *color*" and "Set background to *color*", where *color* is selected from a set of colors. Various types are used to build the final grammar, such as [String](https://go.microsoft.com/fwlink/?LinkId=159733), , and objects. The explicit cast operators in the calls to the methods are optional. ```csharp private Grammar CreateColorGrammar() @@ -1025,12 +1025,12 @@ private Grammar CreateColorGrammar() This method accepts the objects listed above for the `builder` parameter. - For more information, see the and operators. + For more information, see the and operators. ## Examples - The following example creates a speech recognition grammar that can recognize the two phrases, "Make background *color*" and "Set background to *color*", where *color* is selected from a set of colors. Various types are used to build the final grammar, such as [String](https://go.microsoft.com/fwlink/?LinkId=159733), , and objects. The explicit cast operators in the calls to the methods are optional. + The following example creates a speech recognition grammar that can recognize the two phrases, "Make background *color*" and "Set background to *color*", where *color* is selected from a set of colors. Various types are used to build the final grammar, such as [String](https://go.microsoft.com/fwlink/?LinkId=159733), , and objects. The explicit cast operators in the calls to the methods are optional. ```csharp private Grammar CreateColorGrammar() @@ -1105,12 +1105,12 @@ private Grammar CreateColorGrammar() This method accepts the objects listed above for the `builder` parameter. - For more information, see the and operators. + For more information, see the and operators. ## Examples - The following example creates a speech recognition grammar that can recognize the two phrases, "Make background *color*" and "Set background to *color*", where *color* is selected from a set of colors. Various types are used to build the final grammar, such as [String](https://go.microsoft.com/fwlink/?LinkId=159733), , and objects. The explicit cast operators in the calls to the methods are optional. + The following example creates a speech recognition grammar that can recognize the two phrases, "Make background *color*" and "Set background to *color*", where *color* is selected from a set of colors. Various types are used to build the final grammar, such as [String](https://go.microsoft.com/fwlink/?LinkId=159733), , and objects. The explicit cast operators in the calls to the methods are optional. ```csharp private Grammar CreateColorGrammar() @@ -1202,7 +1202,7 @@ private Grammar CreateColorGrammar() ## Examples - The following example creates a speech recognition grammar for phrases such as "Call James at work" and "Call Anne on her cell phone", where the word "phone" is optional. The example highlights the use of the method. + The following example creates a speech recognition grammar for phrases such as "Call James at work" and "Call Anne on her cell phone", where the word "phone" is optional. The example highlights the use of the method. ```csharp public static Grammar CreatePhonePhrase() @@ -1279,7 +1279,7 @@ public static Grammar CreatePhonePhrase() ## Examples - The following example creates a speech recognition grammar for phrases such as "Call James at work" and "Call Anne on her cell phone", where the word "phone" is optional. and objects are used to construct the grammar. The example highlights the use of the method. + The following example creates a speech recognition grammar for phrases such as "Call James at work" and "Call Anne on her cell phone", where the word "phone" is optional. and objects are used to construct the grammar. The example highlights the use of the method. ```csharp public static Grammar CreatePhonePhrase() @@ -1714,7 +1714,7 @@ private Grammar[] CreateSubsetMatchTest() ## Examples - The following example creates a speech recognition grammar for phrases such as "Call James at work" and "Call Anne on her cell phone", where the word "phone" is optional. and objects are used to construct the grammar. The example highlights the use of the method. + The following example creates a speech recognition grammar for phrases such as "Call James at work" and "Call Anne on her cell phone", where the word "phone" is optional. and objects are used to construct the grammar. The example highlights the use of the method. ```csharp public static Grammar CreatePhonePhrase() @@ -1795,7 +1795,7 @@ public static Grammar CreatePhonePhrase() ## Examples - The following example creates a speech recognition grammar for phrases such as "Call James at work" and "Call Anne on her cell phone", where the word "phone" is optional. and objects are used to construct the grammar. The example highlights the use of the method. + The following example creates a speech recognition grammar for phrases such as "Call James at work" and "Call Anne on her cell phone", where the word "phone" is optional. and objects are used to construct the grammar. The example highlights the use of the method. ```csharp public static Grammar CreatePhonePhrase() @@ -1851,7 +1851,7 @@ public static Grammar CreatePhonePhrase() methods allow you to append a dictation grammar as a rule to a . + The methods allow you to append a dictation grammar as a rule to a . For more information on dictation grammars, see . @@ -1965,7 +1965,7 @@ grammarWithDictation.Name = "Grammar with Dictation"; methods can append a grammar file or a grammar rule from a file. These methods allow applications to make use of pre-deployed or publicly available grammar rules. The application must have read access to the location of specified grammar files. + The methods can append a grammar file or a grammar rule from a file. These methods allow applications to make use of pre-deployed or publicly available grammar rules. The application must have read access to the location of specified grammar files. These methods can read a speech recognition grammar from the following formats. @@ -2010,7 +2010,7 @@ grammarWithDictation.Name = "Grammar with Dictation"; ## Remarks The URI provided by the `path` argument may be local or remote. The application must have read access to the location of specified grammar files. - A W3C Speech Recognition Grammar Specification (SRGS) representation can define a root rule. This method appends the grammar, beginning with its root rule, to the current sequence of grammar elements. To append a specific grammar rule, use the method. + A W3C Speech Recognition Grammar Specification (SRGS) representation can define a root rule. This method appends the grammar, beginning with its root rule, to the current sequence of grammar elements. To append a specific grammar rule, use the method. @@ -2099,7 +2099,7 @@ private static Grammar CreateCitiesGrammar1() ## Remarks The URI provided by the `path` argument may be local or remote. The application must have read access to the location of specified grammar files. - You can use the use the method to append a grammar file beginning with its root rule. + You can use the use the method to append a grammar file beginning with its root rule. @@ -2289,7 +2289,7 @@ private bool IsValidPassword(RecognizedAudio passwordAudio) constructor creates a object that can be used by a speech recognizer of the corresponding culture. Only the property of the that is provided as the parameter to the Grammar constructor is used to set the culture of the resulting speech recognition grammar. + The constructor creates a object that can be used by a speech recognizer of the corresponding culture. Only the property of the that is provided as the parameter to the Grammar constructor is used to set the culture of the resulting speech recognition grammar. Microsoft Windows and the System.Speech API accept all valid language-country codes. To perform speech recognition using the language specified in the `Culture` property, a speech recognition engine that supports that language-country code must be installed. The speech recognition engines that shipped with Microsoft Windows 7 work with the following language-country codes. @@ -2488,12 +2488,12 @@ private static Grammar CreatePizzaGrammar() - - This method accepts the objects listed above for the `builder` parameter. For more information, see the operators. + This method accepts the objects listed above for the `builder` parameter. For more information, see the operators. > [!IMPORTANT] > When you combine and objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. - The equivalent method for this operator is ]]> + The equivalent method for this operator is ]]> @@ -2545,12 +2545,12 @@ private static Grammar CreatePizzaGrammar() - - This method accepts the objects listed above for the `builder` parameter. For more information, see the operators. + This method accepts the objects listed above for the `builder` parameter. For more information, see the operators. > [!IMPORTANT] > When you combine and objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. - The equivalent method for this operator is + The equivalent method for this operator is ## Examples The following example creates a speech recognition grammar that can recognize the two phrases, "Make background *color*" and "Set background to *color*", where *color* is selected from a set of colors. Various types are used to build the final grammar, such as [String](https://go.microsoft.com/fwlink/?LinkId=159733), , and objects. @@ -2631,12 +2631,12 @@ private Grammar CreateColorGrammar() - - This method accepts the objects listed above for the `builder1` and `builder2` parameters. For more information, see the operators. + This method accepts the objects listed above for the `builder1` and `builder2` parameters. For more information, see the operators. > [!IMPORTANT] > When you combine objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. - The equivalent method for this operator is ]]> + The equivalent method for this operator is ]]> @@ -2688,9 +2688,9 @@ private Grammar CreateColorGrammar() - - This method accepts the objects listed above for the `builder` parameter. For more information, see the operators. + This method accepts the objects listed above for the `builder` parameter. For more information, see the operators. - The equivalent method for this operator is ]]> + The equivalent method for this operator is ]]> @@ -2742,9 +2742,9 @@ private Grammar CreateColorGrammar() - - This method accepts the objects listed above for the `builder` parameter. For more information, see the operators. + This method accepts the objects listed above for the `builder` parameter. For more information, see the operators. - The equivalent method for this operator is + The equivalent method for this operator is ## Examples The following example creates a speech recognition grammar that can recognize the two phrases, "Make background *color*" and "Set background to *color*", where *color* is selected from a set of colors. Various types are used to build the final grammar, such as [String](https://go.microsoft.com/fwlink/?LinkId=159733), , and objects. @@ -2835,9 +2835,9 @@ private Grammar CreateColorGrammar() . This conversion operator is equivalent to calling and specifying `choices` for the `alternateChoices`. + Implicit conversion creates a new instance of . This conversion operator is equivalent to calling and specifying `choices` for the `alternateChoices`. - The equivalent method for this operator is + The equivalent method for this operator is ## Examples The following example creates a speech recognition grammar that can recognize a response to a "yes" or "no" question. The implicit conversion operator is used in the construction of a object from a object, in the construction of a object from two objects, and in the construction of a object from a object. @@ -2891,9 +2891,9 @@ yesnoGrammar.Name = "yesno"; . This conversion operator is equivalent to calling and specifying `semanticKey` for the `key`. + Implicit conversion creates a new instance of . This conversion operator is equivalent to calling and specifying `semanticKey` for the `key`. - The equivalent method for this operator is + The equivalent method for this operator is ## Examples The following example creates a speech recognition grammar that can recognize a response to a "yes" or "no" question. The implicit conversion operator is used in the construction of a object from a object, in the construction of a object from two objects, and in the construction of a object from a object. @@ -2947,9 +2947,9 @@ yesnoGrammar.Name = "yesno"; . This conversion operator is equivalent to calling and specifying `semanticValue` for the `value`. + Implicit conversion creates a new instance of . This conversion operator is equivalent to calling and specifying `semanticValue` for the `value`. - The equivalent method for this operator is + The equivalent method for this operator is ## Examples The following example creates a speech recognition grammar that can recognize a response to a "yes" or "no" question. The implicit conversion operator is used in the construction of a object from a object, in the construction of a object from two objects, and in the construction of a object from a object. @@ -3003,9 +3003,9 @@ yesnoGrammar.Name = "yesno"; . This conversion operator is equivalent to calling and specifying the same `phrase`. + Implicit conversion creates a new instance of . This conversion operator is equivalent to calling and specifying the same `phrase`. - The equivalent method for this operator is + The equivalent method for this operator is ## Examples The following example uses and objects to construct a grammar that can recognize either of the two phrases, "Make background *colorChoice*" or "Set background to *colorChoice*". diff --git a/xml/System.Speech.Recognition/RecognitionResult.xml b/xml/System.Speech.Recognition/RecognitionResult.xml index 9dbcfc683c0..3493d68f31a 100644 --- a/xml/System.Speech.Recognition/RecognitionResult.xml +++ b/xml/System.Speech.Recognition/RecognitionResult.xml @@ -51,7 +51,7 @@ - The property references the semantic information contained in the result. The semantic information is a dictionary of the key names and associated semantic data. -- The property contains a collection of objects that represent other candidate interpretations of the audio input. See for additional information. +- The property contains a collection of objects that represent other candidate interpretations of the audio input. See for additional information. - The property contains an ordered collection of objects that represent each recognized word in the input. Each contains display format, lexical format, and pronunciation information for the corresponding word. @@ -59,9 +59,9 @@ - Methods and events of the class: - - + - - - + - - @@ -71,9 +71,9 @@ - Methods and events of the class: - - + - - - + - - @@ -166,11 +166,11 @@ void SpeechRecognizedHandler(object sender, SpeechRecognizedEventArgs e) are ordered by the values of their properties. The confidence value of a given phrase indicates the probability that the phrase matches the input. The phrase with the highest confidence value is the phrase that most likely matches the input. + Recognition are ordered by the values of their properties. The confidence value of a given phrase indicates the probability that the phrase matches the input. The phrase with the highest confidence value is the phrase that most likely matches the input. - Each value should be evaluated individually and without reference to the confidence values of other . The properties that the inherits from provide detailed information about the phrase with the highest confidence score. + Each value should be evaluated individually and without reference to the confidence values of other . The properties that the inherits from provide detailed information about the phrase with the highest confidence score. - One use for the collection is for automated error correction. For example, when designing a directory dialog, an application could prompt the user to check if the application has the correct information from a recognition event, as in, "Did you say 'Anna'?" If the user says "no", then the application could query the user about any alternates that had a high enough score. + One use for the collection is for automated error correction. For example, when designing a directory dialog, an application could prompt the user to check if the application has the correct information from a recognition event, as in, "Did you say 'Anna'?" If the user says "no", then the application could query the user about any alternates that had a high enough score. For more information about speech recognition and the use of recognition alternates, see [Speech Recognition](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh361633(v=office.14)) and [Using Speech Recognition Events](https://msdn.microsoft.com/library/01c598ca-2e0e-4e89-b303-cd1cef9e8482). @@ -248,7 +248,7 @@ void SpeechRecognizedHandler(object sender, SpeechRecognizedEventArgs e) method. + To get a section of the audio that is associated with a specific range of words in the recognition result, use the method. diff --git a/xml/System.Speech.Recognition/RecognizeCompletedEventArgs.xml b/xml/System.Speech.Recognition/RecognizeCompletedEventArgs.xml index b5bcd0d9bd2..141ad5486eb 100644 --- a/xml/System.Speech.Recognition/RecognizeCompletedEventArgs.xml +++ b/xml/System.Speech.Recognition/RecognizeCompletedEventArgs.xml @@ -33,7 +33,7 @@ ## Examples - The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. + The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. ``` using System; @@ -189,7 +189,7 @@ namespace SampleRecognition ## Examples - The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. + The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. ``` using System; @@ -341,7 +341,7 @@ namespace SampleRecognition method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. + The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. ``` using System; @@ -493,7 +493,7 @@ namespace SampleRecognition method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. + The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. ``` using System; @@ -645,12 +645,12 @@ namespace SampleRecognition and methods. + The recognizer sets this property to `true` when a file provides the input stream for the recognizer and the end of the file is reached. The end of the input stream can coincide with a successful recognition operation. For more information about using a file as the input stream, see the and methods. ## Examples - The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. + The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. ``` using System; @@ -805,7 +805,7 @@ namespace SampleRecognition ## Examples - The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. + The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. ``` using System; diff --git a/xml/System.Speech.Recognition/RecognizeMode.xml b/xml/System.Speech.Recognition/RecognizeMode.xml index 6741ed7ba5f..c033c3c682e 100644 --- a/xml/System.Speech.Recognition/RecognizeMode.xml +++ b/xml/System.Speech.Recognition/RecognizeMode.xml @@ -24,54 +24,54 @@ Enumerates values of the recognition mode. - . - - - -## Examples - The following example shows the implementation of a start/stop button for an application that has a graphical user interface and uses . Depending on the state of the application, is called with either Single or Multiple when the button is clicked. - -``` -private void _startRecogButton_Click(object sender, EventArgs eventArgs) -{ - - // Toggle speech recognition on. - if (_startRecogButton.Text == "Start Speech Recognition") - { - _startRecogButton.Text = "Stop Speech Recognition"; - if (_useMultiple) - { - _recognitionEngine.RecognizeAsync(RecognizeMode.Multiple); - } - else - { - _recognitionEngine.RecognizeAsync(RecognizeMode.Single); - } - } - - // Toggle speech recognition off. - else - { - _startRecogButton.Text = "Start Speech Recognition"; - - // Stop after current phrase is finished. - if (_friendlyStop) - { - _recognitionEngine.RecognizeAsyncStop(); - } - - // Stop before current phrase is finished. - else - { - _recognitionEngine.RecognizeAsyncCancel(); - } - } -} -``` - + . + + + +## Examples + The following example shows the implementation of a start/stop button for an application that has a graphical user interface and uses . Depending on the state of the application, is called with either Single or Multiple when the button is clicked. + +``` +private void _startRecogButton_Click(object sender, EventArgs eventArgs) +{ + + // Toggle speech recognition on. + if (_startRecogButton.Text == "Start Speech Recognition") + { + _startRecogButton.Text = "Stop Speech Recognition"; + if (_useMultiple) + { + _recognitionEngine.RecognizeAsync(RecognizeMode.Multiple); + } + else + { + _recognitionEngine.RecognizeAsync(RecognizeMode.Single); + } + } + + // Toggle speech recognition off. + else + { + _startRecogButton.Text = "Start Speech Recognition"; + + // Stop after current phrase is finished. + if (_friendlyStop) + { + _recognitionEngine.RecognizeAsyncStop(); + } + + // Stop before current phrase is finished. + else + { + _recognitionEngine.RecognizeAsyncCancel(); + } + } +} +``` + ]]> diff --git a/xml/System.Speech.Recognition/RecognizedAudio.xml b/xml/System.Speech.Recognition/RecognizedAudio.xml index bce2b2af156..639ec2d8ee8 100644 --- a/xml/System.Speech.Recognition/RecognizedAudio.xml +++ b/xml/System.Speech.Recognition/RecognizedAudio.xml @@ -35,7 +35,7 @@ property or the method of the . + A speech recognizer generates information about the audio input as part of the recognition operation. To access the recognized audio, use the property or the method of the . A recognition result can be produced by the following events and methods of the and classes: @@ -53,16 +53,16 @@ - 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. +> 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. @@ -517,7 +517,7 @@ void SpeechRecognizedHandler(object sender, SpeechRecognizedEventArgs e) ## Remarks Audio data is written to `outputStream` in binary form. No header information is included. - The method uses the Wave format, but does not include the Wave header. To include the Wave header, use the method. + The method uses the Wave format, but does not include the Wave header. To include the Wave header, use the method. ]]> @@ -554,7 +554,7 @@ void SpeechRecognizedHandler(object sender, SpeechRecognizedEventArgs e) ## Remarks Audio data is written to `outputStream` in Wave format, which includes a resource interchange file format (RIFF) header. - The method uses the same binary format, but does not include the Wave header. + The method uses the same binary format, but does not include the Wave header. diff --git a/xml/System.Speech.Recognition/RecognizedPhrase.xml b/xml/System.Speech.Recognition/RecognizedPhrase.xml index dfd510e9b4f..461bfcdd1b9 100644 --- a/xml/System.Speech.Recognition/RecognizedPhrase.xml +++ b/xml/System.Speech.Recognition/RecognizedPhrase.xml @@ -51,7 +51,7 @@ - The property contains information about specialized word substitution. -- The and properties contain information about recognition alternates that have the same or similar pronunciation. +- The and properties contain information about recognition alternates that have the same or similar pronunciation. - The value of the property indicates the degree of certainty, assigned by the speech recognizer, that a recognized phrase matches the input. @@ -161,7 +161,7 @@ void SpeechRecognizedHandler(object sender, SpeechRecognizedEventArgs e) Confidence values are relative and unique to each recognition engine. Confidence values returned by two different recognition engines cannot be meaningfully compared. - A speech recognition engine may assign a low confidence score to spoken input for various reasons, including background interference, inarticulate speech, or unanticipated words or word sequences. If your application is using a instance, you can modify the confidence level at which speech input is accepted or rejected with one of the methods. Confidence thresholds for the shared recognizer, managed by , are associated with a user profile and stored in the Windows registry. Applications should not write changes to the registry for the properties of the shared recognizer. + A speech recognition engine may assign a low confidence score to spoken input for various reasons, including background interference, inarticulate speech, or unanticipated words or word sequences. If your application is using a instance, you can modify the confidence level at which speech input is accepted or rejected with one of the methods. Confidence thresholds for the shared recognizer, managed by , are associated with a user profile and stored in the Windows registry. Applications should not write changes to the registry for the properties of the shared recognizer. The property of the object contains an ordered collection of objects, each of which is a possible match for the input to the recognizer. The alternates are ordered from highest to lowest confidence. diff --git a/xml/System.Speech.Recognition/RecognizedWordUnit.xml b/xml/System.Speech.Recognition/RecognizedWordUnit.xml index 9c506ca4d4b..8edd0f3de13 100644 --- a/xml/System.Speech.Recognition/RecognizedWordUnit.xml +++ b/xml/System.Speech.Recognition/RecognizedWordUnit.xml @@ -43,18 +43,18 @@ An array of objects is accessible for any recognition operation through the property on the object. - In addition to providing a measure of recognition certainty () a instance provides: + In addition to providing a measure of recognition certainty () a instance provides: -- Normalized and exact (or lexical) text representations for a recognized word. For more information, see , , and . +- Normalized and exact (or lexical) text representations for a recognized word. For more information, see , , and . -- Pronunciation information using characters from a supported phonetic alphabet, such as the International Phonetic Alphabet (IPA) or the Universal Phone Set (UPS). For more information see . +- Pronunciation information using characters from a supported phonetic alphabet, such as the International Phonetic Alphabet (IPA) or the Universal Phone Set (UPS). For more information see . - Formatting for printing. For more information see the class and its property. ## Examples - The following example shows a utility routine (`stringFromWordArray`) that generates strings. The strings contain lexical output (using ), normalized text (using ), or phonetic characters from the International Phonetic Alphabet (using ). Strings are formatted using objects obtained from the property from a of objects. The objects are obtained from the property on the object. + The following example shows a utility routine (`stringFromWordArray`) that generates strings. The strings contain lexical output (using ), normalized text (using ), or phonetic characters from the International Phonetic Alphabet (using ). Strings are formatted using objects obtained from the property from a of objects. The objects are obtained from the property on the object. ```csharp internal enum WordType @@ -168,7 +168,7 @@ internal static string stringFromWordArray(ReadOnlyCollection and the is used in a recognition operation, the recognition engine will generate appropriate values in any output instance. - Direct construction of instances is typically used only when emulating recognition operations using the or methods of the class and the or methods of the class. + Direct construction of instances is typically used only when emulating recognition operations using the or methods of the class and the or methods of the class. For actual applications, do not directly construct , rather obtain it through the property on the object. @@ -266,9 +266,9 @@ private void _emulateAndVerify_Click(object sender, EventArgs e) A confidence score on its own is not meaningful unless you have alternative results to compare against, either from the same recognition operation or from previous recognitions of the same input. - The values returned by are relative and unique to each recognition engine. There is no definition of how confidence values between two different recognition engines compare, nor how the of individual objects define the of a . + The values returned by are relative and unique to each recognition engine. There is no definition of how confidence values between two different recognition engines compare, nor how the of individual objects define the of a . - A speech recognition engine may assign a low confidence score to spoken input for various reasons, including background interference, inarticulate speech, or unanticipated words or word sequences. If your application is using a instance, you can modify the confidence level at which speech input is accepted or rejected with one of the methods. Confidence thresholds for the shared recognizer, managed by , are associated with a user profile and stored in the Windows registry. Applications should not write changes to the registry for the properties of the shared recognizer. + A speech recognition engine may assign a low confidence score to spoken input for various reasons, including background interference, inarticulate speech, or unanticipated words or word sequences. If your application is using a instance, you can modify the confidence level at which speech input is accepted or rejected with one of the methods. Confidence thresholds for the shared recognizer, managed by , are associated with a user profile and stored in the Windows registry. Applications should not write changes to the registry for the properties of the shared recognizer. ]]> @@ -311,7 +311,7 @@ private void _emulateAndVerify_Click(object sender, EventArgs e) ## Examples - The following example shows a utility routine (`stringFromWordArray`) that generates a string that is formatted in one of three ways: lexically (using ), normalized (using ), or phonetically (using ). The text output is obtained from the property on a of objects, which is obtained from the property on a object. + The following example shows a utility routine (`stringFromWordArray`) that generates a string that is formatted in one of three ways: lexically (using ), normalized (using ), or phonetically (using ). The text output is obtained from the property on a of objects, which is obtained from the property on a object. ```csharp internal enum WordType @@ -410,12 +410,12 @@ internal static string stringFromWordArray( and are identical. However, recognition engines may use speech normalization to return more user-friendly or colloquial text representations of audio input. + In most cases the values returned by and are identical. However, recognition engines may use speech normalization to return more user-friendly or colloquial text representations of audio input. Speech normalization is the use of special constructs or symbols to express speech in writing. For example, normalization can replace the spoken words "a dollar and sixteen cents" with "$1.16" in output text. ## Examples - The following example shows a utility routine that generates text in one of three formats: lexical (using ), normalized (using ), and phonetic (using ). The text output is obtained from a of objects, which is obtained from the property on the object. + The following example shows a utility routine that generates text in one of three formats: lexical (using ), normalized (using ), and phonetic (using ). The text output is obtained from a of objects, which is obtained from the property on the object. ```csharp internal enum WordType @@ -514,14 +514,14 @@ internal static string stringFromWordArray( indicate which pronunciation the speech recognition engine used to match speech input to one of its loaded objects. Pronunciations may be defined in the speech recognition engine's internal lexicon, in a lexicon document that is linked from a recognition grammar in a loaded object, or inline in a recognition grammar in a loaded object. A speech recognition engine may also create pronunciations for uncommon words whose pronunciations are not defined in a lexicon or grammar to which the speech recognition engine currently has access. + The contents of indicate which pronunciation the speech recognition engine used to match speech input to one of its loaded objects. Pronunciations may be defined in the speech recognition engine's internal lexicon, in a lexicon document that is linked from a recognition grammar in a loaded object, or inline in a recognition grammar in a loaded object. A speech recognition engine may also create pronunciations for uncommon words whose pronunciations are not defined in a lexicon or grammar to which the speech recognition engine currently has access. Many Windows-based Unicode fonts, such as Courier New, support the display of IPA strings. For more information, see [International Phonetic Alphabet](https://www.internationalphoneticassociation.org/content/ipa-chart). ## Examples - The following example shows a utility routine that generates a string with one of three possible formats: lexical (using ), normalized (using ), and phonetic (using ). The text output is obtained from a of objects, which is obtained from the property on the object. + The following example shows a utility routine that generates a string with one of three possible formats: lexical (using ), normalized (using ), and phonetic (using ). The text output is obtained from a of objects, which is obtained from the property on the object. ```csharp internal enum WordType @@ -620,12 +620,12 @@ internal static string stringFromWordArray( and will be identical. However, recognition engines may use speech normalization to return more user-friendly or colloquial text representations of audio input. + In most cases the values returned by and will be identical. However, recognition engines may use speech normalization to return more user-friendly or colloquial text representations of audio input. Speech normalization is the use of special constructs or symbols to express speech in writing. For example, normalization can replace the spoken words "a dollar and sixteen cents" with "$1.16" in output text. ## Examples - The following example shows a utility routine that generates a string in one of three formats: lexical (using ), normalized (using ), and phonetic (using ). The text output is obtained from a of objects, which is obtained from the property on the object. + The following example shows a utility routine that generates a string in one of three formats: lexical (using ), normalized (using ), and phonetic (using ). The text output is obtained from a of objects, which is obtained from the property on the object. ```csharp internal enum WordType diff --git a/xml/System.Speech.Recognition/RecognizerInfo.xml b/xml/System.Speech.Recognition/RecognizerInfo.xml index c828c7909ef..9b8e941fa42 100644 --- a/xml/System.Speech.Recognition/RecognizerInfo.xml +++ b/xml/System.Speech.Recognition/RecognizerInfo.xml @@ -37,13 +37,13 @@ for a object or for a object. + You can obtain identifying information for an initialized recognition engine using for a object or for a object. The information returned in instances of obtained from a is determined by the settings in the **Speech Properties** member of the **Control Panel**. - You can use instances of to construct a specific configuration of using the constructor. + You can use instances of to construct a specific configuration of using the constructor. - The static method returns a list of all available configurations as instances. + The static method returns a list of all available configurations as instances. @@ -107,7 +107,7 @@ private SpeechRecognitionEngine SelectRecognizer(CultureInfo requiredCulture, st ## Examples The following example implements a button click that displays all the information in a object in a . - The key/value pairs contained in the instance returned by are concatenated into a text table. + The key/value pairs contained in the instance returned by are concatenated into a text table. ```csharp private void recognizerInfoButton_Click(object sender, EventArgs e) diff --git a/xml/System.Speech.Recognition/RecognizerState.xml b/xml/System.Speech.Recognition/RecognizerState.xml index 5e57a722cdc..842d0d7c0f9 100644 --- a/xml/System.Speech.Recognition/RecognizerState.xml +++ b/xml/System.Speech.Recognition/RecognizerState.xml @@ -38,7 +38,7 @@ Both the **On** and **Sleep** settings in the Speech Recognition UI correspond to the `Listening` state. The **Off** setting in the Speech Recognition UI corresponds to Stopped. - is the other property that affects the readiness of a shared speech recognition engine to receive and process speech input. You can use to control whether or not a shared speech recognition engine's grammars are active for recognition. However, changing the property has no effect on the property. + is the other property that affects the readiness of a shared speech recognition engine to receive and process speech input. You can use to control whether or not a shared speech recognition engine's grammars are active for recognition. However, changing the property has no effect on the property. Information such as the description, the supported culture and audio formats, and the recognition engine name is encapsulated in the type. diff --git a/xml/System.Speech.Recognition/RecognizerUpdateReachedEventArgs.xml b/xml/System.Speech.Recognition/RecognizerUpdateReachedEventArgs.xml index 9c338b141b3..340ae10e291 100644 --- a/xml/System.Speech.Recognition/RecognizerUpdateReachedEventArgs.xml +++ b/xml/System.Speech.Recognition/RecognizerUpdateReachedEventArgs.xml @@ -25,132 +25,132 @@ Returns data from a or a event. - instance to manage recognition, it can use one of the methods to request that the engine pauses to receive an update. The instance raises a event when it is ready for the update. - - While a instance is paused, you can load, unload, enable, and disable objects, and modify values for the , , and properties. - - If your application is using a instance to manage recognition, it can use one of the methods to request that the engine pauses to receive an update. The instance raises a event when it is ready for the update. - - While a instance is paused, you can load, unload, enable, and disable objects. - - When handling and events, a recognition engine pauses until the event handler returns. - - derives from . - - - -## Examples - The following example shows a console application that loads and unloads objects. The application uses the method to request the speech recognition engine to pause so it can receive an update. The application then loads or unloads a object. - - At each update, a handler for event writes the name and status of the currently loaded objects to the console. As grammars are loaded and unloaded, the application first recognizes the names of farm animals, then the names of farm animals and the names of fruits, then only the names of fruits. - -```csharp -using System; -using System.Speech.Recognition; -using System.Collections.Generic; -using System.Threading; - -namespace SampleRecognition -{ - class Program - { - private static SpeechRecognitionEngine recognizer; - public static void Main(string[] args) - { - - // Initialize an in-process speech recognition engine and configure its input. - using (recognizer = new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US"))) - { - recognizer.SetInputToDefaultAudioDevice(); - - // Create the first grammar - Farm. - Choices animals = new Choices(new string[] { "cow", "pig", "goat" }); - GrammarBuilder farm = new GrammarBuilder(animals); - Grammar farmAnimals = new Grammar(farm); - farmAnimals.Name = "Farm"; - - // Create the second grammar - Fruit. - Choices fruit = new Choices(new string[] { "apples", "peaches", "oranges" }); - GrammarBuilder favorite = new GrammarBuilder(fruit); - Grammar favoriteFruit = new Grammar(favorite); - favoriteFruit.Name = "Fruit"; - - // Attach event handlers. - recognizer.SpeechRecognized += - new EventHandler(recognizer_SpeechRecognized); - recognizer.RecognizerUpdateReached += - new EventHandler(recognizer_RecognizerUpdateReached); - recognizer.SpeechRecognitionRejected += - new EventHandler(recognizer_SpeechRecognitionRejected); - - // Load the Farm grammar. - recognizer.LoadGrammar(farmAnimals); - - // Start asynchronous, continuous recognition. - recognizer.RecognizeAsync(RecognizeMode.Multiple); - Console.WriteLine("Starting asynchronous, continuous recognition"); - Console.WriteLine(" Farm grammar is loaded and enabled."); - - // Pause to recognize farm animals. - Thread.Sleep(7000); - Console.WriteLine(); - - // Request an update and load the Fruit grammar. - recognizer.RequestRecognizerUpdate(); - recognizer.LoadGrammarAsync(favoriteFruit); - Thread.Sleep(7000); - - // Request an update and unload the Farm grammar. - recognizer.RequestRecognizerUpdate(); - recognizer.UnloadGrammar(farmAnimals); - Thread.Sleep(7000); - } - - // Keep the console window open. - Console.WriteLine(); - Console.WriteLine("Press any key to exit..."); - Console.ReadKey(); - } - - // At the update, get the names and enabled status of the currently loaded grammars. - public static void recognizer_RecognizerUpdateReached( - object sender, RecognizerUpdateReachedEventArgs e) - { - Console.WriteLine(); - Console.WriteLine("Update reached:"); - Thread.Sleep(1000); - - string qualifier; - List grammars = new List(recognizer.Grammars); - foreach (Grammar g in grammars) - { - qualifier = (g.Enabled) ? "enabled" : "disabled"; - Console.WriteLine(" {0} grammar is loaded and {1}.", - g.Name, qualifier); - } - } - - // Write the text of the recognized phrase to the console. - static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) - { - Console.WriteLine(" Speech recognized: " + e.Result.Text); - } - - // Write a message to the console when recognition fails. - static void recognizer_SpeechRecognitionRejected(object sender, SpeechRecognitionRejectedEventArgs e) - { - Console.WriteLine(" Recognition attempt failed"); - } - } -} - -``` - + instance to manage recognition, it can use one of the methods to request that the engine pauses to receive an update. The instance raises a event when it is ready for the update. + + While a instance is paused, you can load, unload, enable, and disable objects, and modify values for the , , and properties. + + If your application is using a instance to manage recognition, it can use one of the methods to request that the engine pauses to receive an update. The instance raises a event when it is ready for the update. + + While a instance is paused, you can load, unload, enable, and disable objects. + + When handling and events, a recognition engine pauses until the event handler returns. + + derives from . + + + +## Examples + The following example shows a console application that loads and unloads objects. The application uses the method to request the speech recognition engine to pause so it can receive an update. The application then loads or unloads a object. + + At each update, a handler for event writes the name and status of the currently loaded objects to the console. As grammars are loaded and unloaded, the application first recognizes the names of farm animals, then the names of farm animals and the names of fruits, then only the names of fruits. + +```csharp +using System; +using System.Speech.Recognition; +using System.Collections.Generic; +using System.Threading; + +namespace SampleRecognition +{ + class Program + { + private static SpeechRecognitionEngine recognizer; + public static void Main(string[] args) + { + + // Initialize an in-process speech recognition engine and configure its input. + using (recognizer = new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US"))) + { + recognizer.SetInputToDefaultAudioDevice(); + + // Create the first grammar - Farm. + Choices animals = new Choices(new string[] { "cow", "pig", "goat" }); + GrammarBuilder farm = new GrammarBuilder(animals); + Grammar farmAnimals = new Grammar(farm); + farmAnimals.Name = "Farm"; + + // Create the second grammar - Fruit. + Choices fruit = new Choices(new string[] { "apples", "peaches", "oranges" }); + GrammarBuilder favorite = new GrammarBuilder(fruit); + Grammar favoriteFruit = new Grammar(favorite); + favoriteFruit.Name = "Fruit"; + + // Attach event handlers. + recognizer.SpeechRecognized += + new EventHandler(recognizer_SpeechRecognized); + recognizer.RecognizerUpdateReached += + new EventHandler(recognizer_RecognizerUpdateReached); + recognizer.SpeechRecognitionRejected += + new EventHandler(recognizer_SpeechRecognitionRejected); + + // Load the Farm grammar. + recognizer.LoadGrammar(farmAnimals); + + // Start asynchronous, continuous recognition. + recognizer.RecognizeAsync(RecognizeMode.Multiple); + Console.WriteLine("Starting asynchronous, continuous recognition"); + Console.WriteLine(" Farm grammar is loaded and enabled."); + + // Pause to recognize farm animals. + Thread.Sleep(7000); + Console.WriteLine(); + + // Request an update and load the Fruit grammar. + recognizer.RequestRecognizerUpdate(); + recognizer.LoadGrammarAsync(favoriteFruit); + Thread.Sleep(7000); + + // Request an update and unload the Farm grammar. + recognizer.RequestRecognizerUpdate(); + recognizer.UnloadGrammar(farmAnimals); + Thread.Sleep(7000); + } + + // Keep the console window open. + Console.WriteLine(); + Console.WriteLine("Press any key to exit..."); + Console.ReadKey(); + } + + // At the update, get the names and enabled status of the currently loaded grammars. + public static void recognizer_RecognizerUpdateReached( + object sender, RecognizerUpdateReachedEventArgs e) + { + Console.WriteLine(); + Console.WriteLine("Update reached:"); + Thread.Sleep(1000); + + string qualifier; + List grammars = new List(recognizer.Grammars); + foreach (Grammar g in grammars) + { + qualifier = (g.Enabled) ? "enabled" : "disabled"; + Console.WriteLine(" {0} grammar is loaded and {1}.", + g.Name, qualifier); + } + } + + // Write the text of the recognized phrase to the console. + static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) + { + Console.WriteLine(" Speech recognized: " + e.Result.Text); + } + + // Write a message to the console when recognition fails. + static void recognizer_SpeechRecognitionRejected(object sender, SpeechRecognitionRejectedEventArgs e) + { + Console.WriteLine(" Recognition attempt failed"); + } + } +} + +``` + ]]> @@ -186,11 +186,11 @@ namespace SampleRecognition Gets the audio position associated with the event. Returns the location within the speech buffer of a or a when it pauses and raises a RecognizerUpdateReached event. - to access audio input that occurred while the recognition engine was paused. - + to access audio input that occurred while the recognition engine was paused. + ]]> @@ -227,111 +227,111 @@ namespace SampleRecognition Gets the UserToken passed to the system when an application calls or . Returns an object that contains the UserToken. - or methods that take a `userToken` parameter. - - - -## Examples - The following example shows a console application that loads and unloads objects. The application uses the method to request the speech recognition engine to pause so it can receive an update. The method passes in a object for the `userToken` parameter that describes what the application will recognize after the update. The application then loads or unloads a object. - - At each update, a handler for event writes the contents of `userToken` to the console. As grammars are loaded and unloaded, the application first recognizes the names of farm animals, then the names of farm animals and the names of fruits, then only the names of fruits. - -``` -using System; -using System.Speech.Recognition; -using System.Collections.Generic; -using System.Threading; - -namespace SampleRecognition -{ - class Program - { - private static SpeechRecognitionEngine recognizer; - public static void Main(string[] args) - { - - // Initialize an in-process speech recognition engine and configure its input. - using (recognizer = new SpeechRecognitionEngine( - new System.Globalization.CultureInfo("en-US"))) - { - recognizer.SetInputToDefaultAudioDevice(); - - // Create the first grammar - Farm. - Choices animals = new Choices(new string[] { "cow", "pig", "goat" }); - GrammarBuilder farm = new GrammarBuilder(animals); - Grammar farmAnimals = new Grammar(farm); - farmAnimals.Name = "Farm"; - - // Create the second grammar - Fruit. - Choices fruit = new Choices(new string[] { "apples", "peaches", "oranges" }); - GrammarBuilder favorite = new GrammarBuilder(fruit); - Grammar favoriteFruit = new Grammar(favorite); - favoriteFruit.Name = "Fruit"; - - // Attach event handlers. - recognizer.SpeechRecognized += - new EventHandler(recognizer_SpeechRecognized); - recognizer.RecognizerUpdateReached += - new EventHandler(recognizer_RecognizerUpdateReached); - recognizer.SpeechRecognitionRejected += - new EventHandler(recognizer_SpeechRecognitionRejected); - - // Load the farmAnimals grammar - recognizer.LoadGrammar(farmAnimals); - - // Start continuous, asynchronous recognition. - recognizer.RecognizeAsync(RecognizeMode.Multiple); - Console.WriteLine("Starting asynchronous recognition..."); - Console.WriteLine(" Farm animals will now be recognized."); - Thread.Sleep(7000); - Console.WriteLine(); - - // Load the Fruit grammar. - string activeGrammars = "Farm animals and fruits will now be recognized."; - recognizer.RequestRecognizerUpdate(activeGrammars); - recognizer.LoadGrammarAsync(favoriteFruit); - Console.WriteLine(); - Thread.Sleep(7000); - Console.WriteLine(); - - // Unload the Farm grammar. - string onlyFruit = "Only fruits will now be recognized."; - recognizer.RequestRecognizerUpdate(onlyFruit); - recognizer.UnloadGrammar(farmAnimals); - Thread.Sleep(7000); - } - - // Keep the console window open. - Console.WriteLine(); - Console.WriteLine("Press any key to exit..."); - Console.ReadKey(); - } - - // At the update, describe what the application will recognize next. - public static void recognizer_RecognizerUpdateReached(object sender, RecognizerUpdateReachedEventArgs e) - { - Console.WriteLine(" Update reached: " + e.UserToken); - } - - // Write the text of the recognized phrase to the console. - static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) - { - Console.WriteLine(" Speech recognized: " + e.Result.Text); - } - - // Write a message to the console when recognition fails. - static void recognizer_SpeechRecognitionRejected(object sender, SpeechRecognitionRejectedEventArgs e) - { - Console.WriteLine(" Recognition attempt failed"); - } - } -} - -``` - + or methods that take a `userToken` parameter. + + + +## Examples + The following example shows a console application that loads and unloads objects. The application uses the method to request the speech recognition engine to pause so it can receive an update. The method passes in a object for the `userToken` parameter that describes what the application will recognize after the update. The application then loads or unloads a object. + + At each update, a handler for event writes the contents of `userToken` to the console. As grammars are loaded and unloaded, the application first recognizes the names of farm animals, then the names of farm animals and the names of fruits, then only the names of fruits. + +``` +using System; +using System.Speech.Recognition; +using System.Collections.Generic; +using System.Threading; + +namespace SampleRecognition +{ + class Program + { + private static SpeechRecognitionEngine recognizer; + public static void Main(string[] args) + { + + // Initialize an in-process speech recognition engine and configure its input. + using (recognizer = new SpeechRecognitionEngine( + new System.Globalization.CultureInfo("en-US"))) + { + recognizer.SetInputToDefaultAudioDevice(); + + // Create the first grammar - Farm. + Choices animals = new Choices(new string[] { "cow", "pig", "goat" }); + GrammarBuilder farm = new GrammarBuilder(animals); + Grammar farmAnimals = new Grammar(farm); + farmAnimals.Name = "Farm"; + + // Create the second grammar - Fruit. + Choices fruit = new Choices(new string[] { "apples", "peaches", "oranges" }); + GrammarBuilder favorite = new GrammarBuilder(fruit); + Grammar favoriteFruit = new Grammar(favorite); + favoriteFruit.Name = "Fruit"; + + // Attach event handlers. + recognizer.SpeechRecognized += + new EventHandler(recognizer_SpeechRecognized); + recognizer.RecognizerUpdateReached += + new EventHandler(recognizer_RecognizerUpdateReached); + recognizer.SpeechRecognitionRejected += + new EventHandler(recognizer_SpeechRecognitionRejected); + + // Load the farmAnimals grammar + recognizer.LoadGrammar(farmAnimals); + + // Start continuous, asynchronous recognition. + recognizer.RecognizeAsync(RecognizeMode.Multiple); + Console.WriteLine("Starting asynchronous recognition..."); + Console.WriteLine(" Farm animals will now be recognized."); + Thread.Sleep(7000); + Console.WriteLine(); + + // Load the Fruit grammar. + string activeGrammars = "Farm animals and fruits will now be recognized."; + recognizer.RequestRecognizerUpdate(activeGrammars); + recognizer.LoadGrammarAsync(favoriteFruit); + Console.WriteLine(); + Thread.Sleep(7000); + Console.WriteLine(); + + // Unload the Farm grammar. + string onlyFruit = "Only fruits will now be recognized."; + recognizer.RequestRecognizerUpdate(onlyFruit); + recognizer.UnloadGrammar(farmAnimals); + Thread.Sleep(7000); + } + + // Keep the console window open. + Console.WriteLine(); + Console.WriteLine("Press any key to exit..."); + Console.ReadKey(); + } + + // At the update, describe what the application will recognize next. + public static void recognizer_RecognizerUpdateReached(object sender, RecognizerUpdateReachedEventArgs e) + { + Console.WriteLine(" Update reached: " + e.UserToken); + } + + // Write the text of the recognized phrase to the console. + static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) + { + Console.WriteLine(" Speech recognized: " + e.Result.Text); + } + + // Write a message to the console when recognition fails. + static void recognizer_SpeechRecognitionRejected(object sender, SpeechRecognitionRejectedEventArgs e) + { + Console.WriteLine(" Recognition attempt failed"); + } + } +} + +``` + ]]> diff --git a/xml/System.Speech.Recognition/ReplacementText.xml b/xml/System.Speech.Recognition/ReplacementText.xml index 3019a4beb4c..09f22bc50d5 100644 --- a/xml/System.Speech.Recognition/ReplacementText.xml +++ b/xml/System.Speech.Recognition/ReplacementText.xml @@ -49,11 +49,11 @@ Using the object, an application can determine: -- The location and number of words replaced by normalization. For more information, see or . +- The location and number of words replaced by normalization. For more information, see or . -- The replaced text and its display attributes. For more information, see , and . +- The replaced text and its display attributes. For more information, see , and . - Instances of are typically obtained as members of the object returned by the property on (or classes that inherit from , such as ) when returned text has been normalized. + Instances of are typically obtained as members of the object returned by the property on (or classes that inherit from , such as ) when returned text has been normalized. diff --git a/xml/System.Speech.Recognition/SemanticResultKey.xml b/xml/System.Speech.Recognition/SemanticResultKey.xml index 40d97d910e7..89b489e4cf7 100644 --- a/xml/System.Speech.Recognition/SemanticResultKey.xml +++ b/xml/System.Speech.Recognition/SemanticResultKey.xml @@ -151,7 +151,7 @@ private void pwdGrammar() , , , and objects as well. For more information on implicit conversions, see . + Because of implicit conversions, the `builders` argument supports , , , and objects as well. For more information on implicit conversions, see . When performing a recognition operation, the objects provided in the `builders` argument are treated as sequential. For example, if the following is used to construct a , input to the recognition engine must contain the words "the quick brown fox" in sequence to be recognized. @@ -166,7 +166,7 @@ SemanticResultKey stringTest=new SemanticResultKey( The `semanticResultKey` argument contains the tag used to access the that might be returned. - The of the is determined by the instances provided by the `builders` parameter. + The of the is determined by the instances provided by the `builders` parameter. If the objects contain no defining instances of , the value of the is `null`. @@ -280,14 +280,14 @@ SemanticResultKey stringTest=new SemanticResultKey("stringTest", The `semanticResultKey` argument determines the key used to access the that might be returned. - If you construct a using a object that contains a semantic key with an array of string objects, the of the produced by a recognition operation will be the string used in recognition. In the preceding example, this means that would be "the quick brown fox". + If you construct a using a object that contains a semantic key with an array of string objects, the of the produced by a recognition operation will be the string used in recognition. In the preceding example, this means that would be "the quick brown fox". ## Examples The following example creates a from a object that uses a , which is defined by an array of objects. - A recognition engine using the created will recognize the phrase "color red green blue zero". The semantics of the returned by recognition will contain a with a of "red green blue". You can access the using the "code" tag. + A recognition engine using the created will recognize the phrase "color red green blue zero". The semantics of the returned by recognition will contain a with a of "red green blue". You can access the using the "code" tag. Because of the `SemanticResultValue("zero", 5)` appended to the , the root object in the will have a value of 5. @@ -334,14 +334,14 @@ private void keyTest() is equivalent to using the constructor which takes as an argument (). + The use of is equivalent to using the constructor which takes as an argument (). ## Examples The following example creates a object that supports commands to change the background color. - A object (`colorChoice`) containing the list of options for background colors is filled using the method with instances. The instances are obtained through the method on the objects created from color strings. + A object (`colorChoice`) containing the list of options for background colors is filled using the method with instances. The instances are obtained through the method on the objects created from color strings. A is then obtained by calling on a instance, which will be used to key the semantic choices in `colorChoice`. diff --git a/xml/System.Speech.Recognition/SemanticResultValue.xml b/xml/System.Speech.Recognition/SemanticResultValue.xml index 6eab75562d3..7dd01c04901 100644 --- a/xml/System.Speech.Recognition/SemanticResultValue.xml +++ b/xml/System.Speech.Recognition/SemanticResultValue.xml @@ -52,25 +52,25 @@ 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 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 . Semantic keys can be explicitly attached to a , using a object. instances not explicitly attached to a key are attached to the root key of the default . - After a has been used to set the , whether it is tagged with the default root key or by any particular , that value must not be modified or an exception will occur during recognition operations. + After a has been used to set the , whether it is tagged with the default root key or by any particular , that value must not be modified or an exception will occur during recognition operations. - The following example will cause an exception because it sets and then modifies the root of a . + The following example will cause an exception because it sets and then modifies the root of a . ```csharp GrammarBuilder gb=new GrammarBuilder(); @@ -473,14 +473,14 @@ private Grammar FgBgColorGrammar() is equivalent to using the constructor that takes a as an argument (). + The use of is equivalent to using the constructor that takes a as an argument (). ## Examples The following example creates objects that support commands to change the background color. - A object (`colorChoice`) containing the list of options for background colors is filled using the method with instances that are obtained from the method on the `SemanticResultValue` objects created from color strings. + A object (`colorChoice`) containing the list of options for background colors is filled using the method with instances that are obtained from the method on the `SemanticResultValue` objects created from color strings. A is then obtained by calling on a instance, which will be used to key the semantic choices in the `colorChoice` instance. diff --git a/xml/System.Speech.Recognition/SemanticValue.xml b/xml/System.Speech.Recognition/SemanticValue.xml index ceca3b3b557..cdab794ba25 100644 --- a/xml/System.Speech.Recognition/SemanticValue.xml +++ b/xml/System.Speech.Recognition/SemanticValue.xml @@ -78,7 +78,7 @@ - A measure of the accuracy of semantic parsing, returned by the property. -- 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. +- 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 foreach (KeyValuePair child in semantics) @@ -93,24 +93,24 @@ objects obtained for recognized phrases without semantic structure are characterized by: -- The lack of children ( is 0). +- The lack of children ( is 0). - The property is `null`. -- An artificial semantic confidence level of 1.0 (returned by ). +- An artificial semantic confidence level of 1.0 (returned by ). Typically, applications create instances indirectly, adding them to objects by using and instances, in conjunction with and objects. Direct construction of a instance is useful during the creation of strongly-typed grammars. - implements the , , and interfaces. + implements the , , and interfaces. ## Examples The following example shows a handler for a event designed to handle commands to change foreground and background color. - The handler identifies recognized phrases that have no underlying semantic structure by detecting a of zero and a of `null`. This recognition output is then processed directly by parsing the raw text. + The handler identifies recognized phrases that have no underlying semantic structure by detecting a of zero and a of `null`. This recognition output is then processed directly by parsing the raw text. In other cases, the handler uses keys to obtain the RGB components of a color name, to determine whether the command will change the foreground or background, or to indicate that no valid key was found. @@ -447,14 +447,14 @@ internal static void CreateSemanticsTreeNodes( before using with a given instance of . + You can only access data by key value at runtime, for example to check *semantic["myKey"].Value*, and this generates an exception. We recommend that you query the object with before using with a given instance of . ## Examples The following example shows a handler for a event designed to handle commands to change foreground and background color. - After handling phrases that are recognized but have no semantic structure, the handler checks for the presence of appropriate keys using (`applyChgToBackground`, `colorRGBValueList`, or `colorStringList)`, and then processes the semantically organized data. + After handling phrases that are recognized but have no semantic structure, the handler checks for the presence of appropriate keys using (`applyChgToBackground`, `colorRGBValueList`, or `colorStringList)`, and then processes the semantically organized data. ```csharp newGrammar.SpeechRecognized += @@ -586,14 +586,14 @@ newGrammar.SpeechRecognized += value of zero, as well as a of `null`. + Recognition results that do not make use of semantic parsing always have a value of zero, as well as a of `null`. ## Examples The following example shows a handler for a event designed to handle commands to change foreground and background color. - The handler identifies recognized phrases that have no underlying semantic structure by detecting a of zero and a of `null`. This recognition output is then processed directly by parsing the raw text. + The handler identifies recognized phrases that have no underlying semantic structure by detecting a of zero and a of `null`. This recognition output is then processed directly by parsing the raw text. In other cases, the handler uses keys to obtain the RGB components of a color name, to determine whether the command will change the foreground or background, or to indicate that no valid key was found. @@ -789,7 +789,7 @@ newGrammar.SpeechRecognized += is read-only and generates exceptions if members are modified. + The is read-only and generates exceptions if members are modified. You can only access data by key value at run-time, not at compile-time, for example to check `semantic["myKey"].Value`. Specifying a key that is not present generates an exception. @@ -798,9 +798,9 @@ newGrammar.SpeechRecognized += ## Examples The following example shows a handler for a event designed to handle commands to change foreground and background color. - After handling recognized phrases that have no semantic structure, the handler checks for the presence of appropriate keys using (`applyChgToBackground`, `colorRGBValueList`, or `colorStringList)`, and then uses the property to obtain the nodes with needed information. + After handling recognized phrases that have no semantic structure, the handler checks for the presence of appropriate keys using (`applyChgToBackground`, `colorRGBValueList`, or `colorStringList)`, and then uses the property to obtain the nodes with needed information. - The use of is highlighted below. + The use of is highlighted below. ```csharp newGrammar.SpeechRecognized += @@ -1286,7 +1286,7 @@ This member is an explicit interface member implementation. It can be used only of `null` and a property of zero. + Recognition results which do not make use of semantic parsing always have a of `null` and a property of zero. diff --git a/xml/System.Speech.Recognition/SpeechRecognitionEngine.xml b/xml/System.Speech.Recognition/SpeechRecognitionEngine.xml index e8e41d6125f..cff7af4e7c8 100644 --- a/xml/System.Speech.Recognition/SpeechRecognitionEngine.xml +++ b/xml/System.Speech.Recognition/SpeechRecognitionEngine.xml @@ -32,35 +32,35 @@ method. + You can create an instance of this class for any of the installed speech recognizers. To get information about which recognizers are installed, use the static method. This class is for running speech recognition engines in-process, and provides control over various aspects of speech recognition, as follows: -- To create an in-process speech recognizer, use one of the constructors. +- To create an in-process speech recognizer, use one of the constructors. -- To manage speech recognition grammars, use the , , , and methods, and the property. +- To manage speech recognition grammars, use the , , , and methods, and the property. -- To configure the input to the recognizer, use the , , , , or method. +- To configure the input to the recognizer, use the , , , , or method. -- To perform speech recognition, use the or method. +- To perform speech recognition, use the or method. -- To modify how recognition handles silence or unexpected input, use the , , , and properties. +- To modify how recognition handles silence or unexpected input, use the , , , and properties. - To change the number of alternates the recognizer returns, use the property. The recognizer returns recognition results in a object. -- To synchronize changes to the recognizer, use the method. The recognizer uses more than one thread to perform tasks. +- To synchronize changes to the recognizer, use the method. The recognizer uses more than one thread to perform tasks. -- To emulate input to the recognizer, use the and methods. +- To emulate input to the recognizer, use the and methods. The object is for the sole use of the process that instantiated the object. By contrast, the shares a single recognizer with any application that wants to use it. > [!NOTE] -> Always call before you release your last reference to the speech recognizer. Otherwise, the resources it is using will not be freed until the garbage collector calls the recognizer object's `Finalize` method. +> Always call before you release your last reference to the speech recognizer. Otherwise, the resources it is using will not be freed until the garbage collector calls the recognizer object's `Finalize` method. ## Examples - The following example shows part of a console application that demonstrates basic speech recognition. Because this example uses the `Multiple` mode of the method, it performs recognition until you close the console window or stop debugging. + The following example shows part of a console application that demonstrates basic speech recognition. Because this example uses the `Multiple` mode of the method, it performs recognition until you close the console window or stop debugging. ```csharp using System; @@ -139,19 +139,19 @@ namespace SpeechRecognitionApp Before the speech recognizer can begin recognition, you must load at least one speech recognition grammar and configure the input for the recognizer. - To load a grammar, call the or method. + To load a grammar, call the or method. To configure the audio input, use one of the following methods: -- +- -- +- -- +- -- +- -- +- ]]> @@ -179,19 +179,19 @@ namespace SpeechRecognitionApp ## Remarks Before the speech recognizer can begin speech recognition, you must load at least one recognition grammar and configure the input for the recognizer. - To load a grammar, call the or method. + To load a grammar, call the or method. To configure the audio input, use one of the following methods: -- +- -- +- -- +- -- +- -- +- ]]> @@ -243,19 +243,19 @@ namespace SpeechRecognitionApp Before the speech recognizer can begin recognition, you must load at least one speech recognition grammar and configure the input for the recognizer. - To load a grammar, call the or method. + To load a grammar, call the or method. To configure the audio input, use one of the following methods: -- +- -- +- -- +- -- +- -- +- @@ -341,23 +341,23 @@ namespace SpeechRecognitionApp method. + You can create an instance of this class for any of the installed speech recognizers. To get information about which recognizers are installed, use the method. Before the speech recognizer can begin recognition, you must load at least one speech recognition grammar and configure the input for the recognizer. - To load a grammar, call the or method. + To load a grammar, call the or method. To configure the audio input, use one of the following methods: -- +- -- +- -- +- -- +- -- +- @@ -450,23 +450,23 @@ namespace SpeechRecognitionApp property of the object returned by the property of the recognizer. To get a collection of all the installed recognizers, use the static method. + The token name of the recognizer is the value of the property of the object returned by the property of the recognizer. To get a collection of all the installed recognizers, use the static method. Before the speech recognizer can begin recognition, you must load at least one speech recognition grammar and configure the input for the recognizer. - To load a grammar, call the or method. + To load a grammar, call the or method. To configure the audio input, use one of the following methods: -- +- -- +- -- +- -- +- -- +- @@ -553,20 +553,20 @@ namespace SpeechRecognitionApp ## Remarks To configure the audio input, use one of the following methods: -- +- -- +- -- +- -- +- -- +- ## Examples - The example below uses to obtain and display audio format data. + The example below uses to obtain and display audio format data. ``` static void DisplayAudioDeviceFormat(Label label, SpeechRecognitionEngine recognitionEngine) @@ -721,7 +721,7 @@ void recognizer_AudioLevelUpdated(object sender, AudioLevelUpdatedEventArgs e) ## Examples - In the following example, the in-process speech recognizer uses a dictation grammar to match speech input. A handler for the event writes to the console the , , and when the speech recognizer detects speech at its input. + In the following example, the in-process speech recognizer uses a dictation grammar to match speech input. A handler for the event writes to the console the , , and when the speech recognizer detects speech at its input. ``` using System; @@ -932,7 +932,7 @@ void recognizer_AudioSignalProblemOccurred(object sender, AudioSignalProblemOccu ## Examples - The following example uses a handler for the event to write the recognizer's new to the console each time it changes, using a member of the enumeration. + The following example uses a handler for the event to write the recognizer's new to the console each time it changes, using a member of the enumeration. ``` using System; @@ -1061,7 +1061,7 @@ namespace SampleRecognition ## Examples - The following example shows part of a console application that demonstrates basic speech recognition that sets the and properties of a before initiating speech recognition. Handlers for the speech recognizer's and events output event information to the console to demonstrate how the properties of a affect recognition operations. + The following example shows part of a console application that demonstrates basic speech recognition that sets the and properties of a before initiating speech recognition. Handlers for the speech recognizer's and events output event information to the console to demonstrate how the properties of a affect recognition operations. ```csharp @@ -1255,14 +1255,14 @@ namespace SpeechRecognitionApp objects or as an array of objects. This can be helpful when you are testing or debugging an application or grammar. For example, you can use emulation to determine whether a word is in a grammar and what semantics are returned when the word is recognized. Use the method to disable audio input to the speech recognition engine during emulation operations. + These methods bypass the system audio input and provide text to the recognizer as objects or as an array of objects. This can be helpful when you are testing or debugging an application or grammar. For example, you can use emulation to determine whether a word is in a grammar and what semantics are returned when the word is recognized. Use the method to disable audio input to the speech recognition engine during emulation operations. The speech recognizer raises the , , , and events as if the recognition operation is not emulated. The recognizer ignores new lines and extra white space and treats punctuation as literal input. > [!NOTE] > The object generated by the speech recognizer in response to emulated input has a value of `null` for its property. - To emulate asynchronous recognition, use the method. + To emulate asynchronous recognition, use the method. ]]> @@ -1616,14 +1616,14 @@ namespace Sre_EmulateRecognize objects or as an array of objects. This can be helpful when you are testing or debugging an application or grammar. For example, you can use emulation to determine whether a word is in a grammar and what semantics are returned when the word is recognized. Use the method to disable audio input to the speech recognition engine during emulation operations. + These methods bypass the system audio input and provide text to the recognizer as objects or as an array of objects. This can be helpful when you are testing or debugging an application or grammar. For example, you can use emulation to determine whether a word is in a grammar and what semantics are returned when the word is recognized. Use the method to disable audio input to the speech recognition engine during emulation operations. The speech recognizer raises the , , , and events as if the recognition operation is not emulated. When the recognizer completes the asynchronous recognition operation, it raises the event. The recognizer ignores new lines and extra white space and treats punctuation as literal input. > [!NOTE] > The object generated by the speech recognizer in response to emulated input has a value of `null` for its property. - To emulate synchronous recognition, use the method. + To emulate synchronous recognition, use the method. ]]> @@ -2033,9 +2033,9 @@ namespace SreEmulateRecognizeAsync method begins an asynchronous recognition operation. The raises the event when it finalizes the asynchronous operation. + Each method begins an asynchronous recognition operation. The raises the event when it finalizes the asynchronous operation. - The operation can raise the , , , and events. The event is the last such event that the recognizer raises for a given operation. + The operation can raise the , , , and events. The event is the last such event that the recognizer raises for a given operation. If emulated recognition was successful, you can access the recognition result using the either of the following: @@ -2043,7 +2043,7 @@ namespace SreEmulateRecognizeAsync - property in the object in the handler for the event. - If emulated recognition was not successful, the event is not raised and the will be null. + If emulated recognition was not successful, the event is not raised and the will be null. derives from . @@ -2349,7 +2349,7 @@ private static void ListGrammars(SpeechRecognitionEngine recognizer) ## Examples - The following example shows part of a console application that demonstrates basic speech recognition. The example sets the and properties of a before initiating speech recognition. Handlers for the speech recognizer's and events output event information to the console to demonstrate how the properties of a properties affect recognition operations. + The following example shows part of a console application that demonstrates basic speech recognition. The example sets the and properties of a before initiating speech recognition. Handlers for the speech recognizer's and events output event information to the console to demonstrate how the properties of a properties affect recognition operations. ```csharp @@ -2500,7 +2500,7 @@ namespace SpeechRecognitionApp ## Examples - The following example shows part of a console application that demonstrates basic speech recognition. The example uses the collection returned by the method to find a speech recognizer that supports the English language. + The following example shows part of a console application that demonstrates basic speech recognition. The example uses the collection returned by the method to find a speech recognizer that supports the English language. ```csharp using System; @@ -2595,11 +2595,11 @@ namespace SpeechRecognitionApp ## Remarks The recognizer throws an exception if the object is already loaded, is being asynchronously loaded, or has failed to load into any recognizer. You cannot load the same object into multiple instances of . Instead, create a new object for each instance. - If the recognizer is running, applications must use to pause the speech recognition engine before loading, unloading, enabling, or disabling a grammar. + If the recognizer is running, applications must use to pause the speech recognition engine before loading, unloading, enabling, or disabling a grammar. When you load a grammar, it is enabled by default. To disable a loaded grammar, use the property. - To load a object asynchronously, use the method. + To load a object asynchronously, use the method. @@ -2696,11 +2696,11 @@ namespace SpeechRecognitionApp ## Remarks When the recognizer completes loading a object, it raises a event. The recognizer throws an exception if the object is already loaded, is being asynchronously loaded, or has failed to load into any recognizer. You cannot load the same object into multiple instances of . Instead, create a new object for each instance. - If the recognizer is running, applications must use to pause the speech recognition engine before loading, unloading, enabling, or disabling a grammar. + If the recognizer is running, applications must use to pause the speech recognition engine before loading, unloading, enabling, or disabling a grammar. When you load a grammar, it is enabled by default. To disable a loaded grammar, use the property. - To load a speech recognition grammar synchronously, use the method. + To load a speech recognition grammar synchronously, use the method. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -2742,9 +2742,9 @@ namespace SpeechRecognitionApp method initiates an asynchronous operation. The raises this event when it completes the operation. To get the object that the recognizer loaded, use the property of the associated . To get the current objects the recognizer has loaded, use the recognizer's property. + The recognizer's method initiates an asynchronous operation. The raises this event when it completes the operation. To get the object that the recognizer loaded, use the property of the associated . To get the current objects the recognizer has loaded, use the recognizer's property. - If the recognizer is running, applications must use to pause the speech recognition engine before loading, unloading, enabling, or disabling a grammar. + If the recognizer is running, applications must use to pause the speech recognition engine before loading, unloading, enabling, or disabling a grammar. When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Events and Delegates](https://go.microsoft.com/fwlink/?LinkId=162418). @@ -2875,7 +2875,7 @@ namespace SampleRecognition ## Remarks The property of the class contains the collection of objects that represent possible interpretations of the input. - The default value for is 10. + The default value for is 10. ]]> @@ -2925,7 +2925,7 @@ namespace SampleRecognition |`AdaptationOn`|Indicates whether adaptation of the acoustic model is ON (value = `1`) or OFF (value = `0`). The default value is `1` (ON).| |`PersistedBackgroundAdaptation`|Indicates whether background adaptation is ON (value = `1`) or OFF (value = `0`), and persists the setting in the registry. The default value is `1` (ON).| - To update a setting for the recognizer, use one of the methods. + To update a setting for the recognizer, use one of the methods. @@ -3028,21 +3028,21 @@ namespace RecognizerSettings - or . Raised when the recognizer finalizes a recognition operation. - The recognizer does not raise the event when using one of the methods. + The recognizer does not raise the event when using one of the methods. - The methods return a object, or `null` if the operation is not successful or the recognizer is not enabled. + The methods return a object, or `null` if the operation is not successful or the recognizer is not enabled. A synchronous recognition operation can fail for the following reasons: -- Speech is not detected before the timeout intervals expire for the or properties, or for the `initialSilenceTimeout` parameter of the method. +- Speech is not detected before the timeout intervals expire for the or properties, or for the `initialSilenceTimeout` parameter of the method. - The recognition engine detects speech but finds no matches in any of its loaded and enabled objects. - To modify how the recognizer handles the timing of speech or silence with respect to recognition, use the , , , and properties. + To modify how the recognizer handles the timing of speech or silence with respect to recognition, use the , , , and properties. - The must have at least one object loaded before performing recognition. To load a speech recognition grammar, use the or method. + The must have at least one object loaded before performing recognition. To load a speech recognition grammar, use the or method. - To perform asynchronous recognition, use one of the methods. + To perform asynchronous recognition, use one of the methods. ]]> @@ -3089,11 +3089,11 @@ namespace RecognizerSettings A synchronous recognition operation can fail for the following reasons: -- Speech is not detected before the timeout intervals expire for the or properties. +- Speech is not detected before the timeout intervals expire for the or properties. - The recognition engine detects speech but finds no matches in any of its loaded and enabled objects. - To perform asynchronous recognition, use one of the methods. + To perform asynchronous recognition, use one of the methods. @@ -3189,7 +3189,7 @@ namespace SynchronousRecognition performs a single recognition operation and then terminates. The `initialSilenceTimeout` parameter supersedes the recognizer's property. + If the speech recognition engine detects speech within the time interval specified by `initialSilenceTimeout` argument, performs a single recognition operation and then terminates. The `initialSilenceTimeout` parameter supersedes the recognizer's property. During a call to this method, the recognizer can raise the following events: @@ -3205,11 +3205,11 @@ namespace SynchronousRecognition A synchronous recognition operation can fail for the following reasons: -- Speech is not detected before the timeout intervals expire for the or for the `initialSilenceTimeout` parameter. +- Speech is not detected before the timeout intervals expire for the or for the `initialSilenceTimeout` parameter. - The recognition engine detects speech but finds no matches in any of its loaded and enabled objects. - To perform asynchronous recognition, use one of the methods. + To perform asynchronous recognition, use one of the methods. @@ -3294,21 +3294,21 @@ namespace SynchronousRecognition - or . Raised when the recognizer finalizes a recognition operation. -- . Raised when a operation finishes. +- . Raised when a operation finishes. To retrieve the result of an asynchronous recognition operation, attach an event handler to the recognizer's event. The recognizer raises this event whenever it successfully completes a synchronous or asynchronous recognition operation. If recognition was not successful, the property on object, which you can access in the handler for the event, will be `null`. An asynchronous recognition operation can fail for the following reasons: -- Speech is not detected before the timeout intervals expire for the or properties. +- Speech is not detected before the timeout intervals expire for the or properties. - The recognition engine detects speech but finds no matches in any of its loaded and enabled objects. -- The must have at least one object loaded before performing recognition. To load a speech recognition grammar, use the or method. +- The must have at least one object loaded before performing recognition. To load a speech recognition grammar, use the or method. -- To modify how the recognizer handles the timing of speech or silence with respect to recognition, use the , , , and properties. +- To modify how the recognizer handles the timing of speech or silence with respect to recognition, use the , , , and properties. -- To perform synchronous recognition, use one of the methods. +- To perform synchronous recognition, use one of the methods. ]]> @@ -3354,11 +3354,11 @@ namespace SynchronousRecognition - or . Raised when the recognizer finalizes a recognition operation. -- . Raised when a operation finishes. +- . Raised when a operation finishes. To retrieve the result of an asynchronous recognition operation, attach an event handler to the recognizer's event. The recognizer raises this event whenever it successfully completes a synchronous or asynchronous recognition operation. If recognition was not successful, the property on object, which you can access in the handler for the event, will be `null`. - To perform synchronous recognition, use one of the methods. + To perform synchronous recognition, use one of the methods. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -3592,7 +3592,7 @@ namespace AsynchronousRecognition , the recognizer continues performing asynchronous recognition operations until the or method is called. + If `mode` is , the recognizer continues performing asynchronous recognition operations until the or method is called. During a call to this method, the recognizer can raise the following events: @@ -3602,17 +3602,17 @@ namespace AsynchronousRecognition - or . Raised when the recognizer finalizes a recognition operation. -- . Raised when a operation finishes. +- . Raised when a operation finishes. To retrieve the result of an asynchronous recognition operation, attach an event handler to the recognizer's event. The recognizer raises this event whenever it successfully completes a synchronous or asynchronous recognition operation. If recognition was not successful, the property on object, which you can access in the handler for the event, will be `null`. An asynchronous recognition operation can fail for the following reasons: -- Speech is not detected before the timeout intervals expire for the or properties. +- Speech is not detected before the timeout intervals expire for the or properties. - The recognition engine detects speech but finds no matches in any of its loaded and enabled objects. - To perform synchronous recognition, use one of the methods. + To perform synchronous recognition, use one of the methods. @@ -3847,14 +3847,14 @@ namespace AsynchronousRecognition or event when an asynchronous operation is canceled, and sets the property of the to `true`. This method cancels asynchronous operations initiated by the and methods. + This method immediately finalizes asynchronous recognition. If the current asynchronous recognition operation is receiving input, the input is truncated and the operation completes with the existing input. The recognizer raises the or event when an asynchronous operation is canceled, and sets the property of the to `true`. This method cancels asynchronous operations initiated by the and methods. - To stop asynchronous recognition without truncating the input, use the method. + To stop asynchronous recognition without truncating the input, use the method. ## Examples - The following example shows part of a console application that demonstrates the use of the method. The example creates and loads a speech recognition grammar, initiates a continuing asynchronous recognition operation, and then pauses 2 seconds before it cancels the operation. The recognizer receives input from the file, c:\temp\audioinput\sample.wav. Event handlers are included to demonstrate the events that the recognizer raises during the operation. + The following example shows part of a console application that demonstrates the use of the method. The example creates and loads a speech recognition grammar, initiates a continuing asynchronous recognition operation, and then pauses 2 seconds before it cancels the operation. The recognizer receives input from the file, c:\temp\audioinput\sample.wav. Event handlers are included to demonstrate the events that the recognizer raises during the operation. ```csharp @@ -4073,14 +4073,14 @@ namespace AsynchronousRecognition or event when an asynchronous operation is stopped, and sets the property of the to `true`. This method stops asynchronous operations initiated by the and methods. + This method finalizes asynchronous recognition without truncating input. If the current asynchronous recognition operation is receiving input, the recognizer continues accepting input until the current recognition operation is completed. The recognizer raises the or event when an asynchronous operation is stopped, and sets the property of the to `true`. This method stops asynchronous operations initiated by the and methods. - To immediately cancel asynchronous recognition with only the existing input, use the method. + To immediately cancel asynchronous recognition with only the existing input, use the method. ## Examples - The following example shows part of a console application that demonstrates the use of the method. The example creates and loads a speech recognition grammar, initiates a continuing asynchronous recognition operation, and then pauses 2 seconds before it stops the operation. The recognizer receives input from the file, c:\temp\audioinput\sample.wav. Event handlers are included to demonstrate the events that the recognizer raises during the operation. + The following example shows part of a console application that demonstrates the use of the method. The example creates and loads a speech recognition grammar, initiates a continuing asynchronous recognition operation, and then pauses 2 seconds before it stops the operation. The recognizer receives input from the file, c:\temp\audioinput\sample.wav. Event handlers are included to demonstrate the events that the recognizer raises during the operation. ```csharp @@ -4300,9 +4300,9 @@ namespace AsynchronousRecognition object's method initiates an asynchronous recognition operation. When the recognizer finalizes the asynchronous operation, it raises this event. + The object's method initiates an asynchronous recognition operation. When the recognizer finalizes the asynchronous operation, it raises this event. - Using the handler for the event, you can access the in the object. If recognition was not successful, will be `null`. To determine whether a timeout or an interruption in audio input caused recognition to fail, you can access the properties for , , or . + Using the handler for the event, you can access the in the object. If recognition was not successful, will be `null`. To determine whether a timeout or an interruption in audio input caused recognition to fail, you can access the properties for , , or . See the class for more information. @@ -4486,7 +4486,7 @@ namespace SampleRecognition method. + To get information about all of the installed speech recognizers for the current system, use the method. @@ -4550,16 +4550,16 @@ namespace RecognitionEngine to pause a running instance of before modifying its settings or its objects. The raises this event when it is ready to accept modifications. + Applications must use to pause a running instance of before modifying its settings or its objects. The raises this event when it is ready to accept modifications. - For example, while the is paused, you can load, unload, enable, and disable objects, and modify values for the , , and properties. For more information, see the method. + For example, while the is paused, you can load, unload, enable, and disable objects, and modify values for the , , and properties. For more information, see the method. When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Events and Delegates](https://go.microsoft.com/fwlink/?LinkId=162418). ## Examples - The following example shows a console application that loads and unloads objects. The application uses the method to request the speech recognition engine to pause so it can receive an update. The application then loads or unloads a object. + The following example shows a console application that loads and unloads objects. The application uses the method to request the speech recognition engine to pause so it can receive an update. The application then loads or unloads a object. At each update, a handler for event writes the name and status of the currently loaded objects to the console. As grammars are loaded and unloaded, the application first recognizes the names of farm animals, then the names of farm animals and the names of fruits, then only the names of fruits. @@ -4734,12 +4734,12 @@ namespace SampleRecognition ## Remarks When the recognizer generates the event, the property of the is `null`. - To provide a user token, use the or method. To specify an audio position offset, use the method. + To provide a user token, use the or method. To specify an audio position offset, use the method. ## Examples - The following example shows a console application that loads and unloads objects. The application uses the method to request the speech recognition engine to pause so it can receive an update. The application then loads or unloads a object. + The following example shows a console application that loads and unloads objects. The application uses the method to request the speech recognition engine to pause so it can receive an update. The application then loads or unloads a object. At each update, a handler for event writes the name and status of the currently loaded objects to the console. As grammars are loaded and unloaded, the application first recognizes the names of farm animals, then the names of farm animals and the names of fruits, then only the names of fruits. @@ -4881,7 +4881,7 @@ namespace SampleRecognition ## Remarks When the recognizer generates the event, the property of the contains the value of the `userToken` parameter. - To specify an audio position offset, use the method. + To specify an audio position offset, use the method. ]]> @@ -4919,7 +4919,7 @@ namespace SampleRecognition equals the current plus `audioPositionAheadToRaiseUpdate`. + The recognizer does not initiate the recognizer update request until the recognizer's equals the current plus `audioPositionAheadToRaiseUpdate`. When the recognizer generates the event, the property of the contains the value of the `userToken` parameter. @@ -5231,7 +5231,7 @@ namespace DefaultInput object for no input when using the and methods, or when taking a recognition engine temporarily off line. + Configure the object for no input when using the and methods, or when taking a recognition engine temporarily off line. ]]> @@ -5437,14 +5437,14 @@ recognizer.SetInputToWaveFile(@"c:\temp\SampleWAVInput.wav"); ## Remarks Each speech recognizer has an algorithm to distinguish between silence and speech. When the performs a speech recognition operation, it raises the event when its algorithm identifies the input as speech. The property of the associated object indicates location in the input stream where the recognizer detected speech. The raises the event before it raises any of the , , or events. - For more information see the , , , and methods. + For more information see the , , , and methods. When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Events and Delegates](https://go.microsoft.com/fwlink/?LinkId=162418). ## Examples - The following example is part of a console application for choosing origin and destination cities for a flight. The application recognizes phrases such as "I want to fly from Miami to Chicago." The example uses the event to report the each time speech is detected. + The following example is part of a console application for choosing origin and destination cities for a flight. The application recognizes phrases such as "I want to fly from Miami to Chicago." The example uses the event to report the each time speech is detected. ``` using System; @@ -5557,7 +5557,7 @@ namespace SampleRecognition derives from . - For more information see the property and the , , , and methods. + For more information see the property and the , , , and methods. When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Events and Delegates](https://go.microsoft.com/fwlink/?LinkId=162418). @@ -5684,16 +5684,16 @@ namespace SampleRecognition objects. The property of the contains the rejected object. You can use the handler for the event to retrieve recognition that were rejected and their scores. + The recognizer raises this event if it determines that input does not match with sufficient confidence any of its loaded and enabled objects. The property of the contains the rejected object. You can use the handler for the event to retrieve recognition that were rejected and their scores. - If your application is using a instance, you can modify the confidence level at which speech input is accepted or rejected with one of the methods. You can modify how the speech recognition responds to non-speech input using the , , , and properties. + If your application is using a instance, you can modify the confidence level at which speech input is accepted or rejected with one of the methods. You can modify how the speech recognition responds to non-speech input using the , , , and properties. When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Events and Delegates](https://go.microsoft.com/fwlink/?LinkId=162418). ## Examples - The following example recognizes phrases such as "Display the list of artists in the jazz category" or "Display albums gospel". The example uses a handler for the event to display a notification in the console when the speech input cannot be matched to the contents of the grammar with sufficient to produce a successful recognition. The handler also displays recognition result that were rejected because of low confidence scores. + The following example recognizes phrases such as "Display the list of artists in the jazz category" or "Display albums gospel". The example uses a handler for the event to display a notification in the console when the speech input cannot be matched to the contents of the grammar with sufficient to produce a successful recognition. The handler also displays recognition result that were rejected because of low confidence scores. ``` using System; @@ -5815,9 +5815,9 @@ namespace SampleRecognition or methods. The recognizer raises the event if it determines that input matches one of its loaded objects with a sufficient level of confidence to constitute recognition. The property of the contains the accepted object. Handlers of events can obtain the recognized phrase as well as a list of recognition with lower confidence scores. + You can initiate a recognition operation using the one of the or methods. The recognizer raises the event if it determines that input matches one of its loaded objects with a sufficient level of confidence to constitute recognition. The property of the contains the accepted object. Handlers of events can obtain the recognized phrase as well as a list of recognition with lower confidence scores. - If your application is using a instance, you can modify the confidence level at which speech input is accepted or rejected with one of the methods. You can modify how the speech recognition responds to non-speech input using the , , , and properties. + If your application is using a instance, you can modify the confidence level at which speech input is accepted or rejected with one of the methods. You can modify how the speech recognition responds to non-speech input using the , , , and properties. When the recognizer receives input that matches a grammar, the object can raise its event. The object's event is raised prior to the speech recognizer's event. Any tasks specific to a particular grammar should always be performed by a handler for the event. @@ -5953,7 +5953,7 @@ namespace SampleRecognition ## Remarks If the recognizer is currently loading a asynchronously, this method waits until the is loaded, before it unloads all of the objects from the instance. - To unload a specific grammar, use the method. + To unload a specific grammar, use the method. @@ -6084,7 +6084,7 @@ namespace UnloadGrammars to pause the instance before loading, unloading, enabling, or disabling a object. To unload all objects, use the method. + If the recognizer is running, applications must use to pause the instance before loading, unloading, enabling, or disabling a object. To unload all objects, use the method. @@ -6212,11 +6212,11 @@ namespace UnloadGrammars |`AdaptationOn`|Indicates whether adaptation of the acoustic model is ON (value = `1`) or OFF (value = `0`). The default value is `1` (ON).| |`PersistedBackgroundAdaptation`|Indicates whether background adaptation is ON (value = `1`) or OFF (value = `0`), and persists the setting in the registry. The default value is `1` (ON).| - To return one of the recognizer's settings, use the method. + To return one of the recognizer's settings, use the method. - With the exception of `PersistedBackgroundAdaptation`, property values set using the methods remain in effect only for the current instance of , after which they revert to their default settings. + With the exception of `PersistedBackgroundAdaptation`, property values set using the methods remain in effect only for the current instance of , after which they revert to their default settings. - You can modify how the speech recognition responds to non-speech input using the , , , and properties. + You can modify how the speech recognition responds to non-speech input using the , , , and properties. ]]> @@ -6251,7 +6251,7 @@ namespace UnloadGrammars method remain in effect only for the current instance of , after which they revert to their default settings. See for descriptions of supported settings. + With the exception of `PersistedBackgroundAdaptation`, property values set using the method remain in effect only for the current instance of , after which they revert to their default settings. See for descriptions of supported settings. @@ -6385,7 +6385,7 @@ namespace RecognizerSettings method remain in effect only for the current instance of , after which they revert to their default settings. See for descriptions of supported settings. + With the exception of `PersistedBackgroundAdaptation`, property values set using the method remain in effect only for the current instance of , after which they revert to their default settings. See for descriptions of supported settings. ]]> diff --git a/xml/System.Speech.Recognition/SpeechRecognizer.xml b/xml/System.Speech.Recognition/SpeechRecognizer.xml index b7c1fd5f37b..36884ec32af 100644 --- a/xml/System.Speech.Recognition/SpeechRecognizer.xml +++ b/xml/System.Speech.Recognition/SpeechRecognizer.xml @@ -36,29 +36,29 @@ This class provides control over various aspects of the speech recognition process: -- To manage speech recognition grammars, use the , , , , and . +- To manage speech recognition grammars, use the , , , , and . - To get information about current speech recognition operations, subscribe to the 's , , , and events. - To view or modify the number of alternate results the recognizer returns, use the property. The recognizer returns recognition results in a object. -- To access or monitor the state of the shared recognizer, use the , , , , , , and properties and the , , , and events. +- To access or monitor the state of the shared recognizer, use the , , , , , , and properties and the , , , and events. -- To synchronize changes to the recognizer, use the method. The shared recognizer uses more than one thread to perform tasks. +- To synchronize changes to the recognizer, use the method. The shared recognizer uses more than one thread to perform tasks. -- To emulate input to the shared recognizer, use the and methods. +- To emulate input to the shared recognizer, use the and methods. The configuration of Windows Speech Recognition is managed by the use of the **Speech Properties** dialog in the **Control Panel**. This interface is used to select the default desktop speech recognition engine and language, the audio input device, and the sleep behavior of speech recognition. If the configuration of Windows Speech Recognition is changed while the application is running, (for instance, if speech recognition is disabled or the input language is changed), the change affects all objects. To create an in-process speech recognizer that is independent of Windows Speech Recognition, use the class. > [!NOTE] -> Always call before you release your last reference to the speech recognizer. Otherwise, the resources it is using will not be freed until the garbage collector calls the recognizer object's `Finalize` method. +> Always call before you release your last reference to the speech recognizer. Otherwise, the resources it is using will not be freed until the garbage collector calls the recognizer object's `Finalize` method. ## Examples - The following example is part of a console application that loads a speech recognition grammar and demonstrates asynchronous emulated input, the associated recognition results, and the associated events raised by the speech recognizer. If Windows Speech Recognition is not running, then starting this application will also start Windows Speech Recognition. If Windows Speech Recognition is in the **Sleeping** state, then always returns null. + The following example is part of a console application that loads a speech recognition grammar and demonstrates asynchronous emulated input, the associated recognition results, and the associated events raised by the speech recognizer. If Windows Speech Recognition is not running, then starting this application will also start Windows Speech Recognition. If Windows Speech Recognition is in the **Sleeping** state, then always returns null. ```csharp using System; @@ -189,7 +189,7 @@ namespace SharedRecognizer ## Examples - The following example is part of a console application that loads a speech recognition grammar and demonstrates asynchronous emulated input, the associated recognition results, and the associated events raised by the speech recognizer. If Windows Speech Recognition is not running, then starting this application will also start Windows Speech Recognition. If Windows Speech Recognition is in the **Sleeping** state, then always returns null. + The following example is part of a console application that loads a speech recognition grammar and demonstrates asynchronous emulated input, the associated recognition results, and the associated events raised by the speech recognizer. If Windows Speech Recognition is not running, then starting this application will also start Windows Speech Recognition. If Windows Speech Recognition is in the **Sleeping** state, then always returns null. ```csharp using System; @@ -435,7 +435,7 @@ void recognizer_AudioLevelUpdated(object sender, AudioLevelUpdatedEventArgs e) ## Examples - In the following example, the shared speech recognizer uses a dictation grammar to match speech input. A handler for the event writes to the console the , , and when the speech recognizer detects speech at its input. + In the following example, the shared speech recognizer uses a dictation grammar to match speech input. A handler for the event writes to the console the , , and when the speech recognizer detects speech at its input. ``` using System; @@ -639,7 +639,7 @@ void recognizer_AudioSignalProblemOccurred(object sender, AudioSignalProblemOccu ## Examples - The following example uses a handler for the `AudioStateChanged` event to write the recognizer's new to the console each time it changes using a member of the enumeration. + The following example uses a handler for the `AudioStateChanged` event to write the recognizer's new to the console each time it changes using a member of the enumeration. ``` using System; @@ -804,7 +804,7 @@ namespace SampleRecognition > [!NOTE] > The object generated by the shared recognizer in response to emulated input has a value of `null` for its property. - To emulate asynchronous recognition, use the method. + To emulate asynchronous recognition, use the method. ]]> @@ -843,7 +843,7 @@ namespace SampleRecognition ## Examples - The following example loads a sample grammar to the shared recognizer and emulates input to the recognizer. If Windows Speech Recognition is not running, then starting this application will also start Windows Speech Recognition. If Windows Speech Recognition is in the **Sleeping** state, then always returns null. + The following example loads a sample grammar to the shared recognizer and emulates input to the recognizer. If Windows Speech Recognition is not running, then starting this application will also start Windows Speech Recognition. If Windows Speech Recognition is in the **Sleeping** state, then always returns null. ```csharp @@ -1020,7 +1020,7 @@ namespace SharedRecognizer > [!NOTE] > The object generated by the shared recognizer in response to emulated input has a value of `null` for its property. - To emulate synchronous recognition, use the method. + To emulate synchronous recognition, use the method. ]]> @@ -1058,7 +1058,7 @@ namespace SharedRecognizer This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ## Examples - The following example is part of a console application that loads a speech recognition grammar and demonstrates asynchronous emulated input, the associated recognition results, and the associated events raised by the speech recognizer. If Windows Speech Recognition is not running, then starting this application will also start Windows Speech Recognition. If Windows Speech Recognition is in the **Sleeping** state, then always returns null. + The following example is part of a console application that loads a speech recognition grammar and demonstrates asynchronous emulated input, the associated recognition results, and the associated events raised by the speech recognizer. If Windows Speech Recognition is not running, then starting this application will also start Windows Speech Recognition. If Windows Speech Recognition is in the **Sleeping** state, then always returns null. ```csharp using System; @@ -1272,7 +1272,7 @@ namespace SharedRecognizer method begins an asynchronous recognition operation. The recognizer raises the `EmulateRecognizeCompleted` event when it finalizes the asynchronous operation. + Each method begins an asynchronous recognition operation. The recognizer raises the `EmulateRecognizeCompleted` event when it finalizes the asynchronous operation. The asynchronous recognition operation can raise the , , , and events. The event is the last such event that the recognizer raises for a given operation. @@ -1281,7 +1281,7 @@ namespace SharedRecognizer ## Examples - The following example is part of a console application that loads a speech recognition grammar and demonstrates asynchronous emulated input, the associated recognition results, and the associated events raised by the speech recognizer. If Windows Speech Recognition is not running, then starting this application will also start Windows Speech Recognition. If Windows Speech Recognition is in the **Sleeping** mode, then always returns null. + The following example is part of a console application that loads a speech recognition grammar and demonstrates asynchronous emulated input, the associated recognition results, and the associated events raised by the speech recognizer. If Windows Speech Recognition is not running, then starting this application will also start Windows Speech Recognition. If Windows Speech Recognition is in the **Sleeping** mode, then always returns null. ```csharp using System; @@ -1535,14 +1535,14 @@ namespace SharedRecognizer to pause the speech recognition engine before loading, unloading, enabling, or disabling a grammar. + The shared recognizer throws an exception if the speech recognition grammar is already loaded, is being asynchronously loaded, or has failed to load into any recognizer. If the recognizer is running, applications must use to pause the speech recognition engine before loading, unloading, enabling, or disabling a grammar. - To load a speech recognition grammar asynchronously, use the method. + To load a speech recognition grammar asynchronously, use the method. ## Examples - The following example is part of a console application that loads a speech recognition grammar and demonstrates asynchronous emulated input, the associated recognition results, and the associated events raised by the speech recognizer. If Windows Speech Recognition is not running, then starting this application will also start Windows Speech Recognition. If Windows Speech Recognition is in the **Sleeping** state, then always returns null. + The following example is part of a console application that loads a speech recognition grammar and demonstrates asynchronous emulated input, the associated recognition results, and the associated events raised by the speech recognizer. If Windows Speech Recognition is not running, then starting this application will also start Windows Speech Recognition. If Windows Speech Recognition is in the **Sleeping** state, then always returns null. ```csharp using System; @@ -1672,9 +1672,9 @@ namespace SharedRecognizer event. The recognizer throws an exception if the speech recognition grammar is already loaded, is being asynchronously loaded, or has failed to load into any recognizer. If the recognizer is running, applications must use to pause the speech recognition engine before loading, unloading, enabling, or disabling a grammar. + When the recognizer completes this asynchronous operation, it raises a event. The recognizer throws an exception if the speech recognition grammar is already loaded, is being asynchronously loaded, or has failed to load into any recognizer. If the recognizer is running, applications must use to pause the speech recognition engine before loading, unloading, enabling, or disabling a grammar. - To load a speech recognition grammar synchronously, use the method. + To load a speech recognition grammar synchronously, use the method. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -1711,7 +1711,7 @@ namespace SharedRecognizer method initiates an asynchronous operation. The recognizer raises the `LoadGrammarCompleted` event when it completes the operation. To get the object that the recognizer loaded, use the property of the associated . To get the current objects the recognizer has loaded, use the recognizer's property. + The recognizer's method initiates an asynchronous operation. The recognizer raises the `LoadGrammarCompleted` event when it completes the operation. To get the object that the recognizer loaded, use the property of the associated . To get the current objects the recognizer has loaded, use the recognizer's property. When you create a delegate for a `LoadGrammarCompleted` event, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Events and Delegates](https://go.microsoft.com/fwlink/?LinkId=162418). @@ -1850,7 +1850,7 @@ namespace SampleRecognition ## Remarks The property of the class contains the collection of objects that represent other candidate interpretations of the input. - The default value for is 10. + The default value for is 10. ]]> @@ -1888,9 +1888,9 @@ namespace SampleRecognition > [!NOTE] > Setting the property to `true` causes each event handler in every application to block the Windows speech recognition service. - To synchronize the changes to the shared recognizer with your application state, use the method. + To synchronize the changes to the shared recognizer with your application state, use the method. - When is `true`, during the execution of the handler the speech recognition service pauses and buffers new audio input as it arrives. Once the event handler exits, the speech recognition service resumes recognition and starts processing information from its input buffer. + When is `true`, during the execution of the handler the speech recognition service pauses and buffers new audio input as it arrives. Once the event handler exits, the speech recognition service resumes recognition and starts processing information from its input buffer. To enable or disable the speech recognition service, use the property. @@ -2021,14 +2021,14 @@ namespace SharedRecognizer to pause a running instance of before modifying its objects. For example, while the is paused, you can load, unload, enable, and disable objects. The raises this event when it is ready to accept modifications. + Applications must use to pause a running instance of before modifying its objects. For example, while the is paused, you can load, unload, enable, and disable objects. The raises this event when it is ready to accept modifications. When you create a delegate for a event, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Events and Delegates](https://go.microsoft.com/fwlink/?LinkId=162418). ## Examples - The following example shows a console application that loads and unloads objects. The application uses the method to request the speech recognition engine to pause so it can receive an update. The application then loads or unloads a object. + The following example shows a console application that loads and unloads objects. The application uses the method to request the speech recognition engine to pause so it can receive an update. The application then loads or unloads a object. At each update, a handler for event writes the name and status of the currently loaded objects to the console. As grammars are loaded and unloaded, the application first recognizes the names of farm animals, then the names of farm animals and the names of fruits, then only the names of fruits. @@ -2170,7 +2170,7 @@ namespace SampleRecognition ## Examples - The following example shows a console application that loads and unloads objects. The application uses the method to request the speech recognition engine to pause so it can receive an update. The application then loads or unloads a object. + The following example shows a console application that loads and unloads objects. The application uses the method to request the speech recognition engine to pause so it can receive an update. The application then loads or unloads a object. At each update, a handler for event writes the name and status of the currently loaded objects to the console. As grammars are loaded and unloaded, the application first recognizes the names of farm animals, then the names of farm animals and the names of fruits, then only the names of fruits. @@ -2301,7 +2301,7 @@ namespace SampleRecognition ## Remarks When the recognizer generates the event, the property of the is `null`. - To provide a user token, use the or method. To specify an audio position offset, use the method. + To provide a user token, use the or method. To specify an audio position offset, use the method. ]]> @@ -2339,7 +2339,7 @@ namespace SampleRecognition ## Remarks When the recognizer generates the event, the property of the contains the value of the `userToken` parameter. - To specify an audio position offset, use the method. + To specify an audio position offset, use the method. ]]> @@ -2377,7 +2377,7 @@ namespace SampleRecognition equals the current plus the value of the `audioPositionAheadToRaiseUpdate` parameter. + The recognizer does not initiate the recognizer update request until the recognizer's equals the current plus the value of the `audioPositionAheadToRaiseUpdate` parameter. When the recognizer generates the event, the property of the contains the value of the `userToken` parameter. @@ -2412,14 +2412,14 @@ namespace SampleRecognition property of the associated object indicates location in the input stream where the recognizer detected speech. For more information see the and properties and the and methods. + The shared recognizer can raise this event in response to input. The property of the associated object indicates location in the input stream where the recognizer detected speech. For more information see the and properties and the and methods. When you create a delegate for a event, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Events and Delegates](https://go.microsoft.com/fwlink/?LinkId=162418). ## Examples - The following example is part of a console application for choosing origin and destination cities for a flight. The application recognizes phrases such as "I want to fly from Miami to Chicago." The example uses the event to report the each time speech is detected. + The following example is part of a console application for choosing origin and destination cities for a flight. The application recognizes phrases such as "I want to fly from Miami to Chicago." The example uses the event to report the each time speech is detected. ``` using System; @@ -2910,7 +2910,7 @@ namespace SampleRecognition ## Examples - The following example creates a shared speech recognizer, and then creates two types of grammars for recognizing specific words and for accepting free dictation. The example asynchronously loads all the created grammars to the recognizer. A handler for the event uses the method to put Windows Recognition in "listening" mode. + The following example creates a shared speech recognizer, and then creates two types of grammars for recognizing specific words and for accepting free dictation. The example asynchronously loads all the created grammars to the recognizer. A handler for the event uses the method to put Windows Recognition in "listening" mode. ```csharp using System; @@ -3035,7 +3035,7 @@ namespace SampleRecognition ## Remarks If the recognizer is currently loading a grammar asynchronously, this method waits until the grammar is loaded, before it unloads all of the recognizer's grammars. - To unload a specific grammar, use the method. + To unload a specific grammar, use the method. ]]> @@ -3072,7 +3072,7 @@ namespace SampleRecognition to pause the speech recognition engine before loading, unloading, enabling, or disabling a grammar. To unload all grammars, use the method. + If the recognizer is running, applications must use to pause the speech recognition engine before loading, unloading, enabling, or disabling a grammar. To unload all grammars, use the method. ]]> diff --git a/xml/System.Speech.Recognition/SpeechUI.xml b/xml/System.Speech.Recognition/SpeechUI.xml index bc8868d9819..c0e55dd77a0 100644 --- a/xml/System.Speech.Recognition/SpeechUI.xml +++ b/xml/System.Speech.Recognition/SpeechUI.xml @@ -25,51 +25,51 @@ Provides text and status information on recognition operations to be displayed in the Speech platform user interface. - class can be used to indicate exact feedback to the end user through the speech recognition user interface. An application can return arbitrary text and success/failure information using this class. - - - -## Examples - The following example is a handler for the event. This event is used by a that is designed to handle password input in the form "My password is …". - - If a password is not present, or not valid, sends error information to the Speech platform user interface. - -``` - -grammar.SpeechRecognized += -delegate(object sender, SpeechRecognizedEventArgs eventArgs) -{ - SemanticValue semantics = eventArgs.Result.Semantics; - RecognitionResult result=eventArgs.Result; - - if (!semantics.ContainsKey("Password")) - { - SpeechUI.SendTextFeedback(eventArgs.Result, "No Password Provided", false); - } - else - { - RecognizedAudio pwdAudio = result.GetAudioForWordRange( - result.Words[3], - result.Words[result.Words.Count - 1]); - MemoryStream pwdMemoryStream = new MemoryStream(); - pwdAudio.WriteToAudioStream(pwdMemoryStream); - if (!IsValidPwd(pwdMemoryStream)) - { - string badPwd = System.IO.Path.GetTempPath() + - "BadPwd" + (new Random()).Next().ToString() + ".wav"; - FileStream waveStream = new FileStream(badPwd, FileMode.Create); - pwdAudio.WriteToWaveStream(waveStream); - waveStream.Flush(); - waveStream.Close(); - SpeechUI.SendTextFeedback(eventArgs.Result, "Invalid Password", false); - } - } -}; -``` - + class can be used to indicate exact feedback to the end user through the speech recognition user interface. An application can return arbitrary text and success/failure information using this class. + + + +## Examples + The following example is a handler for the event. This event is used by a that is designed to handle password input in the form "My password is …". + + If a password is not present, or not valid, sends error information to the Speech platform user interface. + +``` + +grammar.SpeechRecognized += +delegate(object sender, SpeechRecognizedEventArgs eventArgs) +{ + SemanticValue semantics = eventArgs.Result.Semantics; + RecognitionResult result=eventArgs.Result; + + if (!semantics.ContainsKey("Password")) + { + SpeechUI.SendTextFeedback(eventArgs.Result, "No Password Provided", false); + } + else + { + RecognizedAudio pwdAudio = result.GetAudioForWordRange( + result.Words[3], + result.Words[result.Words.Count - 1]); + MemoryStream pwdMemoryStream = new MemoryStream(); + pwdAudio.WriteToAudioStream(pwdMemoryStream); + if (!IsValidPwd(pwdMemoryStream)) + { + string badPwd = System.IO.Path.GetTempPath() + + "BadPwd" + (new Random()).Next().ToString() + ".wav"; + FileStream waveStream = new FileStream(badPwd, FileMode.Create); + pwdAudio.WriteToWaveStream(waveStream); + waveStream.Flush(); + waveStream.Close(); + SpeechUI.SendTextFeedback(eventArgs.Result, "Invalid Password", false); + } + } +}; +``` + ]]> @@ -104,53 +104,53 @@ delegate(object sender, SpeechRecognizedEventArgs eventArgs) if the information provided to the method (, and ) was successfully made available to the Speech platform user interface, and if the operation failed. - can be used to indicate that a recognition operation failed to meet certain criteria, even if the input was recognized. - - An example is the verification of security code information, where the input was fully recognized, but the verification information was wrong. - - - -## Examples - The following example is a handler for a event. This event is used by a that is designed to handle password input of the form, "My password is …". - - If a password is not present, or not valid, **SendTextFeedback** is used to send error information to the Speech platform user interface. - -``` - -grammar.SpeechRecognized += -delegate(object sender, SpeechRecognizedEventArgs eventArgs) -{ - SemanticValue semantics = eventArgs.Result.Semantics; - RecognitionResult result=eventArgs.Result; - - if (!semantics.ContainsKey("Password")) - { - SpeechUI.SendTextFeedback(eventArgs.Result, "No Password Provided", false); - } - else - { - RecognizedAudio pwdAudio = result.GetAudioForWordRange( - result.Words[3], - result.Words[result.Words.Count - 1]); - MemoryStream pwdMemoryStream = new MemoryStream(); - pwdAudio.WriteToAudioStream(pwdMemoryStream); - if (!IsValidPwd(pwdMemoryStream)) - { - string badPwd = System.IO.Path.GetTempPath() + "BadPwd" + - (new Random()).Next().ToString() + ".wav"; - FileStream waveStream = new FileStream(badPwd, FileMode.Create); - pwdAudio.WriteToWaveStream(waveStream); - waveStream.Flush(); - waveStream.Close(); - SpeechUI.SendTextFeedback(eventArgs.Result, "Invalid Password", false); - } - } -}; -``` - + can be used to indicate that a recognition operation failed to meet certain criteria, even if the input was recognized. + + An example is the verification of security code information, where the input was fully recognized, but the verification information was wrong. + + + +## Examples + The following example is a handler for a event. This event is used by a that is designed to handle password input of the form, "My password is …". + + If a password is not present, or not valid, **SendTextFeedback** is used to send error information to the Speech platform user interface. + +``` + +grammar.SpeechRecognized += +delegate(object sender, SpeechRecognizedEventArgs eventArgs) +{ + SemanticValue semantics = eventArgs.Result.Semantics; + RecognitionResult result=eventArgs.Result; + + if (!semantics.ContainsKey("Password")) + { + SpeechUI.SendTextFeedback(eventArgs.Result, "No Password Provided", false); + } + else + { + RecognizedAudio pwdAudio = result.GetAudioForWordRange( + result.Words[3], + result.Words[result.Words.Count - 1]); + MemoryStream pwdMemoryStream = new MemoryStream(); + pwdAudio.WriteToAudioStream(pwdMemoryStream); + if (!IsValidPwd(pwdMemoryStream)) + { + string badPwd = System.IO.Path.GetTempPath() + "BadPwd" + + (new Random()).Next().ToString() + ".wav"; + FileStream waveStream = new FileStream(badPwd, FileMode.Create); + pwdAudio.WriteToWaveStream(waveStream); + waveStream.Flush(); + waveStream.Close(); + SpeechUI.SendTextFeedback(eventArgs.Result, "Invalid Password", false); + } + } +}; +``` + ]]> diff --git a/xml/System.Speech.Recognition/StateChangedEventArgs.xml b/xml/System.Speech.Recognition/StateChangedEventArgs.xml index 9386fa968d6..f43d03a234d 100644 --- a/xml/System.Speech.Recognition/StateChangedEventArgs.xml +++ b/xml/System.Speech.Recognition/StateChangedEventArgs.xml @@ -30,14 +30,14 @@ ## Remarks The event is raised by the class. derives from and is passed to handlers for events. - is a read-only property. A shared speech recognizer's state cannot be changed programmatically. Users can change a shared speech recognizer's state using the Speech Recognition user interface (UI) or through the **Speech Recognition** member of the Windows **Control Panel**. + is a read-only property. A shared speech recognizer's state cannot be changed programmatically. Users can change a shared speech recognizer's state using the Speech Recognition user interface (UI) or through the **Speech Recognition** member of the Windows **Control Panel**. Both the **On** and **Sleep** settings in the Speech Recognition UI correspond to the `Listening` state. The **Off** setting in the Speech Recognition UI corresponds to . ## Examples - The following example creates a shared speech recognizer, and then creates two types of grammars for recognizing specific words and for accepting free dictation. The example asynchronously loads all the created grammars to the recognizer. A handler for the event uses the method to put Windows Recognition in "listening" mode. + The following example creates a shared speech recognizer, and then creates two types of grammars for recognizing specific words and for accepting free dictation. The example asynchronously loads all the created grammars to the recognizer. A handler for the event uses the method to put Windows Recognition in "listening" mode. ``` using System; diff --git a/xml/System.Speech.Recognition/SubsetMatchingMode.xml b/xml/System.Speech.Recognition/SubsetMatchingMode.xml index 314fe13117a..b18f3239250 100644 --- a/xml/System.Speech.Recognition/SubsetMatchingMode.xml +++ b/xml/System.Speech.Recognition/SubsetMatchingMode.xml @@ -29,7 +29,7 @@ ## Remarks In System.Speech, you can construct a grammar that successfully recognizes a phrase even though only a subset of its contents is found in the audio input. - By default, a recognition engine requires an exact match against an entire phrase. The recognition engine can also match partial phrases according to parameters defined by a member used as an argument to the or constructors, or the method. + By default, a recognition engine requires an exact match against an entire phrase. The recognition engine can also match partial phrases according to parameters defined by a member used as an argument to the or constructors, or the method. The following illustrates how each of the members affects recognition when used in a grammar that contains the phrase "a car the truck a boat that plane". diff --git a/xml/System.Speech.Synthesis.TtsEngine/ContourPoint.xml b/xml/System.Speech.Synthesis.TtsEngine/ContourPoint.xml index d2b0eee84a2..38843571e65 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/ContourPoint.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/ContourPoint.xml @@ -40,7 +40,7 @@ ## Remarks The pitch contour is defined as an array of targets at specified time positions in the speech output. Each target is defined by three parameters. The first value is a percentage of the period of the contained text (a number followed by "%"). The second value specifies the amount to raise or lower the pitch. The third value designates the unit to use for the number specified in the second value; either percentage or hertz (Hz). - objects are obtained by the method, or used to set the pitch contour for a by the method. + objects are obtained by the method, or used to set the pitch contour for a by the method. ]]> @@ -284,7 +284,7 @@ Determines if two instances of are equal. Returns if the instances referenced by and are equal, otherwise returns . - .]]> + .]]> @@ -315,7 +315,7 @@ Determines if two instances of are NOT equal. Returns if the instances referenced by and are NOT equal, otherwise returns . - .]]> + .]]> diff --git a/xml/System.Speech.Synthesis.TtsEngine/EmphasisBreak.xml b/xml/System.Speech.Synthesis.TtsEngine/EmphasisBreak.xml index f32f830f9a4..8dd31bbdc5b 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/EmphasisBreak.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/EmphasisBreak.xml @@ -31,9 +31,9 @@ Each synthetic speech engine is free to determine how to render breaks between words; the nature of emphasis differs between languages, dialects, genders, or voices. - Both and may be used when setting or getting the on a instance. + Both and may be used when setting or getting the on a instance. - The two values may be distinguished by the fact that the actual values of are all less than zero and values of are greater than or equal to zero; and by using the value of returned by the property on the object returned by the property on an instance. From more information, see ,and . + The two values may be distinguished by the fact that the actual values of are all less than zero and values of are greater than or equal to zero; and by using the value of returned by the property on the object returned by the property on an instance. From more information, see ,and . ]]> diff --git a/xml/System.Speech.Synthesis.TtsEngine/EmphasisWord.xml b/xml/System.Speech.Synthesis.TtsEngine/EmphasisWord.xml index 6ee46d51dc9..3a622b4ac96 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/EmphasisWord.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/EmphasisWord.xml @@ -31,9 +31,9 @@ Each synthetic speech engine is free to determine how to render emphasis; the nature of emphasis differs between languages, dialects, genders, or voices. - Both and may be used when setting or getting the on a instance. + Both and may be used when setting or getting the on a instance. - The two values may be distinguished by the fact that the actual values of are greater than or equal to zero, and the values of are all less than zero; and by using the value of returned by the property on the object returned by the property on an instance. From more information, see ,and . + The two values may be distinguished by the fact that the actual values of are greater than or equal to zero, and the values of are all less than zero; and by using the value of returned by the property on the object returned by the property on an instance. From more information, see ,and . ]]> diff --git a/xml/System.Speech.Synthesis.TtsEngine/EventParameterType.xml b/xml/System.Speech.Synthesis.TtsEngine/EventParameterType.xml index 329711a287d..3ad65e25008 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/EventParameterType.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/EventParameterType.xml @@ -32,7 +32,7 @@ The `EventParameterType` enumeration is used when constructing a . -For detailed information on how use `EventParameterType`, see the documentation for +For detailed information on how use `EventParameterType`, see the documentation for > [!NOTE] > Currently, instances of a managed synthetic speech engines written using the members of the namespace cannot change resources after construction. @@ -40,7 +40,7 @@ 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. @@ -50,7 +50,7 @@ For detailed information on how use `EventParameterType`, see the documentation - 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. diff --git a/xml/System.Speech.Synthesis.TtsEngine/FragmentState.xml b/xml/System.Speech.Synthesis.TtsEngine/FragmentState.xml index 6e574709c41..9d87ce6a7fc 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/FragmentState.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/FragmentState.xml @@ -38,15 +38,15 @@ instances are obtained from the on objects. + instances are obtained from the on objects. The information in is obtained by parsing the attributes decorating speech text in the Synthesize Speech Markup Language (SSML) used as an input to a synthesis engine. A object can exist for any synthesizer action request as specified by its property. However, the meaning of its members may change for different actions. For more information on synthesize actions, see for more information about specifying synthesizer actions. -- Specification and control of the quality of the spoken output is largely handled through the , , and +- Specification and control of the quality of the spoken output is largely handled through the , , and -- Phonetic, language, and linguist structure information is available through , , and . +- Phonetic, language, and linguist structure information is available through , , and . ]]> @@ -209,19 +209,19 @@ depends on the value returned by the property on the current . + 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. ]]> @@ -355,7 +355,7 @@ are those used with the Windows Speech API (SAPI) and are generated from the "`xml:lang`" attribute on SSML input to a speech synthesizer engine. + The value of are those used with the Windows Speech API (SAPI) and are generated from the "`xml:lang`" attribute on SSML input to a speech synthesizer engine. ]]> @@ -388,7 +388,7 @@ Determines if two instances of describes the same state. Returns if both instances of , and , describe the same state, otherwise is returned. - .]]> + .]]> @@ -419,7 +419,7 @@ Determines if two instances of describes the different state. Returns if both instances of , and , do not describe the same state, otherwise is returned. - .]]> + .]]> @@ -528,7 +528,7 @@ corresponds to the `` tag and its attributes in the SSML specification, and can specify: + The information returned by corresponds to the `` tag and its attributes in the SSML specification, and can specify: - The content type (such as currency, date, or address) or language construct represented by property of a . diff --git a/xml/System.Speech.Synthesis.TtsEngine/ProsodyNumber.xml b/xml/System.Speech.Synthesis.TtsEngine/ProsodyNumber.xml index a634823ae3d..fcdd99a8351 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/ProsodyNumber.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/ProsodyNumber.xml @@ -294,7 +294,7 @@ if is the same as ; otherwise, . - .]]> + .]]> @@ -326,7 +326,7 @@ if is different from ; otherwise, . - .]]> + .]]> diff --git a/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml b/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml index 525c5f889e6..9dd5fddbb09 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml @@ -38,12 +38,12 @@ instance to member of the engine site object passed to implementations of , , and . + A custom speech synthesis engine requests the generation of events under the Speech Platform by providing an appropriate instance to member of the engine site object passed to implementations 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 + 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. @@ -151,7 +151,7 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si ## Remarks Permitted values used for `parameterType`, `param1`, and `param2` and their meaning is dictated by the type of event being requested, as specified by the member of used for `eventId`. - For detailed information on appropriate values for `parameterType`, `param1`, and `param2`, see documentation for + For detailed information on appropriate values for `parameterType`, `param1`, and `param2`, see documentation for 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 . @@ -160,7 +160,7 @@ 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. @@ -326,7 +326,7 @@ 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. @@ -336,7 +336,7 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si - 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. @@ -450,7 +450,7 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si if is the same as ; otherwise, . - .]]> + .]]> @@ -482,7 +482,7 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si if is different from ; otherwise, . - .]]> + .]]> @@ -516,16 +516,16 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si property of are uniquely determined by the values of the and properties the instance. + The requirements and meaning of property of are uniquely determined by the values of the and properties the instance. - For detailed information on how use , see documentation for . + For detailed information on how use , see documentation for . ## 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. @@ -535,7 +535,7 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si - 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. @@ -627,16 +627,16 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si property of are uniquely determined by the values of the and properties the instance. + The requirements on the `System.IntPtr` reference of the property of are uniquely determined by the values of the and properties the instance. - For detailed information on how use , see documentation for . + For detailed information on how use , see documentation for . ## 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. @@ -646,7 +646,7 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si - 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. @@ -738,16 +738,16 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si property of are uniquely determined by the values of the and properties the instance. + The requirements on the `System.IntPtr` reference of the property of are uniquely determined by the values of the and properties the instance. - For detailed information on how use , see documentation for . + For detailed information on how use , see documentation for . ## 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. @@ -757,7 +757,7 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si - 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 a0b49c5a3aa..d707582f101 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/TextFragment.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/TextFragment.xml @@ -30,7 +30,7 @@ ## Remarks The Speech platform infrastructure unpacks the XML based structure of the SSML input and constructs objects. - Speech content is available through the , , and properties of a instance. + Speech content is available through the , , and properties of a instance. Speech attribute information, such as emphasis, pitch, and rate, are obtained from the object returned by the property. @@ -39,11 +39,11 @@ ## 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. - 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 @@ -169,7 +169,7 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si ## Remarks The default value of this property is `null`. - Prosody information can be obtained from the instance of returned by the property on the instance of returned by . + Prosody information can be obtained from the instance of returned by the property on the instance of returned by . ]]> @@ -216,11 +216,11 @@ 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. - 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 @@ -325,11 +325,11 @@ 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. - 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 @@ -425,20 +425,20 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si ## Remarks The default value of this property is `System.String.Empty`. - Applications are free to completely change the value of . + Applications are free to completely change the value of . - Resetting the value of will not change the value of and . + 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 + 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. + 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 diff --git a/xml/System.Speech.Synthesis.TtsEngine/TtsEngineAction.xml b/xml/System.Speech.Synthesis.TtsEngine/TtsEngineAction.xml index 9c7bc1dce89..fd0bc71a443 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/TtsEngineAction.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/TtsEngineAction.xml @@ -32,14 +32,14 @@ The value associated with a is returned by the property. - Processing of the value returned by the property is handled by a speech synthesizes implementation of the method on a class derived from . + 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 + 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. diff --git a/xml/System.Speech.Synthesis.TtsEngine/TtsEngineSsml.xml b/xml/System.Speech.Synthesis.TtsEngine/TtsEngineSsml.xml index 1d83b0a68cd..a9291829c6e 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/TtsEngineSsml.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/TtsEngineSsml.xml @@ -32,19 +32,19 @@ A properly registered implementation of can then be used as a synthesizer voice by name space based applications. - Objects inheriting from must override the following members: , , , and . + Objects inheriting from must override the following members: , , , and . - The most important member of the class to be implemented is the method. + The most important member of the class to be implemented is the method. - The method is called by the infrastructures text parser receiving: + 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. 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. + 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. - An implementer can also provide support for managing external definitions of pronunciations, or lexicons, by their implementation of and . + An implementer can also provide support for managing external definitions of pronunciations, or lexicons, by their implementation of and . ]]> @@ -121,14 +121,14 @@ ## Remarks A pronunciation lexicon is a collection of words or phrases together with their pronunciations specified using an appropriate pronunciation alphabet. - This method is typically called by the platform infrastructure in response to a based applications calling and using the synthesizer voice implemented by the current instance. + This method is typically called by the platform infrastructure in response to a based applications calling and using the synthesizer voice implemented by the current instance. The value of `mediaType` is typically a MIME specification, as the SSML specification uses MIME for media specifications. [!INCLUDE [untrusted-data-class-note](~/includes/untrusted-data-class-note.md)] ## Examples - The implementation of uses the interface passed in to load a lexicon from a resource. It then stores a `System.IO.Stream` to the lexicon in a `System.Collections.Generic.Dictionary` instance, indexed by the lexicon URI. + The implementation of uses the interface passed in to load a lexicon from a resource. It then stores a `System.IO.Stream` to the lexicon in a `System.Collections.Generic.Dictionary` instance, indexed by the lexicon URI. ``` public static Dictionary _aLexicons = new Dictionary(); @@ -276,12 +276,12 @@ internal struct WaveFormat { ## Remarks A pronunciation lexicon is a collection of words or phrases together with their pronunciations specified using an appropriate pronunciation alphabet. - This method is typically called in response to a based applications calling and using the synthesizer voice implemented by the current instance. + This method is typically called in response to a based applications calling and using the synthesizer voice implemented by the current instance. [!INCLUDE [untrusted-data-class-note](~/includes/untrusted-data-class-note.md)] ## Examples - The implementation of uses the lexicon URI to query an instance `System.Collections.Generic.Dictionary` for the `System.IO.Stream`, closes the stream and removes the uri referring to the lexicon. + The implementation of uses the lexicon URI to query an instance `System.Collections.Generic.Dictionary` for the `System.IO.Stream`, closes the stream and removes the uri referring to the lexicon. ``` public static Dictionary _aLexicons = new Dictionary(); @@ -360,7 +360,7 @@ 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. diff --git a/xml/System.Speech.Synthesis.TtsEngine/TtsEventId.xml b/xml/System.Speech.Synthesis.TtsEngine/TtsEventId.xml index d3c8ec99c8d..6f11db18a3b 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/TtsEventId.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/TtsEventId.xml @@ -29,22 +29,22 @@ ## Remarks Custom speech synthesis engines define the types of events submitted to the Speech platform synthesizer infrastructure with the . - Specification is performed by setting the property of instances passed to the member of the class implementing the interface passed to the method on a custom speech engine's implementation of . + Specification is performed by setting the property of instances passed to the member of the class implementing the interface passed to the method on a custom speech engine's implementation of . The Speech platform infrastructure indicates the type of events it is currently handling through the property on the passed to the speak implementation. - 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. + 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: + 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. -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. diff --git a/xml/System.Speech.Synthesis/BookmarkReachedEventArgs.xml b/xml/System.Speech.Synthesis/BookmarkReachedEventArgs.xml index 1cfb96c63a9..8bb92da2bb0 100644 --- a/xml/System.Speech.Synthesis/BookmarkReachedEventArgs.xml +++ b/xml/System.Speech.Synthesis/BookmarkReachedEventArgs.xml @@ -25,73 +25,73 @@ Returns data from the event. - is created when the object raises the event. The raises the event when it encounters a bookmark while processing any of the , , , or methods. To obtain the name and location of the bookmark that triggered the event, access the and the properties in the handler for the event. - - - -## Examples - The following example creates a prompt that includes two bookmarks and sends the output to a WAV file for playback. The handler for the event writes the name of the bookmark and its position in the audio stream when the event was raised to the console. - -``` -using System; -using System.Speech.Synthesis; - -namespace SampleSynthesis -{ - class Program - { - static void Main(string[] args) - { - - // Initialize a new instance of the SpeechSynthesizer. - using (SpeechSynthesizer synth = new SpeechSynthesizer()) - { - - // Configure the audio output. - synth.SetOutputToWaveFile(@"C:\test\weather.wav"); - - // Create a SoundPlayer instance to play the output audio file. - System.Media.SoundPlayer m_SoundPlayer = - new System.Media.SoundPlayer(@"C:\test\weather.wav"); - - // Build a prompt and append bookmarks. - PromptBuilder builder = new PromptBuilder( - new System.Globalization.CultureInfo("en-US")); - builder.AppendText( - "The weather forecast for today is partly cloudy with some sun breaks."); - builder.AppendBookmark("Daytime forecast"); - builder.AppendText( - "Tonight's weather will be cloudy with a 30% chance of showers."); - builder.AppendBookmark("Nighttime forecast"); - - // Add a handler for the BookmarkReached event. - synth.BookmarkReached += - new EventHandler(synth_BookmarkReached); - - // Speak the prompt and play back the output file. - synth.Speak(builder); - m_SoundPlayer.Play(); - } - - Console.WriteLine(); - Console.WriteLine("Press any key to exit..."); - Console.ReadKey(); - } - - // Write the name and position of the bookmark to the console. - static void synth_BookmarkReached(object sender, BookmarkReachedEventArgs e) - { - Console.WriteLine("Bookmark ({0}) reached at: {1} ", - e.Bookmark, e.AudioPosition); - } - } -} - -``` - + is created when the object raises the event. The raises the event when it encounters a bookmark while processing any of the , , , or methods. To obtain the name and location of the bookmark that triggered the event, access the and the properties in the handler for the event. + + + +## Examples + The following example creates a prompt that includes two bookmarks and sends the output to a WAV file for playback. The handler for the event writes the name of the bookmark and its position in the audio stream when the event was raised to the console. + +``` +using System; +using System.Speech.Synthesis; + +namespace SampleSynthesis +{ + class Program + { + static void Main(string[] args) + { + + // Initialize a new instance of the SpeechSynthesizer. + using (SpeechSynthesizer synth = new SpeechSynthesizer()) + { + + // Configure the audio output. + synth.SetOutputToWaveFile(@"C:\test\weather.wav"); + + // Create a SoundPlayer instance to play the output audio file. + System.Media.SoundPlayer m_SoundPlayer = + new System.Media.SoundPlayer(@"C:\test\weather.wav"); + + // Build a prompt and append bookmarks. + PromptBuilder builder = new PromptBuilder( + new System.Globalization.CultureInfo("en-US")); + builder.AppendText( + "The weather forecast for today is partly cloudy with some sun breaks."); + builder.AppendBookmark("Daytime forecast"); + builder.AppendText( + "Tonight's weather will be cloudy with a 30% chance of showers."); + builder.AppendBookmark("Nighttime forecast"); + + // Add a handler for the BookmarkReached event. + synth.BookmarkReached += + new EventHandler(synth_BookmarkReached); + + // Speak the prompt and play back the output file. + synth.Speak(builder); + m_SoundPlayer.Play(); + } + + Console.WriteLine(); + Console.WriteLine("Press any key to exit..."); + Console.ReadKey(); + } + + // Write the name and position of the bookmark to the console. + static void synth_BookmarkReached(object sender, BookmarkReachedEventArgs e) + { + Console.WriteLine("Bookmark ({0}) reached at: {1} ", + e.Bookmark, e.AudioPosition); + } + } +} + +``` + ]]> diff --git a/xml/System.Speech.Synthesis/FilePrompt.xml b/xml/System.Speech.Synthesis/FilePrompt.xml index 1e5aaf488ca..d4933817966 100644 --- a/xml/System.Speech.Synthesis/FilePrompt.xml +++ b/xml/System.Speech.Synthesis/FilePrompt.xml @@ -65,63 +65,63 @@ The media type of the file. Creates a new instance of the class, and specifies the path to the file and its media type. - can consume to generate speech. - + can consume to generate speech. + [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] - -## Examples - The example that follows creates a object that specifies a path to an SSML prompt. To speak the contents of the prompt, the example then provides the object as the argument to the method. - -```csharp -using System; -using System.Speech.Synthesis; - -namespace SampleSynthesis -{ - class Program - { - static void Main(string[] args) - { - - // Initialize a new instance of the SpeechSynthesizer. - using (SpeechSynthesizer synth = new SpeechSynthesizer()) - { - - // Configure the audio output. - synth.SetOutputToDefaultAudioDevice(); - - // Create a FilePrompt object that references an SSML prompt. - FilePrompt ssmlFile = new FilePrompt("c:\\test\\Weather.ssml", SynthesisMediaType.Ssml); - - // Speak the contents of the SSML prompt. - synth.Speak(ssmlFile); - } - - Console.WriteLine(); - Console.WriteLine("Press any key to exit..."); - Console.ReadKey(); - } - } -} -``` - - The following is the SSML file that the preceding example references. - -```xml - - - - The weather forecast for today is partly cloudy with some sun breaks. - - -``` - + +## Examples + The example that follows creates a object that specifies a path to an SSML prompt. To speak the contents of the prompt, the example then provides the object as the argument to the method. + +```csharp +using System; +using System.Speech.Synthesis; + +namespace SampleSynthesis +{ + class Program + { + static void Main(string[] args) + { + + // Initialize a new instance of the SpeechSynthesizer. + using (SpeechSynthesizer synth = new SpeechSynthesizer()) + { + + // Configure the audio output. + synth.SetOutputToDefaultAudioDevice(); + + // Create a FilePrompt object that references an SSML prompt. + FilePrompt ssmlFile = new FilePrompt("c:\\test\\Weather.ssml", SynthesisMediaType.Ssml); + + // Speak the contents of the SSML prompt. + synth.Speak(ssmlFile); + } + + Console.WriteLine(); + Console.WriteLine("Press any key to exit..."); + Console.ReadKey(); + } + } +} +``` + + The following is the SSML file that the preceding example references. + +```xml + + + + The weather forecast for today is partly cloudy with some sun breaks. + + +``` + ]]> diff --git a/xml/System.Speech.Synthesis/InstalledVoice.xml b/xml/System.Speech.Synthesis/InstalledVoice.xml index d3835ac1366..9414d99bed3 100644 --- a/xml/System.Speech.Synthesis/InstalledVoice.xml +++ b/xml/System.Speech.Synthesis/InstalledVoice.xml @@ -151,7 +151,7 @@ namespace SampleSynthesis property is `true` by default. When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `false`. An application cannot select a voice whose property is `false`. Typically, applications will not set a voice's property. + The value of the property is `true` by default. When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `false`. An application cannot select a voice whose property is `false`. Typically, applications will not set a voice's property. ]]> diff --git a/xml/System.Speech.Synthesis/Prompt.xml b/xml/System.Speech.Synthesis/Prompt.xml index 5d8e95d7870..e3e93d55173 100644 --- a/xml/System.Speech.Synthesis/Prompt.xml +++ b/xml/System.Speech.Synthesis/Prompt.xml @@ -31,15 +31,15 @@ Represents information about what can be rendered, either text or an audio file, by the . - object can contain plain text, text formatted with markup language, or audio files. - - An empty object is created with each new instance of . The class provides methods for adding content, including text, SSML markup, bookmarks, and prerecorded audio files (such as .wav files), to the empty object that it contains. Typically, applications will use , rather than a object, to create prompts and populate them with content. - - To generate speech from the contents of a object, use the method. - + object can contain plain text, text formatted with markup language, or audio files. + + An empty object is created with each new instance of . The class provides methods for adding content, including text, SSML markup, bookmarks, and prerecorded audio files (such as .wav files), to the empty object that it contains. Typically, applications will use , rather than a object, to create prompts and populate them with content. + + To generate speech from the contents of a object, use the method. + ]]> @@ -103,44 +103,44 @@ The text to be spoken. Creates a new instance of the class and specifies the text to be spoken. - object from a string and passes the object as an argument to the method. - -```csharp -using System; -using System.Speech.Synthesis; - -namespace SampleSynthesis -{ - class Program - { - static void Main(string[] args) - { - - // Initialize a new instance of the SpeechSynthesizer. - using (SpeechSynthesizer synth = new SpeechSynthesizer()) - { - - // Configure the audio output. - synth.SetOutputToDefaultAudioDevice(); - - // Create a prompt from a string. - Prompt color = new Prompt("What is your favorite color?"); - - // Speak the contents of the prompt synchronously. - synth.Speak(color); - } - - Console.WriteLine(); - Console.WriteLine("Press any key to exit..."); - Console.ReadKey(); - } - } -} -``` - + object from a string and passes the object as an argument to the method. + +```csharp +using System; +using System.Speech.Synthesis; + +namespace SampleSynthesis +{ + class Program + { + static void Main(string[] args) + { + + // Initialize a new instance of the SpeechSynthesizer. + using (SpeechSynthesizer synth = new SpeechSynthesizer()) + { + + // Configure the audio output. + synth.SetOutputToDefaultAudioDevice(); + + // Create a prompt from a string. + Prompt color = new Prompt("What is your favorite color?"); + + // Speak the contents of the prompt synchronously. + synth.Speak(color); + } + + Console.WriteLine(); + Console.WriteLine("Press any key to exit..."); + Console.ReadKey(); + } + } +} +``` + ]]> @@ -168,57 +168,57 @@ namespace SampleSynthesis A value that specifies the format of the text. Creates a new instance of the class and specifies the text to be spoken and whether its format is plain text or markup language. - object from the string, and speaks the prompt. - -```csharp -using System; -using System.Speech.Synthesis; - -namespace SampleSynthesis -{ - class Program - { - static void Main(string[] args) - { - - // Initialize a new instance of the SpeechSynthesizer. - using (SpeechSynthesizer synth = new SpeechSynthesizer()) - { - - // Configure the audio output. - synth.SetOutputToDefaultAudioDevice(); - - // Build an SSML prompt in a string. - string fileName = ""; - fileName += "Say a name for the new file ."; - fileName += ""; - - // Create a Prompt object from the string. - Prompt ssmlFile = new Prompt(fileName, SynthesisTextFormat.Ssml); - - // Speak the contents of the SSML prompt. - synth.Speak(ssmlFile); - } - - Console.WriteLine(); - Console.WriteLine("Press any key to exit..."); - Console.ReadKey(); - } - } -} - -``` - + object from the string, and speaks the prompt. + +```csharp +using System; +using System.Speech.Synthesis; + +namespace SampleSynthesis +{ + class Program + { + static void Main(string[] args) + { + + // Initialize a new instance of the SpeechSynthesizer. + using (SpeechSynthesizer synth = new SpeechSynthesizer()) + { + + // Configure the audio output. + synth.SetOutputToDefaultAudioDevice(); + + // Build an SSML prompt in a string. + string fileName = ""; + fileName += "Say a name for the new file ."; + fileName += ""; + + // Create a Prompt object from the string. + Prompt ssmlFile = new Prompt(fileName, SynthesisTextFormat.Ssml); + + // Speak the contents of the SSML prompt. + synth.Speak(ssmlFile); + } + + Console.WriteLine(); + Console.WriteLine("Press any key to exit..."); + Console.ReadKey(); + } + } +} + +``` + ]]> diff --git a/xml/System.Speech.Synthesis/PromptBuilder.xml b/xml/System.Speech.Synthesis/PromptBuilder.xml index d086263a914..8714d275633 100644 --- a/xml/System.Speech.Synthesis/PromptBuilder.xml +++ b/xml/System.Speech.Synthesis/PromptBuilder.xml @@ -37,13 +37,13 @@ ## Remarks With , you can add a variety of content types to a prompt, including plain text, SSML markup (as a string or a file), recorded audio, or even another object. - To append text to a object and optionally control voice attributes such as emphasis, rate, and volume, use one of the methods. You can also control voice attributes as a group with the and methods. + To append text to a object and optionally control voice attributes such as emphasis, rate, and volume, use one of the methods. You can also control voice attributes as a group with the and methods. - You can append text and control what is spoken or how it is pronounced using the , , , , or methods. + You can append text and control what is spoken or how it is pronounced using the , , , , or methods. - Change the currently selected speaking voice in the prompt using one of the overloaded methods, naming a specific voice to use or specifying required voice characteristics, such as age and gender. + Change the currently selected speaking voice in the prompt using one of the overloaded methods, naming a specific voice to use or specifying required voice characteristics, such as age and gender. - To generate speech from a object, you can pass it as an argument to the method. + To generate speech from a object, you can pass it as an argument to the method. For more information, see [Constructing a Complex Prompt](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh361616(v%3doffice.14)). @@ -131,7 +131,7 @@ public void MySimpleText () ## Remarks This constructor sets the value for the property. The object will attempt to select an installed voice that supports the language specified by the `culture` parameter to process the prompt. If a voice with the specified culture is found, it will be used. If a voice with the specified culture cannot be found, the default voice will be used. - To correctly pronounce words in the language specified by the `culture` parameter, a speech synthesis (text-to-speech or TTS) engine that supports the language must be installed. An installed TTS engine is called a voice. To get information about which voices are installed for a specific culture, use the method. + To correctly pronounce words in the language specified by the `culture` parameter, a speech synthesis (text-to-speech or TTS) engine that supports the language must be installed. An installed TTS engine is called a voice. To get information about which voices are installed for a specific culture, use the method. Microsoft Windows and the System.Speech API accept all valid language-country codes as values for `culture`. The TTS engines that shipped with Windows 7 support the following language-country codes: @@ -146,7 +146,7 @@ public void MySimpleText () ## Examples - The example that follows creates a instance and specifies its . + The example that follows creates a instance and specifies its . ```csharp using System.Speech.Synthesis; @@ -362,7 +362,7 @@ public void SimpleConcatenation() event if it encounters a bookmark while speaking a prompt using any of the , , , or methods. + A speech synthesis engine will generate a event if it encounters a bookmark while speaking a prompt using any of the , , , or methods. @@ -796,12 +796,12 @@ namespace SampleSynthesis ## Remarks The SSML file must be an XML-format file that conforms to the [Speech Synthesis Markup Language (SSML) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201763) specification. - You can also append SSML markup as a string using . + You can also append SSML markup as a string using . ## Examples - The example that follows creates a object and appends the contents of an SSML file using the method. + The example that follows creates a object and appends the contents of an SSML file using the method. ```csharp using System; @@ -884,13 +884,13 @@ namespace SampleSynthesis ## Remarks The SSML file must be an XML-format file that conforms to the [Speech Synthesis Markup Language (SSML) Version 1.0](https://www.w3.org/TR/speech-synthesis/) specification. - You can also append SSML markup as a string using . + You can also append SSML markup as a string using . [!INCLUDE [untrusted-data-class-note](~/includes/untrusted-data-class-note.md)] ## Examples - The example that follows creates a object and appends the contents of an SSML file using the method. + The example that follows creates a object and appends the contents of an SSML file using the method. ```csharp using System; @@ -974,7 +974,7 @@ namespace SampleSynthesis ## Remarks The SSML file must be an XML-format file that conforms to the [Speech Synthesis Markup Language (SSML) Version 1.0](https://www.w3.org/TR/speech-synthesis/) specification. - You can also append SSML markup as a string using . + You can also append SSML markup as a string using . @@ -1081,9 +1081,9 @@ builder.AppendSsmlMarkup(" chair ``` > [!NOTE] -> The string used as an argument to cannot include a `speak` element. +> The string used as an argument to cannot include a `speak` element. - When using to specify inline pronunciations in a `phoneme` element, you can use phones from any of the following phonetic alphabets, provided that the current speech engine supports it: + When using to specify inline pronunciations in a `phoneme` element, you can use phones from any of the following phonetic alphabets, provided that the current speech engine supports it: - International Phonetic Alphabet (IPA) @@ -1093,7 +1093,7 @@ builder.AppendSsmlMarkup(" chair Any SSML-compliant speech engine will speak phones from the IPA. - You can also append a file containing SSML markup using one of the methods. To append text to be spoken that is not formatted with markup language, use one of the , , , or methods. + You can also append a file containing SSML markup using one of the methods. To append text to be spoken that is not formatted with markup language, use one of the , , , or methods. ]]> @@ -1135,12 +1135,12 @@ builder.AppendSsmlMarkup(" chair . + To append text that is formatted as SSML markup language, use . ## Examples - The example that follows creates a object and appends a text string using the method. + The example that follows creates a object and appends a text string using the method. ```csharp using System; @@ -1244,7 +1244,7 @@ namespace SampleSynthesis object and appends text strings. The example uses the method to specify a slow speaking rate for the string being added, which enumerates the contents of an order. + The following example creates a object and appends text strings. The example uses the method to specify a slow speaking rate for the string being added, which enumerates the contents of an order. ```csharp using System; @@ -1321,7 +1321,7 @@ namespace SampleSynthesis ## Examples - The following example uses the method to specify volume settings that the should apply to speech output. + The following example uses the method to specify volume settings that the should apply to speech output. ```csharp using System; @@ -1568,13 +1568,13 @@ namespace SampleSynthesis Pronunciations specified inline in prompts apply only to the individual occurrence of a word and override pronunciations of the speech engine or any of its currently active lexicons. Typically, you will use inline pronunciations for custom pronunciations of existing words or for pronunciation of uncommon words, such as proper names, which the speech synthesis engine may not pronounce as well as expected. - Inline pronunciations must be specified using phones from the International Phonetic Alphabet (IPA). A phone is a letter or character that represents a discreet sound of speech. Speech engines that comply with the [Speech Synthesis Markup Language (SSML) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201763) specification will pronounce phones from the IPA. To specify inline pronunciations using other phonetic alphabets, see . + Inline pronunciations must be specified using phones from the International Phonetic Alphabet (IPA). A phone is a letter or character that represents a discreet sound of speech. Speech engines that comply with the [Speech Synthesis Markup Language (SSML) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201763) specification will pronounce phones from the IPA. To specify inline pronunciations using other phonetic alphabets, see . The IPA publishes a [chart](https://www.phon.ucl.ac.uk/home/wells/ipa-unicode.htm) that lists its phones and maps them to Unicode numbers. Some phones in the IPA alphabet have the same representations as letters in the Latin alphabet. In those cases, it is possible to type the Latin character and have the proper representation for a phone. Because the Latin characters as commonly used in text may represent several phones of the IPA phone set, simply typing the Latin character might not result in the precise IPA phone desired. Other phones of the IPA alphabet need to be represented in code as character references consisting of an ampersand (&), the number sign (#), and a Unicode number for the desired phone in hexadecimal or decimal, all followed by a semicolon (;). For example, a schwa (&\#x0259;) would be represented by `ə`. - To add new or custom pronunciations for multiple words, for example to express regional dialects or to add proper names or vocabulary that is specific to an educational or medical discipline, build a lexicon and add it to the using . + To add new or custom pronunciations for multiple words, for example to express regional dialects or to add proper names or vocabulary that is specific to an educational or medical discipline, build a lexicon and add it to the using . @@ -1660,9 +1660,9 @@ public void ProperName() ## Remarks The object will attempt to select an installed voice that supports the language specified by the property to process the prompt. If a voice with the specified culture is found, it will be used. If a voice with the specified culture cannot be found, the default voice will be used. - A culture may also be specified within the prompt for discreet sections of content using the , , and methods. A culture specified for a portion of content using one of the above methods will override the property while in effect, and the will attempt to select an installed voice that supports the language specified by the `culture` parameter of the method. + A culture may also be specified within the prompt for discreet sections of content using the , , and methods. A culture specified for a portion of content using one of the above methods will override the property while in effect, and the will attempt to select an installed voice that supports the language specified by the `culture` parameter of the method. - To correctly pronounce words in the language specified by the property, a speech synthesis (text-to-speech or TTS) engine that supports the language must be installed. An installed TTS engine is called a voice. To get information about which voices are installed for a specific culture, use the method. + To correctly pronounce words in the language specified by the property, a speech synthesis (text-to-speech or TTS) engine that supports the language must be installed. An installed TTS engine is called a voice. To get information about which voices are installed for a specific culture, use the method. Microsoft Windows and the System.Speech API accept all valid language-country codes as values for `culture`. The TTS engines that shipped with Windows 7 support the following language-country codes: @@ -1702,7 +1702,7 @@ public void ProperName() for an example. + Long prompts can be rendered more like human speech if they are broken into sentences and paragraphs. See for an example. ]]> @@ -1732,7 +1732,7 @@ public void ProperName() for an example. + Long prompts can be rendered more like human speech if they are broken into sentences and paragraphs. See for an example. ]]> @@ -1762,7 +1762,7 @@ public void ProperName() method stops the current speaking style. The speaking style reverts to the setting that was in effect before the method initiated a new speaking style. See for an example. + The method stops the current speaking style. The speaking style reverts to the setting that was in effect before the method initiated a new speaking style. See for an example. ]]> @@ -1792,7 +1792,7 @@ public void ProperName() method stops the use of the current voice for speech output. The voice reverts to the setting that was in effect before the method initiated a new voice. + The method stops the use of the current voice for speech output. The voice reverts to the setting that was in effect before the method initiated a new voice. ]]> @@ -1954,9 +1954,9 @@ namespace SampleSynthesis ## Remarks Long prompts can be rendered more like human speech if they are broken into sentences and paragraphs. - The `culture` parameter for a paragraph can be different than the property of the object that contains it. While in effect, the value of the `culture` parameter will override the property. The will attempt to select an installed voice that supports the language specified by the `culture` parameter to speak the paragraph. If a voice with the specified culture is found, it will be used. If a voice with the specified culture cannot be found, the default voice will be used. To stop using the voice specified by , call . + The `culture` parameter for a paragraph can be different than the property of the object that contains it. While in effect, the value of the `culture` parameter will override the property. The will attempt to select an installed voice that supports the language specified by the `culture` parameter to speak the paragraph. If a voice with the specified culture is found, it will be used. If a voice with the specified culture cannot be found, the default voice will be used. To stop using the voice specified by , call . - To correctly pronounce words in the language specified by the `culture` parameter, a speech synthesis (text-to-speech or TTS) engine that supports the language must be installed. An installed TTS engine is called a voice. To get information about which voices are installed for a specific culture, use the method. + To correctly pronounce words in the language specified by the `culture` parameter, a speech synthesis (text-to-speech or TTS) engine that supports the language must be installed. An installed TTS engine is called a voice. To get information about which voices are installed for a specific culture, use the method. Microsoft Windows and the System.Speech API accept all valid language-country codes as values for `culture`. The TTS engines that shipped with Windows 7 support the following language-country codes: @@ -2107,9 +2107,9 @@ namespace SampleSynthesis The `culture` parameter for a sentence can be different than the `culture` parameter for the paragraph that contains the sentence or the property of the object that contains them. - While in effect, the value of the `culture` parameter will override the property and the `culture` parameter for the paragraph that contains the sentence. The will attempt to select an installed voice that supports the language specified by the `culture` parameter to speak the sentence. If a voice with the specified culture is found, it will be used. If a voice with the specified culture cannot be found, the default voice will be used. To stop using the voice specified by , call . + While in effect, the value of the `culture` parameter will override the property and the `culture` parameter for the paragraph that contains the sentence. The will attempt to select an installed voice that supports the language specified by the `culture` parameter to speak the sentence. If a voice with the specified culture is found, it will be used. If a voice with the specified culture cannot be found, the default voice will be used. To stop using the voice specified by , call . - To correctly pronounce words in the language specified by the `culture` parameter, a speech synthesis (text-to-speech or TTS) engine that supports the language must be installed. An installed TTS engine is called a voice. To get information about which voices are installed for a specific culture, use the method. + To correctly pronounce words in the language specified by the `culture` parameter, a speech synthesis (text-to-speech or TTS) engine that supports the language must be installed. An installed TTS engine is called a voice. To get information about which voices are installed for a specific culture, use the method. Microsoft Windows and the System.Speech API accept all valid language-country codes as values for `culture`. The TTS engines that shipped with Windows 7 support the following language-country codes: @@ -2152,7 +2152,7 @@ namespace SampleSynthesis method takes a object as its argument. You can use the properties of the object to set the emphasis, speaking rate, and volume (loudness) to apply to speech output while the style is in effect. To stop using the current style, call the method. + The method takes a object as its argument. You can use the properties of the object to set the emphasis, speaking rate, and volume (loudness) to apply to speech output while the style is in effect. To stop using the current style, call the method. > [!NOTE] > - The speech synthesis engines in Windows do not support the emphasis parameter at this time. Setting values for the emphasis parameter will produce no audible change in the synthesized speech output. @@ -2161,7 +2161,7 @@ namespace SampleSynthesis ## Examples - The following example creates a object and appends text strings. The example uses the method to specify a slow speaking rate for the string being added, which enumerates the contents of an order. + The following example creates a object and appends text strings. The example uses the method to specify a slow speaking rate for the string being added, which enumerates the contents of an order. ```csharp using System; @@ -2216,9 +2216,9 @@ namespace SampleSynthesis methods and class to obtain the names and attributes of installed text-to-speech (TTS) voices that you can select. + A voice represents an installed TTS engine. Use the methods and class to obtain the names and attributes of installed text-to-speech (TTS) voices that you can select. - When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot call any of the methods on a voice whose property is `False`. Typically, applications will not set a voice's property. + When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot call any of the methods on a voice whose property is `False`. Typically, applications will not set a voice's property. ]]> @@ -2251,9 +2251,9 @@ namespace SampleSynthesis can be different than the property of the object that contains it. While in effect, the value of the `culture` parameter will override the property. The will attempt to select an installed voice that supports the language specified by the `culture` parameter to speak the content enclosed by and . If a voice with the specified culture is found, it will be used. If a voice with the specified culture cannot be found, the default voice will be used. To stop using the voice specified by , call . + The `culture` parameter for can be different than the property of the object that contains it. While in effect, the value of the `culture` parameter will override the property. The will attempt to select an installed voice that supports the language specified by the `culture` parameter to speak the content enclosed by and . If a voice with the specified culture is found, it will be used. If a voice with the specified culture cannot be found, the default voice will be used. To stop using the voice specified by , call . - To correctly pronounce words in the language specified by the `culture` parameter, a speech synthesis (text-to-speech or TTS) engine that supports the language must be installed. An installed TTS engine is called a voice. To get information about which voices are installed for a specific culture, use the method. + To correctly pronounce words in the language specified by the `culture` parameter, a speech synthesis (text-to-speech or TTS) engine that supports the language must be installed. An installed TTS engine is called a voice. To get information about which voices are installed for a specific culture, use the method. Microsoft Windows and the System.Speech API accept all valid language-country codes as values for `culture`. The TTS engines that shipped with Windows 7 support the following language-country codes: @@ -2296,9 +2296,9 @@ namespace SampleSynthesis methods and class to obtain the names and attributes of installed text-to-speech (TTS) voices that you can select. + Use the methods and class to obtain the names and attributes of installed text-to-speech (TTS) voices that you can select. - To stop using the voice specified by call . + To stop using the voice specified by call . ]]> @@ -2331,9 +2331,9 @@ namespace SampleSynthesis methods and class to obtain the names and attributes of installed text-to-speech (TTS) voices that you can select. + Use the methods and class to obtain the names and attributes of installed text-to-speech (TTS) voices that you can select. - To stop using the voice specified by call . + To stop using the voice specified by call . ]]> @@ -2366,9 +2366,9 @@ namespace SampleSynthesis methods. + To get information about which voices are installed, use one of the methods. - To stop using the voice specified by call . + To stop using the voice specified by call . ]]> @@ -2403,9 +2403,9 @@ namespace SampleSynthesis methods and class to obtain the names and attributes of installed text-to-speech (TTS) voices that you can select. + Use the methods and class to obtain the names and attributes of installed text-to-speech (TTS) voices that you can select. - To stop using the voice specified by call . + To stop using the voice specified by call . ]]> @@ -2444,9 +2444,9 @@ namespace SampleSynthesis ## Remarks A speech synthesis engine counts the matches it finds for the specified parameters, and returns the voice when the count equals the `voiceAlternate` parameter. - Use the methods and class to obtain the names and attributes of installed text-to-speech (TTS) voices that you can select. + Use the methods and class to obtain the names and attributes of installed text-to-speech (TTS) voices that you can select. - To stop using the voice specified by call . + To stop using the voice specified by call . ]]> @@ -2478,7 +2478,7 @@ namespace SampleSynthesis method makes no attempt to format the returned SSML in any way. + The method makes no attempt to format the returned SSML in any way. diff --git a/xml/System.Speech.Synthesis/PromptEmphasis.xml b/xml/System.Speech.Synthesis/PromptEmphasis.xml index 71de61936c5..ea5f053d79e 100644 --- a/xml/System.Speech.Synthesis/PromptEmphasis.xml +++ b/xml/System.Speech.Synthesis/PromptEmphasis.xml @@ -27,7 +27,7 @@ enumeration are used by the constructor, by the method, and by the method to specify the level of emphasis for spoken text. The property gets the emphasis for a object using a instance. + Members of the enumeration are used by the constructor, by the method, and by the method to specify the level of emphasis for spoken text. The property gets the emphasis for a object using a instance. > [!NOTE] > The speech synthesis engines in Windows do not support variations in the emphasis of speech output at this time. Setting values for emphasis using a member of the enumeration will produce no audible change in the synthesized speech output. diff --git a/xml/System.Speech.Synthesis/PromptRate.xml b/xml/System.Speech.Synthesis/PromptRate.xml index 6844ec6a187..1e6d0e9b5a2 100644 --- a/xml/System.Speech.Synthesis/PromptRate.xml +++ b/xml/System.Speech.Synthesis/PromptRate.xml @@ -27,7 +27,7 @@ enumeration are used by the constructor, by the method, and by the method to specify the rate of speech for spoken text. The property gets the rate for a object using a instance. + Members of the enumeration are used by the constructor, by the method, and by the method to specify the rate of speech for spoken text. The property gets the rate for a object using a instance. ]]> diff --git a/xml/System.Speech.Synthesis/PromptStyle.xml b/xml/System.Speech.Synthesis/PromptStyle.xml index 4d23f81f6f3..c5b5c954b08 100644 --- a/xml/System.Speech.Synthesis/PromptStyle.xml +++ b/xml/System.Speech.Synthesis/PromptStyle.xml @@ -89,11 +89,11 @@ The setting for the emphasis of the style. Initializes a new instance of the class and specifies the setting for the emphasis of the style. - enumeration will produce no audible change in the synthesized speech output. - + enumeration will produce no audible change in the synthesized speech output. + ]]> @@ -119,49 +119,49 @@ The setting for the speaking rate of the style. Initializes a new instance of the class and specifies the setting for the speaking rate of the style. - object and appends text strings. The example uses the constructor as an argument to the method to specify a slow speaking rate for the string being added, which enumerates the contents of an order. - -```csharp -using System; -using System.Speech.Synthesis; - -namespace SampleSynthesis -{ - class Program - { - static void Main(string[] args) - { - - // Initialize a new instance of the SpeechSynthesizer. - using (SpeechSynthesizer synth = new SpeechSynthesizer()) - { - - // Configure the audio output. - synth.SetOutputToDefaultAudioDevice(); - - // Create a PromptBuilder object and add content. - PromptBuilder style = new PromptBuilder(); - style.AppendText("Your order for"); - style.StartStyle(new PromptStyle(PromptRate.Slow)); - style.AppendText("one kitchen sink and one faucet"); - style.EndStyle(); - style.AppendText("has been confirmed."); - - // Speak the contents of the SSML prompt. - synth.Speak(style); - } - - Console.WriteLine(); - Console.WriteLine("Press any key to exit..."); - Console.ReadKey(); - } - } -} -``` - + object and appends text strings. The example uses the constructor as an argument to the method to specify a slow speaking rate for the string being added, which enumerates the contents of an order. + +```csharp +using System; +using System.Speech.Synthesis; + +namespace SampleSynthesis +{ + class Program + { + static void Main(string[] args) + { + + // Initialize a new instance of the SpeechSynthesizer. + using (SpeechSynthesizer synth = new SpeechSynthesizer()) + { + + // Configure the audio output. + synth.SetOutputToDefaultAudioDevice(); + + // Create a PromptBuilder object and add content. + PromptBuilder style = new PromptBuilder(); + style.AppendText("Your order for"); + style.StartStyle(new PromptStyle(PromptRate.Slow)); + style.AppendText("one kitchen sink and one faucet"); + style.EndStyle(); + style.AppendText("has been confirmed."); + + // Speak the contents of the SSML prompt. + synth.Speak(style); + } + + Console.WriteLine(); + Console.WriteLine("Press any key to exit..."); + Console.ReadKey(); + } + } +} +``` + ]]> @@ -187,61 +187,61 @@ namespace SampleSynthesis The setting for the volume (loudness) of the style. Initializes a new instance of the class and specifies the setting for the speaking volume of the style. - setting for is full volume, which is the same as . The other settings decrease the volume of speech output relative to full volume. - - - -## Examples - The following example uses the constructor to specify volume settings that the should apply to speech output. - -```csharp -using System; -using System.Speech.Synthesis; - -namespace SampleSynthesis -{ - class Program - { - static void Main(string[] args) - { - - // Initialize a new instance of the SpeechSynthesizer. - using (SpeechSynthesizer synth = new SpeechSynthesizer()) - { - - // Configure the audio output. - synth.SetOutputToDefaultAudioDevice(); - - // Build a prompt that applies different volume settings. - PromptBuilder builder = new PromptBuilder(); - builder.StartStyle(new PromptStyle(PromptVolume.Default)); - builder.AppendText("This is the default speaking volume."); - builder.EndStyle(); - builder.AppendBreak(); - builder.StartStyle(new PromptStyle(PromptVolume.ExtraLoud)); - builder.AppendText("This is the extra-loud speaking volume."); - builder.EndStyle(); - builder.AppendBreak(); - builder.StartStyle(new PromptStyle(PromptVolume.Medium)); - builder.AppendText("This is the medium speaking volume."); - builder.EndStyle(); - - // Speak the prompt. - synth.Speak(builder); - } - - Console.WriteLine(); - Console.WriteLine("Press any key to exit..."); - Console.ReadKey(); - } - } -} - -``` - + setting for is full volume, which is the same as . The other settings decrease the volume of speech output relative to full volume. + + + +## Examples + The following example uses the constructor to specify volume settings that the should apply to speech output. + +```csharp +using System; +using System.Speech.Synthesis; + +namespace SampleSynthesis +{ + class Program + { + static void Main(string[] args) + { + + // Initialize a new instance of the SpeechSynthesizer. + using (SpeechSynthesizer synth = new SpeechSynthesizer()) + { + + // Configure the audio output. + synth.SetOutputToDefaultAudioDevice(); + + // Build a prompt that applies different volume settings. + PromptBuilder builder = new PromptBuilder(); + builder.StartStyle(new PromptStyle(PromptVolume.Default)); + builder.AppendText("This is the default speaking volume."); + builder.EndStyle(); + builder.AppendBreak(); + builder.StartStyle(new PromptStyle(PromptVolume.ExtraLoud)); + builder.AppendText("This is the extra-loud speaking volume."); + builder.EndStyle(); + builder.AppendBreak(); + builder.StartStyle(new PromptStyle(PromptVolume.Medium)); + builder.AppendText("This is the medium speaking volume."); + builder.EndStyle(); + + // Speak the prompt. + synth.Speak(builder); + } + + Console.WriteLine(); + Console.WriteLine("Press any key to exit..."); + Console.ReadKey(); + } + } +} + +``` + ]]> @@ -278,11 +278,11 @@ namespace SampleSynthesis Gets or sets the setting for the emphasis of the style. Returns the setting for the emphasis of the style. - enumeration will produce no audible change in the synthesized speech output. - + enumeration will produce no audible change in the synthesized speech output. + ]]> @@ -351,11 +351,11 @@ namespace SampleSynthesis Gets or sets the setting for the volume (loudness) of the style. Returns the setting for the volume (loudness) of the style. - setting for is full volume, which is the same as . The other settings decrease the volume of speech output relative to full volume. - + setting for is full volume, which is the same as . The other settings decrease the volume of speech output relative to full volume. + ]]> diff --git a/xml/System.Speech.Synthesis/PromptVolume.xml b/xml/System.Speech.Synthesis/PromptVolume.xml index da29c5561a4..b47daf23979 100644 --- a/xml/System.Speech.Synthesis/PromptVolume.xml +++ b/xml/System.Speech.Synthesis/PromptVolume.xml @@ -27,7 +27,7 @@ enumeration are used by the constructor, by the method, and by the method to specify the volume level for spoken text. The property gets the volume for a object using a instance. + Members of the enumeration are used by the constructor, by the method, and by the method to specify the volume level for spoken text. The property gets the volume for a object using a instance. ]]> diff --git a/xml/System.Speech.Synthesis/SayAs.xml b/xml/System.Speech.Synthesis/SayAs.xml index 297c6d4186d..ffbcb04fe56 100644 --- a/xml/System.Speech.Synthesis/SayAs.xml +++ b/xml/System.Speech.Synthesis/SayAs.xml @@ -24,11 +24,11 @@ Enumerates the content types for the speaking of elements such as times, dates, and currency. - method uses members of the enumeration to specify the content type of the appended text, which the speech synthesis engine can use to inform its pronunciation. - + method uses members of the enumeration to specify the content type of the appended text, which the speech synthesis engine can use to inform its pronunciation. + ]]> diff --git a/xml/System.Speech.Synthesis/SpeakCompletedEventArgs.xml b/xml/System.Speech.Synthesis/SpeakCompletedEventArgs.xml index d36ee47ebd6..e6d4b40e418 100644 --- a/xml/System.Speech.Synthesis/SpeakCompletedEventArgs.xml +++ b/xml/System.Speech.Synthesis/SpeakCompletedEventArgs.xml @@ -25,11 +25,11 @@ Returns notification from the event. - class has no properties, and does not return data from the event. It is provided to enable application authors to write event handlers for the event. The raises the event at the completion of any of the or methods. - + class has no properties, and does not return data from the event. It is provided to enable application authors to write event handlers for the event. The raises the event at the completion of any of the or methods. + ]]> diff --git a/xml/System.Speech.Synthesis/SpeakProgressEventArgs.xml b/xml/System.Speech.Synthesis/SpeakProgressEventArgs.xml index 7e88b9db259..ee7329fac46 100644 --- a/xml/System.Speech.Synthesis/SpeakProgressEventArgs.xml +++ b/xml/System.Speech.Synthesis/SpeakProgressEventArgs.xml @@ -28,14 +28,14 @@ is created when the object raises the event. The raises this event for each new word that it speaks in a prompt using any of the , , , or methods. + An instance of is created when the object raises the event. The raises this event for each new word that it speaks in a prompt using any of the , , , or methods. - The returned data is based on the Speech Synthesis Markup Language (SSML) that the code generates. The values returned for include spaces and the characters and contents of the SSML tags generated by the code. + The returned data is based on the Speech Synthesis Markup Language (SSML) that the code generates. The values returned for include spaces and the characters and contents of the SSML tags generated by the code. ## Examples - The following example demonstrates the information that is available from . Note how the , , , and methods affect the by their addition of **\

**, **\

**, **\**, and **\** tags to the generated SSML. Also, there are two entries in the output for "30%", one for each word to speak this number string (thirty percent). The and are the same for each entry and represent the characters "30%. However, the changes to reflect the speaking of the words "thirty" and "percent" by the . + The following example demonstrates the information that is available from . Note how the , , , and methods affect the by their addition of **\

**, **\

**, **\**, and **\** tags to the generated SSML. Also, there are two entries in the output for "30%", one for each word to speak this number string (thirty percent). The and are the same for each entry and represent the characters "30%. However, the changes to reflect the speaking of the words "thirty" and "percent" by the . ```csharp using System; @@ -132,7 +132,7 @@ namespace SampleSynthesis normalizes numbers to the words that correspond to how the number will be spoken. For example, the synthesizer speaks the number "4003" as "four thousand three". It raises a event for each of the spoken words, and returns the for each word. + The normalizes numbers to the words that correspond to how the number will be spoken. For example, the synthesizer speaks the number "4003" as "four thousand three". It raises a event for each of the spoken words, and returns the for each word. ]]> @@ -204,23 +204,23 @@ namespace SampleSynthesis includes the count for characters in XML tags, including their enclosing brackets. When using any of the , , , , or methods, the contents are added to an SSML prompt that includes the opening and closing `speak` elements. The opening `speak` element adds an offset of 82 characters and spaces to the of the all the words and letters in the prompt. For example, in the following snippet, the of the first word, "this", is 82. + The includes the count for characters in XML tags, including their enclosing brackets. When using any of the , , , , or methods, the contents are added to an SSML prompt that includes the opening and closing `speak` elements. The opening `speak` element adds an offset of 82 characters and spaces to the of the all the words and letters in the prompt. For example, in the following snippet, the of the first word, "this", is 82. ```csharp builder.AppendText("This is a test"); Synthesizer.Speak(builder); ``` - In the above example the of the word "test" is 92. In the following snippet the of the word "test" is 23 characters higher (115) because the opening **\** tag that precedes it contains 23 characters and spaces (the two escape characters "\\" are not counted). + In the above example the of the word "test" is 92. In the following snippet the of the word "test" is 23 characters higher (115) because the opening **\** tag that precedes it contains 23 characters and spaces (the two escape characters "\\" are not counted). ```csharp builder.AppendSsmlMarkup("This is a test ."); Synthesizer.Speak(builder); ``` - If you use the methods to add content to a prompt by specifying a file, the opening `xml` declaration and `speak` elements in the file are not used or counted. The first character in the file after the opening `speak` tag will be at position 82 if it is the first content in the prompt. + If you use the methods to add content to a prompt by specifying a file, the opening `xml` declaration and `speak` elements in the file are not used or counted. The first character in the file after the opening `speak` tag will be at position 82 if it is the first content in the prompt. - By contrast, the string parameter of a method does not get added to an SSML prompt before being spoken. Therefore, the of the first word, "this", in the following snippet is zero. + By contrast, the string parameter of a method does not get added to an SSML prompt before being spoken. Therefore, the of the first word, "this", in the following snippet is zero. ```csharp Synthesizer.Speak("This is a test."); @@ -352,7 +352,7 @@ showers.

## Examples - The following example illustrates the how the event reports the and properties for strings that contain numbers. + The following example illustrates the how the event reports the and properties for strings that contain numbers. ```csharp using System; diff --git a/xml/System.Speech.Synthesis/SpeakStartedEventArgs.xml b/xml/System.Speech.Synthesis/SpeakStartedEventArgs.xml index 1216e4efb0b..ab3c1e46e90 100644 --- a/xml/System.Speech.Synthesis/SpeakStartedEventArgs.xml +++ b/xml/System.Speech.Synthesis/SpeakStartedEventArgs.xml @@ -25,13 +25,13 @@ Returns notification from the event. - is created when the object raises the event. The raises the event when it begins speaking a prompt using any of the , , , or methods. - - The class has no properties, and does not return data from the event. It is provided to enable application authors to write event handlers for the event. - + is created when the object raises the event. The raises the event when it begins speaking a prompt using any of the , , , or methods. + + The class has no properties, and does not return data from the event. It is provided to enable application authors to write event handlers for the event. + ]]> diff --git a/xml/System.Speech.Synthesis/SpeechSynthesizer.xml b/xml/System.Speech.Synthesis/SpeechSynthesizer.xml index 0768bf45574..d9e89c2b5d5 100644 --- a/xml/System.Speech.Synthesis/SpeechSynthesizer.xml +++ b/xml/System.Speech.Synthesis/SpeechSynthesizer.xml @@ -32,24 +32,24 @@ object, it uses the default system voice. To configure the to use one of the installed speech synthesis (text-to-speech) voices, use the or method. To get information about which voices are installed, use the method and the class. + When you create a new object, it uses the default system voice. To configure the to use one of the installed speech synthesis (text-to-speech) voices, use the or method. To get information about which voices are installed, use the method and the class. This class also provides control over the following aspects of speech synthesis: -- To configure the output for the object, use the , , , and methods. +- To configure the output for the object, use the , , , and methods. -- To generate speech, use the , , , or method. The can produce speech from text, a or object, or from [Speech Synthesis Markup Language (SSML) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201763). +- To generate speech, use the , , , or method. The can produce speech from text, a or object, or from [Speech Synthesis Markup Language (SSML) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201763). -- To pause and resume speech synthesis, use the and methods. +- To pause and resume speech synthesis, use the and methods. -- To add or remove lexicons, use the and methods. The can use one or more lexicons to guide its pronunciation of words. +- To add or remove lexicons, use the and methods. The can use one or more lexicons to guide its pronunciation of words. -- To modify the delivery of speech output, use the and properties. +- To modify the delivery of speech output, use the and properties. The raises events when it encounters certain features in prompts: (, , , and ). It also raises events that report on the start () and end () of speak operations and on the change of the speaking voice (). > [!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. @@ -118,7 +118,7 @@ namespace SampleSynthesis instance, it uses the default system voice. To configure the to use one of the installed speech synthesis (text-to-speech) voices, use the or method. To get information about which voices are installed, use the method and the class. + When you initialize a new instance, it uses the default system voice. To configure the to use one of the installed speech synthesis (text-to-speech) voices, use the or method. To get information about which voices are installed, use the method and the class. ]]> @@ -159,7 +159,7 @@ namespace SampleSynthesis ## Remarks A pronunciation lexicon is a collection of words or phrases together with their pronunciations, which consist of letters and characters from a supported phonetic alphabet. You can use a lexicon to specify custom pronunciations for specialized vocabulary in your application. - Pronunciations specified in an external lexicon file take precedence over the pronunciations of the speech synthesizer's internal lexicon or dictionary. However, pronunciations specified inline in prompts created with any of the , , or methods take precedence over pronunciations specified in any lexicon. Inline pronunciations apply only to a single occurrence of a word. See [Lexicons and Phonetic Alphabets](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh378335(v%3doffice.14)) for more information. + Pronunciations specified in an external lexicon file take precedence over the pronunciations of the speech synthesizer's internal lexicon or dictionary. However, pronunciations specified inline in prompts created with any of the , , or methods take precedence over pronunciations specified in any lexicon. Inline pronunciations apply only to a single occurrence of a word. See [Lexicons and Phonetic Alphabets](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh378335(v%3doffice.14)) for more information. You can add multiple lexicons to a object. Two values are currently supported for the `mediaType` parameter: @@ -260,9 +260,9 @@ namespace SampleSynthesis raises this event while processing any of the , , , or methods. For information about data associated with the event, see . + The raises this event while processing any of the , , , or methods. For information about data associated with the event, see . - You can add bookmarks using the method. + You can add bookmarks using the method. @@ -413,7 +413,7 @@ namespace SampleSynthesis , the method verifies that each of the voices (engines for text-to-speech) it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. + When an application calls , the method verifies that each of the voices (engines for text-to-speech) it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. ]]> @@ -768,7 +768,7 @@ namespace SampleSynthesis for an example. + See for an example. [!INCLUDE [untrusted-data-class-note](~/includes/untrusted-data-class-note.md)] @@ -830,11 +830,11 @@ namespace SampleSynthesis method and class to obtain the names of installed text-to-speech (TTS) voices that you can select. To select a voice, pass the entire contents of the property as the argument for the method. The object selects the first installed voice that contains `name` in the voice's property. The performs a case-sensitive, substring comparison to determine if the voice matches the `name`. + Use the method and class to obtain the names of installed text-to-speech (TTS) voices that you can select. To select a voice, pass the entire contents of the property as the argument for the method. The object selects the first installed voice that contains `name` in the voice's property. The performs a case-sensitive, substring comparison to determine if the voice matches the `name`. - When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. + When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. - To select a voice by gender, age, or locale, use one of the methods. + To select a voice by gender, age, or locale, use one of the methods. ]]> @@ -853,11 +853,11 @@ namespace SampleSynthesis method and class to obtain the names of installed text-to-speech (TTS) voices that you can select. The object selects the first installed voice that matches the specified characteristics. + Use the method and class to obtain the names of installed text-to-speech (TTS) voices that you can select. The object selects the first installed voice that matches the specified characteristics. - When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. + When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. - To select a voice by name, use the method + To select a voice by name, use the method ]]> @@ -890,13 +890,13 @@ namespace SampleSynthesis method and class to obtain the names of installed text-to-speech (TTS) voices that you can select. The object selects the first installed voice whose property matches the `gender` parameter. + Use the method and class to obtain the names of installed text-to-speech (TTS) voices that you can select. The object selects the first installed voice whose property matches the `gender` parameter. - When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. + When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. - To select a voice based on other characteristics, see the other methods. + To select a voice based on other characteristics, see the other methods. - To select a voice by name, use the method. + To select a voice by name, use the method. ]]> @@ -934,13 +934,13 @@ namespace SampleSynthesis method and class to obtain the names of installed text-to-speech (TTS) voices that you can select. The object selects the first installed voice whose and properties match the `gender` and `age` parameters. + Use the method and class to obtain the names of installed text-to-speech (TTS) voices that you can select. The object selects the first installed voice whose and properties match the `gender` and `age` parameters. - When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. + When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. - To select a voice based on other characteristics, see the other methods. + To select a voice based on other characteristics, see the other methods. - To select a voice by name, use the method. + To select a voice by name, use the method. ]]> @@ -981,13 +981,13 @@ namespace SampleSynthesis method and class to obtain the names of installed text-to-speech (TTS) voices that you can select. The object finds installed voices whose and properties match the `gender` and `age` parameters. The counts the matches it finds, and returns the voice when the count equals the `voiceAlternate` parameter. + Use the method and class to obtain the names of installed text-to-speech (TTS) voices that you can select. The object finds installed voices whose and properties match the `gender` and `age` parameters. The counts the matches it finds, and returns the voice when the count equals the `voiceAlternate` parameter. - When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. + When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. - To select a voice based on other characteristics, see the other overloads. + To select a voice based on other characteristics, see the other overloads. - To select a voice by name, use the method. + To select a voice by name, use the method. ]]> @@ -1030,7 +1030,7 @@ namespace SampleSynthesis object finds voices whose , , and properties match the `gender`, `age`, and `culture` parameters. The counts the matches it finds, and returns the voice when the count equals the `voiceAlternate` parameter. + The object finds voices whose , , and properties match the `gender`, `age`, and `culture` parameters. The counts the matches it finds, and returns the voice when the count equals the `voiceAlternate` parameter. Microsoft Windows and the System.Speech API accept all valid language-country codes. To perform text-to-speech using the language specified in the `culture` parameter, a speech synthesis engine that supports that language-country code must be installed. The speech synthesis engines that shipped with Microsoft Windows 7 work with the following language-country codes: @@ -1042,11 +1042,11 @@ namespace SampleSynthesis Two-letter language codes such as "en" are also permitted. - When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. + When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. - To select a voice based on other characteristics, see the other overloads. + To select a voice based on other characteristics, see the other overloads. - To select a voice by name, use the method. + To select a voice by name, use the method. ]]> @@ -1086,9 +1086,9 @@ namespace SampleSynthesis to release the 's reference to the stream. + Call to release the 's reference to the stream. - For other output configuration options, see the , , , and methods. + For other output configuration options, see the , , , and methods. ]]> @@ -1126,7 +1126,7 @@ namespace SampleSynthesis ## Remarks You can use the **Sound** window in the Windows **Control Panel** to configure the default audio device for the computer. - For other output configuration options, see the , , , and methods. + For other output configuration options, see the , , , and methods. @@ -1191,9 +1191,9 @@ namespace SampleSynthesis 's reference to a file or stream. See for an example. + Use this method to release the 's reference to a file or stream. See for an example. - For other output configuration options, see the , , , and methods. + For other output configuration options, see the , , , and methods. ]]> @@ -1210,9 +1210,9 @@ namespace SampleSynthesis 's reference to the file, reconfigure the 's output, for example, by calling . + To release the 's reference to the file, reconfigure the 's output, for example, by calling . - For other output configuration options, see the , , , and methods. + For other output configuration options, see the , , , and methods. ]]> @@ -1245,12 +1245,12 @@ namespace SampleSynthesis method. + To configure the output and specify the audio format, use the method. ## Examples - The following example uses an instance of to play a prompt that has been output to a .wav file. Because the call is asynchronous, the instance is created (and the method invoked) in the handler for the event. + The following example uses an instance of to play a prompt that has been output to a .wav file. Because the call is asynchronous, the instance is created (and the method invoked) in the handler for the event. ```csharp using System; @@ -1415,9 +1415,9 @@ namespace SampleSynthesis 's reference to the stream, reconfigure the synthesizer's output, for example, by calling . + To release the 's reference to the stream, reconfigure the synthesizer's output, for example, by calling . - For other output configuration options, see the , , , and methods. + For other output configuration options, see the , , , and methods. @@ -1482,7 +1482,7 @@ namespace SampleSynthesis methods generate speech synchronously. The methods do not return until the content of the instance has been completely spoken. This is the simplest way to generate speech. However, if your application needs to perform tasks while speaking, for example highlight text, paint animation, monitor controls, or other tasks, use the methods or the method to generate speech asynchronously. + The methods generate speech synchronously. The methods do not return until the content of the instance has been completely spoken. This is the simplest way to generate speech. However, if your application needs to perform tasks while speaking, for example highlight text, paint animation, monitor controls, or other tasks, use the methods or the method to generate speech asynchronously. During a call to this method, the can raise the following events: @@ -1500,7 +1500,7 @@ namespace SampleSynthesis - . Raised when the speaking voice for the synthesizer changes. - The does not raise the event while processing any of the methods. + The does not raise the event while processing any of the methods. ]]> @@ -1533,12 +1533,12 @@ namespace SampleSynthesis object, use . + To asynchronously speak the contents of a object, use . ## Examples - The following example creates a object from a string and passes the object as an argument to the method. + The following example creates a object from a string and passes the object as an argument to the method. ```csharp using System; @@ -1604,12 +1604,12 @@ namespace SampleSynthesis object, use . + To asynchronously speak the contents of a object, use . ## Examples - The following example creates a object from a string and passes the object as an argument to the method. + The following example creates a object from a string and passes the object as an argument to the method. ```csharp using System; @@ -1676,12 +1676,12 @@ namespace SampleSynthesis method. To asynchronously speak the contents of a string, use the method. + To synchronously speak a string that contains SSML markup, use the method. To asynchronously speak the contents of a string, use the method. ## Examples - As shown in the following example, the method provides the simplest means to generate speech output synchronously. + As shown in the following example, the method provides the simplest means to generate speech output synchronously. ```csharp using System; @@ -1728,7 +1728,7 @@ namespace SampleSynthesis methods generate speech asynchronously. The methods return immediately without waiting for the content of the object to finish speaking. Use if your application needs to perform tasks while speaking, for example highlight text, paint animation, monitor controls, or other tasks. + The methods generate speech asynchronously. The methods return immediately without waiting for the content of the object to finish speaking. Use if your application needs to perform tasks while speaking, for example highlight text, paint animation, monitor controls, or other tasks. During a call to this method, the can raise the following events: @@ -1746,9 +1746,9 @@ namespace SampleSynthesis - . Raised when the speaking voice for the synthesizer changes. -- . Raised when the synthesizer finishes a operation. +- . Raised when the synthesizer finishes a operation. - If your application does not need to perform tasks while speaking, you can use the methods or the method to generate speech synchronously. + If your application does not need to perform tasks while speaking, you can use the methods or the method to generate speech synchronously. ]]> @@ -1789,14 +1789,14 @@ namespace SampleSynthesis or the method. + You can cancel the asynchronous speaking of a prompt with the or the method. - To synchronously speak the contents of a object, use . + To synchronously speak the contents of a object, use . This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ## Examples - The following example creates a object from a string and passes the object as an argument to the method. + The following example creates a object from a string and passes the object as an argument to the method. ```csharp using System; @@ -1861,12 +1861,12 @@ namespace SampleSynthesis object, use . + To synchronously speak the contents of a object, use . ## Examples - The following example creates a object from a string and passes the object as an argument to the method. + The following example creates a object from a string and passes the object as an argument to the method. ```csharp using System; @@ -1934,12 +1934,12 @@ namespace SampleSynthesis method. To synchronously speak the contents of a string, use the method. You can cancel the asynchronous speaking of a prompt with the or the method. + To asynchronously speak a string that contains SSML markup, use the method. To synchronously speak the contents of a string, use the method. You can cancel the asynchronous speaking of a prompt with the or the method. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ## Examples - As shown in the following example, the method provides the simplest means to generate speech output asynchronously. + As shown in the following example, the method provides the simplest means to generate speech output asynchronously. ```csharp using System; @@ -2003,13 +2003,13 @@ namespace SampleSynthesis ## Remarks You can also use this method to cancel an asynchronous speak operation for the following: -- The contents of a specified by a method. +- The contents of a specified by a method. -- The contents of a specified by a method. +- The contents of a specified by a method. -- The contents of a containing SSML specified by a method. +- The contents of a containing SSML specified by a method. - When you call , , or , System.Speech creates a object and populates it with the contents of the method's parameter, and returns the object. If you retain a copy of the returned , you can pass it into to cancel speaking content specified in a or a object. + When you call , , or , System.Speech creates a object and populates it with the contents of the method's parameter, and returns the object. If you retain a copy of the returned , you can pass it into to cancel speaking content specified in a or a object. ]]> @@ -2039,7 +2039,7 @@ namespace SampleSynthesis to cancel the asynchronous speaking of a prompt, so that a new prompt can be spoken. Note that the event fires when a operation is cancelled. + The following example show a use of to cancel the asynchronous speaking of a prompt, so that a new prompt can be spoken. Note that the event fires when a operation is cancelled. ```csharp using System; @@ -2136,7 +2136,7 @@ namespace SampleSynthesis raises the event at the completion of any of the or methods. + The raises the event at the completion of any of the or methods. The class has no properties, and does not return data from the event. It is provided to enable application authors to write event handlers for the event. @@ -2168,7 +2168,7 @@ namespace SampleSynthesis raises this event for each new word that it speaks in a prompt using any of the , , , or methods. For an example and more information about data associated with the event, see . + The raises this event for each new word that it speaks in a prompt using any of the , , , or methods. For an example and more information about data associated with the event, see . ]]> @@ -2203,7 +2203,7 @@ namespace SampleSynthesis ## Remarks The contents of the `textToSpeak` parameter must include a `speak` element and must conform to the [Speech Synthesis Markup Language (SSML) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201763). For more information, see [Speech Synthesis Markup Language Reference](https://msdn.microsoft.com/library/0c51279e-84d2-4f73-a924-8832039abf94). - To asynchronously speak a string that contains SSML markup, use the method. You can use to initiate the synchronous speaking of a string that does not contain SSML markup. + To asynchronously speak a string that contains SSML markup, use the method. You can use to initiate the synchronous speaking of a string that does not contain SSML markup. During a call to this method, the can raise the following events: @@ -2221,7 +2221,7 @@ namespace SampleSynthesis - . Raised when the speaking voice for the synthesizer changes. - The does not raise the event while processing the method. + The does not raise the event while processing the method. @@ -2296,7 +2296,7 @@ namespace SampleSynthesis ## Remarks The contents of the `textToSpeak` parameter must include a `speak` element and must conform to the [Speech Synthesis Markup Language (SSML) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201763). For more information, see [Speech Synthesis Markup Language Reference](https://msdn.microsoft.com/library/0c51279e-84d2-4f73-a924-8832039abf94). - To synchronously speak a string that contains SSML markup, use the method. You can use to initiate the asynchronous speaking of a string that does not contain SSML markup. + To synchronously speak a string that contains SSML markup, use the method. You can use to initiate the asynchronous speaking of a string that does not contain SSML markup. During a call to this method, the can raise the following events: @@ -2314,9 +2314,9 @@ namespace SampleSynthesis - . Raised when the speaking voice for the synthesizer changes. -- . Raised when the synthesizer finishes processing a operation. +- . Raised when the synthesizer finishes processing a operation. - If your application dos not need to perform tasks while speaking, you can use the or the method to generate speech synchronously. + If your application dos not need to perform tasks while speaking, you can use the or the method to generate speech synchronously. @@ -2387,7 +2387,7 @@ namespace SampleSynthesis raises this event when it begins processing a prompt using any of the , , , or methods. + The raises this event when it begins processing a prompt using any of the , , , or methods. The class has no properties, and does not return data from the event. It is provided to enable application authors to write event handlers for the event. @@ -2501,9 +2501,9 @@ namespace SampleSynthesis raises this event when its speaking changes. For an example and more information about data associated with the event, see . + The raises this event when its speaking changes. For an example and more information about data associated with the event, see . - To pause and resume speech synthesis, use the and methods. + To pause and resume speech synthesis, use the and methods. ]]> @@ -2593,7 +2593,7 @@ namespace SampleSynthesis , it uses the default system voice. To configure the object to use one of the installed speech synthesis voices, use the or method. To get information about which voices are installed, use the method and the class. + When you initialize a new , it uses the default system voice. To configure the object to use one of the installed speech synthesis voices, use the or method. To get information about which voices are installed, use the method and the class. @@ -2694,7 +2694,7 @@ namespace SampleSynthesis ## Remarks For an example and information about data associated with the event, see . - You can change the voice that the uses with any of the 's methods or the 's or methods. + You can change the voice that the uses with any of the 's methods or the 's or methods. ]]> diff --git a/xml/System.Speech.Synthesis/StateChangedEventArgs.xml b/xml/System.Speech.Synthesis/StateChangedEventArgs.xml index 34879207c0a..a301d889307 100644 --- a/xml/System.Speech.Synthesis/StateChangedEventArgs.xml +++ b/xml/System.Speech.Synthesis/StateChangedEventArgs.xml @@ -28,7 +28,7 @@ is created when the object raises the event. To obtain the values for the new and the previous , access the and properties in the handler for the event. + An instance of is created when the object raises the event. To obtain the values for the new and the previous , access the and properties in the handler for the event. diff --git a/xml/System.Speech.Synthesis/SynthesisTextFormat.xml b/xml/System.Speech.Synthesis/SynthesisTextFormat.xml index eeb20fbe1c9..5d0be96c15f 100644 --- a/xml/System.Speech.Synthesis/SynthesisTextFormat.xml +++ b/xml/System.Speech.Synthesis/SynthesisTextFormat.xml @@ -24,16 +24,16 @@ Enumerates the types of text formats that may be used to construct a object. - constructor uses to indicate the format of the text that its `textToSpeak` parameter contains. +## Remarks + +The constructor uses to indicate the format of the text that its `textToSpeak` parameter contains. ## Examples - See for an example. - + See for an example. + ]]> diff --git a/xml/System.Speech.Synthesis/SynthesizerState.xml b/xml/System.Speech.Synthesis/SynthesizerState.xml index ba5a9ef0436..2bc63c271ef 100644 --- a/xml/System.Speech.Synthesis/SynthesizerState.xml +++ b/xml/System.Speech.Synthesis/SynthesizerState.xml @@ -27,9 +27,9 @@ property uses to indicate the current state of the . See for an example. + The property uses to indicate the current state of the . See for an example. - The and properties use to indicate state of the when the event is raised. + The and properties use to indicate state of the when the event is raised. ]]> diff --git a/xml/System.Speech.Synthesis/VoiceAge.xml b/xml/System.Speech.Synthesis/VoiceAge.xml index 18ef025a443..da8a571f63d 100644 --- a/xml/System.Speech.Synthesis/VoiceAge.xml +++ b/xml/System.Speech.Synthesis/VoiceAge.xml @@ -27,7 +27,7 @@ can indicate the age of an existing voice or an age preference when selecting a voice. Three of the methods and two of the methods use to specify the age when selecting a voice. The property obtains the age of an existing voice using a member. + can indicate the age of an existing voice or an age preference when selecting a voice. Three of the methods and two of the methods use to specify the age when selecting a voice. The property obtains the age of an existing voice using a member. ]]> diff --git a/xml/System.Speech.Synthesis/VoiceChangeEventArgs.xml b/xml/System.Speech.Synthesis/VoiceChangeEventArgs.xml index 8d3904ecd62..f001b0231ee 100644 --- a/xml/System.Speech.Synthesis/VoiceChangeEventArgs.xml +++ b/xml/System.Speech.Synthesis/VoiceChangeEventArgs.xml @@ -28,9 +28,9 @@ is created when the object raises the event. To obtain the identity of the new , access the property in the handler for the event. + An instance of is created when the object raises the event. To obtain the identity of the new , access the property in the handler for the event. - You can change the voice in use by the with any of the 's methods or the 's or methods. + You can change the voice in use by the with any of the 's methods or the 's or methods. ]]> diff --git a/xml/System.Speech.Synthesis/VoiceGender.xml b/xml/System.Speech.Synthesis/VoiceGender.xml index fdb9b72227f..5784448b4be 100644 --- a/xml/System.Speech.Synthesis/VoiceGender.xml +++ b/xml/System.Speech.Synthesis/VoiceGender.xml @@ -27,7 +27,7 @@ can indicate the gender of an existing voice or a gender preference when selecting a voice. All of the methods and three of the methods use to specify the gender when selecting a voice. The property obtains the gender of an existing voice using a member. + can indicate the gender of an existing voice or a gender preference when selecting a voice. All of the methods and three of the methods use to specify the gender when selecting a voice. The property obtains the gender of an existing voice using a member. ]]> diff --git a/xml/System.Speech.Synthesis/VoiceInfo.xml b/xml/System.Speech.Synthesis/VoiceInfo.xml index 8d8c1ea546a..883883b8682 100644 --- a/xml/System.Speech.Synthesis/VoiceInfo.xml +++ b/xml/System.Speech.Synthesis/VoiceInfo.xml @@ -39,7 +39,7 @@ object uses a voice to generate speech from text. The properties of the object identify a voice and describe its characteristics. The most defining characteristic of a voice is its , which defines the single language that a voice can speak. + A voice is an installed speech synthesis engine, which is also referred to as a text-to-speech engine or a TTS engine. The object uses a voice to generate speech from text. The properties of the object identify a voice and describe its characteristics. The most defining characteristic of a voice is its , which defines the single language that a voice can speak. The property returns a object that contains information about the current voice in use by the . You can also use a object to get information about any of the voices that are installed on the system, as returned by the method. See for more information. @@ -275,7 +275,7 @@ namespace SampleSynthesis method takes a type as its parameter. If that object is not of the type, the method returns `False`. + The method takes a type as its parameter. If that object is not of the type, the method returns `False`. ]]> From dc44b095661292c79d51013cdbfa75f2b4a7677a Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 30 Mar 2026 16:03:21 -0700 Subject: [PATCH 3/4] System.P* --- .../PrintPropertyDictionary.xml | 6 +- .../BaseDevModeType.xml | 10 +- .../PrintTicketConverter.xml | 10 +- xml/System.Printing/Collation.xml | 2 +- xml/System.Printing/ConflictStatus.xml | 10 +- .../DeviceFontSubstitution.xml | 2 +- xml/System.Printing/Duplexing.xml | 2 +- .../EnumeratedPrintQueueTypes.xml | 2 +- xml/System.Printing/InputBin.xml | 2 +- xml/System.Printing/LocalPrintServer.xml | 152 +++++----- xml/System.Printing/OutputColor.xml | 2 +- xml/System.Printing/OutputQuality.xml | 2 +- xml/System.Printing/PageBorderless.xml | 2 +- xml/System.Printing/PageImageableArea.xml | 2 +- xml/System.Printing/PageMediaSize.xml | 74 ++--- xml/System.Printing/PageMediaType.xml | 4 +- xml/System.Printing/PageOrder.xml | 2 +- xml/System.Printing/PageOrientation.xml | 2 +- xml/System.Printing/PageResolution.xml | 70 ++--- .../PageScalingFactorRange.xml | 2 +- .../PagesPerSheetDirection.xml | 2 +- xml/System.Printing/PhotoPrintingIntent.xml | 4 +- xml/System.Printing/PrintCapabilities.xml | 8 +- .../PrintDocumentImageableArea.xml | 2 +- .../PrintJobInfoCollection.xml | 6 +- xml/System.Printing/PrintJobSettings.xml | 2 +- xml/System.Printing/PrintQueue.xml | 74 ++--- xml/System.Printing/PrintQueueCollection.xml | 6 +- xml/System.Printing/PrintQueueStream.xml | 10 +- .../PrintQueueStringProperty.xml | 38 +-- xml/System.Printing/PrintServer.xml | 272 +++++++++--------- xml/System.Printing/PrintSystemJobInfo.xml | 48 ++-- xml/System.Printing/PrintSystemObject.xml | 10 +- ...SystemObjectPropertiesChangedEventArgs.xml | 2 +- ...ntSystemObjectPropertyChangedEventArgs.xml | 4 +- xml/System.Printing/PrintSystemObjects.xml | 4 +- xml/System.Printing/PrintTicket.xml | 38 +-- xml/System.Printing/PrintTicketScope.xml | 14 +- .../PrintingNotSupportedException.xml | 12 +- xml/System.Printing/Stapling.xml | 2 +- xml/System.Printing/TrueTypeFontMode.xml | 2 +- 41 files changed, 460 insertions(+), 460 deletions(-) diff --git a/xml/System.Printing.IndexedProperties/PrintPropertyDictionary.xml b/xml/System.Printing.IndexedProperties/PrintPropertyDictionary.xml index 8049812ca43..00fc389b087 100644 --- a/xml/System.Printing.IndexedProperties/PrintPropertyDictionary.xml +++ b/xml/System.Printing.IndexedProperties/PrintPropertyDictionary.xml @@ -179,7 +179,7 @@ ## Remarks The property of `attributeValue` becomes the property of the new . The as a whole becomes the property of the new . - For another way to add an entry to the dictionary, see . + For another way to add an entry to the dictionary, see . @@ -243,7 +243,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 that 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 that it is using will not be freed until the garbage collector calls the method of the object. +> Always call before you release your last reference to the . Otherwise, the resources that it is using will not be freed until the garbage collector calls the method of the object. ]]> @@ -291,7 +291,7 @@ method and the method, if it has been overridden. invokes the protected method with the unnamed Boolean parameter set to `true`. `Finalize` invokes with the parameter set to `false`. + This method is called by the public method and the method, if it has been overridden. invokes the protected method with the unnamed Boolean parameter set to `true`. `Finalize` invokes with the parameter set to `false`. When the Boolean parameter is `true`, this method releases all the resources that are held by any managed objects that this references. This method invokes the `Dispose()` method of each referenced object. diff --git a/xml/System.Printing.Interop/BaseDevModeType.xml b/xml/System.Printing.Interop/BaseDevModeType.xml index a202b1305ce..1bde4bd0b8b 100644 --- a/xml/System.Printing.Interop/BaseDevModeType.xml +++ b/xml/System.Printing.Interop/BaseDevModeType.xml @@ -29,11 +29,11 @@ Specifies the type of default DEVMODE structure to use as the base DEVMODE for conversions of managed objects to unmanaged DEVMODE structures. - method. - + method. + ]]> diff --git a/xml/System.Printing.Interop/PrintTicketConverter.xml b/xml/System.Printing.Interop/PrintTicketConverter.xml index 4825a8febcd..6d43b23346b 100644 --- a/xml/System.Printing.Interop/PrintTicketConverter.xml +++ b/xml/System.Printing.Interop/PrintTicketConverter.xml @@ -37,7 +37,7 @@ . To validate it, use . + None of the methods of this class will validate the . To validate it, use . ]]> @@ -140,7 +140,7 @@ The scope of the returned is the entire print job. - This method does not validate the . To validate it, use . + This method does not validate the . To validate it, use . ]]> @@ -186,7 +186,7 @@ . To validate it, use . + This method does not validate the . To validate it, use . For more information on the DEVMODE structure, see [DEVMODE](/windows/win32/api/wingdi/ns-wingdi-devmodea). @@ -252,7 +252,7 @@ ## Remarks The scope of the parameter must be the entire print job. - This method does not validate the . To validate it, use . + This method does not validate the . To validate it, use . For more information on the DEVMODE structure, see [DEVMODE](/windows/win32/api/wingdi/ns-wingdi-devmodea). @@ -303,7 +303,7 @@ . To validate it, use . + This method does not validate the . To validate it, use . For more information on the DEVMODE structure, see [DEVMODE](/windows/win32/api/wingdi/ns-wingdi-devmodea). diff --git a/xml/System.Printing/Collation.xml b/xml/System.Printing/Collation.xml index efcb985d27f..03d7af94487 100644 --- a/xml/System.Printing/Collation.xml +++ b/xml/System.Printing/Collation.xml @@ -32,7 +32,7 @@ Use the values of this type primarily for the following purposes. -- As members of the collection, which is a property of , these values indicate the type of output that the printer supports. (Many printers support both types.) +- As members of the collection, which is a property of , these values indicate the type of output that the printer supports. (Many printers support both types.) - As the value of the property of a , the value instructs the printer whether to collate. diff --git a/xml/System.Printing/ConflictStatus.xml b/xml/System.Printing/ConflictStatus.xml index 16ba0dca637..2bb0a11a96c 100644 --- a/xml/System.Printing/ConflictStatus.xml +++ b/xml/System.Printing/ConflictStatus.xml @@ -29,11 +29,11 @@ Specifies whether any changes were made to a merged to ensure a viable . - method merges two objects, the initial print ticket may request printing functions that the printer does not support. In such cases, the printer driver changes the non-viable settings to ensure that the final print ticket is viable. The method uses this enumeration to report whether it had to make changes to ensure a viable print ticket. - + method merges two objects, the initial print ticket may request printing functions that the printer does not support. In such cases, the printer driver changes the non-viable settings to ensure that the final print ticket is viable. The method uses this enumeration to report whether it had to make changes to ensure a viable print ticket. + ]]> diff --git a/xml/System.Printing/DeviceFontSubstitution.xml b/xml/System.Printing/DeviceFontSubstitution.xml index cc1daa9a0f8..db56e256554 100644 --- a/xml/System.Printing/DeviceFontSubstitution.xml +++ b/xml/System.Printing/DeviceFontSubstitution.xml @@ -30,7 +30,7 @@ The values of this type are used primarily for these purposes: -- As members of the collection, a property of , they represent the printer capabilities. +- As members of the collection, a property of , they represent the printer capabilities. - As the value of the property of a , they instruct the printer to enable or disable device font substitution for the print job. diff --git a/xml/System.Printing/Duplexing.xml b/xml/System.Printing/Duplexing.xml index aecd9014fc1..067b474751b 100644 --- a/xml/System.Printing/Duplexing.xml +++ b/xml/System.Printing/Duplexing.xml @@ -28,7 +28,7 @@ ## Remarks Use the values of this type primarily for these purposes: -- As members of the collection, which is a property of , these values indicate the kinds of one-sided and two-sided printing that the printer supports. +- As members of the collection, which is a property of , these values indicate the kinds of one-sided and two-sided printing that the printer supports. - As the value of the property of a , they direct the printer to use one-sided printing or some kind of two-sided printing. diff --git a/xml/System.Printing/EnumeratedPrintQueueTypes.xml b/xml/System.Printing/EnumeratedPrintQueueTypes.xml index 406124784c3..1a54346005d 100644 --- a/xml/System.Printing/EnumeratedPrintQueueTypes.xml +++ b/xml/System.Printing/EnumeratedPrintQueueTypes.xml @@ -33,7 +33,7 @@ method to list subsets of available print queues. + Use these values with the method to list subsets of available print queues. `PushedMachineConnection` and `PushedUserConnection` refer to policies that enable automated connection of machines and users to printers. See the section ["Deploying Printers to Users or Computers by Using Group Policy"](https://learn.microsoft.com/previous-versions/windows/it-pro/windows-server-2008-r2-and-2008/cc753109(v=ws.10)#to-deploy-printers-to-users-or-computers-by-using-group-policy) in the [Step-by-Step Guide for Print Management](https://learn.microsoft.com/previous-versions/windows/it-pro/windows-server-2008-r2-and-2008/cc753109(v=ws.10)). diff --git a/xml/System.Printing/InputBin.xml b/xml/System.Printing/InputBin.xml index edd3d0a8932..7e66bae25ed 100644 --- a/xml/System.Printing/InputBin.xml +++ b/xml/System.Printing/InputBin.xml @@ -28,7 +28,7 @@ ## Remarks The values of this type are used primarily for these purposes: -- As members of the collection, a property of , they indicate the types of input bins that the printer supports. +- As members of the collection, a property of , they indicate the types of input bins that the printer supports. - As the value of the property of a , they instruct the printer to use the specified bin. diff --git a/xml/System.Printing/LocalPrintServer.xml b/xml/System.Printing/LocalPrintServer.xml index 9c40c62430e..664ac41da59 100644 --- a/xml/System.Printing/LocalPrintServer.xml +++ b/xml/System.Printing/LocalPrintServer.xml @@ -25,26 +25,26 @@ Represents the local print server (the computer on which your application is running) and enables management of its print queues. - object, that change has no effect until the value is passed to the computer that is represented by the object. To ensure that the change in value takes effect, use the method. - - In addition, other applications may also change the print service properties of the computer. To ensure that the object used by your application has the latest actual values, use the method. - + object, that change has no effect until the value is passed to the computer that is represented by the object. To ensure that the change in value takes effect, use the method. + + In addition, other applications may also change the print service properties of the computer. To ensure that the object used by your application has the latest actual values, use the method. + > [!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. - - If you want to print from a Windows Forms application, see the namespace. - - - -## Examples - The following example shows how to create an instance of the class. - +> 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 create an instance of the class. + :::code language="csharp" source="~/snippets/csharp/System.Printing/LocalPrintServer/Overview/XpsPrintHelper.cs" id="Snippetprintqueuesnip"::: - :::code language="vb" source="~/snippets/visualbasic/System.Printing/LocalPrintServer/Overview/xpsprinthelper.vb" id="Snippetprintqueuesnip"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Printing/LocalPrintServer/Overview/xpsprinthelper.vb" id="Snippetprintqueuesnip"::: + ]]> @@ -82,15 +82,15 @@ Initializes a new instance of the class. - @@ -151,14 +151,14 @@ A value specifying the type of access to the print server that your application needs. Initializes a new instance of the class that has the specified . - @@ -287,26 +287,26 @@ Writes any changes that your application made to the properties of the to the actual print server that the object represents. - object be created with rights. - - - -## Examples - The following example shows how to use this method in code that will install a second printer that differs in its properties from an existing printer only in location, port, and shared status. - + object be created with rights. + + + +## Examples + The following example shows how to use this method in code that will install a second printer that differs in its properties from an existing printer only in location, port, and shared status. + :::code language="csharp" source="~/snippets/csharp/System.Printing/LocalPrintServer/.ctor/Program.cs" id="Snippetcloneprinter"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/ClonePrinter/visualbasic/program.vb" id="Snippetcloneprinter"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/ClonePrinter/visualbasic/program.vb" id="Snippetcloneprinter"::: + ]]> Some properties are not committed. - Some of the properties could not be committed. - + Some of the properties could not be committed. + -or- - + The object was not created with sufficient rights. @@ -417,19 +417,19 @@ Gets or sets the default print queue. The that is designated as the default queue for the local computer. - access to the default queue, even if you have rights to the print server. To open the queue with greater access, use one of the constructors that enables you to specify the desired access level. - - - -## Examples - The following example shows how to use this property in code that will install a second printer that differs in its properties from an existing printer only in location, port, and shared status. - + access to the default queue, even if you have rights to the print server. To open the queue with greater access, use one of the constructors that enables you to specify the desired access level. + + + +## Examples + The following example shows how to use this property in code that will install a second printer that differs in its properties from an existing printer only in location, port, and shared status. + :::code language="csharp" source="~/snippets/csharp/System.Printing/LocalPrintServer/.ctor/Program.cs" id="Snippetcloneprinter"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/ClonePrinter/visualbasic/program.vb" id="Snippetcloneprinter"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/ClonePrinter/visualbasic/program.vb" id="Snippetcloneprinter"::: + ]]> @@ -541,19 +541,19 @@ Returns a reference to the default print queue of the . The default . - access to the default queue, even if you have rights to the print server. To open the queue with greater access, use one of the constructors that enables you to specify the desired access level. - - - -## Examples - The following example shows how to use this method to discover at run time the properties, and the types of those properties, of a print queue, without using reflection. - + access to the default queue, even if you have rights to the print server. To open the queue with greater access, use one of the constructors that enables you to specify the desired access level. + + + +## Examples + The following example shows how to use this method to discover at run time the properties, and the types of those properties, of a print queue, without using reflection. + :::code language="csharp" source="~/snippets/csharp/System.Printing/LocalPrintServer/GetDefaultPrintQueue/Program.cs" id="Snippetshowpropertytypeswithoutreflection"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/GetPrintObjectPropertyTypesWithoutReflection/visualbasic/program.vb" id="Snippetshowpropertytypeswithoutreflection"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/GetPrintObjectPropertyTypesWithoutReflection/visualbasic/program.vb" id="Snippetshowpropertytypeswithoutreflection"::: + ]]> @@ -585,11 +585,11 @@ Updates the properties of the object so that their values match the values of the print server that the object represents. - properties that are not written to the print server by using the method are lost when runs. - + properties that are not written to the print server by using the method are lost when runs. + ]]> Some properties did not update. diff --git a/xml/System.Printing/OutputColor.xml b/xml/System.Printing/OutputColor.xml index b0dda55bf8b..e1a93bb4db2 100644 --- a/xml/System.Printing/OutputColor.xml +++ b/xml/System.Printing/OutputColor.xml @@ -28,7 +28,7 @@ ## Remarks Use the values of this type for these purposes: -- As members of the collection, which is a property of , these values specify the types of output that a printer supports. (Many printers support more than one type.) +- As members of the collection, which is a property of , these values specify the types of output that a printer supports. (Many printers support more than one type.) - As the value of the property of a , they direct the printer to produce the designated type of output. diff --git a/xml/System.Printing/OutputQuality.xml b/xml/System.Printing/OutputQuality.xml index 25e7a4db4b4..32b277bd7cc 100644 --- a/xml/System.Printing/OutputQuality.xml +++ b/xml/System.Printing/OutputQuality.xml @@ -28,7 +28,7 @@ ## Remarks Use the values of this type primarily for these purposes: -- As members of the collection, which is a property of , these values indicate the types of output quality that a printer supports. +- As members of the collection, which is a property of , these values indicate the types of output quality that a printer supports. - As the value of the property of a , they direct a printer to produce a particular quality. diff --git a/xml/System.Printing/PageBorderless.xml b/xml/System.Printing/PageBorderless.xml index 48e31f59486..b491b6c5909 100644 --- a/xml/System.Printing/PageBorderless.xml +++ b/xml/System.Printing/PageBorderless.xml @@ -30,7 +30,7 @@ Use the values of this type primarily for these purposes: -- As members of the collection, which is a property of , these values indicate whether the device supports borderless printing. +- As members of the collection, which is a property of , these values indicate whether the device supports borderless printing. - As the value of the property of a , the value instructs the printer whether to print to the edge of the media. diff --git a/xml/System.Printing/PageImageableArea.xml b/xml/System.Printing/PageImageableArea.xml index 73337c57058..57fe0a02f29 100644 --- a/xml/System.Printing/PageImageableArea.xml +++ b/xml/System.Printing/PageImageableArea.xml @@ -227,7 +227,7 @@ ## Remarks The string that is returned has the following format: - (, ), (, ) + (, ), (, ) ]]> diff --git a/xml/System.Printing/PageMediaSize.xml b/xml/System.Printing/PageMediaSize.xml index 72dad99bce9..d1ba5b445f4 100644 --- a/xml/System.Printing/PageMediaSize.xml +++ b/xml/System.Printing/PageMediaSize.xml @@ -24,24 +24,24 @@ Describes the page size for paper or other media. - and also includes information about the imageable area of the page, see . - + and also includes information about the imageable area of the page, see . + > [!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. - - If you want to print from a Windows Forms application, see the namespace. - - - -## Examples - The following example shows how to use this class to scale a visual element to fit within the margins of the paper on which it is to print. - +> 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 use this class to scale a visual element to fit within the margins of the paper on which it is to print. + :::code language="csharp" source="~/snippets/csharp/System.Printing/LocalPrintServer/Overview/XpsPrintHelper.cs" id="Snippetpagemediasize"::: - :::code language="vb" source="~/snippets/visualbasic/System.Printing/LocalPrintServer/Overview/xpsprinthelper.vb" id="Snippetpagemediasize"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Printing/LocalPrintServer/Overview/xpsprinthelper.vb" id="Snippetpagemediasize"::: + ]]> @@ -181,14 +181,14 @@ Gets the page height. A that represents the page height, in pixels, which are 1/96 inch units. - @@ -256,13 +256,13 @@ Displays the page size for paper or other media. A that represents the page size for paper or other media. - ( x ) - + ( x ) + ]]> @@ -300,14 +300,14 @@ Gets the page width. A that represents the page width, in pixels, which are 1/96 inch units. - diff --git a/xml/System.Printing/PageMediaType.xml b/xml/System.Printing/PageMediaType.xml index b78e4c87035..e9d590d5764 100644 --- a/xml/System.Printing/PageMediaType.xml +++ b/xml/System.Printing/PageMediaType.xml @@ -28,7 +28,7 @@ ## Remarks The values of this type are used primarily for these purposes: -- As members of the collection, a property of , they indicate the types of media that the printer supports. +- As members of the collection, a property of , they indicate the types of media that the printer supports. - As the value of the property of a , they instruct the printer to use a specific type of media. @@ -36,7 +36,7 @@ You should never set a property to Unknown. If some other producing application has created a PrintTicket document that sets the page media type feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)), then a object in your application that is constructed with that document will have Unknown as the value of the property. - Although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. For more information, see [How to: Extend the Print Schema and Create New Print System Classes](https://learn.microsoft.com/previous-versions/aa970573(v=vs.100)). + Although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. For more information, see [How to: Extend the Print Schema and Create New Print System Classes](https://learn.microsoft.com/previous-versions/aa970573(v=vs.100)). diff --git a/xml/System.Printing/PageOrder.xml b/xml/System.Printing/PageOrder.xml index 2a17dafd036..120a739e539 100644 --- a/xml/System.Printing/PageOrder.xml +++ b/xml/System.Printing/PageOrder.xml @@ -28,7 +28,7 @@ ## Remarks Use the values of this type primarily for these purposes: -- As members of the collection, a property of , these values indicate the type of page order that a printer supports. (Many printers support both types.) +- As members of the collection, a property of , these values indicate the type of page order that a printer supports. (Many printers support both types.) - As the value of the property of a , the value directs a printer to print output in a specified order. diff --git a/xml/System.Printing/PageOrientation.xml b/xml/System.Printing/PageOrientation.xml index 090d1d111d4..764f3296b36 100644 --- a/xml/System.Printing/PageOrientation.xml +++ b/xml/System.Printing/PageOrientation.xml @@ -28,7 +28,7 @@ ## Remarks Use the values of this type primarily for these purposes: -- As members of the collection, which is a property of , these values indicate the orientation types that a printer supports. +- As members of the collection, which is a property of , these values indicate the orientation types that a printer supports. - As the value of the property of a , the value directs the printer to use a particular orientation. diff --git a/xml/System.Printing/PageResolution.xml b/xml/System.Printing/PageResolution.xml index 8b328970b0e..a03dbd7283b 100644 --- a/xml/System.Printing/PageResolution.xml +++ b/xml/System.Printing/PageResolution.xml @@ -24,15 +24,15 @@ Defines the page resolution of printed output as either a qualitative value or as dots per inch, or both. - [!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. - - If you want to print from a Windows Forms application, see the namespace. - +> 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. + ]]> @@ -105,11 +105,11 @@ The vertical resolution in dots per inch. Initiates a new instance of the class that has the specified vertical and horizontal dots per inch. - @@ -145,11 +145,11 @@ A value representing the resolution. Initiates a new instance of the class that has the specified and the specified vertical and horizontal dots per inch. - @@ -217,13 +217,13 @@ Returns the page resolution as a . A that contains the property values of the object. - x (Qualitative Resolution: ) - + x (Qualitative Resolution: ) + ]]> @@ -261,11 +261,11 @@ Gets the dots-per-inch measure of the horizontal page resolution. An value that represents a horizontal page resolution. - is the paper dimension that is parallel to the direction of paper movement. The two values are usually the same. - + is the paper dimension that is parallel to the direction of paper movement. The two values are usually the same. + ]]> @@ -303,11 +303,11 @@ Gets the dots-per-inch measure of the vertical page resolution. A nullable value that represents a vertical page resolution. - is the paper dimension that is perpendicular to the direction of paper movement. The two values are usually the same. - + is the paper dimension that is perpendicular to the direction of paper movement. The two values are usually the same. + ]]> diff --git a/xml/System.Printing/PageScalingFactorRange.xml b/xml/System.Printing/PageScalingFactorRange.xml index e4536a91764..9c0e9b8fc93 100644 --- a/xml/System.Printing/PageScalingFactorRange.xml +++ b/xml/System.Printing/PageScalingFactorRange.xml @@ -141,7 +141,7 @@ ## Remarks The format is as follows: - (, ) + (, ) ]]> diff --git a/xml/System.Printing/PagesPerSheetDirection.xml b/xml/System.Printing/PagesPerSheetDirection.xml index 79604b9570a..96831743d0f 100644 --- a/xml/System.Printing/PagesPerSheetDirection.xml +++ b/xml/System.Printing/PagesPerSheetDirection.xml @@ -28,7 +28,7 @@ ## Remarks Use the values of this type primarily for these purposes: -- As members of the collection, which is a property of , these values indicate the page arrangements that the printer supports. +- As members of the collection, which is a property of , these values indicate the page arrangements that the printer supports. - As the value of the property of a , the value directs the printer to arrange pages of content in a specified direction. diff --git a/xml/System.Printing/PhotoPrintingIntent.xml b/xml/System.Printing/PhotoPrintingIntent.xml index 4e8e2be6e1a..0d0f3db6804 100644 --- a/xml/System.Printing/PhotoPrintingIntent.xml +++ b/xml/System.Printing/PhotoPrintingIntent.xml @@ -28,9 +28,9 @@ ## Remarks The values of this type are used primarily for these purposes: -- As members of the collection, which is a property of , they specify the quality levels that the printer supports. +- As members of the collection, which is a property of , they specify the quality levels that the printer supports. -- As a value, which is a property of , instructs the printer to use a particular quality. +- As a value, which is a property of , instructs the printer to use a particular quality. The `Unknown` value is never used in properties of objects. diff --git a/xml/System.Printing/PrintCapabilities.xml b/xml/System.Printing/PrintCapabilities.xml index 2ae2fa7d220..45004f93e50 100644 --- a/xml/System.Printing/PrintCapabilities.xml +++ b/xml/System.Printing/PrintCapabilities.xml @@ -565,7 +565,7 @@ that have "Capability" at the end of the name, such as , are collections of values of an enumerated type. But and are collections of objects. For the latter two properties, you cannot test for the presence of a particular value by using the **Contains** method of . This is because, with reference types, the method returns `true` only when the memory address of the object passed to it is the same as the address of an object in the collection; that is, they are the same object. Since this will not usually be the case, the method will nearly always return `false` even if there is an object in the collection with exactly the same values in all its properties as the object passed to the **Contains** method of . To determine the contents of the , you must enumerate through each of its members, comparing them with the desired value. + Most of the properties of that have "Capability" at the end of the name, such as , are collections of values of an enumerated type. But and are collections of objects. For the latter two properties, you cannot test for the presence of a particular value by using the **Contains** method of . This is because, with reference types, the method returns `true` only when the memory address of the object passed to it is the same as the address of an object in the collection; that is, they are the same object. Since this will not usually be the case, the method will nearly always return `false` even if there is an object in the collection with exactly the same values in all its properties as the object passed to the **Contains** method of . To determine the contents of the , you must enumerate through each of its members, comparing them with the desired value. If the printer does not support media size selection, the collection is empty. @@ -574,7 +574,7 @@ ## Examples - The following code example shows how to search for a particular value in the . + The following code example shows how to search for a particular value in the . ```csharp foreach (PageMediaSize mediaSize in pc.PageMediaSizeCapability) @@ -735,7 +735,7 @@ foreach (PageMediaSize mediaSize in pc.PageMediaSizeCapability) that have "Capability" at the end of the name, such as , are collections of values of an enumerated type. But and are collections of objects. For the latter two properties, you cannot test for the presence of a particular value by using the **Contains** method of . This is because, with reference types, the method returns `true` only when the memory address of the object passed to it is the same as the address of an object in the collection; that is, they are the same object. Since this will not usually be the case, the method will nearly always return `false` even if there is an object in the collection with exactly the same values in all its properties as the object passed to the **Contains** method of . To determine the contents of the , you must enumerate through each of its members, comparing them with the desired value. See the example. + Most of the properties of that have "Capability" at the end of the name, such as , are collections of values of an enumerated type. But and are collections of objects. For the latter two properties, you cannot test for the presence of a particular value by using the **Contains** method of . This is because, with reference types, the method returns `true` only when the memory address of the object passed to it is the same as the address of an object in the collection; that is, they are the same object. Since this will not usually be the case, the method will nearly always return `false` even if there is an object in the collection with exactly the same values in all its properties as the object passed to the **Contains** method of . To determine the contents of the , you must enumerate through each of its members, comparing them with the desired value. See the example. The class has properties in which you can specify the dots-per-inch for the X and Y dimensions and a property where you can give a qualitative expression to the resolution. @@ -746,7 +746,7 @@ foreach (PageMediaSize mediaSize in pc.PageMediaSizeCapability) ## Examples - The following code example shows how to search for a particular value in the . + The following code example shows how to search for a particular value in the . ```csharp foreach (PageResolution pageRes in pc.PageResolutionCapability) diff --git a/xml/System.Printing/PrintDocumentImageableArea.xml b/xml/System.Printing/PrintDocumentImageableArea.xml index bb025181f8a..1a829001a84 100644 --- a/xml/System.Printing/PrintDocumentImageableArea.xml +++ b/xml/System.Printing/PrintDocumentImageableArea.xml @@ -29,7 +29,7 @@ ## Remarks Most laser and inkjet printers do not support borderless printing. They must leave an unprinted area around the edges of the paper to prevent toner from getting on the parts of the printer that move the paper. For printers that do not support borderless printing, the imageable area of the paper is smaller than the paper dimensions. - Use objects primarily as parameters to the methods. + Use objects primarily as parameters to the methods. > [!CAUTION] > Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. diff --git a/xml/System.Printing/PrintJobInfoCollection.xml b/xml/System.Printing/PrintJobInfoCollection.xml index c74fa131663..e1ed4306ae0 100644 --- a/xml/System.Printing/PrintJobInfoCollection.xml +++ b/xml/System.Printing/PrintJobInfoCollection.xml @@ -213,7 +213,7 @@ only when you need to customize iteration, such as by skipping every other member. + We recommend that you use the `foreach` statement to iterate through all members of the collection. Use only when you need to customize iteration, such as by skipping every other member. ]]> @@ -253,7 +253,7 @@ ## Remarks We recommend that you use the `foreach` statement to iterate through all members of the collection. Use your own enumerator object only when you need to customize iteration, such as by skipping every other member. - If you need your own enumerator, we recommend that you use the generic, type-safe function instead of . The is public only to fulfill the requirements of the interface, which is implemented by this collection. + If you need your own enumerator, we recommend that you use the generic, type-safe function instead of . The is public only to fulfill the requirements of the interface, which is implemented by this collection. ]]> @@ -293,7 +293,7 @@ ## Remarks -We recommend that you use the `foreach` statement to iterate through all members of the collection. Use only when you need to customize iteration, such as by skipping every other member. +We recommend that you use the `foreach` statement to iterate through all members of the collection. Use only when you need to customize iteration, such as by skipping every other member. ]]> diff --git a/xml/System.Printing/PrintJobSettings.xml b/xml/System.Printing/PrintJobSettings.xml index 57e526de0a1..f2c859cdb34 100644 --- a/xml/System.Printing/PrintJobSettings.xml +++ b/xml/System.Printing/PrintJobSettings.xml @@ -78,7 +78,7 @@ property does not validate or modify the specified for a particular . If needed, use the method to create a -specific that is valid for a given printer. + Setting this property does not validate or modify the specified for a particular . If needed, use the method to create a -specific that is valid for a given printer. ]]> diff --git a/xml/System.Printing/PrintQueue.xml b/xml/System.Printing/PrintQueue.xml index 7995246bdd6..8cf3f5a9045 100644 --- a/xml/System.Printing/PrintQueue.xml +++ b/xml/System.Printing/PrintQueue.xml @@ -28,7 +28,7 @@ object represent characteristics of the print queue utility that runs on the computer, but others represent features or states of the printer itself. For example, is a characteristic of the print queue, but is a property of the printer. Many of the properties of the printer, such as whether it needs user attention, need to be passed, by means of the method, from the printer itself to the object. This should be done before the corresponding property () is read by your program. Similarly, when your program changes the values of one or more properties of a object, the change must be written to the actual print queue utility on the computer. Do this with the method. + Some properties of the object represent characteristics of the print queue utility that runs on the computer, but others represent features or states of the printer itself. For example, is a characteristic of the print queue, but is a property of the printer. Many of the properties of the printer, such as whether it needs user attention, need to be passed, by means of the method, from the printer itself to the object. This should be done before the corresponding property () is read by your program. Similarly, when your program changes the values of one or more properties of a object, the change must be written to the actual print queue utility on the computer. Do this with the method. > [!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. @@ -441,7 +441,7 @@ ## Remarks Unless the queue is paused or in an error state, the job prints when it reaches the top of the queue, so this is a printing function. - Other ways to print in Windows Presentation Foundation (WPF) include the method, which can be used with or without opening the dialog, and the many and methods of the . + Other ways to print in Windows Presentation Foundation (WPF) include the method, which can be used with or without opening the dialog, and the many and methods of the . ]]> @@ -486,14 +486,14 @@ ## Remarks Use this method to write device specific information, to a spool file, that is not automatically included by the Microsoft Windows spooler. Of course, you need to know whether the spool file is Enhanced Metafile (EMF) or XML Paper Specification (XPS). If you prefer to work with the API, you can use the class instead of this method. - After the method has been called, you must write a array to the property of the that is returned by or no print job is created. This array is what prints if the printer is working and is not paused. + After the method has been called, you must write a array to the property of the that is returned by or no print job is created. This array is what prints if the printer is working and is not paused. > [!CAUTION] -> If the is not closed with before the end of the thread in which is called, then an is thrown when that thread ends because the spooler thread cannot gain control over the object. +> If the is not closed with before the end of the thread in which is called, then an is thrown when that thread ends because the spooler thread cannot gain control over the object. - In the print queue's graphical user interface (GUI), the job has the name "Print System Document". To give the job a different name, use the overload. + In the print queue's graphical user interface (GUI), the job has the name "Print System Document". To give the job a different name, use the overload. - Other ways to print in Windows Presentation Foundation (WPF) include the method, which can be used with or without opening the dialog, and the many and methods of the . + Other ways to print in Windows Presentation Foundation (WPF) include the method, which can be used with or without opening the dialog, and the many and methods of the . @@ -549,17 +549,17 @@ ## Remarks Use this method to write device specific information, to a spool file, that is not automatically included by the Microsoft Windows spooler. Of course, you need to know whether the spool file is Enhanced Metafile (EMF) or XML Paper Specification (XPS). If you prefer to work with the API, you can use the class instead of this method. - After the method has been called, you must write a array to the property of the that is returned by or no print job is created. This array is what prints if the printer is working and is not paused. + After the method has been called, you must write a array to the property of the that is returned by or no print job is created. This array is what prints if the printer is working and is not paused. > [!CAUTION] -> If the is not closed with before the end of the thread in which is called, then an is thrown when that thread ends because the spooler thread cannot gain control over the object. +> If the is not closed with before the end of the thread in which is called, then an is thrown when that thread ends because the spooler thread cannot gain control over the object. - Other ways to print in Windows Presentation Foundation (WPF) include the method, which can be used with or without opening the dialog, and the many and methods of the . + Other ways to print in Windows Presentation Foundation (WPF) include the method, which can be used with or without opening the dialog, and the many and methods of the . ## Examples - The following example shows how to use to read a file into a array and send the array to a print queue. This code assumes that there is a file called test.txt in the root of the C: drive. This code only works with printers that can detect and print plain text. Some of them cannot. + The following example shows how to use to read a file into a array and send the array to a print queue. This code assumes that there is a file called test.txt in the root of the C: drive. This code only works with printers that can detect and print plain text. Some of them cannot. :::code language="csharp" source="~/snippets/csharp/System.Printing/PrintQueue/AddJob/Program1.cs" id="Snippetaddnamedjob"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/WriteToSpoolFile/visualbasic/program.vb" id="Snippetaddnamedjob"::: @@ -609,7 +609,7 @@ . + For more information, see . ]]> @@ -660,23 +660,23 @@ method throws an exception. + If `fastCopy` is `true`, then the printer must be an [Printing Overview](https://learn.microsoft.com/dotnet/framework/wpf/advanced/printing-overview). If it is not, the method throws an exception. If `fastCopy` is `false`, then it is not necessary to use an XPSDrv printer. The XPS file being added to the queue is converted to the printer's page description language, such as PCL or Postscript. However, this kind of printing makes a call to Component Object Model (COM). The call to COM requires that the calling thread have a single-threaded apartment () instead of multiple-threaded apartment (), which is the default. There are two ways of doing this: - The simplest way is to add the (that is, "`[System.STAThreadAttribute()]`") just above the first line of the application's `Main` method (usually "`static void Main(string[] args)`"). -- If you need your `Main` thread's apartment state to be , you can house the call to in a separate thread whose apartment state is set to with . The example below illustrates this second technique. +- If you need your `Main` thread's apartment state to be , you can house the call to in a separate thread whose apartment state is set to with . The example below illustrates this second technique. > [!NOTE] -> You cannot apply the to any method except `Main` and you cannot use for the `Main` thread. +> You cannot apply the to any method except `Main` and you cannot use for the `Main` thread. - Other ways to print in Windows Presentation Foundation (WPF) include the method, which can be used with or without opening the dialog, and the many and methods of the . + Other ways to print in Windows Presentation Foundation (WPF) include the method, which can be used with or without opening the dialog, and the many and methods of the . ## Examples - The following example shows how to use to batch print all the XML Paper Specification (XPS) files in a directory. + The following example shows how to use to batch print all the XML Paper Specification (XPS) files in a directory. :::code language="csharp" source="~/snippets/csharp/System.Printing/PrintQueue/AddJob/Program.cs" id="Snippetbatchprintxpsfiles"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/BatchPrintXPSFiles/visualbasic/program.vb" id="Snippetbatchprintxpsfiles"::: @@ -735,7 +735,7 @@ . + For more information, see . ]]> @@ -879,7 +879,7 @@ object do not actually take effect until the program executes the method. + Changes that your program makes to the properties of a object do not actually take effect until the program executes the method. The method requires that the object be created with rights. @@ -1305,13 +1305,13 @@ specifies print job options such as , , , , and others. + The default specifies print job options such as , , , , and others. - Each maintains its own . + Each maintains its own . - In normal operation the property returns a . If the detects an invalid state, returns `null`. If returns `null`, the application should display an informational user dialog that an error has occurred on this print queue and that the print job should be restarted with the output directed to a different print queue. + In normal operation the property returns a . If the detects an invalid state, returns `null`. If returns `null`, the application should display an informational user dialog that an error has occurred on this print queue and that the print job should be restarted with the output directed to a different print queue. - Getting or setting the property does not validate the . The method can be used to validate a . + Getting or setting the property does not validate the . The method can be used to validate a . @@ -1430,9 +1430,9 @@ , otherwise it includes the full UNC (Universal Naming Convention) name. + For print queues on the local print server, this property's value is identical to , otherwise it includes the full UNC (Universal Naming Convention) name. - The object also has writeable and properties. + The object also has writeable and properties. @@ -1480,7 +1480,7 @@ method for the same purpose. + You can also use the method for the same purpose. @@ -1594,7 +1594,7 @@ ## Remarks The parameter is used as the basis on which to construct the object. For example, suppose the printer supported only media types A and B from input bin 1 and it only supported media type C from input bin 2. If the `printTicket` parameter specified input bin 1, then the object that is returned would include all three media types, but it would report type C as "constrained." If the `printTicket` parameter specified input bin 2, then the object that is returned would include all three media types, but it would report types A and B as "constrained." See the [Print Schema](https://learn.microsoft.com/windows/win32/printdocs/printschema) for more information on constraints. - If `printTicket` is `null`, the is used. + If `printTicket` is `null`, the is used. ]]> @@ -1699,7 +1699,7 @@ ## Remarks The parameter is used as the basis on which to construct the print capabilities XML. For example, suppose the printer supported only media types A and B from input bin 1 and it only supported media type C from input bin 2. If the `printTicket` parameter specified input bin 1, then the print capabilities XML that is returned would include all three media types, but it would report type C as "constrained." If the `printTicket` parameter specified input bin 2, then the print capabilities XML that is returned would include all three media types, but it would report types A and B as "constrained." See the [Print Schema](https://learn.microsoft.com/windows/win32/printdocs/printschema) for more information on constraints. - If `printTicket` is `null`, the is used. + If `printTicket` is `null`, the is used. ]]> @@ -1782,7 +1782,7 @@ ## Remarks If the printer does not support a signal with this meaning, then the property is always `false`. - The object also has and properties. + The object also has and properties. @@ -1828,7 +1828,7 @@ to indicate that toner is low. + Some printer manufacturers may use this signal to indicate that toner is not low. Others may use it to indicate that the toner cartridge is present and properly inserted while using to indicate that toner is low. If the printer does not support a signal with this meaning, then the property is always `false`. @@ -2809,7 +2809,7 @@ . + Some printer manufacturers support this signal instead of the less specific . If the printer does not support a signal with this meaning, then the property is always `false`. @@ -3330,11 +3330,11 @@ The merged ticket is then checked against the actual capabilities of the printer. If any settings in the ticket are incompatible with the printer's capabilities, then the printer driver changes those settings by using whatever logic it wants. Typically, it substitutes the user's or printer's default value for the setting. It the driver's source of substitute values is not the same ticket as `basePrintTicket`, then the merged ticket might have some settings that are different from both of the input tickets. If the printer driver has to change any settings then this fact is reported in the property of the . - To merge and validate based on a print queue's default settings, you should set `basePrintTicket` to the or the . + To merge and validate based on a print queue's default settings, you should set `basePrintTicket` to the or the . The `deltaPrintTicket` parameter can be `null`, in which case the `basePrintTicket` is validated, checked for viability, and returned, possibly with changes. - With this overload of , both the `deltaPrintTicket` and the in the that is returned have job wide scope. To specify a different scope use the other overload of this method. + With this overload of , both the `deltaPrintTicket` and the in the that is returned have job wide scope. To specify a different scope use the other overload of this method. @@ -3401,7 +3401,7 @@ The merged ticket is then checked against the actual capabilities of the printer. If any settings in the ticket are incompatible with the printer's capabilities, then the printer driver changes those settings by using whatever logic it wants. Typically, it substitutes the user's or printer's default value for the setting. It the driver's source of substitute values is not the same ticket as `basePrintTicket`, then the merged ticket might have some settings that are different from both of the input tickets. If the printer driver has to change any settings then this fact is reported in the property of the . - To merge and validate based on a print queue's default settings, you should set `basePrintTicket` to the or the . + To merge and validate based on a print queue's default settings, you should set `basePrintTicket` to the or the . The `deltaPrintTicket` parameter can be `null`, in which case the `basePrintTicket` is validated, checked for viability, and returned, possibly with changes. @@ -3451,7 +3451,7 @@ ## Remarks The object also has a read only property and a writeable property. - For queues on the local print server, and are the same. + For queues on the local print server, and are the same. @@ -3891,7 +3891,7 @@ object's properties are lost when executes, unless they have been written to the printer and print queue with . + Changes your program makes to a object's properties are lost when executes, unless they have been written to the printer and print queue with . @@ -4082,7 +4082,7 @@ to 12 AM in your time zone, you set it to 8 AM UTC, which is 480 (= 8 * 60). You also must remember that time rolls over to zero after 24 hours (that is; after the 1439th minute). To set it to 6 PM in your time zone, you set it to 2 AM UTC, which is 120 (= 2 * 60). See , , and classes for helpful time zone manipulating methods. + If you are not in the UTC time zone, you must add or subtract multiples of 60 to set or get the correct time for your time zone. For example, if you are in the Pacific Time Zone of North America and daylight savings time is not in effect, then your local time is 8 hours earlier than UTC. To set to 12 AM in your time zone, you set it to 8 AM UTC, which is 480 (= 8 * 60). You also must remember that time rolls over to zero after 24 hours (that is; after the 1439th minute). To set it to 6 PM in your time zone, you set it to 2 AM UTC, which is 120 (= 2 * 60). See , , and classes for helpful time zone manipulating methods. If the printer is always available, then this property returns 0 in all time zones. @@ -4133,7 +4133,7 @@ to 12 AM in your time zone, you set it to 8 AM UTC, which is 480 (= 8 * 60). You also must remember that time rolls over to zero after the 24th hour (the 1439th minute). To set it to 6 PM in your time zone, you set it to 2 AM UTC, which is 120 (= 2 * 60). See , , and classes for helpful time zone manipulating methods. + If you are not in the UTC time zone, you must add or subtract multiples of 60 to set or get the correct time for your time zone. For example, if you are in the Pacific Time Zone of North America and daylight savings time is not in effect, then your local time is 8 hours earlier than UTC. To set to 12 AM in your time zone, you set it to 8 AM UTC, which is 480 (= 8 * 60). You also must remember that time rolls over to zero after the 24th hour (the 1439th minute). To set it to 6 PM in your time zone, you set it to 2 AM UTC, which is 120 (= 2 * 60). See , , and classes for helpful time zone manipulating methods. If the printer is always available, then this property returns 0 in all time zones. diff --git a/xml/System.Printing/PrintQueueCollection.xml b/xml/System.Printing/PrintQueueCollection.xml index 8d810a32e95..ac10c054e47 100644 --- a/xml/System.Printing/PrintQueueCollection.xml +++ b/xml/System.Printing/PrintQueueCollection.xml @@ -297,7 +297,7 @@ only when you need to customize iteration, such as by skipping every other member. + We recommend that you use the `foreach` statement to iterate through all members of the collection. Use only when you need to customize iteration, such as by skipping every other member. @@ -346,7 +346,7 @@ ## Remarks We recommend that you use the `foreach` statement to iterate through all members of the collection. Use your own enumerator object only when you need to customize iteration, such as by skipping every other member. - If you need your own enumerator, we recommend that you use the generic, type-safe function instead of . The is public only to fulfill the requirements of the interface, which is implemented by this collection. + If you need your own enumerator, we recommend that you use the generic, type-safe function instead of . The is public only to fulfill the requirements of the interface, which is implemented by this collection. ]]> @@ -421,7 +421,7 @@ ## Remarks -We recommend that you use the `foreach` statement to iterate through all members of the collection. Use only when you need to customize iteration, such as by skipping every other member. +We recommend that you use the `foreach` statement to iterate through all members of the collection. Use only when you need to customize iteration, such as by skipping every other member. ]]> diff --git a/xml/System.Printing/PrintQueueStream.xml b/xml/System.Printing/PrintQueueStream.xml index 899030e1897..ec2d3dc38e2 100644 --- a/xml/System.Printing/PrintQueueStream.xml +++ b/xml/System.Printing/PrintQueueStream.xml @@ -27,7 +27,7 @@ array, you can also use two of the overloads of the method and the property to write to the spool file. + Use this class to write device specific information to a spool file that is not automatically included by the Microsoft Windows spooler. Of course, you need to know whether the spool file is Enhanced Metafile (EMF) or XML Paper Specification (XPS). If you prefer working with a array, you can also use two of the overloads of the method and the property to write to the spool file. > [!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. @@ -379,7 +379,7 @@ method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the unnamed Boolean parameter set to `true`. `Finalize` invokes `Dispose` with the unnamed Boolean parameter set to `false`. + This method is called by the method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the unnamed Boolean parameter set to `true`. `Finalize` invokes `Dispose` with the unnamed Boolean parameter set to `false`. When the unnamed Boolean parameter is `true`, this method releases all resources that are held by any managed objects that this references. This method invokes the `Dispose()` method of each referenced object. @@ -426,7 +426,7 @@ must be called exactly once on every that is returned from a call to . + must be called exactly once on every that is returned from a call to . ]]> @@ -468,7 +468,7 @@ . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + This method overrides . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. For more information, see [Finalize Methods and Destructors](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/0s71x931(v%3dvs.100)), [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged), and [Overriding the Finalize Method](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/ddae83kx(v=vs.100)). @@ -791,7 +791,7 @@ to work. + A stream must support both writing and seeking for to work. Use the property to determine whether the current instance supports writing, and use the property to determine whether seeking is supported. diff --git a/xml/System.Printing/PrintQueueStringProperty.xml b/xml/System.Printing/PrintQueueStringProperty.xml index 39007afb0f1..8dc9deec370 100644 --- a/xml/System.Printing/PrintQueueStringProperty.xml +++ b/xml/System.Printing/PrintQueueStringProperty.xml @@ -24,16 +24,16 @@ Represents one, and only one, of three possible properties of a print queue: , , or . - methods of a . This method makes it possible to install a print queue while initializing only one of its three major properties. Having three separate overloads of the method is not possible because they would have the same signature and no two overloads of a method can have the same signature. If you want to install a print queue and initialize two or more of its major string properties, there is another overload, , that substitutes three parameters for the parameter. These parameters are used to set the major String properties in this order: , , and . Use an empty string for a parameter that corresponds to a property you do not want to initialize. - + methods of a . This method makes it possible to install a print queue while initializing only one of its three major properties. Having three separate overloads of the method is not possible because they would have the same signature and no two overloads of a method can have the same signature. If you want to install a print queue and initialize two or more of its major string properties, there is another overload, , that substitutes three parameters for the parameter. These parameters are used to set the major String properties in this order: , , and . Use an empty string for a parameter that corresponds to a property you do not want to initialize. + > [!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. - - If you want to print from a Windows Forms application, see the namespace. - +> 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. + ]]> @@ -106,11 +106,11 @@ Gets or sets the value of the print queue property that is represented. A with the value of the property. - is , the might be "Department Supply Room"; but if the is , the might be "Use only A4 size paper with this printer." - + is , the might be "Department Supply Room"; but if the is , the might be "Use only A4 size paper with this printer." + ]]> @@ -148,11 +148,11 @@ Gets or sets a value that identifies which of the three possible properties of a print queue is being represented. A that specifies the kind of print queue property that is being represented. - method of a uses this information to ensure that the value is assigned to the correct property of the being installed. - + method of a uses this information to ensure that the value is assigned to the correct property of the being installed. + ]]> diff --git a/xml/System.Printing/PrintServer.xml b/xml/System.Printing/PrintServer.xml index 20a2ccacba8..b6783608bb1 100644 --- a/xml/System.Printing/PrintServer.xml +++ b/xml/System.Printing/PrintServer.xml @@ -25,26 +25,26 @@ Manages the print queues on a print server, which is usually a computer, but can be a dedicated hardware print server appliance. - , that change has no effect until it is passed on to the computer that is represented by the object. To commit changes, use the method for the object. - - Similarly, other applications may change the actual print service properties of the computer. To make sure that the object for your program has the latest values, use the method for the object. - + , that change has no effect until it is passed on to the computer that is represented by the object. To commit changes, use the method for the object. + + Similarly, other applications may change the actual print service properties of the computer. To make sure that the object for your program has the latest values, use the method for the object. + > [!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. - - If you want to print from a Windows Forms application, see the namespace. - - - -## Examples - The following example shows how to create an instance of . - +> 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 create an instance of . + :::code language="csharp" source="~/snippets/csharp/System.Printing/PrintServer/Overview/PrintServerCreate.cs" id="Snippet_createprintserver"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PrintServerCreate/visualbasic/printservercreate.vb" id="Snippet_createprintserver"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PrintServerCreate/visualbasic/printservercreate.vb" id="Snippet_createprintserver"::: + ]]> @@ -112,11 +112,11 @@ A value that specifies the type of print server access that your program needs. Initializes a new instance of the class that represents the local print server and assigns it the specified . - will be initialized with the local print server's properties, such as . - + will be initialized with the local print server's properties, such as . + ]]> @@ -150,19 +150,19 @@ The name and complete path of the print server. Initializes a new instance of the class that has the specified path. - will represent the local print server and will be initialized with its properties, such as . - - - -## Examples - The following example shows how to use this constructor to create an instance of . - + will represent the local print server and will be initialized with its properties, such as . + + + +## Examples + The following example shows how to use this constructor to create an instance of . + :::code language="csharp" source="~/snippets/csharp/System.Printing/PrintServer/Overview/PrintServerCreate.cs" id="Snippet_createprintserver"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PrintServerCreate/visualbasic/printservercreate.vb" id="Snippet_createprintserver"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PrintServerCreate/visualbasic/printservercreate.vb" id="Snippet_createprintserver"::: + ]]> @@ -196,11 +196,11 @@ The properties that the constructor initializes. Initializes a new instance of the class by using the specified array to determine which properties will be initialized. - will represent the local print server and will be initialized with its properties, such as . - + will represent the local print server and will be initialized with its properties, such as . + ]]> @@ -234,20 +234,20 @@ A value that specifies the type of print server access that your program needs. Initializes a new instance of the class that has the specified path and the needed access. - will represent the local print server and will be initialized with its properties, such as . - - - -## Examples - The following example shows how to use this constructor to survey all printers for possible error status. - + will represent the local print server and will be initialized with its properties, such as . + + + +## Examples + The following example shows how to use this constructor to survey all printers for possible error status. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Wpf/PrinterStatusSurvey/CPP/Program.cpp" id="Snippetsurveyqueues"::: :::code language="csharp" source="~/snippets/csharp/System.Printing/PrintQueue/HasPaperProblem/Program.cs" id="Snippetsurveyqueues"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PrinterStatusSurvey/visualbasic/program.vb" id="Snippetsurveyqueues"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PrinterStatusSurvey/visualbasic/program.vb" id="Snippetsurveyqueues"::: + ]]> @@ -283,11 +283,11 @@ An array of the names of properties that the constructor initializes. Initializes a new instance of the class that has the specified path and properties filter. - will represent the local print server and will be initialized with its properties, such as . - + will represent the local print server and will be initialized with its properties, such as . + ]]> @@ -323,11 +323,11 @@ A value that specifies the type of print server access that your program needs. Initializes a new instance of the class and provides the specified path, the array, and the needed access. - will represent the local print server and will be initialized with its properties, such as . - + will represent the local print server and will be initialized with its properties, such as . + ]]> @@ -365,11 +365,11 @@ A value that specifies the type of print server access that your program needs. Initializes a new instance of the class that has the specified path, properties filter, and the needed access. - will represent the local print server and will be initialized with its properties, such as . - + will represent the local print server and will be initialized with its properties, such as . + ]]> @@ -434,18 +434,18 @@ Commits any changes that your program made to the properties of the print server object by writing them to the print server that the object represents. - object be created with rights. - + object be created with rights. + ]]> Some of the properties are not committed. - Some of the properties could not be committed. - + Some of the properties could not be committed. + -or- - + The object was not created with sufficient rights. @@ -757,14 +757,14 @@ Gets the collection of print queues that the print server hosts. The of print queues on the print server. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.Printing/PrintServer/Overview/PrintServerCreate.cs" id="Snippet_createprintserver"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PrintServerCreate/visualbasic/printservercreate.vb" id="Snippet_createprintserver"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PrintServerCreate/visualbasic/printservercreate.vb" id="Snippet_createprintserver"::: + ]]> @@ -800,15 +800,15 @@ Gets the collection of print queues of the specified types that are named in and hosted by the print server. The of print queues, of the specified types, on the print server. - @@ -912,11 +912,11 @@ Gets a collection of print queues of the specified types. These print queues are only initialized in the properties that are specified in the array. The of the print server. - array. - + array. + ]]> @@ -1004,14 +1004,14 @@ Installs a print queue, and associated printer driver, on the print server. The new . - object that inherits the method from ) to install a second printer that differs in its properties from an existing printer only in location, port, and shared status. - + object that inherits the method from ) to install a second printer that differs in its properties from an existing printer only in location, port, and shared status. + :::code language="csharp" source="~/snippets/csharp/System.Printing/LocalPrintServer/.ctor/Program.cs" id="Snippetcloneprinter"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/ClonePrinter/visualbasic/program.vb" id="Snippetcloneprinter"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/ClonePrinter/visualbasic/program.vb" id="Snippetcloneprinter"::: + ]]> @@ -1102,11 +1102,11 @@ Installs a prioritized print queue, and associated printer driver, on the print server. The newly created . - , , or properties. If you want to initialize more than one, use the overload of this method. - + , , or properties. If you want to initialize more than one, use the overload of this method. + ]]> @@ -1162,11 +1162,11 @@ Installs a shared, prioritized print queue, and associated printer driver, on the print server. The newly created . - , , or properties; you can pass an empty string for one or more of `printQueueShareName`, `printQueueComment`, and `printQueueLocation`. If you want to initialize just one of these properties, use the overload of this method. - + , , or properties; you can pass an empty string for one or more of `printQueueShareName`, `printQueueComment`, and `printQueueLocation`. If you want to initialize just one of these properties, use the overload of this method. + ]]> @@ -1403,11 +1403,11 @@ Gets or sets the thread priority for the process that manages I/O through the printer ports. A enumeration value that identifies the thread priority for the process that manages the printer ports. The default is . - @@ -1439,11 +1439,11 @@ Updates the properties of the object so that each property value matches the corresponding attribute value of the print server that the object represents. - can be lost when the method executes. This loss occurs if you did not yet write the changes to the print server that the object represents with . - + can be lost when the method executes. This loss occurs if you did not yet write the changes to the print server that the object represents with . + ]]> Some of the properties cannot be refreshed. @@ -1478,11 +1478,11 @@ if jobs can be restarted when printer pooling is enabled; otherwise, . - @@ -1514,11 +1514,11 @@ Gets or sets a value that indicates the wait time before a job can be restarted, if an error occurs when printer pooling is also enabled. The wait time, in minutes, before a job restarts. - @@ -1579,11 +1579,11 @@ Gets the version of the print spooler system. A that identifies the version of the print spooler system. - except that the latter is a type . - + except that the latter is a type . + ]]> diff --git a/xml/System.Printing/PrintSystemJobInfo.xml b/xml/System.Printing/PrintSystemJobInfo.xml index 001b34f396d..8b5cf33f996 100644 --- a/xml/System.Printing/PrintSystemJobInfo.xml +++ b/xml/System.Printing/PrintSystemJobInfo.xml @@ -28,13 +28,13 @@ object, use the static method or one of the following instance methods: , , or . + This class has no public constructor. To get a reference to a object, use the static method or one of the following instance methods: , , or . - Many print job properties, such as whether a job is completed, must be passed from the printer to the object before your application reads the corresponding property (). The method provides this functionality. + Many print job properties, such as whether a job is completed, must be passed from the printer to the object before your application reads the corresponding property (). The method provides this functionality. - Similarly, when your application changes the value of the property, the change must be written to the print queue utility on the computer. The method provides this functionality. + Similarly, when your application changes the value of the property, the change must be written to the print queue utility on the computer. The method provides this functionality. - If you derive a class from that has additional writable properties, then you must implement an override of the and methods. + If you derive a class from that has additional writable properties, then you must implement an override of the and methods. > [!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. @@ -115,7 +115,7 @@ property is writable. If you derive a class from that has additional writable properties, you must override the and methods with implementations of your own. + Only the property is writable. If you derive a class from that has additional writable properties, you must override the and methods with implementations of your own. ]]> @@ -158,7 +158,7 @@ method for the same purpose. + You can also use the method for the same purpose. ]]> @@ -386,7 +386,7 @@ object only *represents* a real print job. Deleting the latter from its print queue does not automatically dispose of the object in your application. Similarly, the object is not removed from any that was created before the print job it represents was deleted. For example, if the method is run before the print job was deleted, the returned collection will include a object that represents the print job. This object is not removed from the collection when the print job is deleted. But if is then run again, the returned collection will have no members that represent the deleted print jobs. + It may seem paradoxical at first that an object can report its own status as deleted, but keep in mind that the object only *represents* a real print job. Deleting the latter from its print queue does not automatically dispose of the object in your application. Similarly, the object is not removed from any that was created before the print job it represents was deleted. For example, if the method is run before the print job was deleted, the returned collection will include a object that represents the print job. This object is not removed from the collection when the print job is deleted. But if is then run again, the returned collection will have no members that represent the deleted print jobs. @@ -601,7 +601,7 @@ can be `false` even when the value of the property is `true`. + The entire print queue can also be paused. For example, the value of can be `false` even when the value of the property is `true`. @@ -731,7 +731,7 @@ method, which resumes a job at the point it was paused. + When a job is restarted, it prints in its entirety. Contrast restarting with using the method, which resumes a job at the point it was paused. ]]> @@ -771,7 +771,7 @@ property of the object is set to `true` and if the properties of the queue have been committed with the method of the . + A print queue retains printed jobs if the property of the object is set to `true` and if the properties of the queue have been committed with the method of the . ]]> @@ -1012,7 +1012,7 @@ and . + This method gives you a means to avoid individually checking each of the status properties, such as and . @@ -1173,7 +1173,7 @@ ## Remarks If another job is in the queue, it begins printing when the current job is paused. - The hosting also has and methods. If the print queue is paused, resuming an individual job does not cause that job to resume printing. + The hosting also has and methods. If the print queue is paused, resuming an individual job does not cause that job to resume printing. ]]> @@ -1269,9 +1269,9 @@ object must be written to the actual print job by using the method. Any changes that you have not committed are lost when the method runs. + Any changes that you make to the properties of a object must be written to the actual print job by using the method. Any changes that you have not committed are lost when the method runs. - If you derive a class from that has additional properties, then you must override the method with an implementation of your own. + If you derive a class from that has additional properties, then you must override the method with an implementation of your own. ]]> @@ -1308,7 +1308,7 @@ method, which restarts a paused print job, starting at the point it was paused. + Optionally, you can use the method, which restarts a paused print job, starting at the point it was paused. ]]> @@ -1344,7 +1344,7 @@ also has and methods. If the print queue is paused, resuming an individual job does not resume the printing of the print job. + The hosting also has and methods. If the print queue is paused, resuming an individual job does not resume the printing of the print job. @@ -1391,13 +1391,13 @@ object from the property of the hosting at the time the job enters the queue. If is changed, then any value that is earlier than is changed to the value of . + This value is propagated to each object from the property of the hosting at the time the job enters the queue. If is changed, then any value that is earlier than is changed to the value of . - After the job is added to the queue, it can be given a new value through the Microsoft Windows user interface (UI), provided that it is not earlier than . + After the job is added to the queue, it can be given a new value through the Microsoft Windows user interface (UI), provided that it is not earlier than . - If you are not in the UTC time zone, you must add or subtract multiples of 60 to get the correct time for your time zone. For example, if you are in the Pacific Time Zone of North America and daylight savings time is not in effect, then your local time is 8 hours earlier than UTC. If returns 960, that means 16:00 (4:00 PM) in UTC (because 960/60 = 16). To convert this to Pacific Time, you must subtract 480 (= 8 * 60) minutes. + If you are not in the UTC time zone, you must add or subtract multiples of 60 to get the correct time for your time zone. For example, if you are in the Pacific Time Zone of North America and daylight savings time is not in effect, then your local time is 8 hours earlier than UTC. If returns 960, that means 16:00 (4:00 PM) in UTC (because 960/60 = 16). To convert this to Pacific Time, you must subtract 480 (= 8 * 60) minutes. - You also must remember that time rolls over to zero after 24 hours (that is; after the 1439th minute). If returns 120, that means 2:00 AM in UTC. To convert this to Pacific Time, you must subtract 480 minutes, which results in -360. To get a positive value that has meaning, add the negative number to the total minutes in a day, 1440, resulting in a final value of 1080 (6:00 PM) Pacific Time. + You also must remember that time rolls over to zero after 24 hours (that is; after the 1439th minute). If returns 120, that means 2:00 AM in UTC. To convert this to Pacific Time, you must subtract 480 minutes, which results in -360. To get a positive value that has meaning, add the negative number to the total minutes in a day, 1440, resulting in a final value of 1080 (6:00 PM) Pacific Time. See , , and for methods that help make time-zone adjustments. @@ -1550,13 +1550,13 @@ object from the property of the hosting at the time the job enters the queue. If is changed, then any value that is later than is changed to the value of . + This value is propagated to each object from the property of the hosting at the time the job enters the queue. If is changed, then any value that is later than is changed to the value of . - After the job is added to the queue, it can be given a new value through the Microsoft Windows user interface (UI), provided that it is not later than . + After the job is added to the queue, it can be given a new value through the Microsoft Windows user interface (UI), provided that it is not later than . - If you are not in the UTC time zone, you must add or subtract multiples of 60 to get the correct time for your time zone. For example, if you are in the Pacific Time Zone of North America and daylight savings time is not in effect, then your local time is 8 hours earlier than UTC. If returns 960, that means 16:00 (4:00 PM) in UTC (because 960/60 = 16). To convert this to Pacific Time, you must subtract 480 (= 8 * 60) minutes. + If you are not in the UTC time zone, you must add or subtract multiples of 60 to get the correct time for your time zone. For example, if you are in the Pacific Time Zone of North America and daylight savings time is not in effect, then your local time is 8 hours earlier than UTC. If returns 960, that means 16:00 (4:00 PM) in UTC (because 960/60 = 16). To convert this to Pacific Time, you must subtract 480 (= 8 * 60) minutes. - You also must remember that time rolls over to zero after 24 hours (that is; after the 1439th minute). If returns 120, that means 2:00 AM in UTC. To convert this to Pacific Time, you must subtract 480 minutes, which results in -360. To get a positive value that has meaning, add the negative number to the total minutes in a day, 1440, resulting in a final value of 1080 (6:00 PM) Pacific Time. + You also must remember that time rolls over to zero after 24 hours (that is; after the 1439th minute). If returns 120, that means 2:00 AM in UTC. To convert this to Pacific Time, you must subtract 480 minutes, which results in -360. To get a positive value that has meaning, add the negative number to the total minutes in a day, 1440, resulting in a final value of 1080 (6:00 PM) Pacific Time. See , , and for methods that help make time-zone adjustments. diff --git a/xml/System.Printing/PrintSystemObject.xml b/xml/System.Printing/PrintSystemObject.xml index cd9c9e9641a..7a7247c60b6 100644 --- a/xml/System.Printing/PrintSystemObject.xml +++ b/xml/System.Printing/PrintSystemObject.xml @@ -32,7 +32,7 @@ collection of different object types, calling the method on each of them in turn. + In addition to being the base class for print system objects, this class can be useful for calling methods when your application does not know or does not care what particular type of print system object it is using. For example, you could enumerate through a collection of different object types, calling the method on each of them in turn. > [!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. @@ -169,7 +169,7 @@ class, will write changes that are made to the object's properties to the actual computer that the object represents. + For example, when overridden by the class, will write changes that are made to the object's properties to the actual computer that the object represents. @@ -233,7 +233,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 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. ]]> @@ -337,7 +337,7 @@ method acts as a safeguard to clean up resources in the event that the method is not called. You should implement the method to clean up only unmanaged resources. You should not implement this method for managed objects, because the garbage collector cleans up managed resources automatically. + The method acts as a safeguard to clean up resources in the event that the method is not called. You should implement the method to clean up only unmanaged resources. You should not implement this method for managed objects, because the garbage collector cleans up managed resources automatically. ]]> @@ -611,7 +611,7 @@ of the derived class executes. The loss will occur if the changes have not yet been written to the actual software or hardware component, by using the derived class' implementation of . + Any changes that you have made to the properties of an object of the derived class may be lost when the of the derived class executes. The loss will occur if the changes have not yet been written to the actual software or hardware component, by using the derived class' implementation of . ]]> diff --git a/xml/System.Printing/PrintSystemObjectPropertiesChangedEventArgs.xml b/xml/System.Printing/PrintSystemObjectPropertiesChangedEventArgs.xml index c393091146f..45bf70f4e3e 100644 --- a/xml/System.Printing/PrintSystemObjectPropertiesChangedEventArgs.xml +++ b/xml/System.Printing/PrintSystemObjectPropertiesChangedEventArgs.xml @@ -167,7 +167,7 @@ method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the unnamed Boolean parameter set to `true`. `Finalize` invokes `Dispose` with the parameter set to `false`. + This method is called by the method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the unnamed Boolean parameter set to `true`. `Finalize` invokes `Dispose` with the parameter set to `false`. When the Boolean parameter is `true`, this method releases all resources that are held by any managed objects that this references. This method invokes the `Dispose()` method of each referenced object. diff --git a/xml/System.Printing/PrintSystemObjectPropertyChangedEventArgs.xml b/xml/System.Printing/PrintSystemObjectPropertyChangedEventArgs.xml index 4a38bbd921b..312854fbc0d 100644 --- a/xml/System.Printing/PrintSystemObjectPropertyChangedEventArgs.xml +++ b/xml/System.Printing/PrintSystemObjectPropertyChangedEventArgs.xml @@ -119,7 +119,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 that 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 are not freed until the garbage collector calls the method of the object. +> Always call before you release your last reference to the . Otherwise, the resources it is using are not freed until the garbage collector calls the method of the object. ]]> @@ -167,7 +167,7 @@ method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the unnamed Boolean parameter set to `true`. `Finalize` invokes `Dispose` with the parameter set to `false`. + This method is called by the method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the unnamed Boolean parameter set to `true`. `Finalize` invokes `Dispose` with the parameter set to `false`. When the Boolean parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose()` method of each referenced object. diff --git a/xml/System.Printing/PrintSystemObjects.xml b/xml/System.Printing/PrintSystemObjects.xml index f4b8d94b7ae..c1eadd1f40e 100644 --- a/xml/System.Printing/PrintSystemObjects.xml +++ b/xml/System.Printing/PrintSystemObjects.xml @@ -122,7 +122,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 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. ]]> @@ -170,7 +170,7 @@ method and the method, if it has been overridden. invokes the protected method with the unnamed Boolean parameter set to `true`. `Finalize` invokes with the parameter set to `false`. + This method is called by the public method and the method, if it has been overridden. invokes the protected method with the unnamed Boolean parameter set to `true`. `Finalize` invokes with the parameter set to `false`. When the Boolean parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose()` method of each referenced object. diff --git a/xml/System.Printing/PrintTicket.xml b/xml/System.Printing/PrintTicket.xml index 2fad15f9453..547ae18d62a 100644 --- a/xml/System.Printing/PrintTicket.xml +++ b/xml/System.Printing/PrintTicket.xml @@ -139,7 +139,7 @@ When any of the properties of the are written to, this non-public PrintTicket document is changed as well. - It is this non-public PrintTicket document that is returned by the and methods. + It is this non-public PrintTicket document that is returned by the and methods. ]]> @@ -210,7 +210,7 @@ (see and ) will not contain any markup for this feature. + A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `DocumentCollate` keyword, not the `JobCollateAllDocuments` keyword. @@ -260,7 +260,7 @@ (see and ) will not contain any markup for this feature. + A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `JobCopiesAllDocuments` keyword, not the `DocumentCopiesAllPages` keyword, or the `PageCopies` keyword. @@ -301,7 +301,7 @@ (see and ) will not contain any markup for this feature. + A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageDeviceFontSubstitution` keyword. @@ -342,7 +342,7 @@ (see and ) will not contain any markup for this feature. + A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `JobDuplexAllDocumentsContiguously` keyword, not the `DocumentDuplex` keyword. @@ -431,7 +431,7 @@ (see and ) will not contain any markup for this feature. That is, there will be no markup for the [Print Schema](/windows/win32/printdocs/printschema)'s features `JobInputBin`, `DocumentInputBin`, or `PageInputBin`. + A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. That is, there will be no markup for the [Print Schema](/windows/win32/printdocs/printschema)'s features `JobInputBin`, `DocumentInputBin`, or `PageInputBin`. When this property is not `null`, it will have the following relationships to the features defined in the [Print Schema](/windows/win32/printdocs/printschema). @@ -480,7 +480,7 @@ (see and ) will not contain any markup for this feature. + A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageOutputColor` keyword. @@ -529,7 +529,7 @@ (see and ) will not contain any markup for this feature. + A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageOutputQuality` keyword. @@ -570,7 +570,7 @@ (see and ) will not contain any markup for this feature. + A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageBorderless` keyword. @@ -666,7 +666,7 @@ (see and ) will not contain any markup for this feature. + A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageMediaType` keyword. @@ -707,7 +707,7 @@ (see and ) will not contain any markup for this feature. + A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `JobPageOrder` keyword. @@ -748,7 +748,7 @@ (see and ) will not contain any markup for this feature. + A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageOrientation` keyword. @@ -847,9 +847,9 @@ . + The printer can have maximum and minimum limits for scaling. You can test for scale limits by using . - A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. + A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. This property generally represents the **Scale** `ScoredProperty` of the [Print Schema](/windows/win32/printdocs/printschema)'s `PageScaling` keyword. But there are some complexities as follows. @@ -904,7 +904,7 @@ ## Remarks Most printers support only a limited range of specific possibilities, such as 1, 2, 4, 6, 8, and 16 pages per side. You can test for the options that the printer supports by using the property. - A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. + A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. This property corresponds to the **PagesPerSheet**`ScoredProperty` of the [Print Schema](/windows/win32/printdocs/printschema)'s `JobNUpAllDocumentsContiguously` keyword, not the `DocumentNUp` keyword. @@ -947,7 +947,7 @@ ## Remarks For example, a printer can present pages in left-to-right rows with rows stacked top-to-bottom. - A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. + A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. This property corresponds to the **PresentationDirection** subfeature of the [Print Schema](/windows/win32/printdocs/printschema)'s `JobNUpAllDocumentsContiguously` keyword, not the `DocumentNUp` keyword. @@ -990,7 +990,7 @@ ## Remarks The photographic printer driver translates the qualitative expression in this property into specific quantitative values for resolution and other factors. - A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. + A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PagePhotoPrintingIntent` keyword. @@ -1109,7 +1109,7 @@ ## Remarks For example, a printer can place two staples on the left edge of a sheet of paper, or one staple in the upper left corner. - A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. + A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `JobStapleAllDocuments` keyword, not the `DocumentStaple` keyword. @@ -1159,7 +1159,7 @@ (see and ) will not contain any markup for this feature. + A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageTrueTypeFontMode` keyword. diff --git a/xml/System.Printing/PrintTicketScope.xml b/xml/System.Printing/PrintTicketScope.xml index f9683c7f5d4..b5da9991fb4 100644 --- a/xml/System.Printing/PrintTicketScope.xml +++ b/xml/System.Printing/PrintTicketScope.xml @@ -29,13 +29,13 @@ Specifies whether a applies to an entire print job, one document within the print job, or just a page within the print job. - method of a . - - The values in this enumeration parallel the **PrintTicket** keyword scoping prefix in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397), where in the **PrintTicket** every keyword must start with either the "Job" or "Document" or "Page" scoping prefix. - + method of a . + + The values in this enumeration parallel the **PrintTicket** keyword scoping prefix in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397), where in the **PrintTicket** every keyword must start with either the "Job" or "Document" or "Page" scoping prefix. + ]]> diff --git a/xml/System.Printing/PrintingNotSupportedException.xml b/xml/System.Printing/PrintingNotSupportedException.xml index 2df694db91c..8e3bc841539 100644 --- a/xml/System.Printing/PrintingNotSupportedException.xml +++ b/xml/System.Printing/PrintingNotSupportedException.xml @@ -91,8 +91,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The localized error message string.| +||`null`.| +||The localized error message string.| ]]> @@ -133,8 +133,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| ]]> @@ -224,8 +224,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| ]]> diff --git a/xml/System.Printing/Stapling.xml b/xml/System.Printing/Stapling.xml index e69c528e95b..0d43b65819f 100644 --- a/xml/System.Printing/Stapling.xml +++ b/xml/System.Printing/Stapling.xml @@ -28,7 +28,7 @@ ## Remarks Use the values of this type primarily for these purposes: -- As members of the collection, which is a property of , these values indicate the types of stapling that a printer supports. +- As members of the collection, which is a property of , these values indicate the types of stapling that a printer supports. - As the value of the property of a , the value instructs the printer whether, and where, to staple. diff --git a/xml/System.Printing/TrueTypeFontMode.xml b/xml/System.Printing/TrueTypeFontMode.xml index 78ced5eff16..2b222d37479 100644 --- a/xml/System.Printing/TrueTypeFontMode.xml +++ b/xml/System.Printing/TrueTypeFontMode.xml @@ -40,7 +40,7 @@ Use the values of this type for these purposes: -- As members of the collection, which is a property of , these values indicate which of the preceding techniques is available for a particular printer. Many printers support more than one of these techniques. +- As members of the collection, which is a property of , these values indicate which of the preceding techniques is available for a particular printer. Many printers support more than one of these techniques. - As the value of the property of a , the value instructs the printer to handle TrueType fonts in a particular way. From 98f42d18c0ec73059af547ef709bc697e70145c6 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 2 Apr 2026 13:40:27 -0700 Subject: [PATCH 4/4] more unencodings --- xml/System.Printing/PrintServer.xml | 4 +- .../ContentInfo.xml | 2 +- xml/System.Security.Cryptography/AesCng.xml | 2 +- .../TripleDESCng.xml | 2 +- .../ServiceHostFactory.xml | 74 +++++++++---------- xml/System.ServiceModel.Channels/Binding.xml | 4 +- .../MessageEncoder.xml | 2 +- .../MessageFilterTable`1.xml | 4 +- xml/System.ServiceModel/ClientBase`1.xml | 2 +- .../OperationBehaviorAttribute.xml | 2 +- .../ServiceBehaviorAttribute.xml | 2 +- xml/System.ServiceModel/ServiceHost.xml | 8 +- xml/System.ServiceProcess/ServiceBase.xml | 2 +- xml/System.Speech.Recognition/Choices.xml | 4 +- .../SemanticResultKey.xml | 2 +- .../SemanticResultValue.xml | 2 +- xml/System.Text.RegularExpressions/Regex.xml | 22 +++--- xml/System.Text/EncoderFallbackBuffer.xml | 2 +- xml/System.Text/Encoding.xml | 28 +++---- xml/System.Text/StringBuilder.xml | 8 +- xml/System.Text/UTF32Encoding.xml | 2 +- xml/System.Text/UTF8Encoding.xml | 2 +- xml/System.Text/UnicodeEncoding.xml | 4 +- .../ActionBlock`1.xml | 2 +- xml/System.Threading.Tasks/Parallel.xml | 2 +- xml/System.Threading.Tasks/Task.xml | 32 ++++---- xml/System.Threading.Tasks/TaskFactory.xml | 8 +- xml/System.Threading.Tasks/TaskFactory`1.xml | 2 +- xml/System.Threading.Tasks/Task`1.xml | 24 +++--- .../AsyncLocalValueChangedArgs`1.xml | 2 +- xml/System.Threading/CancellationToken.xml | 2 +- .../CancellationTokenSource.xml | 4 +- xml/System.Threading/Thread.xml | 2 +- xml/System.Threading/WaitHandle.xml | 12 +-- 34 files changed, 139 insertions(+), 139 deletions(-) diff --git a/xml/System.Printing/PrintServer.xml b/xml/System.Printing/PrintServer.xml index b6783608bb1..0acb6a0da72 100644 --- a/xml/System.Printing/PrintServer.xml +++ b/xml/System.Printing/PrintServer.xml @@ -1105,7 +1105,7 @@ , , or properties. If you want to initialize more than one, use the overload of this method. + Use the `printQueueProperty` parameter to initialize one, and only one, of the queue's , , or properties. If you want to initialize more than one, use the overload of this method. ]]> @@ -1165,7 +1165,7 @@ , , or properties; you can pass an empty string for one or more of `printQueueShareName`, `printQueueComment`, and `printQueueLocation`. If you want to initialize just one of these properties, use the overload of this method. + If you do not want to initialize all three of the queue's , , or properties; you can pass an empty string for one or more of `printQueueShareName`, `printQueueComment`, and `printQueueLocation`. If you want to initialize just one of these properties, use the overload of this method. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/ContentInfo.xml b/xml/System.Security.Cryptography.Pkcs/ContentInfo.xml index 2d85f1d0bf0..4b018e2798f 100644 --- a/xml/System.Security.Cryptography.Pkcs/ContentInfo.xml +++ b/xml/System.Security.Cryptography.Pkcs/ContentInfo.xml @@ -142,7 +142,7 @@ ## Remarks The digestedData and encryptedData content types, which appear in the CMS/PKCS #7 standards document, are not content types that can be produced by this implementation. However these content types can be passed to this constructor. - Use the following OID strings as arguments to the constructor to build the `contentType` content type parameter. + Use the following OID strings as arguments to the constructor to build the `contentType` content type parameter. |`contentType` content type|OID string| |--------------------------------|----------------| diff --git a/xml/System.Security.Cryptography/AesCng.xml b/xml/System.Security.Cryptography/AesCng.xml index 5aa6e6d21d7..43b2cf47068 100644 --- a/xml/System.Security.Cryptography/AesCng.xml +++ b/xml/System.Security.Cryptography/AesCng.xml @@ -459,7 +459,7 @@ This method decrypts an encrypted message created using the overload with the same signature. + This method decrypts an encrypted message created using the overload with the same signature. > [!NOTE] > If you've created the object using an existing persisted key and you want to make use of that key when decrypting the message, you want to set the property and then call the parameterless overload instead; otherwise, using this method will create an ephemeral key as specified by the `rgbKey` parameter. diff --git a/xml/System.Security.Cryptography/TripleDESCng.xml b/xml/System.Security.Cryptography/TripleDESCng.xml index 1c155e97312..1aa9e3fc444 100644 --- a/xml/System.Security.Cryptography/TripleDESCng.xml +++ b/xml/System.Security.Cryptography/TripleDESCng.xml @@ -427,7 +427,7 @@ overload with the same signature. + This method decrypts an encrypted message created using the overload with the same signature. > [!NOTE] > If you've created the object using an existing persisted key and you want to make use of that key when decrypting the message, you want to set the property and then call the parameterless overload instead; otherwise, using this method will create an ephemeral key as specified by the `rgbKey` parameter. diff --git a/xml/System.ServiceModel.Activation/ServiceHostFactory.xml b/xml/System.ServiceModel.Activation/ServiceHostFactory.xml index a1deed43af2..1edace68709 100644 --- a/xml/System.ServiceModel.Activation/ServiceHostFactory.xml +++ b/xml/System.ServiceModel.Activation/ServiceHostFactory.xml @@ -29,23 +29,23 @@ Factory that provides instances of in managed hosting environments where the host instance is created dynamically in response to incoming messages. - , consider also implementing a factory that derives from the class. - - If you have implemented a custom derivative of instead, then consider also implementing a factory that derives your factory from directly. - - - -## Examples - This examples show how to use the class: - + , consider also implementing a factory that derives from the class. + + If you have implemented a custom derivative of instead, then consider also implementing a factory that derives your factory from directly. + + + +## Examples + This examples show how to use the class: + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/servicehostfactory/cs/program.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/servicehostfactory/vb/program.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/servicehostfactory/vb/program.vb" id="Snippet0"::: + ]]> @@ -69,14 +69,14 @@ Initializes a new instance of the class. - : - + : + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/servicehostfactory/cs/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/servicehostfactory/vb/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/servicehostfactory/vb/program.vb" id="Snippet1"::: + ]]> @@ -119,14 +119,14 @@ Creates a with specific base addresses and initializes it with specified data. A with specific base addresses. - method: - + method: + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/servicehostfactory/cs/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/servicehostfactory/vb/program.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/servicehostfactory/vb/program.vb" id="Snippet3"::: + ]]> @@ -163,13 +163,13 @@ Creates a for a specified type of service with a specific base address. A for the type of service specified with a specific base address. - method: - - - + method: + + + ]]> diff --git a/xml/System.ServiceModel.Channels/Binding.xml b/xml/System.ServiceModel.Channels/Binding.xml index 64fafba94dc..e52d590469b 100644 --- a/xml/System.ServiceModel.Channels/Binding.xml +++ b/xml/System.ServiceModel.Channels/Binding.xml @@ -744,7 +744,7 @@ and catch the exception generated if it cannot be built. + Use this method if you want to check that the channel factory for channels of type `TChannel` can be build for the binding `parameters` specified before attempting to actually build the factory. Alternatively, try to build the channel factory by calling and catch the exception generated if it cannot be built. ]]> @@ -856,7 +856,7 @@ and catch the exception generated if it cannot be built. + Use this method if you want to check that the channel listener for channels of type `TChannel` can be build for the binding `parameters` specified before attempting to actually build the listener. Alternatively, try to build the channel listener by calling and catch the exception generated if it cannot be built. ]]> diff --git a/xml/System.ServiceModel.Channels/MessageEncoder.xml b/xml/System.ServiceModel.Channels/MessageEncoder.xml index 83994f8731f..826ce1d6fa5 100644 --- a/xml/System.ServiceModel.Channels/MessageEncoder.xml +++ b/xml/System.ServiceModel.Channels/MessageEncoder.xml @@ -578,7 +578,7 @@ method. + The following code example shows how to implement the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ue_customtextmessageencoder/cs/customtextmessageencoder.cs" id="Snippet4"::: diff --git a/xml/System.ServiceModel.Dispatcher/MessageFilterTable`1.xml b/xml/System.ServiceModel.Dispatcher/MessageFilterTable`1.xml index f3c7909a63b..7de52c1b5c4 100644 --- a/xml/System.ServiceModel.Dispatcher/MessageFilterTable`1.xml +++ b/xml/System.ServiceModel.Dispatcher/MessageFilterTable`1.xml @@ -1162,7 +1162,7 @@ myFilters(filter) ## Remarks If the filter key of the `item` is present but is associated with data that differs from the `FilterData`, the method fails to remove the filter and returns `false`. - This method implements . + This method implements . ]]> @@ -1201,7 +1201,7 @@ myFilters(filter) . + This method implements . ]]> diff --git a/xml/System.ServiceModel/ClientBase`1.xml b/xml/System.ServiceModel/ClientBase`1.xml index df19ff241b2..f7e87d912be 100644 --- a/xml/System.ServiceModel/ClientBase`1.xml +++ b/xml/System.ServiceModel/ClientBase`1.xml @@ -1098,7 +1098,7 @@ , and when each operation is completed, your event handler can determine which instance of the operation raised the completion event. + Provide a unique value, such as a GUID or hash code, in the `userState` parameter for each call to , and when each operation is completed, your event handler can determine which instance of the operation raised the completion event. ]]> diff --git a/xml/System.ServiceModel/OperationBehaviorAttribute.xml b/xml/System.ServiceModel/OperationBehaviorAttribute.xml index cba71f14e77..9cf6a357662 100644 --- a/xml/System.ServiceModel/OperationBehaviorAttribute.xml +++ b/xml/System.ServiceModel/OperationBehaviorAttribute.xml @@ -234,7 +234,7 @@ You can also use to configure a callback contract operation in a duplex client application. When used on a callback operation, the property must be or an exception is thrown at runtime. - In addition, it is important to realize that if the service is created by passing a service object to the constructor, the value of this property is treated as if it were . + In addition, it is important to realize that if the service is created by passing a service object to the constructor, the value of this property is treated as if it were . diff --git a/xml/System.ServiceModel/ServiceBehaviorAttribute.xml b/xml/System.ServiceModel/ServiceBehaviorAttribute.xml index a9ea34d1b77..2fcb4bea19e 100644 --- a/xml/System.ServiceModel/ServiceBehaviorAttribute.xml +++ b/xml/System.ServiceModel/ServiceBehaviorAttribute.xml @@ -761,7 +761,7 @@ public void MyMethod() ## Remarks Note that you must explicitly set to `false` if there is an operation with set to true and you set to . Otherwise a validation exception is thrown because the default value of is `true`. - In addition, it is important to realize that if the service is created by passing a service object to the constructor, the value of this property is treated as if it were `false`. + In addition, it is important to realize that if the service is created by passing a service object to the constructor, the value of this property is treated as if it were `false`. diff --git a/xml/System.ServiceModel/ServiceHost.xml b/xml/System.ServiceModel/ServiceHost.xml index 36e7eb1c292..14256d0f470 100644 --- a/xml/System.ServiceModel/ServiceHost.xml +++ b/xml/System.ServiceModel/ServiceHost.xml @@ -72,7 +72,7 @@ class. Use the constructor which takes the service type as an input parameter, most of the time. The host can use this to create new services as needed. Use the constructor instead only when you want the service host to use a specific singleton instance of the service. + There are two constructors used to create an instance of the class. Use the constructor which takes the service type as an input parameter, most of the time. The host can use this to create new services as needed. Use the constructor instead only when you want the service host to use a specific singleton instance of the service. ]]> @@ -158,7 +158,7 @@ constructor instead only when you want the service host to use a specific singleton instance of the service. + Use this constructor when you have the service type and you can create new instances of it when needed, even when you need a singleton instance. Use the constructor instead only when you want the service host to use a specific singleton instance of the service. @@ -418,7 +418,7 @@ , to implement the customized model. + This method is used to construct contract descriptions from customized programming models. Override the corresponding base class method, , to implement the customized model. ]]> @@ -577,7 +577,7 @@ protected override void OnClosed() constructor to initialize a singleton instance of the service to be hosted when you want to control the instance of the service that is used. + Use the constructor to initialize a singleton instance of the service to be hosted when you want to control the instance of the service that is used. ]]> diff --git a/xml/System.ServiceProcess/ServiceBase.xml b/xml/System.ServiceProcess/ServiceBase.xml index be4cd5b6fc7..b19d01c1b4b 100644 --- a/xml/System.ServiceProcess/ServiceBase.xml +++ b/xml/System.ServiceProcess/ServiceBase.xml @@ -1152,7 +1152,7 @@ , the Service Control Manager issues Start commands, which result in calls to the methods in the services. The services are not started until the Start commands are executed. + Call this overload in the `main()` function of the service executable to register the services with the Service Control Manager. After you call , the Service Control Manager issues Start commands, which result in calls to the methods in the services. The services are not started until the Start commands are executed. The method is called in much the same way as the method for Windows Forms applications. diff --git a/xml/System.Speech.Recognition/Choices.xml b/xml/System.Speech.Recognition/Choices.xml index 29736e859ee..49bb9470117 100644 --- a/xml/System.Speech.Recognition/Choices.xml +++ b/xml/System.Speech.Recognition/Choices.xml @@ -387,7 +387,7 @@ public Grammar CreatePhonePhrase() If `alternateChoices` is an empty array, this method does not update the set of alternatives. - Applications can use both and to add alternatives to a object. + Applications can use both and to add alternatives to a object. This method throws an when `alternateChoices` is `null` or any of the array elements are `null`. @@ -468,7 +468,7 @@ public Grammar CreatePhonePhrase() and to add alternatives to a object. + Applications can use both and to add alternatives to a object. If `phrases` is an empty array, this method does not update the set of alternates. diff --git a/xml/System.Speech.Recognition/SemanticResultKey.xml b/xml/System.Speech.Recognition/SemanticResultKey.xml index 89b489e4cf7..d05aee17439 100644 --- a/xml/System.Speech.Recognition/SemanticResultKey.xml +++ b/xml/System.Speech.Recognition/SemanticResultKey.xml @@ -341,7 +341,7 @@ private void keyTest() ## Examples The following example creates a object that supports commands to change the background color. - A object (`colorChoice`) containing the list of options for background colors is filled using the method with instances. The instances are obtained through the method on the objects created from color strings. + A object (`colorChoice`) containing the list of options for background colors is filled using the method with instances. The instances are obtained through the method on the objects created from color strings. A is then obtained by calling on a instance, which will be used to key the semantic choices in `colorChoice`. diff --git a/xml/System.Speech.Recognition/SemanticResultValue.xml b/xml/System.Speech.Recognition/SemanticResultValue.xml index 7dd01c04901..b68b18cceff 100644 --- a/xml/System.Speech.Recognition/SemanticResultValue.xml +++ b/xml/System.Speech.Recognition/SemanticResultValue.xml @@ -480,7 +480,7 @@ private Grammar FgBgColorGrammar() ## Examples The following example creates objects that support commands to change the background color. - A object (`colorChoice`) containing the list of options for background colors is filled using the method with instances that are obtained from the method on the `SemanticResultValue` objects created from color strings. + A object (`colorChoice`) containing the list of options for background colors is filled using the method with instances that are obtained from the method on the `SemanticResultValue` objects created from color strings. A is then obtained by calling on a instance, which will be used to key the semantic choices in the `colorChoice` instance. diff --git a/xml/System.Text.RegularExpressions/Regex.xml b/xml/System.Text.RegularExpressions/Regex.xml index f5d847c84d8..4a41c0c4922 100644 --- a/xml/System.Text.RegularExpressions/Regex.xml +++ b/xml/System.Text.RegularExpressions/Regex.xml @@ -973,7 +973,7 @@ For more information about this API, see [Supplemental API remarks for Regex](/d method generates a .NET Framework assembly in which each regular expression defined in the `regexinfos` array is represented by a class. Typically, the method is called from a separate application that generates an assembly of compiled regular expressions. Each regular expression included in the assembly has the following characteristics: + The method generates a .NET Framework assembly in which each regular expression defined in the `regexinfos` array is represented by a class. Typically, the method is called from a separate application that generates an assembly of compiled regular expressions. Each regular expression included in the assembly has the following characteristics: - It is derived from the class. @@ -1083,7 +1083,7 @@ For more information about this API, see [Supplemental API remarks for Regex](/d method generates a .NET Framework assembly in which each regular expression defined in the `regexinfos` array is represented by a class. Typically, the method is called from a separate application that generates an assembly of compiled regular expressions. Each regular expression included in the assembly has the following characteristics: + The method generates a .NET Framework assembly in which each regular expression defined in the `regexinfos` array is represented by a class. Typically, the method is called from a separate application that generates an assembly of compiled regular expressions. Each regular expression included in the assembly has the following characteristics: - It is derived from the class. @@ -1105,7 +1105,7 @@ For more information about this API, see [Supplemental API remarks for Regex](/d 5. Instantiate a object by passing its constructor the object retrieved in step 3 and the array created in step 4. - You can then pass an array of these objects instead of the `attributes` parameter to the method. + You can then pass an array of these objects instead of the `attributes` parameter to the method. @@ -1218,7 +1218,7 @@ For more information about this API, see [Supplemental API remarks for Regex](/d method generates a .NET Framework assembly in which each regular expression defined in the `regexinfos` array is represented by a class. Typically, the method is called from a separate application that generates an assembly of compiled regular expressions. Each regular expression included in the assembly has the following characteristics: + The method generates a .NET Framework assembly in which each regular expression defined in the `regexinfos` array is represented by a class. Typically, the method is called from a separate application that generates an assembly of compiled regular expressions. Each regular expression included in the assembly has the following characteristics: - It is derived from the class. @@ -1240,7 +1240,7 @@ For more information about this API, see [Supplemental API remarks for Regex](/d 5. Instantiate a object by passing its constructor the object retrieved in step 3 and the array created in step 4. - You can then pass an array of these objects instead of the `attributes` parameter to the method. + You can then pass an array of these objects instead of the `attributes` parameter to the method. ]]> @@ -5483,7 +5483,7 @@ For more details about `startat`, see the Remarks section of delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. + The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replace5.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Replace/replace5.vb" id="Snippet2"::: @@ -5917,7 +5917,7 @@ For more details about `startat`, see the Remarks section of delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. The call to the method includes the option so that the comment in the regular expression pattern `\w+ # Matches all the characters in a word.` is ignored by the regular expression engine. + The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. The call to the method includes the option so that the comment in the regular expression pattern `\w+ # Matches all the characters in a word.` is ignored by the regular expression engine. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replace6.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Replace/replace6.vb" id="Snippet10"::: @@ -6250,7 +6250,7 @@ For more details about `startat`, see the Remarks section of delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. The call to the method includes the option so that the comment in the regular expression pattern `\w+ # Matches all the characters in a word.` is ignored by the regular expression engine. + The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. The call to the method includes the option so that the comment in the regular expression pattern `\w+ # Matches all the characters in a word.` is ignored by the regular expression engine. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replace13.cs" id="Snippet13"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Replace/replace13.vb" id="Snippet13"::: @@ -6451,7 +6451,7 @@ For more details about `startat`, see the Remarks section of methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original input string. + The methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original input string. If multiple matches are adjacent to one another, an empty string is inserted into the array. For example, splitting a string on a single hyphen causes the returned array to include an empty string in the position where two adjacent hyphens are found, as the following code shows. @@ -6828,7 +6828,7 @@ For more details about `startat`, see the Remarks section of methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original `input` string. + The methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original `input` string. The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). @@ -6929,7 +6929,7 @@ For more details about `startat`, see the Remarks section of methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original `input` string. + The methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original `input` string. The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). diff --git a/xml/System.Text/EncoderFallbackBuffer.xml b/xml/System.Text/EncoderFallbackBuffer.xml index dd5ae770077..9457077c2ea 100644 --- a/xml/System.Text/EncoderFallbackBuffer.xml +++ b/xml/System.Text/EncoderFallbackBuffer.xml @@ -197,7 +197,7 @@ and methods call if they encounter an unknown input character that cannot be encoded. A return value of `true` indicates that the fallback buffer can process the input character, which causes the calling method to call the method to obtain each character of the fallback buffer. Because it does not process individual characters, the method in an exception fallback handler throws an exception. + The and methods call if they encounter an unknown input character that cannot be encoded. A return value of `true` indicates that the fallback buffer can process the input character, which causes the calling method to call the method to obtain each character of the fallback buffer. Because it does not process individual characters, the method in an exception fallback handler throws an exception. ]]> diff --git a/xml/System.Text/Encoding.xml b/xml/System.Text/Encoding.xml index 04ef4276487..a93cca969cc 100644 --- a/xml/System.Text/Encoding.xml +++ b/xml/System.Text/Encoding.xml @@ -2575,9 +2575,9 @@ For more information about this API, see to store the resulting characters, you should use the method. To calculate the maximum array size, you should use the method. The method generally allows allocation of less memory, while the method generally executes faster. + To calculate the exact array size required by to store the resulting characters, you should use the method. To calculate the maximum array size, you should use the method. The method generally allows allocation of less memory, while the method generally executes faster. - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. Several versions of and are supported. The following are some programming considerations for use of these methods: @@ -2587,7 +2587,7 @@ For more information about this API, see method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. @@ -2750,7 +2750,7 @@ For more information about this API, see allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. @@ -2952,7 +2952,7 @@ For more information about this API, see allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. @@ -3118,7 +3118,7 @@ For more information about this API, see allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. @@ -3326,7 +3326,7 @@ For more information about this API, see allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. @@ -4394,7 +4394,7 @@ In .NET 5 and later versions, the code page name `utf-7` is not supported. Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. ## Examples - The following example reads a UTF-8 encoded string from a binary file represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. + The following example reads a UTF-8 encoded string from a binary file represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetString/getstring1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoding/GetString/getstring1.vb" id="Snippet2"::: @@ -4638,7 +4638,7 @@ The goal is to save this file, then open and decode it as a binary stream. See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. ## Examples - The following example reads a UTF-8 encoded string from a binary file that is represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. + The following example reads a UTF-8 encoded string from a binary file that is represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetString/getstring2.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoding/GetString/getstring2.vb" id="Snippet3"::: diff --git a/xml/System.Text/StringBuilder.xml b/xml/System.Text/StringBuilder.xml index e0337d1c523..0cda6ad8ad2 100644 --- a/xml/System.Text/StringBuilder.xml +++ b/xml/System.Text/StringBuilder.xml @@ -837,7 +837,7 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet6"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet6"::: @@ -2249,7 +2249,7 @@ The following example shows how to call many of the methods defined by the method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + The method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet7"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet7"::: @@ -3033,7 +3033,7 @@ The index of a format item is less than 0 (zero), or greater than or equal to th - A object that provides culture-specific formatting information for date and time values in `args`. -- A custom implementation that provides formatting information for one or more of the objects in `args`. Typically, such an implementation also implements the interface. The second example in the next section illustrates an method call with a custom implementation. +- A custom implementation that provides formatting information for one or more of the objects in `args`. Typically, such an implementation also implements the interface. The second example in the next section illustrates an method call with a custom implementation. If the `provider` parameter is `null`, format provider information is obtained from the current culture. @@ -3048,7 +3048,7 @@ The index of a format item is less than 0 (zero), or greater than or equal to th :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/StringBuilder/AppendFormat/appfmt.vb" id="Snippet1"::: - The following example defines a custom implementation named `CustomerFormatter` that formats a 10-digit customer number with hyphens after the fourth and seventh digits. It is passed to the method to create a string that includes the formatted customer number and customer name. + The following example defines a custom implementation named `CustomerFormatter` that formats a 10-digit customer number with hyphens after the fourth and seventh digits. It is passed to the method to create a string that includes the formatted customer number and customer name. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/customernumberformatter1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/customernumberformatter1.fs" id="Snippet1"::: diff --git a/xml/System.Text/UTF32Encoding.xml b/xml/System.Text/UTF32Encoding.xml index 55902cb9351..83d80759736 100644 --- a/xml/System.Text/UTF32Encoding.xml +++ b/xml/System.Text/UTF32Encoding.xml @@ -652,7 +652,7 @@ ## Examples - The following example populates an array with a Latin uppercase and lowercase characters and calls the method to determine the number of bytes needed to encode the Latin lowercase characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Latin lowercase characters. The following example populates an array with a combination of Greek and Cyrillic characters and calls the method to determine the number of bytes needed to encode the Cyrillic characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Cyrillic characters. + The following example populates an array with a Latin uppercase and lowercase characters and calls the method to determine the number of bytes needed to encode the Latin lowercase characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Latin lowercase characters. The following example populates an array with a combination of Greek and Cyrillic characters and calls the method to determine the number of bytes needed to encode the Cyrillic characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Cyrillic characters. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/GetByteCount/getbytecount2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF32Encoding/GetByteCount/getbytecount2.vb" id="Snippet2"::: diff --git a/xml/System.Text/UTF8Encoding.xml b/xml/System.Text/UTF8Encoding.xml index f6c0b45820c..68691a89f08 100644 --- a/xml/System.Text/UTF8Encoding.xml +++ b/xml/System.Text/UTF8Encoding.xml @@ -706,7 +706,7 @@ ## Examples - The following example populates an array with a Latin uppercase and lowercase characters and calls the method to determine the number of bytes needed to encode the Latin lowercase characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Latin lowercase characters. + The following example populates an array with a Latin uppercase and lowercase characters and calls the method to determine the number of bytes needed to encode the Latin lowercase characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Latin lowercase characters. :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetByteCount/getbytecount2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UTF8Encoding/GetByteCount/getbytecount2.vb" id="Snippet2"::: diff --git a/xml/System.Text/UnicodeEncoding.xml b/xml/System.Text/UnicodeEncoding.xml index a222add878a..faafe2d89ea 100644 --- a/xml/System.Text/UnicodeEncoding.xml +++ b/xml/System.Text/UnicodeEncoding.xml @@ -730,12 +730,12 @@ With error detection enabled, an invalid sequence causes this method to throw an . Without error detection, invalid sequences are ignored, and no exception is thrown. - To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble Is not reflected in the value returned by the method. + To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble Is not reflected in the value returned by the method. ## Examples - The following example populates an array with a Latin uppercase and lowercase characters and calls the method to determine the number of bytes needed to encode the Latin lowercase characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Latin lowercase characters. The following example populates an array with a combination of Greek and Cyrillic characters and calls the method to determine the number of bytes needed to encode the Cyrillic characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Cyrillic characters. + The following example populates an array with a Latin uppercase and lowercase characters and calls the method to determine the number of bytes needed to encode the Latin lowercase characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Latin lowercase characters. The following example populates an array with a combination of Greek and Cyrillic characters and calls the method to determine the number of bytes needed to encode the Cyrillic characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Cyrillic characters. :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetByteCount/getbytecount2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/UnicodeEncoding/GetByteCount/getbytecount2.vb" id="Snippet2"::: diff --git a/xml/System.Threading.Tasks.Dataflow/ActionBlock`1.xml b/xml/System.Threading.Tasks.Dataflow/ActionBlock`1.xml index 58afc7672c0..5b21b04fb0d 100644 --- a/xml/System.Threading.Tasks.Dataflow/ActionBlock`1.xml +++ b/xml/System.Threading.Tasks.Dataflow/ActionBlock`1.xml @@ -189,7 +189,7 @@ constructor to create a new object. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) topic. + The following example shows how to use the constructor to create a new object. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) topic. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks.Dataflow/ActionBlock`1/dataflowdegreeofparallelism.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_degreeofparallelism/vb/dataflowdegreeofparallelism.vb" id="Snippet2"::: diff --git a/xml/System.Threading.Tasks/Parallel.xml b/xml/System.Threading.Tasks/Parallel.xml index f9135bfcb10..704aa9c77f1 100644 --- a/xml/System.Threading.Tasks/Parallel.xml +++ b/xml/System.Threading.Tasks/Parallel.xml @@ -1639,7 +1639,7 @@ ## Examples - The following example uses the method to count the number of vowels and non-white-space characters in a text file. In this case, the value returned by the method is ignored. Note that, because operations can run in parallel, you must ensure that incrementing the counter variables is an atomic operation, and that multiple threads do not attempt to access the counter variables simultaneously. For this purpose, the example uses the `lock` statement (in C#) and the `SyncLock` statement (in Visual Basic). + The following example uses the method to count the number of vowels and non-white-space characters in a text file. In this case, the value returned by the method is ignored. Note that, because operations can run in parallel, you must ensure that incrementing the counter variables is an atomic operation, and that multiple threads do not attempt to access the counter variables simultaneously. For this purpose, the example uses the `lock` statement (in C#) and the `SyncLock` statement (in Visual Basic). :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Parallel/ForEachTSource/foreach1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Parallel/ForEachTSource/foreach1.vb" id="Snippet1"::: diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index bac63e0168b..ab75a43c6af 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -158,7 +158,7 @@ If a task with no action is needed just for the consumer of an API to have something to await, a should be used. ## Examples - The following example uses the constructor to create tasks that retrieve the filenames in specified directories. All tasks write the file names to a single object. The example then calls the method to ensure that all tasks have completed, and then displays a count of the total number of file names written to the object. + The following example uses the constructor to create tasks that retrieve the filenames in specified directories. All tasks write the file names to a single object. The example then calls the method to ensure that all tasks have completed, and then displays a count of the total number of file names written to the object. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/ctor1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/ctor1.fs" id="Snippet1"::: @@ -353,10 +353,10 @@ object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ## Examples - The following example defines an array of 6-letter words. Each word is then passed as an argument to the constructor, whose delegate scrambles the characters in the word, then displays the original word and its scrambled version. + The following example defines an array of 6-letter words. Each word is then passed as an argument to the constructor, whose delegate scrambles the characters in the word, then displays the original word and its scrambled version. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/startnew3.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/startnew3.fs" id="Snippet3"::: @@ -487,7 +487,7 @@ object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -553,7 +553,7 @@ object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -621,7 +621,7 @@ object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -915,7 +915,7 @@ When an asynchronous method awaits a directly ## Examples - The following example defines a task that populates an array with 100 random date and time values. It uses the method to select the earliest and the latest date values once the array is fully populated. + The following example defines a task that populates an array with 100 random date and time values. It uses the method to select the earliest and the latest date values once the array is fully populated. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/ContinueWith/continuewith1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/ContinueWith/continuewith1.fs" id="Snippet1"::: @@ -3207,7 +3207,7 @@ Task t Status: RanToCompletion, Result: 42 > [!NOTE] > Starting with .NET Framework 4.5, the method provides the easiest way to create a object with default configuration values. - The following example uses the static property to make two calls to the method. The first populates an array with the names of files in the user's MyDocuments directory, while the second populates an array with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the two arrays after the first two tasks have completed execution. + The following example uses the static property to make two calls to the method. The first populates an array with the names of files in the user's MyDocuments directory, while the second populates an array with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the two arrays after the first two tasks have completed execution. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Factory/factory1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Factory/factory1.fs" id="Snippet1"::: @@ -3982,7 +3982,7 @@ This method is intended for compiler use rather than use directly in code. The call to the method ensures that the task completes and displays its output before the application ends. Otherwise, it is possible that the `Main` method will complete before the task finishes. - The following example illustrates the method. It defines an array of directory names and starts a separate task to retrieve the file names in each directory. All tasks write the file names to a single object. The example then calls the method to ensure that all tasks have completed, and then displays a count of the total number of file names written to the object. + The following example illustrates the method. It defines an array of directory names and starts a separate task to retrieve the file names in each directory. All tasks write the file names to a single object. The example then calls the method to ensure that all tasks have completed, and then displays a count of the total number of file names written to the object. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run2.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run2.fs" id="Snippet1"::: @@ -4363,7 +4363,7 @@ This method is intended for compiler use rather than use directly in code. ## Examples - The following example counts the approximate number of words in text files that represent published books. Each task is responsible for opening a file, reading its entire contents asynchronously, and calculating the word count by using a regular expression. The method is called to ensure that all tasks have completed before displaying the word count of each book to the console. + The following example counts the approximate number of words in text files that represent published books. Each task is responsible for opening a file, reading its entire contents asynchronously, and calculating the word count by using a regular expression. The method is called to ensure that all tasks have completed before displaying the word count of each book to the console. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run31.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run31.fs" id="Snippet2"::: @@ -6545,7 +6545,7 @@ An exception was thrown during The overloads of the method that return a object are typically called when you are interested in the status of a set of tasks or in the exceptions thrown by a set of tasks. > [!NOTE] -> The call to method does not block the calling thread. +> The call to method does not block the calling thread. If any of the supplied tasks completes in a faulted state, the returned task will also complete in a state, where its exceptions will contain the aggregation of the set of unwrapped exceptions from each of the supplied tasks. @@ -6558,7 +6558,7 @@ An exception was thrown during ## Examples - The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. + The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/WhenAll/WhenAll4.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/WhenAll/WhenAll4.fs" id="Snippet4"::: @@ -6691,7 +6691,7 @@ An exception was thrown during The overloads of the method that return a object are typically called when you are interested in the status of a set of tasks or in the exceptions thrown by a set of tasks. > [!NOTE] -> The call to method does not block the calling thread. +> The call to method does not block the calling thread. If any of the supplied tasks completes in a faulted state, the returned task will also complete in a state, where its exceptions will contain the aggregation of the set of unwrapped exceptions from each of the supplied tasks. @@ -6704,7 +6704,7 @@ An exception was thrown during ## Examples - The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is converted to an array and passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. + The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is converted to an array and passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/WhenAll/WhenAll3.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/WhenAll/WhenAll3.fs" id="Snippet3"::: @@ -6777,7 +6777,7 @@ An exception was thrown during method does not block the calling thread. However, a call to the returned property does block the calling thread. + The call to method does not block the calling thread. However, a call to the returned property does block the calling thread. If any of the supplied tasks completes in a faulted state, the returned task will also complete in a state, where its exceptions will contain the aggregation of the set of unwrapped exceptions from each of the supplied tasks. @@ -6945,7 +6945,7 @@ An exception was thrown during method does not block the calling thread. However, a call to the returned property does block the calling thread. + The call to method does not block the calling thread. However, a call to the returned property does block the calling thread. If any of the supplied tasks completes in a faulted state, the returned task will also complete in a state, where its exceptions will contain the aggregation of the set of unwrapped exceptions from each of the supplied tasks. diff --git a/xml/System.Threading.Tasks/TaskFactory.xml b/xml/System.Threading.Tasks/TaskFactory.xml index ee1c50fd607..d75b8ca6610 100644 --- a/xml/System.Threading.Tasks/TaskFactory.xml +++ b/xml/System.Threading.Tasks/TaskFactory.xml @@ -98,7 +98,7 @@ In most cases, you do not have to instantiate a new instance. Instead, you can use the property, which returns a factory object that uses default values. You can then call its methods to start new tasks or define task continuations. For an illustration, see the example. ## Examples - The following example uses the static property to make two calls to the method. The first populates an array with the names of files in the user's MyDocuments directory, while the second populates an array with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the two arrays after the first two tasks have completed execution. + The following example uses the static property to make two calls to the method. The first populates an array with the names of files in the user's MyDocuments directory, while the second populates an array with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the two arrays after the first two tasks have completed execution. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Factory/factory1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Task/Factory/factory1.vb" id="Snippet1"::: @@ -581,7 +581,7 @@ ## Remarks The method executes the `continuationAction` delegate when all tasks in the `tasks` array have completed, regardless of their completion status. - Exceptions thrown by tasks in the `tasks` array are not available to the continuation task through structured exception handling. You can determine which exceptions were thrown by examining the property of each task in the `tasks` array. To use structured exception handling to handle exceptions thrown by tasks in the `tasks` array, call the method. + Exceptions thrown by tasks in the `tasks` array are not available to the continuation task through structured exception handling. You can determine which exceptions were thrown by examining the property of each task in the `tasks` array. To use structured exception handling to handle exceptions thrown by tasks in the `tasks` array, call the method. @@ -6290,7 +6290,7 @@ The NotOn\* and OnlyOn\* , ## Remarks Calling is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can call the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + Starting with the .NET Framework 4.5, you can call the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. @@ -6450,7 +6450,7 @@ The NotOn\* and OnlyOn\* , ## Remarks Calling is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. + Starting with the .NET Framework 4.5, you can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. diff --git a/xml/System.Threading.Tasks/TaskFactory`1.xml b/xml/System.Threading.Tasks/TaskFactory`1.xml index 2660b7d3ac4..bf46196f50c 100644 --- a/xml/System.Threading.Tasks/TaskFactory`1.xml +++ b/xml/System.Threading.Tasks/TaskFactory`1.xml @@ -106,7 +106,7 @@ In most cases, you do not have to instantiate a new instance. Instead, you can use the static property, which returns a factory object that uses default values. You can then call its methods to start new tasks or define task continuations. For an illustration, see the example. ## Examples - The following example uses the static property to make two calls to the method. The first task returns a string array that is populated with the names of files in the user's MyDocuments directory, while the second returns a string array that is populated with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the arrays returned by the two tasks after they have completed execution. + The following example uses the static property to make two calls to the method. The first task returns a string array that is populated with the names of files in the user's MyDocuments directory, while the second returns a string array that is populated with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the arrays returned by the two tasks after they have completed execution. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Factory/factory2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Task/Factory/factory2.vb" id="Snippet2"::: diff --git a/xml/System.Threading.Tasks/Task`1.xml b/xml/System.Threading.Tasks/Task`1.xml index 5067521dc9f..cc17ba966e0 100644 --- a/xml/System.Threading.Tasks/Task`1.xml +++ b/xml/System.Threading.Tasks/Task`1.xml @@ -90,12 +90,12 @@ ## Remarks The class represents a single operation that returns a value and that usually executes asynchronously. objects are one of the central components of the [task-based asynchronous pattern](https://learn.microsoft.com/dotnet/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap) first introduced in .NET Framework 4. Because the work performed by a object typically executes asynchronously on a thread pool thread rather than synchronously on the main application thread, you can use the property, as well as the , , and properties, to determine the state of a task. Most commonly, a lambda expression is used to specify the work that the task is to perform. - instances may be created in a variety of ways. The most common approach, which is available starting with .NET Framework 4.5, is to call the static or method. These methods provide a simple way to start a task by using default values and without acquiring additional parameters. The following example uses the method to start a task that loops and then displays the number of loop iterations: + instances may be created in a variety of ways. The most common approach, which is available starting with .NET Framework 4.5, is to call the static or method. These methods provide a simple way to start a task by using default values and without acquiring additional parameters. The following example uses the method to start a task that loops and then displays the number of loop iterations: :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskTResult/Overview/run1.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/TaskTResult/Overview/run1.vb" id="Snippet6"::: - An alternative, and the most common way to start a task in .NET Framework 4, is to call the static or method. The property returns a object, and the property returns a object. Overloads of their `StartNew` method let you pass arguments, define task creation options, and specify a task scheduler. The following example uses the method to start a task. It is functionally equivalent to the code in the previous example. + An alternative, and the most common way to start a task in .NET Framework 4, is to call the static or method. The property returns a object, and the property returns a object. Overloads of their `StartNew` method let you pass arguments, define task creation options, and specify a task scheduler. The following example uses the method to start a task. It is functionally equivalent to the code in the previous example. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskTResult/Overview/startnew1.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/TaskTResult/Overview/startnew1.vb" id="Snippet7"::: @@ -175,14 +175,14 @@ For operations that do not return a value, you use the object and launch a task is by calling the static and methods. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static and methods. If a task with no action is needed just for the consumer of an API to have something to await, a should be used. ## Examples - The following example counts the approximate number of words in text files that represent published books. Each task is responsible for opening a file, reading its entire contents asynchronously, and calculating the word count by using a regular expression. The method is called to ensure that all tasks have completed before displaying the word count of each book to the console. + The following example counts the approximate number of words in text files that represent published books. Each task is responsible for opening a file, reading its entire contents asynchronously, and calculating the word count by using a regular expression. The method is called to ensure that all tasks have completed before displaying the word count of each book to the console. Object instantiation is separated from object execution in this example so that the example can ensure that each file exists. If they do not, it displays the name of the missing file. Otherwise, it calls the method to launch each task. @@ -255,7 +255,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -313,7 +313,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static and methods. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static and methods. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -372,7 +372,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -441,7 +441,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -510,7 +510,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -571,7 +571,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -643,7 +643,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -1664,7 +1664,7 @@ For operations that do not return a value, you use the object, for the state argument of the method. Each value represents the time at which the continue task is created. Each task produces as its result a second value that represents the time at which the task finishes. After all tasks finish, the example displays the date and times at which each continuation task starts and finishes. + The following example creates a chain of continuation tasks. Each task provides the current time, a object, for the state argument of the method. Each value represents the time at which the continue task is created. Each task produces as its result a second value that represents the time at which the task finishes. After all tasks finish, the example displays the date and times at which each continuation task starts and finishes. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task`1/ContinueWith/continuationstate.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl_continuationstate/vb/continuationstate.vb" id="Snippet1"::: diff --git a/xml/System.Threading/AsyncLocalValueChangedArgs`1.xml b/xml/System.Threading/AsyncLocalValueChangedArgs`1.xml index 5747f1c2e83..eb941ad552c 100644 --- a/xml/System.Threading/AsyncLocalValueChangedArgs`1.xml +++ b/xml/System.Threading/AsyncLocalValueChangedArgs`1.xml @@ -63,7 +63,7 @@ objects receives change notifications when it is instantiated by calling its constructor. + An objects receives change notifications when it is instantiated by calling its constructor. ]]> diff --git a/xml/System.Threading/CancellationToken.xml b/xml/System.Threading/CancellationToken.xml index 9711db34f6b..c4bf9d6790f 100644 --- a/xml/System.Threading/CancellationToken.xml +++ b/xml/System.Threading/CancellationToken.xml @@ -99,7 +99,7 @@ ## Examples The following example uses a random number generator to emulate a data collection application that reads 10 integral values from eleven different instruments. A value of zero indicates that the measurement has failed for one instrument, in which case the operation should be cancelled and no overall mean should be computed. -To handle the possible cancellation of the operation, the example instantiates a object that generates a cancellation token that's passed to a object. In turn, the object passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not completed because it was cancelled, the method throws an exception. +To handle the possible cancellation of the operation, the example instantiates a object that generates a cancellation token that's passed to a object. In turn, the object passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not completed because it was cancelled, the method throws an exception. :::code language="csharp" source="~/snippets/csharp/System.Threading/CancellationToken/Overview/cancel1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/CancellationToken/Overview/cancel1.vb" id="Snippet1"::: diff --git a/xml/System.Threading/CancellationTokenSource.xml b/xml/System.Threading/CancellationTokenSource.xml index 840ad8bb1e0..839604d9803 100644 --- a/xml/System.Threading/CancellationTokenSource.xml +++ b/xml/System.Threading/CancellationTokenSource.xml @@ -106,7 +106,7 @@ ## Examples The following example uses a random number generator to emulate a data collection application that reads 10 integral values from eleven different instruments. A value of zero indicates that the measurement has failed for one instrument, in which case the operation should be cancelled and no overall mean should be computed. - To handle the possible cancellation of the operation, the example instantiates a object that generates a cancellation token which is passed to a object. The object in turn passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not completed because it has been cancelled, the call to the method throws an exception. + To handle the possible cancellation of the operation, the example instantiates a object that generates a cancellation token which is passed to a object. The object in turn passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not completed because it has been cancelled, the call to the method throws an exception. :::code language="csharp" source="~/snippets/csharp/System.Threading/CancellationToken/Overview/cancel1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/CancellationToken/Overview/cancel1.vb" id="Snippet1"::: @@ -406,7 +406,7 @@ Calling this method has the same effect as calling [`Cancel(false)`](xref:System The following example uses a random number generator to emulate a data collection application that reads 10 integral values from eleven different instruments. A value of zero indicates that the measurement has failed for one instrument, in which case the operation should be cancelled and no overall mean should be computed. -To handle the possible cancellation of the operation, the example instantiates a object that generates a cancellation token which is passed to a object. The object in turn passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not because it has been cancelled, the call to the method throws an exception. +To handle the possible cancellation of the operation, the example instantiates a object that generates a cancellation token which is passed to a object. The object in turn passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not because it has been cancelled, the call to the method throws an exception. :::code language="csharp" source="~/snippets/csharp/System.Threading/CancellationToken/Overview/cancel1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/CancellationToken/Overview/cancel1.vb" id="Snippet1"::: diff --git a/xml/System.Threading/Thread.xml b/xml/System.Threading/Thread.xml index ce348343f00..b2b40271d43 100644 --- a/xml/System.Threading/Thread.xml +++ b/xml/System.Threading/Thread.xml @@ -1321,7 +1321,7 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR > The property doesn't work reliably when used with any thread other than the current thread. In .NET Framework, reading the property is reliable, although setting it for a thread other than the current thread is not. On .NET Core, an is thrown if a thread attempts to read or write the property on a different thread. > We recommend that you use the property to retrieve and set the current culture. - The returned by this property can be a neutral culture. Neutral cultures should not be used with formatting methods such as , , and . Use the method to get a specific culture, or use the property. + The returned by this property can be a neutral culture. Neutral cultures should not be used with formatting methods such as , , and . Use the method to get a specific culture, or use the property. ## Examples The following example determines whether the language of the current thread's UI culture is French. If it is not, it sets the UI culture of the current thread to English (United States). diff --git a/xml/System.Threading/WaitHandle.xml b/xml/System.Threading/WaitHandle.xml index faade36f469..2595479d998 100644 --- a/xml/System.Threading/WaitHandle.xml +++ b/xml/System.Threading/WaitHandle.xml @@ -962,7 +962,7 @@ Calling `Dispose` allows the resources used by the [!NOTE] > 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`. + Calling this method overload is equivalent to calling the method overload and specifying -1 (or ) for `millisecondsTimeout` and `true` for `exitContext`. @@ -1061,7 +1061,7 @@ Note: In the .NET for > [!NOTE] > 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`. + Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. ]]> @@ -1156,7 +1156,7 @@ Note: In the .NET for The maximum value for `timeout` is . - Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. + Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. ]]> @@ -1472,7 +1472,7 @@ The maximum value for `timeout` is state. - Calling this method overload is equivalent to calling the method overload and specifying -1 (or ) for `millisecondsTimeout` and `true` for `exitContext`. + Calling this method overload is equivalent to calling the method overload and specifying -1 (or ) for `millisecondsTimeout` and `true` for `exitContext`. @@ -1564,7 +1564,7 @@ The maximum value for `timeout` is state. - Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. + Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. ]]> @@ -1650,7 +1650,7 @@ The maximum value for `timeout` is . - Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. + Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. ]]>