diff --git a/xml/System.Collections.Generic/Comparer`1.xml b/xml/System.Collections.Generic/Comparer`1.xml index 142e8e42e66..f58106b6cca 100644 --- a/xml/System.Collections.Generic/Comparer`1.xml +++ b/xml/System.Collections.Generic/Comparer`1.xml @@ -78,24 +78,24 @@ The type of objects to compare. Provides a base class for implementations of the generic interface. - interface for use with collection classes such as the and generic classes. - - The difference between deriving from the class and implementing the interface is as follows: - -- To specify how two objects should be compared by default, implement the interface in your class. This ensures that sort operations will use the default comparison code that you provided. - -- To define a comparer to use instead of the default comparer, derive from the class. You can then use this comparer in sort operations that take a comparer as a parameter. - - The object returned by the property uses the generic interface (`IComparable` in C#, `IComparable(Of T)` in Visual Basic) to compare two objects. If type `T` does not implement the generic interface, the property returns a that uses the interface. - - - -## Examples - The following example derives a class, `BoxLengthFirst`, from the class. This comparer compares two objects of type `Box`. It sorts them first by length, then by height, and then by width. The `Box` class implements the interface to control the default comparison between two `Box` objects. This default implementation sorts first by height, then by length, and then by width. The example shows the differences between the two comparisons by sorting a list of `Box` objects first by using the `BoxLengthFirst` comparer and then by using the default comparer. - + interface for use with collection classes such as the and generic classes. + + The difference between deriving from the class and implementing the interface is as follows: + +- To specify how two objects should be compared by default, implement the interface in your class. This ensures that sort operations will use the default comparison code that you provided. + +- To define a comparer to use instead of the default comparer, derive from the class. You can then use this comparer in sort operations that take a comparer as a parameter. + + The object returned by the property uses the generic interface (`IComparable` in C#, `IComparable(Of T)` in Visual Basic) to compare two objects. If type `T` does not implement the generic interface, the property returns a that uses the interface. + + + +## Examples + The following example derives a class, `BoxLengthFirst`, from the class. This comparer compares two objects of type `Box`. It sorts them first by length, then by height, and then by width. The `Box` class implements the interface to control the default comparison between two `Box` objects. This default implementation sorts first by height, then by length, and then by width. The example shows the differences between the two comparisons by sorting a list of `Box` objects first by using the `BoxLengthFirst` comparer and then by using the default comparer. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ComparerT/Overview/program.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/ComparerT/Overview/program.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.boxcompare/vb/program.vb" id="Snippet1"::: @@ -104,11 +104,11 @@ - and may behave differently in terms of culture-sensitivity and case-sensitivity. - - For string comparisons, the class is recommended over Comparer<String>. Properties of the class return predefined instances that perform string comparisons with different combinations of culture-sensitivity and case-sensitivity. The case-sensitivity and culture-sensitivity are consistent among the members of the same instance. - - For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](/dotnet/standard/globalization-localization/). + and may behave differently in terms of culture-sensitivity and case-sensitivity. + + For string comparisons, the class is recommended over Comparer<String>. Properties of the class return predefined instances that perform string comparisons with different combinations of culture-sensitivity and case-sensitivity. The case-sensitivity and culture-sensitivity are consistent among the members of the same instance. + + For more information on culture-specific comparisons, see the namespace and Globalization and Localization. @@ -220,47 +220,47 @@ The first object to compare. The second object to compare. When overridden in a derived class, performs a comparison of two objects of the same type and returns a value indicating whether one object is less than, equal to, or greater than the other. - A signed integer that indicates the relative values of and , as shown in the following table. - - Value - - Meaning - - Less than zero - - is less than . - - Zero - - equals . - - Greater than zero - - is greater than . - + A signed integer that indicates the relative values of and , as shown in the following table. + + Value + + Meaning + + Less than zero + + is less than . + + Zero + + equals . + + Greater than zero + + is greater than . + - class. - + class. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ComparerT/Overview/program.cs" id="Snippet5"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/ComparerT/Overview/program.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.boxcompare/vb/program.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.boxcompare/vb/program.vb" id="Snippet5"::: + ]]> Type does not implement either the generic interface or the interface. - Comparing with any reference type is allowed and does not generate an exception. A null reference is considered to be less than any reference that is not null. - - For information on culture-specific comparisons, see the namespace and [Globalization and Localization](/dotnet/standard/globalization-localization/). + Comparing with any reference type is allowed and does not generate an exception. A null reference is considered to be less than any reference that is not null. + + For information on culture-specific comparisons, see the namespace and Globalization and Localization. @@ -358,26 +358,26 @@ Returns a default sort order comparer for the type specified by the generic argument. An object that inherits and serves as a sort order comparer for type . - returned by this property uses the generic interface (`IComparable` in C#, `IComparable(Of T)` in Visual Basic) to compare two objects. If type `T` does not implement the generic interface, this property returns a that uses the interface. - - - -## Examples - The following example shows how to use the property to get an object that performs the default comparison. This example is part of a larger example provided for the class. - + returned by this property uses the generic interface (`IComparable` in C#, `IComparable(Of T)` in Visual Basic) to compare two objects. If type `T` does not implement the generic interface, this property returns a that uses the interface. + + + +## Examples + The following example shows how to use the property to get an object that performs the default comparison. This example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ComparerT/Overview/program.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/ComparerT/Overview/program.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.boxcompare/vb/program.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.boxcompare/vb/program.vb" id="Snippet3"::: + ]]> - For string comparisons, the class is recommended over Comparer<String> (Comparer(Of String) in Visual Basic). Properties of the class return predefined instances that perform string comparisons with different combinations of culture-sensitivity and case-sensitivity. The case-sensitivity and culture-sensitivity are consistent among the members of the same instance. - - For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](/dotnet/standard/globalization-localization/). + For string comparisons, the class is recommended over Comparer<String> (Comparer(Of String) in Visual Basic). Properties of the class return predefined instances that perform string comparisons with different combinations of culture-sensitivity and case-sensitivity. The case-sensitivity and culture-sensitivity are consistent among the members of the same instance. + + For more information on culture-specific comparisons, see the namespace and Globalization and Localization. @@ -431,57 +431,57 @@ The first object to compare. The second object to compare. Compares two objects and returns a value indicating whether one is less than, equal to, or greater than the other. - A signed integer that indicates the relative values of and , as shown in the following table. - - Value - - Meaning - - Less than zero - - is less than . - - Zero - - equals . - - Greater than zero - - is greater than . - + A signed integer that indicates the relative values of and , as shown in the following table. + + Value + + Meaning + + Less than zero + + is less than . + + Zero + + equals . + + Greater than zero + + is greater than . + - method, so `obj` must be cast to the type specified by the generic argument `T` of the current instance. If it cannot be cast to `T`, an is thrown. - - Comparing `null` with any reference type is allowed and does not generate an exception. When sorting, `null` is considered to be less than any other object. - - - -## Examples - The following example shows how to use the method to compare two objects. This example is part of a larger example provided for the class. - + method, so `obj` must be cast to the type specified by the generic argument `T` of the current instance. If it cannot be cast to `T`, an is thrown. + + Comparing `null` with any reference type is allowed and does not generate an exception. When sorting, `null` is considered to be less than any other object. + + + +## Examples + The following example shows how to use the method to compare two objects. This example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ComparerT/Overview/program.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/ComparerT/Overview/program.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.boxcompare/vb/program.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.boxcompare/vb/program.vb" id="Snippet4"::: + ]]> - or is of a type that cannot be cast to type . - - -or- - + or is of a type that cannot be cast to type . + + -or- + and do not implement either the generic interface or the interface. - and behave differently in terms of culture-sensitivity and case-sensitivity. - - For string comparisons, the class is recommended over Comparer<String>. Properties of the class return predefined instances that perform string comparisons with different combinations of culture-sensitivity and case-sensitivity. The case-sensitivity and culture-sensitivity are consistent among the members of the same instance. - - For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](/dotnet/standard/globalization-localization/). + and behave differently in terms of culture-sensitivity and case-sensitivity. + + For string comparisons, the class is recommended over Comparer<String>. Properties of the class return predefined instances that perform string comparisons with different combinations of culture-sensitivity and case-sensitivity. The case-sensitivity and culture-sensitivity are consistent among the members of the same instance. + + For more information on culture-specific comparisons, see the namespace and Globalization and Localization. diff --git a/xml/System.ComponentModel.Design.Serialization/SerializationStore.xml b/xml/System.ComponentModel.Design.Serialization/SerializationStore.xml index f03b0f1c87c..aae32ec9455 100644 --- a/xml/System.ComponentModel.Design.Serialization/SerializationStore.xml +++ b/xml/System.ComponentModel.Design.Serialization/SerializationStore.xml @@ -207,9 +207,9 @@ - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [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)). + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. diff --git a/xml/System.ComponentModel.Design/ComponentDesigner.xml b/xml/System.ComponentModel.Design/ComponentDesigner.xml index d5e0c1b1bef..d072f422559 100644 --- a/xml/System.ComponentModel.Design/ComponentDesigner.xml +++ b/xml/System.ComponentModel.Design/ComponentDesigner.xml @@ -361,9 +361,9 @@ - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [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)). + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. diff --git a/xml/System.ComponentModel.Design/DesignSurface.xml b/xml/System.ComponentModel.Design/DesignSurface.xml index 3f2f00fbe3e..b4aa1862309 100644 --- a/xml/System.ComponentModel.Design/DesignSurface.xml +++ b/xml/System.ComponentModel.Design/DesignSurface.xml @@ -55,52 +55,52 @@ Presents a user interface for designing components. - class implements what the user perceives as a designer. is the user interface the user manipulates to change design-time features. provides a completely self-contained design surface. - - The class may be used as a stand-alone designer, or it may be coupled with the class to provide a common implementation for an application that hosts multiple objects. - - The class can be used by itself, or the user can derive a new class from it and augment the behavior. - - The class provides several design-time services automatically. The class adds all of its services in its constructor. Most of these services can be overridden by replacing them in the protected property. To replace a service, override the constructor, call base, and make any changes through the protected property. All services that are added to the service container and that implement are disposed when the design surface is disposed. The default set of replaceable services that the class provides is shown in the following table. - -|Service|Description| -|-------------|-----------------| -||Enables objects that are not part of the container's components collection to provide their own extender providers.| -||Used by to get a list of extender providers. With this service, extender providers can live outside of the container.| -||Provides designer metadata hooks. This is the primary interface for metadata filtering.| -||Provides a way to select components in the designer.| -||Provides a way to get a name for objects, even when those objects are not sited.| -||Offers the design surface itself as a service.| -||Provides a base class for getting and setting option values for a designer.| - - The following table shows the non-replaceable services provided by default. - -|Service|Description| -|-------------|-----------------| -||Raises events as changes are made to components.| -||Controls access to types, services, and transactions. Primary interface for designers.| -||Owns the set of components that are being designed. Each designer has an that owns the components.| -||Derives from and provides a way to add and remove services from the designer.| - - In addition to these services, the class also provides a single service that is available through a component's site. This service is unique for each component. The following table shows the services that cannot be replaced. - -|Service|Description| -|-------------|-----------------| -||A generic dictionary of key/value pairs that can be used to store arbitrary data about a component.| -||A container that enables a component to add additional child components to the designer. These components will be part of the design surface, but will not participate in serialization. This is useful when you want to design a control that is capable of exposing a region of itself in a designer, but you do not want the region to participate in serialization.| - - In addition to , the site also implements the following interfaces. - + class implements what the user perceives as a designer. is the user interface the user manipulates to change design-time features. provides a completely self-contained design surface. + + The class may be used as a stand-alone designer, or it may be coupled with the class to provide a common implementation for an application that hosts multiple objects. + + The class can be used by itself, or the user can derive a new class from it and augment the behavior. + + The class provides several design-time services automatically. The class adds all of its services in its constructor. Most of these services can be overridden by replacing them in the protected property. To replace a service, override the constructor, call base, and make any changes through the protected property. All services that are added to the service container and that implement are disposed when the design surface is disposed. The default set of replaceable services that the class provides is shown in the following table. + +|Service|Description| +|-------------|-----------------| +||Enables objects that are not part of the container's components collection to provide their own extender providers.| +||Used by to get a list of extender providers. With this service, extender providers can live outside of the container.| +||Provides designer metadata hooks. This is the primary interface for metadata filtering.| +||Provides a way to select components in the designer.| +||Provides a way to get a name for objects, even when those objects are not sited.| +||Offers the design surface itself as a service.| +||Provides a base class for getting and setting option values for a designer.| + + The following table shows the non-replaceable services provided by default. + +|Service|Description| +|-------------|-----------------| +||Raises events as changes are made to components.| +||Controls access to types, services, and transactions. Primary interface for designers.| +||Owns the set of components that are being designed. Each designer has an that owns the components.| +||Derives from and provides a way to add and remove services from the designer.| + + In addition to these services, the class also provides a single service that is available through a component's site. This service is unique for each component. The following table shows the services that cannot be replaced. + +|Service|Description| +|-------------|-----------------| +||A generic dictionary of key/value pairs that can be used to store arbitrary data about a component.| +||A container that enables a component to add additional child components to the designer. These components will be part of the design surface, but will not participate in serialization. This is useful when you want to design a control that is capable of exposing a region of itself in a designer, but you do not want the region to participate in serialization.| + + In addition to , the site also implements the following interfaces. + > [!CAUTION] -> Check for the existence of these interfaces, rather than use indiscriminate casting, because other site implementations may not implement them. - -|Service|Description| -|-------------|-----------------| -||Provides a way to get to the container of site-specific services. For example, is a site-specific service. With this service, you can add additional site-specific services.| - +> Check for the existence of these interfaces, rather than use indiscriminate casting, because other site implementations may not implement them. + +|Service|Description| +|-------------|-----------------| +||Provides a way to get to the container of site-specific services. For example, is a site-specific service. With this service, you can add additional site-specific services.| + ]]> @@ -188,11 +188,11 @@ The parent service provider, or if there is no parent used to resolve services. Initializes a new instance of the class. - The attached to the has been disposed. @@ -234,14 +234,14 @@ The type of root component to create. Initializes a new instance of the class. - constructor, it creates a simple designer loader that, in turn, creates a component of the given type and then ends the loading process. This is a straightforward way to create a designer, under the assumption that all saving of state will be done externally. Internally, this calls and passes the root component type. - + constructor, it creates a simple designer loader that, in turn, creates a component of the given type and then ends the loading process. This is a straightforward way to create a designer, under the assumption that all saving of state will be done externally. Internally, this calls and passes the root component type. + > [!NOTE] -> The overload is not affected by . The must be in the service container before the design surface loads. If you need access to , call the empty constructor, add the to the and call with `rootComponentType`. - +> The overload is not affected by . The must be in the service container before the design surface loads. If you need access to , call the empty constructor, add the to the and call with `rootComponentType`. + ]]> @@ -288,11 +288,11 @@ The type of root component to create. Initializes a new instance of the class. - constructor creates a simple designer loader that creates a component of the given type and then ends the loading process. This is a straightforward way to create a designer, under the assumption that all saving of state will be done externally. Internally, this calls and passes the root component type. - + constructor creates a simple designer loader that creates a component of the given type and then ends the loading process. This is a straightforward way to create a designer, under the assumption that all saving of state will be done externally. Internally, this calls and passes the root component type. + ]]> @@ -342,13 +342,13 @@ The designer loader to use for loading the designer. Begins the loading process with the given designer loader. - event to be notified when the design surface has completed loading. - - After is called, you can immediately obtain the view for the designer, because designer loaders must provide at least the root component when loading asynchronously. - + event to be notified when the design surface has completed loading. + + After is called, you can immediately obtain the view for the designer, because designer loaders must provide at least the root component when loading asynchronously. + ]]> @@ -390,16 +390,16 @@ The type of component to create in design mode. Begins the loading process. - event to be notified when the design surface has completed loading. - - After is called, you can immediately obtain the view for the designer, because designer loaders must provide at least the root component when loading asynchronously. - + event to be notified when the design surface has completed loading. + + After is called, you can immediately obtain the view for the designer, because designer loaders must provide at least the root component when loading asynchronously. + > [!NOTE] -> The method creates an instance of the component type and initializes a designer for this instance. The event is raised before this method returns. - +> The method creates an instance of the component type and initializes a designer for this instance. The event is raised before this method returns. + ]]> @@ -436,11 +436,11 @@ Gets the implementation within the design surface. The implementation within the design surface. - property holds all objects that are currently in design mode. When components are added to , their designer, if any, is loaded. The component is sited with a site that provides full access to the design surface. - + property holds all objects that are currently in design mode. When components are added to , their designer, if any, is loaded. The component is sited with a site that provides full access to the design surface. + ]]> The attached to the has been disposed. @@ -486,11 +486,11 @@ Creates an instance of a component. The newly created component. - method is called by the design surface's method to create an instance of a component. The component should be created and added to the public container on the design surface. - + method is called by the design surface's method to create an instance of a component. The component should be created and added to the public container on the design surface. + ]]> @@ -535,15 +535,15 @@ Creates a designer when a component is added to the container. An instance of the requested designer, or if no matching designer could be found. - method is called by the design surface's when a component is added to the container. This method creates a designer, but does not initialize it. When it returns, the designer is initialized by the container. - - can create two different types of designers: root designers and normal designers. A root designer is a designer for the root component in the design surface, which by definition is the first component added to the container. Root designers differ from normal designers because they are responsible for the user interface presented to the end user. Root designers typically coordinate with the rest of the designers on a design surface to provide this interface. - - The default implementation of this method delegates to , passing in as the designer type for root designers, or for normal designers. You can override this method to request a specific type of designer. - + method is called by the design surface's when a component is added to the container. This method creates a designer, but does not initialize it. When it returns, the designer is initialized by the container. + + can create two different types of designers: root designers and normal designers. A root designer is a designer for the root component in the design surface, which by definition is the first component added to the container. Root designers differ from normal designers because they are responsible for the user interface presented to the end user. Root designers typically coordinate with the rest of the designers on a design surface to provide this interface. + + The default implementation of this method delegates to , passing in as the designer type for root designers, or for normal designers. You can override this method to request a specific type of designer. + ]]> @@ -585,11 +585,11 @@ Creates an instance of the given type. The newly created object. - , searches for a constructor of type first, followed by an empty constructor. - + , searches for a constructor of type first, followed by an empty constructor. + ]]> @@ -645,11 +645,11 @@ Creates a container suitable for nesting controls or components. The nested container. - @@ -700,13 +700,13 @@ Creates a container suitable for nesting controls or components. The nested container. - method by passing a value into `containerName`. - + method by passing a value into `containerName`. + ]]> @@ -761,19 +761,19 @@ Releases the resources used by the . - method follows the standard pattern. Calling this method destroys the design surface. The protected version of this method is `virtual` and follows the normal pattern. - + method follows the standard pattern. Calling this method destroys the design surface. The protected version of this method is `virtual` and follows the normal pattern. + > [!NOTE] -> Because does not have any native code to clean up, it does not have a finalizer that calls . If you need to call , you must add a finalizer yourself. - - 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). - +> Because does not have any native code to clean up, it does not have a finalizer that calls . If you need to call , you must add a finalizer yourself. + + 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. + ]]> @@ -811,25 +811,25 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the resources used by the . - method follows the standard pattern. Calling this method destroys the design surface. The protected version of this method is `virtual` and follows the normal pattern. - + method follows the standard pattern. Calling this method destroys the design surface. The protected version of this method is `virtual` and follows the normal pattern. + > [!NOTE] -> Because does not have any native code to clean up, it does not have a finalizer that calls . If you need to call , you must add a finalizer yourself. +> Because does not have any native code to clean up, it does not have a finalizer that calls . If you need to call , you must add a finalizer yourself. This method is called by the public `Dispose()` method and the method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -877,11 +877,11 @@ Occurs when the design surface is disposed. - method on is called. - + method on is called. + ]]> @@ -957,11 +957,11 @@ Serializes changes to the design surface. - method can be called to push changes made to the design surface down to the serializer. This ensures that the design surface and its serialized state are synchronized. The actual implementation of this method is forwarded to the designer loader associated with design surface. The designer loader may choose to defer changes until is called, or it may choose to keep the serialized data up to date with all user changes. The method ensures that regardless of the model the designer loader chooses to use, the serialized state is synchronized with the actual design surface. - + method can be called to push changes made to the design surface down to the serializer. This ensures that the design surface and its serialized state are synchronized. The actual implementation of this method is forwarded to the designer loader associated with design surface. The designer loader may choose to defer changes until is called, or it may choose to keep the serialized data up to date with all user changes. The method ensures that regardless of the model the designer loader chooses to use, the serialized state is synchronized with the actual design surface. + ]]> @@ -1010,11 +1010,11 @@ Occurs when a call is made to the method of . - event is raised. - + event is raised. + ]]> @@ -1056,11 +1056,11 @@ Gets a service from the service container. An object that implements, or is a derived class of, , or if the service does not exist in the service container. - method retrieves a service in the design surface's service container. In addition, this will forward to any service provider that was given to the design surface at construction time. - + method retrieves a service in the design surface's service container. In addition, this will forward to any service provider that was given to the design surface at construction time. + ]]> @@ -1147,16 +1147,16 @@ Occurs when the designer load has completed. - event is raised for successful loads as well as unsuccessful ones. If code in this event handler throws an exception, the designer is unloaded. - - The object can be used to determine if loading succeeded, and it can also provide a list of errors that occurred during the load. - + event is raised for successful loads as well as unsuccessful ones. If code in this event handler throws an exception, the designer is unloaded. + + The object can be used to determine if loading succeeded, and it can also provide a list of errors that occurred during the load. + > [!NOTE] -> Errors can occur for successful loads as well, provided that the serialization system can tolerate errors. - +> Errors can occur for successful loads as well, provided that the serialization system can tolerate errors. + ]]> @@ -1437,11 +1437,11 @@ Gets the service container. The service container that provides all services to designers contained within the design surface. - adds default services into this service container. You can leave the default services in their present state, or you can remove them and replace them with your own. The default services are all demand-created, so there is no loss in performance for adding them at construction time. - + adds default services into this service container. You can leave the default services in their present state, or you can remove them and replace them with your own. The default services are all demand-created, so there is no loss in performance for adding them at construction time. + ]]> The attached to the has been disposed. @@ -1537,11 +1537,11 @@ Occurs when a designer is about to unload. - @@ -1575,26 +1575,26 @@ Gets the view for the root designer. The view for the root designer. - method must be called beforehand to start the loading process. It is possible to return a view before the designer loader finishes loading because the root designer, which supplies the view, is the first object created by the designer loader. If a view is unavailable, raises an exception. - - The notion of a view technology is obsolete. But, it remains in the interfaces for root designers for backward compatibility. Its use is hidden from anyone using objects. The property hides view technologies by passing the supported technologies back into the root designer. - - - -## Examples - The following code example shows how hides view technologies. - - ```csharp - IRootDesigner d; - - ViewTechnology[] supported = d.SupportedTechnologies; - + method must be called beforehand to start the loading process. It is possible to return a view before the designer loader finishes loading because the root designer, which supplies the view, is the first object created by the designer loader. If a view is unavailable, raises an exception. + + The notion of a view technology is obsolete. But, it remains in the interfaces for root designers for backward compatibility. Its use is hidden from anyone using objects. The property hides view technologies by passing the supported technologies back into the root designer. + + + +## Examples + The following code example shows how hides view technologies. + + ```csharp + IRootDesigner d; + + ViewTechnology[] supported = d.SupportedTechnologies; + return d.GetView(supported[0]); - ``` - + ``` + ]]> The design surface is not loading, the designer loader has not yet created a root designer, or the design surface finished the load, but failed. More information may available in the . @@ -1646,11 +1646,11 @@ Occurs when the method has been called on . - method, your event handler should activate the window for this design surface. - + method, your event handler should activate the window for this design surface. + ]]> diff --git a/xml/System.ComponentModel.Design/DesignSurfaceManager.xml b/xml/System.ComponentModel.Design/DesignSurfaceManager.xml index 7b0ead112f0..2645efeee73 100644 --- a/xml/System.ComponentModel.Design/DesignSurfaceManager.xml +++ b/xml/System.ComponentModel.Design/DesignSurfaceManager.xml @@ -54,13 +54,13 @@ Manages a collection of objects. - class is designed to be a container of objects. It provides common services that handle event routing between designers, property windows, and other global objects. Using is optional, but it is recommended if you intend to have several designer windows. - - The class provides several design-time services automatically. You can override each of these services by replacing them in the protected property. To replace a service, override the constructor, call base, and make any changes through the protected property. All services added to the service container that implement the interface are disposed when the design surface manager is disposed. The class provides the interface as the default service. provides a global eventing mechanism for designer events. With this mechanism, an application is informed when a designer becomes active. The service provides a collection of designers and a single place where global objects, such as the Properties window, can monitor selection change events. - + class is designed to be a container of objects. It provides common services that handle event routing between designers, property windows, and other global objects. Using is optional, but it is recommended if you intend to have several designer windows. + + The class provides several design-time services automatically. You can override each of these services by replacing them in the protected property. To replace a service, override the constructor, call base, and make any changes through the protected property. All services added to the service container that implement the interface are disposed when the design surface manager is disposed. The class provides the interface as the default service. provides a global eventing mechanism for designer events. With this mechanism, an application is informed when a designer becomes active. The service provides a collection of designers and a single place where global objects, such as the Properties window, can monitor selection change events. + ]]> @@ -177,11 +177,11 @@ Gets or sets the active designer. The active designer. - property should be set by the designer's user interface whenever a designer becomes the active window. The default implementation of this property works with the default implementation of the interface to notify interested parties that a new designer is now active. If you provide your own implementation of , you should override this property to notify your service appropriately. This property can be set to `null`, indicating that no designer is active. - + property should be set by the designer's user interface whenever a designer becomes the active window. The default implementation of this property works with the default implementation of the interface to notify interested parties that a new designer is now active. If you provide your own implementation of , you should override this property to notify your service appropriately. This property can be set to `null`, indicating that no designer is active. + ]]> @@ -305,13 +305,13 @@ Creates an instance of a design surface. A new design surface instance. - method creates a merged service provider that can satisfy service requests from both the given service provider as well as the itself. The method then passes this service provider into the method. - - After returns the design surface, the method tries to obtain the . If it is present, and if it is the instance of the service that provided by default, the method raises the event. - + method creates a merged service provider that can satisfy service requests from both the given service provider as well as the itself. The method then passes this service provider into the method. + + After returns the design surface, the method tries to obtain the . If it is present, and if it is the instance of the service that provided by default, the method raises the event. + ]]> @@ -362,11 +362,11 @@ Implementation that creates the design surface. A new design surface instance. - method is called by both methods. It is the implementation that actually creates the design surface. The default implementation just returns a new . You may override this method to provide a custom object that derives from the class. - + method is called by both methods. It is the implementation that actually creates the design surface. The default implementation just returns a new . You may override this method to provide a custom object that derives from the class. + ]]> @@ -474,11 +474,11 @@ Gets a collection of design surfaces. A collection of design surfaces that are currently hosted by the design surface manager. - property is implemented directly on top of , so if you provide your own implementation of that service, this property uses your implementation. - + property is implemented directly on top of , so if you provide your own implementation of that service, this property uses your implementation. + ]]> @@ -532,14 +532,14 @@ Releases the resources used by the . - method follows the standard pattern. Calling this method destroys the design surface manager. It also disposes the service container, which causes all services that implement to also be disposed. The protected version of this method is `virtual` and follows the normal pattern. - + method follows the standard pattern. Calling this method destroys the design surface manager. It also disposes the service container, which causes all services that implement to also be disposed. The protected version of this method is `virtual` and follows the normal pattern. + > [!NOTE] -> Because does not have any native code to clean up, it does not have a finalizer that calls . If you need to call , you must add a finalizer yourself. - +> Because does not have any native code to clean up, it does not have a finalizer that calls . If you need to call , you must add a finalizer yourself. + ]]> @@ -577,25 +577,25 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method follows the standard pattern. Calling this method destroys the design surface manager. It also disposes the service container, which causes all services that implement to also be disposed. The protected version of this method is `virtual` and follows the normal pattern. - + method follows the standard pattern. Calling this method destroys the design surface manager. It also disposes the service container, which causes all services that implement to also be disposed. The protected version of this method is `virtual` and follows the normal pattern. + > [!NOTE] -> Because does not have any native code to clean up, it does not have a finalizer that calls . If you need to call , you must add a finalizer yourself. +> Because does not have any native code to clean up, it does not have a finalizer that calls . If you need to call , you must add a finalizer yourself. This method is called by the public `Dispose()` method and the method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -642,11 +642,11 @@ Gets a service in the design surface manager's service container. An object that implements, or is a derived class of, the given service type; otherwise, if the service does not exist in the service container. - method forwards to any service provider that was given to the design surface manager at construction time. - + method forwards to any service provider that was given to the design surface manager at construction time. + ]]> @@ -680,11 +680,11 @@ Occurs when the global selection changes. - interface. - + interface. + ]]> diff --git a/xml/System.ComponentModel.Design/DesignerActionService.xml b/xml/System.ComponentModel.Design/DesignerActionService.xml index 073f1aa7f7c..77f082df6ec 100644 --- a/xml/System.ComponentModel.Design/DesignerActionService.xml +++ b/xml/System.ComponentModel.Design/DesignerActionService.xml @@ -544,9 +544,9 @@ - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [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)). + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. diff --git a/xml/System.ComponentModel.Design/DesignerTransaction.xml b/xml/System.ComponentModel.Design/DesignerTransaction.xml index 5e2bc064aad..73fbaa2f1a2 100644 --- a/xml/System.ComponentModel.Design/DesignerTransaction.xml +++ b/xml/System.ComponentModel.Design/DesignerTransaction.xml @@ -56,55 +56,55 @@ Provides a way to group a series of design-time actions to improve performance and enable most types of changes to be undone. - and events. The Properties window, for example, does not update its display after a transaction has opened until the transaction has closed. - - To use transactions for reversible or multiple operations, have your designer create a for each operation or series of operations which should be reversible. Be careful not to perform actions outside the transactions that might prevent a sequence of undo events from completing successfully. - - You can obtain a new by calling the method of an . Be sure to obtain each from the active in order to correctly integrate with the designer transaction processing mechanism, rather than creating a new directly. - - To perform an action within a transaction, you must first create a transaction. Then you must call the method before each change or set of changes occurs, and the method after each change or set of changes occur. Finally, complete and close the transaction by calling the method. - + and events. The Properties window, for example, does not update its display after a transaction has opened until the transaction has closed. + + To use transactions for reversible or multiple operations, have your designer create a for each operation or series of operations which should be reversible. Be careful not to perform actions outside the transactions that might prevent a sequence of undo events from completing successfully. + + You can obtain a new by calling the method of an . Be sure to obtain each from the active in order to correctly integrate with the designer transaction processing mechanism, rather than creating a new directly. + + To perform an action within a transaction, you must first create a transaction. Then you must call the method before each change or set of changes occurs, and the method after each change or set of changes occur. Finally, complete and close the transaction by calling the method. + > [!NOTE] -> When making changes to property values, use the method of a , which calls the component change methods of the and creates a representing the change automatically. - - To perform a transaction, complete the following steps: - -1. Call to obtain a that can be used to control the transaction. - -2. Within a `try` block, for each action that you want to track with a , call the method, make the change or changes, then call the method to signal that the change or changes have been made. - -3. To complete the transaction, call from within a `finally` block. - - In C#, you can use the `using` statement rather than a `try/finally` block, such as in the following example. - -``` -using (host.CreateTransaction() { -// Insert your code here. -} -``` - - To cancel and attempt to roll back a transaction before it has been committed, call the method. When the method is invoked, the actions tracked by the are reversed to attempt to roll back the changes. To undo actions that occurred as part of earlier transactions, you must use the undo command provided by the development environment. - - - -## Examples - The following code example program demonstrates how to create a from a designer. To run this sample, compile the source code into a class library. You must add a reference to the System.Design assembly. In a new project, add a reference to the compiled DLL and add the component in the library to the **Toolbox**. - - There is extensive support for this feature in Visual Studio. - - Also see [Walkthrough: Automatically Populating the Toolbox with Custom Components](/dotnet/desktop/winforms/controls/walkthrough-automatically-populating-the-toolbox-with-custom-components). - - The designer can optionally display notifications about designer transaction events. If you add an instance of the `DTComponent` to a form while in design mode, a message box appears asking whether you would like to receive designer transaction event notifications. You may toggle these notifications using the shortcut menu that appears when you right-click an instance of the `DTComponent`. Transactions are created when you change values using the Properties window. You can also have the designer perform a transaction by clicking **Perform Example Transaction** on the shortcut menu for the component. - +> When making changes to property values, use the method of a , which calls the component change methods of the and creates a representing the change automatically. + + To perform a transaction, complete the following steps: + +1. Call to obtain a that can be used to control the transaction. + +2. Within a `try` block, for each action that you want to track with a , call the method, make the change or changes, then call the method to signal that the change or changes have been made. + +3. To complete the transaction, call from within a `finally` block. + + In C#, you can use the `using` statement rather than a `try/finally` block, such as in the following example. + +``` +using (host.CreateTransaction() { +// Insert your code here. +} +``` + + To cancel and attempt to roll back a transaction before it has been committed, call the method. When the method is invoked, the actions tracked by the are reversed to attempt to roll back the changes. To undo actions that occurred as part of earlier transactions, you must use the undo command provided by the development environment. + + + +## Examples + The following code example program demonstrates how to create a from a designer. To run this sample, compile the source code into a class library. You must add a reference to the System.Design assembly. In a new project, add a reference to the compiled DLL and add the component in the library to the **Toolbox**. + + There is extensive support for this feature in Visual Studio. + + Also see [Walkthrough: Automatically Populating the Toolbox with Custom Components](/dotnet/desktop/winforms/controls/walkthrough-automatically-populating-the-toolbox-with-custom-components). + + The designer can optionally display notifications about designer transaction events. If you add an instance of the `DTComponent` to a form while in design mode, a message box appears asking whether you would like to receive designer transaction event notifications. You may toggle these notifications using the shortcut menu that appears when you right-click an instance of the `DTComponent`. Transactions are created when you change values using the Properties window. You can also have the designer perform a transaction by clicking **Perform Example Transaction** on the shortcut menu for the component. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/DesignerTransaction Sample/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design/DesignerTransaction/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/DesignerTransaction Sample/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/DesignerTransaction Sample/VB/source.vb" id="Snippet1"::: + ]]> @@ -216,11 +216,11 @@ using (host.CreateTransaction() { A description for this transaction. Initializes a new instance of the class using the specified transaction description. - @@ -311,11 +311,11 @@ using (host.CreateTransaction() { if the transaction was canceled; otherwise, . - @@ -358,13 +358,13 @@ using (host.CreateTransaction() { Commits this transaction. - @@ -415,11 +415,11 @@ using (host.CreateTransaction() { if the transaction was committed; otherwise, . - @@ -468,11 +468,11 @@ using (host.CreateTransaction() { Gets a description for the transaction. A description for the transaction. - @@ -525,20 +525,20 @@ using (host.CreateTransaction() { to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. Implementing a Dispose Method Cleaning Up Unmanaged Resources @@ -582,15 +582,15 @@ using (host.CreateTransaction() { Releases the resources associated with this object. This override commits this transaction if it was not already committed. - and cleans up resources by calling `Dispose(false)`. Override `Dispose(Boolean)` to customize the cleanup. - - 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)). - + and cleans up resources by calling `Dispose(false)`. Override `Dispose(Boolean)` to customize the cleanup. + + 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)). + ]]> @@ -633,11 +633,11 @@ using (host.CreateTransaction() { Raises the event. - @@ -684,11 +684,11 @@ using (host.CreateTransaction() { Performs the actual work of committing a transaction. - @@ -738,11 +738,11 @@ using (host.CreateTransaction() { Releases all resources used by the . - diff --git a/xml/System.ComponentModel.Design/InheritanceService.xml b/xml/System.ComponentModel.Design/InheritanceService.xml index c7584418790..b1837da654b 100644 --- a/xml/System.ComponentModel.Design/InheritanceService.xml +++ b/xml/System.ComponentModel.Design/InheritanceService.xml @@ -52,11 +52,11 @@ Provides a set of methods for identifying inherited components. - can be used to find inherited components, select which ones to ignore, and retrieve the inheritance attribute of each inherited class that is tracked by the service. - + can be used to find inherited components, select which ones to ignore, and retrieve the inheritance attribute of each inherited class that is tracked by the service. + ]]> @@ -137,11 +137,11 @@ The container to add the inherited components to. Adds the components inherited by the specified component to the . - is added to the specified container. - + is added to the specified container. + ]]> @@ -192,11 +192,11 @@ The container to add the inherited components to. Adds the components of the specified type that are inherited by the specified component to the . - is added to an internal list that stores an that identifies the inheritance level of the component. The component is then added to the specified container. - + is added to an internal list that stores an that identifies the inheritance level of the component. The component is then added to the specified container. + ]]> @@ -249,11 +249,11 @@ Releases all resources used by the . - allows the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - + allows the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + ]]> @@ -291,20 +291,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -345,11 +345,11 @@ Gets the inheritance attribute of the specified component. An that describes the level of inheritance that this component comes from. - . Otherwise, it returns the inheritance attribute for this component. - + . Otherwise, it returns the inheritance attribute for this component. + ]]> diff --git a/xml/System.ComponentModel.Design/LocalizationExtenderProvider.xml b/xml/System.ComponentModel.Design/LocalizationExtenderProvider.xml index ff092c59bc2..4260d58b172 100644 --- a/xml/System.ComponentModel.Design/LocalizationExtenderProvider.xml +++ b/xml/System.ComponentModel.Design/LocalizationExtenderProvider.xml @@ -43,30 +43,30 @@ Provides design-time support for localization features to a root designer. - can extend an with a set of properties and methods that provide support for the .NET Framework localization architecture. For more about using resources, see [Localization](/dotnet/standard/globalization-localization/localization). - - The localization support architecture enables designers to initialize component properties using resource files that can be swapped at run time to support a variety of languages, culture-specific styles and dynamically configurable features. You can use the methods of this class to enable designers and code generating serializers to load from resources and build initialization code that uses localization features. - - The default serializers that ship with Visual Studio are already capable of localizing components and controls, but they only do so if they locate support for the .NET Framework localization architecture. To detect the presence of localization support, the serialization system must locate a public property named "Localizable" on the root designer component. If a serializer finds this property, it searches for a property of type named "Language" to determine the current resource configuration. Default serializers use these properties to determine if it should localize any localizable resources of the component, and if so, what format the resource information should be saved in. - - - -## Examples - The following code example adds a to a component. - + can extend an with a set of properties and methods that provide support for the .NET Framework localization architecture. For more about using resources, see [Localization](/dotnet/standard/globalization-localization/localization). + + The localization support architecture enables designers to initialize component properties using resource files that can be swapped at run time to support a variety of languages, culture-specific styles and dynamically configurable features. You can use the methods of this class to enable designers and code generating serializers to load from resources and build initialization code that uses localization features. + + The default serializers that ship with Visual Studio are already capable of localizing components and controls, but they only do so if they locate support for the .NET Framework localization architecture. To detect the presence of localization support, the serialization system must locate a public property named "Localizable" on the root designer component. If a serializer finds this property, it searches for a property of type named "Language" to determine the current resource configuration. Default serializers use these properties to determine if it should localize any localizable resources of the component, and if so, what format the resource information should be saved in. + + + +## Examples + The following code example adds a to a component. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/LocalizationExtenderProviderExample/CPP/class1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design/LocalizationExtenderProvider/Overview/class1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/LocalizationExtenderProviderExample/VB/class1.vb" id="Snippet2"::: - - The following code example includes an example component and designer. The designer uses a to add localization support properties for the component. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/LocalizationExtenderProviderExample/VB/class1.vb" id="Snippet2"::: + + The following code example includes an example component and designer. The designer uses a to add localization support properties for the component. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/LocalizationExtenderProviderExample/CPP/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design/LocalizationExtenderProvider/Overview/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/LocalizationExtenderProviderExample/VB/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/LocalizationExtenderProviderExample/VB/class1.vb" id="Snippet1"::: + ]]> @@ -94,20 +94,20 @@ The base component to localize. Initializes a new instance of the class using the specified service provider and base component. - sets the current language to , which is the generic and default language resource setting. This setting causes a designer to generate code that references the generic language resource. You can create other objects to represent and identify other localized resource data that a program can use at run time. - - - -## Examples - The following code example creates a new object. - + sets the current language to , which is the generic and default language resource setting. This setting causes a designer to generate code that references the generic language resource. You can create other objects to represent and identify other localized resource data that a program can use at run time. + + + +## Examples + The following code example creates a new object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/LocalizationExtenderProviderExample/CPP/class1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design/LocalizationExtenderProvider/Overview/class1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/LocalizationExtenderProviderExample/VB/class1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/LocalizationExtenderProviderExample/VB/class1.vb" id="Snippet2"::: + ]]> @@ -182,14 +182,14 @@ Disposes of the resources (other than memory) used by the . - 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). - + 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. + ]]> @@ -218,20 +218,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -270,11 +270,11 @@ Gets the current resource culture for the specified object. A indicating the resource variety. - @@ -382,11 +382,11 @@ The object to reset the resource culture for. Resets the resource culture for the specified object. - . - + . + ]]> diff --git a/xml/System.ComponentModel.Design/MenuCommandService.xml b/xml/System.ComponentModel.Design/MenuCommandService.xml index c4f93335764..17b31dfe47f 100644 --- a/xml/System.ComponentModel.Design/MenuCommandService.xml +++ b/xml/System.ComponentModel.Design/MenuCommandService.xml @@ -49,22 +49,22 @@ Implements the interface. - class implements the interface, which is the managed interface used to add handlers for menu commands and to define verbs. - - The class is automatically offered by the package class to offer global commands for an entire package, and it is also offered by the `Microsoft.VisualStudio.Shell.WindowPane` class to offer commands for the current window. This offering is always done through the service container, so anyone deriving from the package or window pane classes can remove or replace the default implementation of the interface. - - The class utilizes several other services. All of these services are optional, so the behavior of the class degrades if one or more services are missing. The following table shows which services are used and for what purpose. - -|Service|Purpose| -|-------------|-------------| -||Used to discover the current selection in order to obtain verbs offered by the currently selected designer.| -||Used to obtain the designer for the currently selected component, if any.| -|`Microsoft.VisualStudio.Shell.Interop.IVsUIShell`|Used to notify Visual Studio that the command status has changed.| -|`Microsoft.VisualStudio.Shell.Interop.IOleComponentUIManager`|Used to show context menus.| - + class implements the interface, which is the managed interface used to add handlers for menu commands and to define verbs. + + The class is automatically offered by the package class to offer global commands for an entire package, and it is also offered by the `Microsoft.VisualStudio.Shell.WindowPane` class to offer commands for the current window. This offering is always done through the service container, so anyone deriving from the package or window pane classes can remove or replace the default implementation of the interface. + + The class utilizes several other services. All of these services are optional, so the behavior of the class degrades if one or more services are missing. The following table shows which services are used and for what purpose. + +|Service|Purpose| +|-------------|-------------| +||Used to discover the current selection in order to obtain verbs offered by the currently selected designer.| +||Used to obtain the designer for the currently selected component, if any.| +|`Microsoft.VisualStudio.Shell.Interop.IVsUIShell`|Used to notify Visual Studio that the command status has changed.| +|`Microsoft.VisualStudio.Shell.Interop.IOleComponentUIManager`|Used to show context menus.| + ]]> @@ -108,11 +108,11 @@ The service provider that this service uses to obtain other services. Initializes a new instance of the class. - . - + . + ]]> @@ -153,11 +153,11 @@ The to add. Adds a command handler to the menu command service. - method adds a command handler to the menu command service. Command handlers do not define the text, shortcut, or placement of a menu item. Rather, they define the menu item's behavior if the item is clicked. - + method adds a command handler to the menu command service. Command handlers do not define the text, shortcut, or placement of a menu item. Rather, they define the menu item's behavior if the item is clicked. + ]]> @@ -209,11 +209,11 @@ The to add. Adds a verb to the verb table of the . - @@ -270,14 +270,14 @@ Releases all resources used by the . - 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). - + 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. + ]]> @@ -314,20 +314,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases all resources used by the . - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -359,11 +359,11 @@ Ensures that the verb list has been created. - method creates the verb list if it has not already been created. - + method creates the verb list if it has not already been created. + ]]> @@ -601,11 +601,11 @@ , if the command was found; otherwise, . - @@ -649,11 +649,11 @@ , if the command was found; otherwise, . - @@ -704,11 +704,11 @@ Occurs when the status of a menu command has changed. - @@ -744,15 +744,15 @@ A that contains the event data. Raises the event. - method is called by a menu command when its status has changed. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - + method is called by a menu command when its status has changed. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + ]]> @@ -798,11 +798,11 @@ The command to remove. Removes the given menu command from the document. - @@ -893,11 +893,11 @@ The y-coordinate of the shortcut menu's location. Shows the shortcut menu with the given command ID at the given location. - @@ -937,17 +937,17 @@ Gets a collection of the designer verbs that are currently available. A of the designer verbs that are currently available. - property provides a collection of verbs. These verbs come from two places: - -- Verbs added through the method of . - -- Verbs offered by the currently selected designer. - - Verbs added to this service through the method are called global verbs because they are global to this service, but generally there is one instance of this service for each tool or document window. Designer verbs are obtained by querying the service provider for and . If the selection service offers a primary selection, and a designer can be obtained for that selection from , the designer's verbs are added to this list. If the name of a global verb conflicts with the name of a designer verb, the designer-provided designer verb takes precedence. - + property provides a collection of verbs. These verbs come from two places: + +- Verbs added through the method of . + +- Verbs offered by the currently selected designer. + + Verbs added to this service through the method are called global verbs because they are global to this service, but generally there is one instance of this service for each tool or document window. Designer verbs are obtained by querying the service provider for and . If the selection service offers a primary selection, and a designer can be obtained for that selection from , the designer's verbs are added to this list. If the name of a global verb conflicts with the name of a designer verb, the designer-provided designer verb takes precedence. + ]]> diff --git a/xml/System.ComponentModel.Design/ServiceContainer.xml b/xml/System.ComponentModel.Design/ServiceContainer.xml index 1c659db7f3a..9272f75c25e 100644 --- a/xml/System.ComponentModel.Design/ServiceContainer.xml +++ b/xml/System.ComponentModel.Design/ServiceContainer.xml @@ -70,25 +70,25 @@ Provides a simple implementation of the interface. This class cannot be inherited. - object can be used to store and provide services. implements the interface. - - The object can be created using a constructor that adds a parent through which services can be optionally added to or removed from all parent objects, including the immediate parent . To add or remove a service from all implementations that are linked to this through parenting, call the or method overload that accepts a Boolean value indicating whether to promote the service request. - + object can be used to store and provide services. implements the interface. + + The object can be created using a constructor that adds a parent through which services can be optionally added to or removed from all parent objects, including the immediate parent . To add or remove a service from all implementations that are linked to this through parenting, call the or method overload that accepts a Boolean value indicating whether to promote the service request. + > [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - - - -## Examples - The following example program demonstrates service chaining and the resultant service availability of a chain of linked objects. The program provides a user interface that allows you to see the availability of services within a chain of linked services, and uses the , , and methods as well as linked service containers. - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + + + +## Examples + The following example program demonstrates service chaining and the resultant service availability of a chain of linked objects. The program provides a user interface that allows you to see the availability of services within a chain of linked services, and uses the , , and methods as well as linked service containers. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/ServiceArchitectureExample/CPP/serviceform.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design/ServiceContainer/Overview/serviceform.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/ServiceArchitectureExample/VB/serviceform.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/ServiceArchitectureExample/VB/serviceform.vb" id="Snippet1"::: + ]]> @@ -197,11 +197,11 @@ A parent service provider. Initializes a new instance of the class using the specified parent service provider. - @@ -268,15 +268,15 @@ A callback object that can create the service. This allows a service to be declared as available, but delays creation of the object until the service is requested. Adds the specified service to the service container. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/ServiceContainerExample/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design/IServiceContainer/AddService/form1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/ServiceContainerExample/VB/form1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/ServiceContainerExample/VB/form1.vb" id="Snippet3"::: + ]]> @@ -337,15 +337,15 @@ An instance of the service to add. This object must implement or inherit from the type indicated by the parameter. Adds the specified service to the service container. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/ServiceContainerExample/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design/IServiceContainer/AddService/form1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/ServiceContainerExample/VB/form1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/ServiceContainerExample/VB/form1.vb" id="Snippet2"::: + ]]> @@ -511,11 +511,11 @@ Gets the default services implemented directly by . The default services. - . the default implementation of this property is to return the and types. You may override this property and return your own types, modifying the default behavior of . - + . the default implementation of this property is to return the and types. You may override this property and return your own types, modifying the default behavior of . + ]]> @@ -576,16 +576,16 @@ Disposes this service container. - walks all instantiated services within the container and disposes any that implement , and clears the service list. - - 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). - + walks all instantiated services within the container and disposes any that implement , and clears the service list. + + 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. + ]]> @@ -631,22 +631,22 @@ if the is in the process of being disposed of; otherwise, . Disposes this service container. - walks all instantiated services within the container and disposes any that implement , and clears the service list. + walks all instantiated services within the container and disposes any that implement , and clears the service list. This method is called by the public `Dispose()` method and the method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -761,15 +761,15 @@ The type of service to remove. Removes the specified service type from the service container. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/ServiceContainerExample/CPP/form1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design/IServiceContainer/AddService/form1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/ServiceContainerExample/VB/form1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/ServiceContainerExample/VB/form1.vb" id="Snippet4"::: + ]]> diff --git a/xml/System.ComponentModel/AsyncOperation.xml b/xml/System.ComponentModel/AsyncOperation.xml index 50977f043ec..e4b3522e89c 100644 --- a/xml/System.ComponentModel/AsyncOperation.xml +++ b/xml/System.ComponentModel/AsyncOperation.xml @@ -52,35 +52,35 @@ Tracks the lifetime of an asynchronous operation. - class provides ways to track and report the progress of an asynchronous task. - - The following list identifies ways to use an object: - -- To report progress and interim results to the client, call from your asynchronous worker code. - -- To indicate that an asynchronous task has completed, or to cancel a pending asynchronous task, call . - - Your class should get an object for each asynchronous task by calling when each task starts. To allow the client to distinguish separate asynchronous tasks, takes a parameter for a unique client-provided token, which becomes the property. It can then be used by client code to identify the particular asynchronous task that is raising progress or completion events. - - - -## Examples - The following code example demonstrates using an object to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. - - For a full code listing, see [How to: Implement a Component That Supports the Event-based Asynchronous Pattern](/previous-versions/dotnet/netframework-4.0/9hk12d4y(v=vs.100)). For a full code listing of a client form, see [How to: Implement a Client of the Event-based Asynchronous Pattern](/dotnet/standard/asynchronous-programming-patterns/how-to-implement-a-client-of-the-event-based-asynchronous-pattern). - + class provides ways to track and report the progress of an asynchronous task. + + The following list identifies ways to use an object: + +- To report progress and interim results to the client, call from your asynchronous worker code. + +- To indicate that an asynchronous task has completed, or to cancel a pending asynchronous task, call . + + Your class should get an object for each asynchronous task by calling when each task starts. To allow the client to distinguish separate asynchronous tasks, takes a parameter for a unique client-provided token, which becomes the property. It can then be used by client code to identify the particular asynchronous task that is raising progress or completion events. + + + +## Examples + The following code example demonstrates using an object to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. + + For a full code listing, see [How to: Implement a Component That Supports the Event-based Asynchronous Pattern](/previous-versions/dotnet/netframework-4.0/9hk12d4y(v=vs.100)). For a full code listing of a client form, see [How to: Implement a Client of the Event-based Asynchronous Pattern](/dotnet/standard/asynchronous-programming-patterns/how-to-implement-a-client-of-the-event-based-asynchronous-pattern). + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/VB/primenumbercalculatormain.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/VB/primenumbercalculatormain.vb" id="Snippet3"::: + ]]> - Implementers must ensure the and invocations are asynchronous, so that class library providers do not need to concern themselves with potential stack overflows if they assume asynchronous behavior in a particular application model that happens to be synchronous. - - For more information about implementing asynchronous classes, see [Implementing the Event-based Asynchronous Pattern](/dotnet/standard/asynchronous-programming-patterns/implementing-the-event-based-asynchronous-pattern). + Implementers must ensure the and invocations are asynchronous, so that class library providers do not need to concern themselves with potential stack overflows if they assume asynchronous behavior in a particular application model that happens to be synchronous. + + For more information about implementing asynchronous classes, see Implementing the Event-based Asynchronous Pattern. Managed Threading Best Practices @@ -163,11 +163,11 @@ Ends the lifetime of an asynchronous operation. - method to end the lifetime of an asynchronous operation. After this method is called for a particular task, calls to its corresponding will raise an exception. - + method to end the lifetime of an asynchronous operation. After this method is called for a particular task, calls to its corresponding will raise an exception. + ]]> @@ -225,35 +225,35 @@ An argument for the delegate contained in the parameter. Invokes a delegate on the thread or context appropriate for the application model. - method invokes the delegate specified by the `arg` parameter without ending the lifetime of the asynchronous operation. - - You can call the method as often as you like while the lifetime of the asynchronous operation has not been ended by a call to . You can use the method to report progress or interim results back to clients. - - The `d` parameter wraps the delegate you want called when you want to post an update about the status of the asynchronous task. The object will ensure that your delegate is invoked on the thread or context appropriate for the application model. Your method can optionally raise an event that notifies clients of a status change, progress update, or newly available incremental results. - + method invokes the delegate specified by the `arg` parameter without ending the lifetime of the asynchronous operation. + + You can call the method as often as you like while the lifetime of the asynchronous operation has not been ended by a call to . You can use the method to report progress or interim results back to clients. + + The `d` parameter wraps the delegate you want called when you want to post an update about the status of the asynchronous task. The object will ensure that your delegate is invoked on the thread or context appropriate for the application model. Your method can optionally raise an event that notifies clients of a status change, progress update, or newly available incremental results. + The `arg` parameter should be used to pass state to the delegate wrapped by the `d` parameter. It might be a reference to an , or it might be a object. It may be desirable to derive your own class from to provide additional state storage. - -## Examples - The following code example demonstrates using the method for reporting progress and incremental results of an asynchronous operation. This code example is part of a larger example provided for the class. - - + +## Examples + The following code example demonstrates using the method for reporting progress and incremental results of an asynchronous operation. This code example is part of a larger example provided for the class. + + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.cs" id="Snippet5"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/VB/primenumbercalculatormain.vb" id="Snippet5"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/VB/primenumbercalculatormain.vb" id="Snippet5"::: + ]]> The method has been called previously for this task. is . - Inheritors must make the invocation asynchronous, so that class library providers do not need to concern themselves with potential stack overflows if they assume asynchrony but a particular application model happens to be synchronous. - + Inheritors must make the invocation asynchronous, so that class library providers do not need to concern themselves with potential stack overflows if they assume asynchrony but a particular application model happens to be synchronous. + Note: Console applications do not synchronize the execution of calls. This can cause events to be raised out of order. If you wish to have serialized execution of calls, implement and install a class. - - For more information about implementing asynchronous classes, see [Implementing the Event-based Asynchronous Pattern](/dotnet/standard/asynchronous-programming-patterns/implementing-the-event-based-asynchronous-pattern). + + For more information about implementing asynchronous classes, see Implementing the Event-based Asynchronous Pattern. Managed Threading Best Practices @@ -311,24 +311,24 @@ Note: Console applications do not synchronize the execution of An argument for the delegate contained in the parameter. Ends the lifetime of an asynchronous operation. - method to end the lifetime of an asynchronous operation. After this method is called for a particular task, calls to its corresponding object will raise an exception. - - The `d` parameter wraps the delegate you want your class to call when the task's lifetime ends due to completion, cancellation, or failure of the task. The object will ensure that your delegate is invoked on the thread or context appropriate for the application model. Your delegate can optionally raise an event that notifies clients that the asynchronous task's lifetime has ended. - - The `arg` parameter is used to pass state information to the completion delegate `d`. You can use an object, or an object as the parameter value. Alternatively, if you want to provide additional state storage, you can use an instance of a class you derive from the class. - - - -## Examples - The following code example demonstrates using the method to end the lifetime of an asynchronous operation. This code example is part of a larger example provided for the class. - - + method to end the lifetime of an asynchronous operation. After this method is called for a particular task, calls to its corresponding object will raise an exception. + + The `d` parameter wraps the delegate you want your class to call when the task's lifetime ends due to completion, cancellation, or failure of the task. The object will ensure that your delegate is invoked on the thread or context appropriate for the application model. Your delegate can optionally raise an event that notifies clients that the asynchronous task's lifetime has ended. + + The `arg` parameter is used to pass state information to the completion delegate `d`. You can use an object, or an object as the parameter value. Alternatively, if you want to provide additional state storage, you can use an instance of a class you derive from the class. + + + +## Examples + The following code example demonstrates using the method to end the lifetime of an asynchronous operation. This code example is part of a larger example provided for the class. + + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.cs" id="Snippet4"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/VB/primenumbercalculatormain.vb" id="Snippet4"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/VB/primenumbercalculatormain.vb" id="Snippet4"::: + ]]> @@ -336,9 +336,9 @@ Note: Console applications do not synchronize the execution of is . - Inheritors must make the invocation asynchronous, so that class library providers do not need to concern themselves with potential stack overflows if they assume asynchrony but a particular application model happens to be synchronous. The method should be interpreted as an "ending the lifetime" call, meaning the implementation needs to do what is appropriate for the application model. For instance, ASP.NET will decrement its count of outstanding asynchronous operations. This also should put the operation into a state such that any subsequent calls into it will fail, since it has now completed. - - For more information about implementing asynchronous classes, see [Implementing the Event-based Asynchronous Pattern](/dotnet/standard/asynchronous-programming-patterns/implementing-the-event-based-asynchronous-pattern). + Inheritors must make the invocation asynchronous, so that class library providers do not need to concern themselves with potential stack overflows if they assume asynchrony but a particular application model happens to be synchronous. The method should be interpreted as an "ending the lifetime" call, meaning the implementation needs to do what is appropriate for the application model. For instance, ASP.NET will decrement its count of outstanding asynchronous operations. This also should put the operation into a state such that any subsequent calls into it will fail, since it has now completed. + + For more information about implementing asynchronous classes, see Implementing the Event-based Asynchronous Pattern. Managed Threading Best Practices @@ -444,23 +444,23 @@ Note: Console applications do not synchronize the execution of that will act as a task ID. You will use this task ID when you call the , method and this will associate the client's task ID with a particular invocation of your asynchronous operation. This task ID is made available to your implementation through the property. - + that will act as a task ID. You will use this task ID when you call the , method and this will associate the client's task ID with a particular invocation of your asynchronous operation. This task ID is made available to your implementation through the property. + > [!CAUTION] -> Client code must be careful to provide a unique value for the property. Non-unique task IDs may cause your implementation to report progress and other events incorrectly. Your code should check for a non-unique task ID and raise an if one is detected. - - - -## Examples - The following code example demonstrates using to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. - - +> Client code must be careful to provide a unique value for the property. Non-unique task IDs may cause your implementation to report progress and other events incorrectly. Your code should check for a non-unique task ID and raise an if one is detected. + + + +## Examples + The following code example demonstrates using to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. + + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.cs" id="Snippet4"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/VB/primenumbercalculatormain.vb" id="Snippet4"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/VB/primenumbercalculatormain.vb" id="Snippet4"::: + ]]> diff --git a/xml/System.ComponentModel/Component.xml b/xml/System.ComponentModel/Component.xml index 93ff5dfecb7..216eb8297e4 100644 --- a/xml/System.ComponentModel/Component.xml +++ b/xml/System.ComponentModel/Component.xml @@ -85,15 +85,15 @@ Provides the base implementation for the interface and enables object sharing between applications. - is the base class for all components in the common language runtime that marshal by reference. is remotable and derives from the class. provides an implementation of the interface. The provides an implementation of that marshals by value. - - You can host a in any object that implements the interface, and you can query and get services from its container. The container creates an for each it contains. The container uses the site to manage the and is used by the to communicate with its container. - - A should release resources explicitly by calls to its method, without waiting for automatic memory management through an implicit call to the method. When a is disposed, all components within the are also disposed. - + is the base class for all components in the common language runtime that marshal by reference. is remotable and derives from the class. provides an implementation of the interface. The provides an implementation of that marshals by value. + + You can host a in any object that implements the interface, and you can query and get services from its container. The container creates an for each it contains. The container uses the site to manage the and is used by the to communicate with its container. + + A should release resources explicitly by calls to its method, without waiting for automatic memory management through an implicit call to the method. When a is disposed, all components within the are also disposed. + ]]> @@ -188,11 +188,11 @@ if the component can raise events; otherwise, . The default is . - class should override this property to provide the ability to disable the raising of events. For example, in the class, if the control is being hosted as an ActiveX control, the property returns `false` if the ActiveX control has its events frozen. - + class should override this property to provide the ability to disable the raising of events. For example, in the class, if the control is being hosted as an ActiveX control, the property returns `false` if the ActiveX control has its events frozen. + ]]> @@ -256,11 +256,11 @@ Gets the that contains the . The that contains the , if any, or if the is not encapsulated in an . - @@ -319,11 +319,11 @@ if the is in design mode; otherwise, . - ; therefore, if the does not have an associated with it, the value of this property is `false`. - + ; therefore, if the does not have an associated with it, the value of this property is `false`. + ]]> @@ -385,14 +385,14 @@ Releases all resources used by the . - 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). - + 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. + ]]> @@ -444,20 +444,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method and the method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -515,11 +515,11 @@ Occurs when the component is disposed by a call to the method. - delegate, you identify the method that handles 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 the event handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). - + delegate, you identify the method that handles 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 the event handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). + ]]> @@ -577,11 +577,11 @@ Gets the list of event handlers that are attached to this . An that provides the delegates for this component. - @@ -628,13 +628,13 @@ Releases unmanaged resources and performs other cleanup operations before the is reclaimed by garbage collection. - . 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)). - + . 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)). + ]]> @@ -691,11 +691,11 @@ Returns an object that represents a service provided by the or by its . An that represents a service provided by the , or if the does not provide the specified service. - @@ -767,15 +767,15 @@ Gets or sets the of the . The associated with the , or if the is not encapsulated in an , the does not have an associated with it, or the is removed from its . - will have an if it has been added to an and the assigns an to it. The is responsible for assigning the to the . Changing the value of the component's does not necessarily change the name of the site the is assigned to. The property should be set only by an . - - The property value is `null` if the is removed from its . Assigning `null` to this property does not necessarily remove the from the . - - A might or might not have a name. If a is given a name, the name must be unique among other objects within its . The stores the name of the ; therefore, you can only name a if it has an associated with it. - + will have an if it has been added to an and the assigns an to it. The is responsible for assigning the to the . Changing the value of the component's does not necessarily change the name of the site the is assigned to. The property should be set only by an . + + The property value is `null` if the is removed from its . Assigning `null` to this property does not necessarily remove the from the . + + A might or might not have a name. If a is given a name, the name must be unique among other objects within its . The stores the name of the ; therefore, you can only name a if it has an associated with it. + ]]> @@ -831,13 +831,13 @@ Returns a containing the name of the , if any. This method should not be overridden. A containing the name of the , if any, or if the is unnamed. - may or may not have a name. If a is given a name, the name is unique among other objects within its . - - The stores the name of the . A can only have an if it has been added to an and the assigns an to it. - + may or may not have a name. If a is given a name, the name is unique among other objects within its . + + The stores the name of the . A can only have an if it has been added to an and the assigns an to it. + ]]> diff --git a/xml/System.ComponentModel/Container.xml b/xml/System.ComponentModel/Container.xml index c8de291fc58..ba25bd3b259 100644 --- a/xml/System.ComponentModel/Container.xml +++ b/xml/System.ComponentModel/Container.xml @@ -62,15 +62,15 @@ Encapsulates zero or more components. - class is the default implementation for the interface. - - Containers are objects that encapsulate and track zero or more components. In this context, containment refers to logical containment, not visual containment. You can use components and containers in a variety of scenarios, including scenarios that are both visual and not visual. - - The components in a container are tracked in a first-in, first-out list, which also defines the order of the components within the container. Added components are appended to the end of the list. - + class is the default implementation for the interface. + + Containers are objects that encapsulate and track zero or more components. In this context, containment refers to logical containment, not visual containment. You can use components and containers in a variety of scenarios, including scenarios that are both visual and not visual. + + The components in a container are tracked in a first-in, first-out list, which also defines the order of the components within the container. Added components are appended to the end of the list. + ]]> @@ -179,13 +179,13 @@ The component to add. Adds the specified to the . The component is unnamed. - is added to the end of the list. - + is added to the end of the list. + ]]> @@ -247,20 +247,20 @@ The component to add. - The unique, case-insensitive name to assign to the component. - - -or- - + The unique, case-insensitive name to assign to the component. + + -or- + , which leaves the component unnamed. Adds the specified to the and assigns it a name. - is added to the end of the list. - + is added to the end of the list. + ]]> @@ -311,13 +311,13 @@ Gets all the components in the . A collection that contains the components in the . - . - + . + ]]> @@ -374,13 +374,13 @@ Creates a site for the given and assigns the given name to the site. The newly created site. - is added to the without an identifying name. - - This method can be overridden by a derived class. Implementers that need to override the method can provide a custom implementation through a class that implements the interface. - + is added to the without an identifying name. + + This method can be overridden by a derived class. Implementers that need to override the method can provide a custom implementation through a class that implements the interface. + ]]> @@ -436,14 +436,14 @@ Releases all resources used by the . - 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). - + 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. + ]]> @@ -490,20 +490,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the , and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + This method is called by the public `Dispose()` method and the method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -545,13 +545,13 @@ Releases unmanaged resources and performs other cleanup operations before the is reclaimed by garbage collection. - . 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)). - + . 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)). + ]]> @@ -599,11 +599,11 @@ Gets the service object of the specified type, if it is available. An implementing the requested service, or if the service cannot be resolved. - ; otherwise, it returns `null`. You can override this method to provide a custom implementation to return a service object. For more information, see the method. - + ; otherwise, it returns `null`. You can override this method to provide a custom implementation to return a service object. For more information, see the method. + ]]> @@ -664,11 +664,11 @@ The component to remove. Removes a component from the . - @@ -725,11 +725,11 @@ The component to remove. Removes a component from the without setting to . - method cleans up the site as usual, but it does not set the component's property to `null`. - + method cleans up the site as usual, but it does not set the component's property to `null`. + ]]> @@ -791,11 +791,11 @@ The component name to validate. Determines whether the component name is unique for this container. - method is called by the method to determine if the name of the `component` being added is unique for this . If the `name` parameter is not `null` and is not unique, an is thrown. - + method is called by the method to determine if the name of the `component` being added is unique for this . If the `name` parameter is not `null` and is not unique, an is thrown. + ]]> diff --git a/xml/System.ComponentModel/License.xml b/xml/System.ComponentModel/License.xml index 97678ecb896..96a78e6499b 100644 --- a/xml/System.ComponentModel/License.xml +++ b/xml/System.ComponentModel/License.xml @@ -46,17 +46,17 @@ Provides the base class for all licenses. A license is granted to a specific instance of a component. - for the licenses they grant when the component is disposed or finalized. - + for the licenses they grant when the component is disposed or finalized. + ]]> - When you inherit from , you must override the following members: and . - - For more information on licensing, see [How to: License Components and Controls](https://learn.microsoft.com/previous-versions/visualstudio/visual-studio-2013/fe8b1eh9(v=vs.120)). + When you inherit from , you must override the following members: and . + + For more information on licensing, see How to: License Components and Controls. @@ -150,18 +150,18 @@ When overridden in a derived class, disposes of the resources used by the license. - for the licenses that they grant when the component is disposed of or finalized. - - A can use the licenses it grants to track its usage. - - 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 memory it was occupying can be reclaimed by garbage collection. - + for the licenses that they grant when the component is disposed of or finalized. + + A can use the licenses it grants to track its usage. + + 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 memory it was occupying can be reclaimed by garbage collection. + > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources the is using will not be freed until garbage collection calls the object's destructor. - +> Always call before you release your last reference to the . Otherwise, the resources the is using will not be freed until garbage collection calls the object's destructor. + ]]> @@ -222,11 +222,11 @@ When overridden in a derived class, gets the license key granted to this component. A license key granted to this component. - can use any Unicode character string as a license key. The should be treated as an opaque cookie, that is, a cookie with a deliberately hidden internal structure. - + can use any Unicode character string as a license key. The should be treated as an opaque cookie, that is, a cookie with a deliberately hidden internal structure. + ]]> diff --git a/xml/System.ComponentModel/LicenseContext.xml b/xml/System.ComponentModel/LicenseContext.xml index c0425b5ab79..77b783398fd 100644 --- a/xml/System.ComponentModel/LicenseContext.xml +++ b/xml/System.ComponentModel/LicenseContext.xml @@ -46,17 +46,17 @@ Specifies when you can use a licensed object and provides a way of obtaining additional services needed to support licenses running within its domain. - . It implements only run-time support and does not support saved license keys. - + . It implements only run-time support and does not support saved license keys. + ]]> - If you want to implement design-time license support, you must inherit from this class, and override the following members: , , , and . If you want to implement saved license keys, override the and methods. - - For more information about licensing, see [How to: License Components and Controls](https://learn.microsoft.com/previous-versions/visualstudio/visual-studio-2013/fe8b1eh9(v=vs.120)). + If you want to implement design-time license support, you must inherit from this class, and override the following members: , , , and . If you want to implement saved license keys, override the and methods. + + For more information about licensing, see How to: License Components and Controls. @@ -283,11 +283,11 @@ The to save for the type of component. When overridden in a derived class, sets a license key for the specified type. - at design time. You must override the property to implement design-time license support. - + at design time. You must override the property to implement design-time license support. + ]]> diff --git a/xml/System.ComponentModel/LicenseProvider.xml b/xml/System.ComponentModel/LicenseProvider.xml index 078622f557b..a74a6c6b6ea 100644 --- a/xml/System.ComponentModel/LicenseProvider.xml +++ b/xml/System.ComponentModel/LicenseProvider.xml @@ -42,21 +42,21 @@ Provides the base class for implementing a license provider. - method. It uses a that is implemented by the class. - + method. It uses a that is implemented by the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic LicenseManager Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/LicenseManager/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic LicenseManager Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic LicenseManager Example/VB/source.vb" id="Snippet1"::: + ]]> - When you inherit from , you must override the method. - - See for an implementation of this class. For more information on licensing, see [How to: License Components and Controls](https://learn.microsoft.com/previous-versions/visualstudio/visual-studio-2013/fe8b1eh9(v=vs.120)). + When you inherit from , you must override the method. + + See for an implementation of this class. For more information on licensing, see How to: License Components and Controls. diff --git a/xml/System.ComponentModel/MarshalByValueComponent.xml b/xml/System.ComponentModel/MarshalByValueComponent.xml index f9cf5bacd3a..9f3a798d966 100644 --- a/xml/System.ComponentModel/MarshalByValueComponent.xml +++ b/xml/System.ComponentModel/MarshalByValueComponent.xml @@ -93,11 +93,11 @@ Implements and provides the base implementation for remotable components that are marshaled by value (a copy of the serialized object is passed). - , which is a repository of container-specific, per-component information. - + , which is a repository of container-specific, per-component information. + ]]> @@ -146,11 +146,11 @@ Initializes a new instance of the class. - , which is a repository of container-specific, per-component information. - + , which is a repository of container-specific, per-component information. + ]]> @@ -258,11 +258,11 @@ if the component is in design mode; otherwise, . - @@ -319,14 +319,14 @@ Releases all resources used by the . - 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). - + 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. + ]]> @@ -373,20 +373,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -579,11 +579,11 @@ Gets the implementer of the . An that represents the implementer of the . - @@ -651,13 +651,13 @@ Gets or sets the site of the component. An object implementing the interface that represents the site of the component. - @@ -705,17 +705,17 @@ Returns a containing the name of the , if any. This method should not be overridden. - A containing the name of the , if any. - + A containing the name of the , if any. + if the is unnamed. - may or may not have a name. If a is given a name, the name is unique among other objects within its . - - The stores the 's name. A can only have a if it has been added to an and the assigns an to it. - + may or may not have a name. If a is given a name, the name is unique among other objects within its . + + The stores the 's name. A can only have a if it has been added to an and the assigns an to it. + ]]> diff --git a/xml/System.ComponentModel/NestedContainer.xml b/xml/System.ComponentModel/NestedContainer.xml index 08723480cb4..d3835acdb8e 100644 --- a/xml/System.ComponentModel/NestedContainer.xml +++ b/xml/System.ComponentModel/NestedContainer.xml @@ -68,23 +68,23 @@ Provides the base implementation for the interface, which enables containers to have an owning component. - class is a simple implementation of the interface, which defines a component that logically contains zero or more other components and is owned by a parent component. The behavior of nested containers differs from a standard in a number of ways, including the following: - -- Site characteristics such as and are routed through the owning component's site. - -- The site's property is a qualified name that includes the owning component's name followed by a period (.) and the child component's name. - -- provides support for the as a service. - -- When the owning component is disposed, the container is disposed as well. - - In addition, designers treat nested containers differently. A designer host is only interested in one container - the one associated with the host. Therefore, component add and remove events are not raised when a component is added to or removed from a nested container. However, because services flow through to the nested container, component change events are raised when a component in a nested container is changed. - - This disparity in event tracking also impacts undo functionality, which is closely tied to serialization. The standard undo engine uses to track changes made to components. If the undo engine cannot identify a name for a component through the reference service, the engine will ignore any changes for that component. This service automatically recognizes changes to contained components only if they are exposed as public read-only properties of the same name in their owners. Otherwise, the developer must pass component change events up to the owner. For example, if a nested component's `Text` property is resurfaced on its owning component as an `Address` property, when the `Text` property is changed, a property change must be programmatically made for the corresponding `Address` property or else that change will not be tracked by undo. - + class is a simple implementation of the interface, which defines a component that logically contains zero or more other components and is owned by a parent component. The behavior of nested containers differs from a standard in a number of ways, including the following: + +- Site characteristics such as and are routed through the owning component's site. + +- The site's property is a qualified name that includes the owning component's name followed by a period (.) and the child component's name. + +- provides support for the as a service. + +- When the owning component is disposed, the container is disposed as well. + + In addition, designers treat nested containers differently. A designer host is only interested in one container - the one associated with the host. Therefore, component add and remove events are not raised when a component is added to or removed from a nested container. However, because services flow through to the nested container, component change events are raised when a component in a nested container is changed. + + This disparity in event tracking also impacts undo functionality, which is closely tied to serialization. The standard undo engine uses to track changes made to components. If the undo engine cannot identify a name for a component through the reference service, the engine will ignore any changes for that component. This service automatically recognizes changes to contained components only if they are exposed as public read-only properties of the same name in their owners. Otherwise, the developer must pass component change events up to the owner. For example, if a nested component's `Text` property is resurfaced on its owning component as an `Address` property, when the `Text` property is changed, a property change must be programmatically made for the corresponding `Address` property or else that change will not be tracked by undo. + ]]> @@ -130,11 +130,11 @@ The that owns this nested container. Initializes a new instance of the class. - event so that the nested container's method will automatically be called. - + event so that the nested container's method will automatically be called. + ]]> @@ -193,11 +193,11 @@ Creates a site for the component within the container. The newly created . - is added to the nested container without an identifying name. - + is added to the nested container without an identifying name. + ]]> @@ -246,20 +246,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the resources used by the nested container. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -306,11 +306,11 @@ Gets the service object of the specified type, if it is available. An that implements the requested service, or if the service cannot be resolved. - method. This implementation only resolves requests for the and services. - + method. This implementation only resolves requests for the and services. + ]]> @@ -363,11 +363,11 @@ Gets the owning component for this nested container. The that owns this nested container. - @@ -423,11 +423,11 @@ Gets the name of the owning component. The name of the owning component. - and calls , or if there is no nested site. If neither is available, this property returns `null`. - + and calls , or if there is no nested site. If neither is available, this property returns `null`. + ]]> diff --git a/xml/System.ComponentModel/RunInstallerAttribute.xml b/xml/System.ComponentModel/RunInstallerAttribute.xml index b1a038a5320..bb2f39c6bb2 100644 --- a/xml/System.ComponentModel/RunInstallerAttribute.xml +++ b/xml/System.ComponentModel/RunInstallerAttribute.xml @@ -56,31 +56,31 @@ Specifies whether the Visual Studio Custom Action Installer or the Installutil.exe (Installer Tool) should be invoked when the assembly is installed. - is marked with the set to `true`, Visual Studio's Custom Action Installer or the InstallUtil.exe will be invoked when the assembly is installed. Members marked with the set to `false` will not invoke an installer. The default is `true`. - + is marked with the set to `true`, Visual Studio's Custom Action Installer or the InstallUtil.exe will be invoked when the assembly is installed. Members marked with the set to `false` will not invoke an installer. The default is `true`. + > [!NOTE] -> When you mark a property with the set to `true`, the value of this attribute is set to the constant member . For a property marked with the set to `false`, the value is . Therefore, when you want to check the value of this attribute in your code, you must specify the attribute as or . - - For more information, see [Attributes](/dotnet/standard/attributes/). - - - -## Examples - The following example specifies that the installer should be run for `MyProjectInstaller`. - +> When you mark a property with the set to `true`, the value of this attribute is set to the constant member . For a property marked with the set to `false`, the value is . Therefore, when you want to check the value of this attribute in your code, you must specify the attribute as or . + + For more information, see [Attributes](/dotnet/standard/attributes/). + + + +## Examples + The following example specifies that the installer should be run for `MyProjectInstaller`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic RunInstallerAttribute Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/RunInstallerAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic RunInstallerAttribute Example/VB/source.vb" id="Snippet1"::: - - The next example creates an instance of `MyProjectInstaller`. Then it gets the attributes for the class, extracts the , and prints whether to run the installer. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic RunInstallerAttribute Example/VB/source.vb" id="Snippet1"::: + + The next example creates an instance of `MyProjectInstaller`. Then it gets the attributes for the class, extracts the , and prints whether to run the installer. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic RunInstallerAttribute Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/RunInstallerAttribute/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic RunInstallerAttribute Example/VB/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic RunInstallerAttribute Example/VB/source.vb" id="Snippet2"::: + ]]> @@ -171,11 +171,11 @@ Specifies the default visibility, which is . This field is read-only. - . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . - + . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + ]]> @@ -357,15 +357,15 @@ System.ComponentModel.RunInstallerAttribute - Specifies that the Visual Studio Custom Action Installer or the [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool) should not be invoked when the assembly is installed. This field is read-only. + Specifies that the Visual Studio Custom Action Installer or the Installutil.exe (Installer Tool) should not be invoked when the assembly is installed. This field is read-only. - set to `false`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . - + set to `false`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + ]]> @@ -452,13 +452,13 @@ System.ComponentModel.RunInstallerAttribute - Specifies that the Visual Studio Custom Action Installer or the [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool) should be invoked when the assembly is installed. This field is read-only. + Specifies that the Visual Studio Custom Action Installer or the Installutil.exe (Installer Tool) should be invoked when the assembly is installed. This field is read-only. - set to `true`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . - + set to `true`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + ]]> diff --git a/xml/System.ComponentModel/TypeConverter.xml b/xml/System.ComponentModel/TypeConverter.xml index 0b17831dd03..18e0ed01ccf 100644 --- a/xml/System.ComponentModel/TypeConverter.xml +++ b/xml/System.ComponentModel/TypeConverter.xml @@ -58,67 +58,67 @@ Provides a unified way of converting types of values to other types, as well as for accessing standard values and subproperties. - . Unless this attribute is overridden, all classes that inherit from this class use the same type converter as the base class. - + . Unless this attribute is overridden, all classes that inherit from this class use the same type converter as the base class. + > [!NOTE] -> For general type system purposes, do not access a type converter directly. Instead, access the appropriate converter by using . For more information, see the code examples provided. +> For general type system purposes, do not access a type converter directly. Instead, access the appropriate converter by using . For more information, see the code examples provided. > -> However, when using XAML, a XAML processor searches for the directly, instead of going through . For cases where you do want a instance from code, or where you create a shared instance in WPF resources, it is acceptable to construct it directly without referencing or other reflection and type system support. - - Classes derived from are often referenced as part of how a XAML processor converts an attribute or initialization text value from markup (which is inherently a string) and generates an object for a run-time representation. Custom type authors that intend to support a type conversion behavior for XAML typically implement a class that supports their own unique `ConvertFrom` behavior from a string. This behavior enables type conversion from the string provided as a XAML attribute value and provides a XAML processor with the support needed to create an object from the string, so that the object can be produced in a parsed object graph. Custom types or members of custom types are indicated by applying to the definitions, with the attribute referencing the custom implementation. For more information, see [Type Converters for XAML Overview](/dotnet/framework/xaml-services/type-converters-for-xaml-overview). - - - -## Examples - The following code example shows how to create an instance of a type converter and bind it to a class. The class implementing the converter, `MyClassConverter`, must inherit from the class. - +> However, when using XAML, a XAML processor searches for the directly, instead of going through . For cases where you do want a instance from code, or where you create a shared instance in WPF resources, it is acceptable to construct it directly without referencing or other reflection and type system support. + + Classes derived from are often referenced as part of how a XAML processor converts an attribute or initialization text value from markup (which is inherently a string) and generates an object for a run-time representation. Custom type authors that intend to support a type conversion behavior for XAML typically implement a class that supports their own unique `ConvertFrom` behavior from a string. This behavior enables type conversion from the string provided as a XAML attribute value and provides a XAML processor with the support needed to create an object from the string, so that the object can be produced in a parsed object graph. Custom types or members of custom types are indicated by applying to the definitions, with the attribute referencing the custom implementation. For more information, see [Type Converters for XAML Overview](/dotnet/framework/xaml-services/type-converters-for-xaml-overview). + + + +## Examples + The following code example shows how to create an instance of a type converter and bind it to a class. The class implementing the converter, `MyClassConverter`, must inherit from the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic TypeConverter Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/TypeConverter/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic TypeConverter Example/VB/source.vb" id="Snippet1"::: - - When you have a property that has an enumeration, check to see whether an enumeration value is valid before setting the property. The next code example requires that an enumeration called `MyPropertyEnum` has been declared. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic TypeConverter Example/VB/source.vb" id="Snippet1"::: + + When you have a property that has an enumeration, check to see whether an enumeration value is valid before setting the property. The next code example requires that an enumeration called `MyPropertyEnum` has been declared. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic TypeConverter Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/TypeConverter/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic TypeConverter Example/VB/source.vb" id="Snippet2"::: - - Another common type converter usage is to convert an object to a string. The following code example prints out the name of the stored in the variable `c`. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic TypeConverter Example/VB/source.vb" id="Snippet2"::: + + Another common type converter usage is to convert an object to a string. The following code example prints out the name of the stored in the variable `c`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic TypeConverter Example/CPP/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/TypeConverter/Overview/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic TypeConverter Example/VB/source.vb" id="Snippet3"::: - - You can also use a type converter to convert a value from its name, as shown in the next code example. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic TypeConverter Example/VB/source.vb" id="Snippet3"::: + + You can also use a type converter to convert a value from its name, as shown in the next code example. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic TypeConverter Example/CPP/source.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/TypeConverter/Overview/source.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic TypeConverter Example/VB/source.vb" id="Snippet4"::: - - In the following code example, you can use a type converter to print out the set of standard values that the object supports. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic TypeConverter Example/VB/source.vb" id="Snippet4"::: + + In the following code example, you can use a type converter to print out the set of standard values that the object supports. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic TypeConverter Example/CPP/source.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/TypeConverter/Overview/source.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic TypeConverter Example/VB/source.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic TypeConverter Example/VB/source.vb" id="Snippet5"::: + ]]> - Inherit from to implement your own conversion requirements. When you inherit from this class, you can override the following methods: - -- To support custom type conversion, override the , , , and methods. - -- To convert types that must re-create the object to change its value, override the and methods. - -- To convert types that support properties, override the and methods. If the class you are converting does not have properties, and you need to implement properties, you can use the class as a base for implementing the property descriptors. When you inherit from , you must override the and methods. - -- To convert types that support standard values, override the , , and methods. - + Inherit from to implement your own conversion requirements. When you inherit from this class, you can override the following methods: + +- To support custom type conversion, override the , , , and methods. + +- To convert types that must re-create the object to change its value, override the and methods. + +- To convert types that support properties, override the and methods. If the class you are converting does not have properties, and you need to implement properties, you can use the class as a base for implementing the property descriptors. When you inherit from , you must override the and methods. + +- To convert types that support standard values, override the , , and methods. + Note: Your derived type might be marked as or , but an instance of your type can be created with the class. Do not write insecure code by assuming the caller is trusted. Assume instead that callers might create instances of your type in partial trust. - - For more information about type converters for general (non-XAML) purposes, see [How to: Implement a Type Converter](https://learn.microsoft.com/previous-versions/visualstudio/visual-studio-2013/ayybcxe5(v=vs.120)) or [Generalized Type Conversion](/previous-versions/visualstudio/visual-studio-2013/yy580hbd(v=vs.120)). + + For more information about type converters for general (non-XAML) purposes, see How to: Implement a Type Converter or Generalized Type Conversion. @@ -237,11 +237,11 @@ Note: Your derived type might be marked as or if this converter can perform the conversion; otherwise, . - @@ -306,16 +306,16 @@ Note: Your derived type might be marked as or if this converter can perform the conversion; otherwise, . - . - + . + ]]> - Override this method to provide your own conversion requirements. - + Override this method to provide your own conversion requirements. + Use the parameter to extract additional information about the environment from which this converter is invoked. This parameter can be , so always check it. Also, properties on the context object can return . @@ -389,11 +389,11 @@ Note: Your derived type might be marked as or if this converter can perform the conversion; otherwise, . - always returns `true`. - + always returns `true`. + ]]> @@ -452,13 +452,13 @@ Note: Your derived type might be marked as or if this converter can perform the conversion; otherwise, . - always returns `true`. - + always returns `true`. + ]]> @@ -585,22 +585,22 @@ Note: Your derived type might be marked as or Converts the given object to the type of this converter, using the specified context and culture information. An that represents the converted value. - class that supports behavior from a string. This behavior enables type conversion from the string provided as a XAML attribute value and provides a XAML processor with the support needed to create an object from the string, so that the object can be produced in a parsed object graph. Custom types or members of custom types are indicated by applying to the definitions, with the attribute referencing the custom implementation. - - For XAML purposes, you do not typically provide branching implementations based on `culture`. This is because XAML is precompiled in a development environment context, and culture-specific information for runtime XAML is not relevant for XAML type conversion. For more information, see [Type Converters for XAML Overview](/dotnet/framework/xaml-services/type-converters-for-xaml-overview). - + class that supports behavior from a string. This behavior enables type conversion from the string provided as a XAML attribute value and provides a XAML processor with the support needed to create an object from the string, so that the object can be produced in a parsed object graph. Custom types or members of custom types are indicated by applying to the definitions, with the attribute referencing the custom implementation. + + For XAML purposes, you do not typically provide branching implementations based on `culture`. This is because XAML is precompiled in a development environment context, and culture-specific information for runtime XAML is not relevant for XAML type conversion. For more information, see [Type Converters for XAML Overview](/dotnet/framework/xaml-services/type-converters-for-xaml-overview). + ]]> The conversion cannot be performed. - Override this method to provide your own conversion requirements. - - Use the parameter to extract additional information about the environment from which this converter is invoked. This parameter can be , so always check it. Also, properties on the context object can return . - - For implementation patterns for type converters that are used to support XAML and custom types, see [Type Converters for XAML Overview](/dotnet/framework/xaml-services/type-converters-for-xaml-overview). + Override this method to provide your own conversion requirements. + + Use the parameter to extract additional information about the environment from which this converter is invoked. This parameter can be , so always check it. Also, properties on the context object can return . + + For implementation patterns for type converters that are used to support XAML and custom types, see Type Converters for XAML Overview. Overview of type converters for XAML @@ -666,11 +666,11 @@ Note: Your derived type might be marked as or Converts the given string to the type of this converter, using the invariant culture. An that represents the converted text. - The conversion cannot be performed. @@ -730,13 +730,13 @@ Note: Your derived type might be marked as or Converts the given string to the type of this converter, using the invariant culture and the specified context. An that represents the converted text. - The conversion cannot be performed. @@ -807,16 +807,16 @@ Note: Your derived type might be marked as or Converts the specified text to an object. An that represents the converted text. - class. - + class. + ]]> The string cannot be converted into the appropriate object. @@ -875,13 +875,13 @@ Note: Your derived type might be marked as or Converts the given text to an object, using the specified context. An that represents the converted text. - The conversion cannot be performed. @@ -949,13 +949,13 @@ Note: Your derived type might be marked as or Converts the given text to an object, using the specified context and culture information. An that represents the converted text. - The conversion cannot be performed. @@ -1031,11 +1031,11 @@ Note: Your derived type might be marked as or Converts the given value object to the specified type, using the arguments. An that represents the converted value. - on the object, if the object is valid and if the destination type is a string. - + on the object, if the object is valid and if the destination type is a string. + ]]> The parameter is . @@ -1099,25 +1099,25 @@ Note: Your derived type might be marked as or Converts the given value object to the specified type, using the specified context and culture information. An that represents the converted value. - on the object if the object is valid and if the destination type is a string. - - Use the `context` parameter to extract additional information about the environment from which this converter is invoked. This parameter can be `null`, so always check it. Also, properties on the context object can return `null`. - - Custom type authors that intend to support a type conversion behavior for XAML typically implement a class that supports behavior from a string. These type converters might also implement to support serialization back to XAML. - - Some XAML serialization scenarios cannot be adequately addressed with alone. In these cases, it may be necessary to also define a that handles the serialization cases that would otherwise be handled by . For more information, see . - + on the object if the object is valid and if the destination type is a string. + + Use the `context` parameter to extract additional information about the environment from which this converter is invoked. This parameter can be `null`, so always check it. Also, properties on the context object can return `null`. + + Custom type authors that intend to support a type conversion behavior for XAML typically implement a class that supports behavior from a string. These type converters might also implement to support serialization back to XAML. + + Some XAML serialization scenarios cannot be adequately addressed with alone. In these cases, it may be necessary to also define a that handles the serialization cases that would otherwise be handled by . For more information, see . + ]]> The parameter is . The conversion cannot be performed. - Override this method to provide your own conversion requirements. - - For implementation patterns for type converters that are used to support XAML and custom types, see [Type Converters for XAML Overview](/dotnet/framework/xaml-services/type-converters-for-xaml-overview). + Override this method to provide your own conversion requirements. + + For implementation patterns for type converters that are used to support XAML and custom types, see Type Converters for XAML Overview. Overview of type converters for XAML @@ -1177,13 +1177,13 @@ Note: Your derived type might be marked as or Converts the specified value to a culture-invariant string representation. A that represents the converted value. - The conversion cannot be performed. @@ -1236,13 +1236,13 @@ Note: Your derived type might be marked as or Converts the specified value to a culture-invariant string representation, using the specified context. A that represents the converted value. - The conversion cannot be performed. @@ -1303,16 +1303,16 @@ Note: Your derived type might be marked as or Converts the specified value to a string representation. An that represents the converted value. - class. - + class. + ]]> The conversion cannot be performed. @@ -1364,13 +1364,13 @@ Note: Your derived type might be marked as or Converts the given value to a string representation, using the given context. An that represents the converted value. - The conversion cannot be performed. @@ -1425,13 +1425,13 @@ Note: Your derived type might be marked as or Converts the given value to a string representation, using the specified context and culture information. An that represents the converted value. - The conversion cannot be performed. @@ -1502,13 +1502,13 @@ Note: Your derived type might be marked as or Re-creates an given a set of property values for the object. An representing the given , or if the object cannot be created. This method always returns . - . - + . + ]]> @@ -1567,18 +1567,18 @@ Note: Your derived type might be marked as or Creates an instance of the type that this is associated with, using the specified context, given a set of property values for the object. An representing the given , or if the object cannot be created. This method always returns . - - Override this method if the type you want to convert must re-create the object to change its value. - - Use the parameter to extract additional information about the environment from which this converter is invoked. This parameter can be , so always check it. Also, properties on the context object can return . - + Override this method if the type you want to convert must re-create the object to change its value. + + Use the parameter to extract additional information about the environment from which this converter is invoked. This parameter can be , so always check it. Also, properties on the context object can return . + The dictionary provided by the parameter has a series of name/value pairs, one for each property returned from . @@ -1811,16 +1811,16 @@ Note: Your derived type might be marked as or if changing a property on this object requires a call to to create a new value; otherwise, . - - Override this method if the type you want to convert must re-create the object to change its value. - + Override this method if the type you want to convert must re-create the object to change its value. + Use the parameter to extract additional information about the environment from which this converter is invoked. This parameter can be , so always check it. Also, properties on the context object can return . @@ -1894,13 +1894,13 @@ Note: Your derived type might be marked as or Returns a collection of properties for the type of array specified by the value parameter. A with the properties that are exposed for this data type, or if there are no properties. - for the correct data type. - + for the correct data type. + ]]> @@ -1964,15 +1964,15 @@ Note: Your derived type might be marked as or Returns a collection of properties for the type of array specified by the value parameter, using the specified context. A with the properties that are exposed for this data type, or if there are no properties. - for the correct data type. - + for the correct data type. + ]]> @@ -2046,26 +2046,26 @@ Note: Your derived type might be marked as or Returns a collection of properties for the type of array specified by the value parameter, using the specified context and attributes. A with the properties that are exposed for this data type, or if there are no properties. - - Override this method if the type you want to convert supports properties. - - Use the parameter to extract additional information about the environment from which this converter is invoked. This parameter can be , so always check it. Also, properties on the context object can return . - - The attributes array is used to filter the array. The attributes can have a mix of and objects. Filtering is defined by the following rules: - -- A is treated as a wildcard; it matches a property that has the in its set of attributes. - -- If a property does not have an of the same class, the property is not included in the returned array. - -- If the attribute is an instance of , the property must be an exact match or it is not included in the returned array. - + Override this method if the type you want to convert supports properties. + + Use the parameter to extract additional information about the environment from which this converter is invoked. This parameter can be , so always check it. Also, properties on the context object can return . + + The attributes array is used to filter the array. The attributes can have a mix of and objects. Filtering is defined by the following rules: + +- A is treated as a wildcard; it matches a property that has the in its set of attributes. + +- If a property does not have an of the same class, the property is not included in the returned array. + +- If the attribute is an instance of , the property must be an exact match or it is not included in the returned array. + - If an instance is specified and it is the default property, it is included in the returned array even if there is no instance of the in the property. @@ -2129,11 +2129,11 @@ Note: Your derived type might be marked as or if should be called to find the properties of this object; otherwise, . - @@ -2183,16 +2183,16 @@ Note: Your derived type might be marked as or if should be called to find the properties of this object; otherwise, . - - Override this method if the type you want to convert supports properties. - + Override this method if the type you want to convert supports properties. + Use the parameter to extract additional information about the environment from which this converter is invoked. This parameter can be , so always check it. Also, properties on the context object can return . @@ -2255,11 +2255,11 @@ Note: Your derived type might be marked as or Returns a collection of standard values from the default context for the data type this type converter is designed for. A containing a standard set of valid values, or if the data type does not support a standard set of values. - @@ -2308,16 +2308,16 @@ Note: Your derived type might be marked as or Returns a collection of standard values for the data type this type converter is designed for when provided with a format context. A that holds a standard set of valid values, or if the data type does not support a standard set of values. - , this method always returns `null`. - - - -## Examples - For an example on this function, see the class. - + , this method always returns `null`. + + + +## Examples + For an example on this function, see the class. + ]]> @@ -2383,13 +2383,13 @@ Note: Your derived type might be marked as or if the returned from is an exhaustive list of possible values; if other values are possible. - method provides. If the values are exclusive, the list returned by should not allow these values to be edited. - + method provides. If the values are exclusive, the list returned by should not allow these values to be edited. + ]]> @@ -2439,18 +2439,18 @@ Note: Your derived type might be marked as or if the returned from is an exhaustive list of possible values; if other values are possible. - method provides. If the values are exclusive, the list returned by should not allow these values to be edited. - + method provides. If the values are exclusive, the list returned by should not allow these values to be edited. + ]]> - Override this method if the type you want to convert supports standard values. - + Override this method if the type you want to convert supports standard values. + Use the parameter to extract additional information about the environment from which this converter is invoked. This parameter can be , so always check it. Also, properties on the context object can return . @@ -2560,13 +2560,13 @@ Note: Your derived type might be marked as or if should be called to find a common set of values the object supports; otherwise, . - @@ -2639,28 +2639,28 @@ Note: Your derived type might be marked as or if the specified value is valid for this object; otherwise, . - method catches exceptions from the and methods. If the input value type causes to return `false`, or if the input value causes to raise an exception, the method returns `false`. - + method catches exceptions from the and methods. If the input value type causes to return `false`, or if the input value causes to raise an exception, the method returns `false`. + To enable the legacy behavior, insert the following lines into the configuration file of your .NET Framework application. - -```xml - - - - - -``` - + +```xml + + + + + +``` + ]]> - Override this method if the type you want to convert supports standard values that can be validated. - - The method is used to validate a value within the type rather than to determine if can be converted to the given type. For example, can be used to determine if a given value is valid for an enumeration type. For an example, see . - + Override this method if the type you want to convert supports standard values that can be validated. + + The method is used to validate a value within the type rather than to determine if can be converted to the given type. For example, can be used to determine if a given value is valid for an enumeration type. For an example, see . + You can write your own WillConvertSucceed method by wrapping the and methods in exception blocks. @@ -2713,31 +2713,31 @@ Note: Your derived type might be marked as or if the specified value is valid for this object; otherwise, . - method catches exceptions from the and methods. If the input value type causes to return `false`, or if the input value causes to raise an exception, the method returns `false`. - - To enable the legacy behavior, insert the following lines into the configuration file of your .NET Framework application. - -```xml - - - - - + method catches exceptions from the and methods. If the input value type causes to return `false`, or if the input value causes to raise an exception, the method returns `false`. + + To enable the legacy behavior, insert the following lines into the configuration file of your .NET Framework application. + +```xml + + + + + ``` - -## Examples - For an example of this function, see the class. - + +## Examples + For an example of this function, see the class. + ]]> - Override this method if the type you want to convert supports standard values that can be validated. - + Override this method if the type you want to convert supports standard values that can be validated. + The method is used to validate a value within the type rather than to determine if can be converted to the given type. For example, can be used to determine if a given value is valid for an enumeration type. For an example, see . @@ -2795,11 +2795,11 @@ Note: Your derived type might be marked as or Sorts a collection of properties. A that contains the sorted properties. - diff --git a/xml/System.Configuration/ConfigurationManager.xml b/xml/System.Configuration/ConfigurationManager.xml index e178e04423e..f1f2191ca87 100644 --- a/xml/System.Configuration/ConfigurationManager.xml +++ b/xml/System.Configuration/ConfigurationManager.xml @@ -32,298 +32,298 @@ Provides access to configuration files for client applications. This class cannot be inherited. - class enables you to access machine, application, and user configuration information. This class replaces the class, which is deprecated. For web applications, use the class. - - To use the class, your project must reference the `System.Configuration` assembly. By default, some project templates, like Console Application, do not reference this assembly so you must manually reference it. - + class enables you to access machine, application, and user configuration information. This class replaces the class, which is deprecated. For web applications, use the class. + + To use the class, your project must reference the `System.Configuration` assembly. By default, some project templates, like Console Application, do not reference this assembly so you must manually reference it. + > [!NOTE] -> The name and location of the application configuration file depend on the application's host. For more information, see [Configuring Apps by using Configuration Files](/dotnet/framework/configure-apps/). - - You can use the built-in types or derive from them to handle configuration information. By using these types, you can work directly with configuration information and you can extend configuration files to include custom information. - - The class includes members that enable you to perform the following tasks: - -- Read a section from a configuration file. To access configuration information, call the method. For some sections such as `appSettings` and `connectionStrings`, use the and classes. These members perform read-only operations, use a single cached instance of the configuration, and are multithread aware. - -- Read and write configuration files as a whole. Your application can read and write configuration settings at any level, for itself or for other applications or computers, locally or remotely. Use one of the methods provided by the class to open a configuration file such as SampleApp.exe.config. These methods return a object that in turn exposes methods and properties you can use to work with the associated configuration files. The methods perform read or write operations and create the configuration data every time that a file is written. - -- Support configuration tasks. The following types are used to support various configuration tasks: - - - - - - - - - - - - - - - - - - - - - - +> The name and location of the application configuration file depend on the application's host. For more information, see [Configuring Apps by using Configuration Files](/dotnet/framework/configure-apps/). + + You can use the built-in types or derive from them to handle configuration information. By using these types, you can work directly with configuration information and you can extend configuration files to include custom information. + + The class includes members that enable you to perform the following tasks: + +- Read a section from a configuration file. To access configuration information, call the method. For some sections such as `appSettings` and `connectionStrings`, use the and classes. These members perform read-only operations, use a single cached instance of the configuration, and are multithread aware. + +- Read and write configuration files as a whole. Your application can read and write configuration settings at any level, for itself or for other applications or computers, locally or remotely. Use one of the methods provided by the class to open a configuration file such as SampleApp.exe.config. These methods return a object that in turn exposes methods and properties you can use to work with the associated configuration files. The methods perform read or write operations and create the configuration data every time that a file is written. + +- Support configuration tasks. The following types are used to support various configuration tasks: + + - + + - + + - + + - + + - + + - + + - + In addition to working with existing configuration information, you can create and work with custom configuration elements by extending the built-in configuration types such as the , , , and classes. For an example of how to extend a built-in configuration type programmatically, see . For an example of how to extend a built-in configuration type that uses the attribute-based model, see . - -## Examples - The first example shows a simple console application that reads application settings, adds a new setting, and updates an existing setting. - -```csharp -using System; -using System.Configuration; - -namespace ConsoleApplication1 -{ - class Program - { - static void Main(string[] args) - { - ReadAllSettings(); - ReadSetting("Setting1"); - ReadSetting("NotValid"); - AddUpdateAppSettings("NewSetting", "May 7, 2014"); - AddUpdateAppSettings("Setting1", "May 8, 2014"); - ReadAllSettings(); - } - - static void ReadAllSettings() - { - try - { - var appSettings = ConfigurationManager.AppSettings; - - if (appSettings.Count == 0) - { - Console.WriteLine("AppSettings is empty."); - } - else - { - foreach (var key in appSettings.AllKeys) - { - Console.WriteLine("Key: {0} Value: {1}", key, appSettings[key]); - } - } - } - catch (ConfigurationErrorsException) - { - Console.WriteLine("Error reading app settings"); - } - } - - static void ReadSetting(string key) - { - try - { - var appSettings = ConfigurationManager.AppSettings; - string result = appSettings[key] ?? "Not Found"; - Console.WriteLine(result); - } - catch (ConfigurationErrorsException) - { - Console.WriteLine("Error reading app settings"); - } - } - - static void AddUpdateAppSettings(string key, string value) - { - try - { - var configFile = ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None); - var settings = configFile.AppSettings.Settings; - if (settings[key] == null) - { - settings.Add(key, value); - } - else - { - settings[key].Value = value; - } - configFile.Save(ConfigurationSaveMode.Modified); - ConfigurationManager.RefreshSection(configFile.AppSettings.SectionInformation.Name); - } - catch (ConfigurationErrorsException) - { - Console.WriteLine("Error writing app settings"); - } - } - } -} -``` - -```vb -Imports System.Configuration -Module Module1 - - Sub Main() - ReadAllSettings() - ReadSetting("Setting1") - ReadSetting("NotValid") - AddUpdateAppSettings("NewSetting", "May 7, 2014") - AddUpdateAppSettings("Setting1", "May 8, 2014") - ReadAllSettings() - End Sub - - Sub ReadAllSettings() - Try - Dim appSettings = ConfigurationManager.AppSettings - - If appSettings.Count = 0 Then - Console.WriteLine("AppSettings is empty.") - Else - For Each key As String In appSettings.AllKeys - Console.WriteLine("Key: {0} Value: {1}", key, appSettings(key)) - Next - End If - Catch e As ConfigurationErrorsException - Console.WriteLine("Error reading app settings") - End Try - End Sub - - Sub ReadSetting(key As String) - Try - Dim appSettings = ConfigurationManager.AppSettings - Dim result As String = appSettings(key) - If IsNothing(result) Then - result = "Not found" - End If - Console.WriteLine(result) - Catch e As ConfigurationErrorsException - Console.WriteLine("Error reading app settings") - End Try - End Sub - - Sub AddUpdateAppSettings(key As String, value As String) - Try - Dim configFile = ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None) - Dim settings = configFile.AppSettings.Settings - If IsNothing(settings(key)) Then - settings.Add(key, value) - Else - settings(key).Value = value - End If - configFile.Save(ConfigurationSaveMode.Modified) - ConfigurationManager.RefreshSection(configFile.AppSettings.SectionInformation.Name) - Catch e As ConfigurationErrorsException - Console.WriteLine("Error writing app settings") - End Try - End Sub - -End Module -``` - - The previous example assumes your project has an App.config file as shown below. - -```xml - - - - - - - - - - -``` - - The following example shows how to use a connection string to read data from a database. - -```csharp -using System; -using System.Configuration; -using System.Data.SqlClient; - -namespace ConsoleApplication1 -{ - class Program - { - static void Main(string[] args) - { - ReadProducts(); - } - - static void ReadProducts() - { - var connectionString = ConfigurationManager.ConnectionStrings["WingtipToys"].ConnectionString; - string queryString = "SELECT Id, ProductName FROM dbo.Products;"; - using (var connection = new SqlConnection(connectionString)) - { - var command = new SqlCommand(queryString, connection); - connection.Open(); - using (var reader = command.ExecuteReader()) - { - while (reader.Read()) - { - Console.WriteLine(String.Format("{0}, {1}", reader[0], reader[1])); - } - } - } - } - } -} -``` - -```vb -Imports System.Configuration -Imports System.Data.SqlClient -Module Module1 - - Sub Main() - ReadProducts() - End Sub - - Sub ReadProducts() - Dim connectionString = ConfigurationManager.ConnectionStrings("WingtipToys").ConnectionString - Dim queryString = "SELECT Id, ProductName FROM dbo.Products;" - Using connection As New SqlConnection(connectionString) - Dim command = New SqlCommand(queryString, connection) - connection.Open() - - Using reader As SqlDataReader = command.ExecuteReader() - While reader.Read() - Console.WriteLine(String.Format("{0}, {1}", reader(0), reader(1))) - End While - End Using - End Using - End Sub - -End Module -``` - - The previous example assumes your project has an App.config as shown below. - -```xml - - - - - - - - - -``` - + +## Examples + The first example shows a simple console application that reads application settings, adds a new setting, and updates an existing setting. + +```csharp +using System; +using System.Configuration; + +namespace ConsoleApplication1 +{ + class Program + { + static void Main(string[] args) + { + ReadAllSettings(); + ReadSetting("Setting1"); + ReadSetting("NotValid"); + AddUpdateAppSettings("NewSetting", "May 7, 2014"); + AddUpdateAppSettings("Setting1", "May 8, 2014"); + ReadAllSettings(); + } + + static void ReadAllSettings() + { + try + { + var appSettings = ConfigurationManager.AppSettings; + + if (appSettings.Count == 0) + { + Console.WriteLine("AppSettings is empty."); + } + else + { + foreach (var key in appSettings.AllKeys) + { + Console.WriteLine("Key: {0} Value: {1}", key, appSettings[key]); + } + } + } + catch (ConfigurationErrorsException) + { + Console.WriteLine("Error reading app settings"); + } + } + + static void ReadSetting(string key) + { + try + { + var appSettings = ConfigurationManager.AppSettings; + string result = appSettings[key] ?? "Not Found"; + Console.WriteLine(result); + } + catch (ConfigurationErrorsException) + { + Console.WriteLine("Error reading app settings"); + } + } + + static void AddUpdateAppSettings(string key, string value) + { + try + { + var configFile = ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None); + var settings = configFile.AppSettings.Settings; + if (settings[key] == null) + { + settings.Add(key, value); + } + else + { + settings[key].Value = value; + } + configFile.Save(ConfigurationSaveMode.Modified); + ConfigurationManager.RefreshSection(configFile.AppSettings.SectionInformation.Name); + } + catch (ConfigurationErrorsException) + { + Console.WriteLine("Error writing app settings"); + } + } + } +} +``` + +```vb +Imports System.Configuration +Module Module1 + + Sub Main() + ReadAllSettings() + ReadSetting("Setting1") + ReadSetting("NotValid") + AddUpdateAppSettings("NewSetting", "May 7, 2014") + AddUpdateAppSettings("Setting1", "May 8, 2014") + ReadAllSettings() + End Sub + + Sub ReadAllSettings() + Try + Dim appSettings = ConfigurationManager.AppSettings + + If appSettings.Count = 0 Then + Console.WriteLine("AppSettings is empty.") + Else + For Each key As String In appSettings.AllKeys + Console.WriteLine("Key: {0} Value: {1}", key, appSettings(key)) + Next + End If + Catch e As ConfigurationErrorsException + Console.WriteLine("Error reading app settings") + End Try + End Sub + + Sub ReadSetting(key As String) + Try + Dim appSettings = ConfigurationManager.AppSettings + Dim result As String = appSettings(key) + If IsNothing(result) Then + result = "Not found" + End If + Console.WriteLine(result) + Catch e As ConfigurationErrorsException + Console.WriteLine("Error reading app settings") + End Try + End Sub + + Sub AddUpdateAppSettings(key As String, value As String) + Try + Dim configFile = ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None) + Dim settings = configFile.AppSettings.Settings + If IsNothing(settings(key)) Then + settings.Add(key, value) + Else + settings(key).Value = value + End If + configFile.Save(ConfigurationSaveMode.Modified) + ConfigurationManager.RefreshSection(configFile.AppSettings.SectionInformation.Name) + Catch e As ConfigurationErrorsException + Console.WriteLine("Error writing app settings") + End Try + End Sub + +End Module +``` + + The previous example assumes your project has an App.config file as shown below. + +```xml + + + + + + + + + + +``` + + The following example shows how to use a connection string to read data from a database. + +```csharp +using System; +using System.Configuration; +using System.Data.SqlClient; + +namespace ConsoleApplication1 +{ + class Program + { + static void Main(string[] args) + { + ReadProducts(); + } + + static void ReadProducts() + { + var connectionString = ConfigurationManager.ConnectionStrings["WingtipToys"].ConnectionString; + string queryString = "SELECT Id, ProductName FROM dbo.Products;"; + using (var connection = new SqlConnection(connectionString)) + { + var command = new SqlCommand(queryString, connection); + connection.Open(); + using (var reader = command.ExecuteReader()) + { + while (reader.Read()) + { + Console.WriteLine(String.Format("{0}, {1}", reader[0], reader[1])); + } + } + } + } + } +} +``` + +```vb +Imports System.Configuration +Imports System.Data.SqlClient +Module Module1 + + Sub Main() + ReadProducts() + End Sub + + Sub ReadProducts() + Dim connectionString = ConfigurationManager.ConnectionStrings("WingtipToys").ConnectionString + Dim queryString = "SELECT Id, ProductName FROM dbo.Products;" + Using connection As New SqlConnection(connectionString) + Dim command = New SqlCommand(queryString, connection) + connection.Open() + + Using reader As SqlDataReader = command.ExecuteReader() + While reader.Read() + Console.WriteLine(String.Format("{0}, {1}", reader(0), reader(1))) + End While + End Using + End Using + End Sub + +End Module +``` + + The previous example assumes your project has an App.config as shown below. + +```xml + + + + + + + + + +``` + ]]> - The class enables programmatic access for editing configuration files. You use one of the Open methods provided by . These methods return a object, which in turn provides the required methods and properties to handle the underlying configuration files. You can access these files for reading or writing. - - To read the configuration files, use or . The user or process that reads must have the following permissions: - -- Read permission on the configuration file at the current configuration hierarchy level. - -- Read permissions on all the parent configuration files. - - If your application needs read-only access to its own configuration, we recommend that you use the method. This method provides access to the cached configuration values for the current application, which has better performance than the class. - - To write to the configuration files, use one of the methods. The user or process that writes must have the following permissions: - -- Write permission on the configuration file and directory at the current configuration hierarchy level. - + The class enables programmatic access for editing configuration files. You use one of the Open methods provided by . These methods return a object, which in turn provides the required methods and properties to handle the underlying configuration files. You can access these files for reading or writing. + + To read the configuration files, use or . The user or process that reads must have the following permissions: + +- Read permission on the configuration file at the current configuration hierarchy level. + +- Read permissions on all the parent configuration files. + + If your application needs read-only access to its own configuration, we recommend that you use the method. This method provides access to the cached configuration values for the current application, which has better performance than the class. + + To write to the configuration files, use one of the methods. The user or process that writes must have the following permissions: + +- Write permission on the configuration file and directory at the current configuration hierarchy level. + - Read permissions on all the configuration files. @@ -361,172 +361,172 @@ End Module Gets the data for the current application's default configuration. The contents of the object for the current application's default configuration. - object contains the contents of the configuration file's `appSettings` section. - -## Examples - The first example shows a simple console application that reads application settings, adds a new setting, and updates an existing setting. - -```csharp -using System; -using System.Configuration; - -namespace ConsoleApplication1 -{ - class Program - { - static void Main(string[] args) - { - ReadAllSettings(); - ReadSetting("Setting1"); - ReadSetting("NotValid"); - AddUpdateAppSettings("NewSetting", "May 7, 2014"); - AddUpdateAppSettings("Setting1", "May 8, 2014"); - ReadAllSettings(); - } - - static void ReadAllSettings() - { - try - { - var appSettings = ConfigurationManager.AppSettings; - - if (appSettings.Count == 0) - { - Console.WriteLine("AppSettings is empty."); - } - else - { - foreach (var key in appSettings.AllKeys) - { - Console.WriteLine("Key: {0} Value: {1}", key, appSettings[key]); - } - } - } - catch (ConfigurationErrorsException) - { - Console.WriteLine("Error reading app settings"); - } - } - - static void ReadSetting(string key) - { - try - { - var appSettings = ConfigurationManager.AppSettings; - string result = appSettings[key] ?? "Not Found"; - Console.WriteLine(result); - } - catch (ConfigurationErrorsException) - { - Console.WriteLine("Error reading app settings"); - } - } - - static void AddUpdateAppSettings(string key, string value) - { - try - { - var configFile = ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None); - var settings = configFile.AppSettings.Settings; - if (settings[key] == null) - { - settings.Add(key, value); - } - else - { - settings[key].Value = value; - } - configFile.Save(ConfigurationSaveMode.Modified); - ConfigurationManager.RefreshSection(configFile.AppSettings.SectionInformation.Name); - } - catch (ConfigurationErrorsException) - { - Console.WriteLine("Error writing app settings"); - } - } - } -} -``` - -```vb -Imports System.Configuration -Module Module1 - - Sub Main() - ReadAllSettings() - ReadSetting("Setting1") - ReadSetting("NotValid") - AddUpdateAppSettings("NewSetting", "May 7, 2014") - AddUpdateAppSettings("Setting1", "May 8, 2014") - ReadAllSettings() - End Sub - - Sub ReadAllSettings() - Try - Dim appSettings = ConfigurationManager.AppSettings - - If appSettings.Count = 0 Then - Console.WriteLine("AppSettings is empty.") - Else - For Each key As String In appSettings.AllKeys - Console.WriteLine("Key: {0} Value: {1}", key, appSettings(key)) - Next - End If - Catch e As ConfigurationErrorsException - Console.WriteLine("Error reading app settings") - End Try - End Sub - - Sub ReadSetting(key As String) - Try - Dim appSettings = ConfigurationManager.AppSettings - Dim result As String = appSettings(key) - If IsNothing(result) Then - result = "Not found" - End If - Console.WriteLine(result) - Catch e As ConfigurationErrorsException - Console.WriteLine("Error reading app settings") - End Try - End Sub - - Sub AddUpdateAppSettings(key As String, value As String) - Try - Dim configFile = ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None) - Dim settings = configFile.AppSettings.Settings - If IsNothing(settings(key)) Then - settings.Add(key, value) - Else - settings(key).Value = value - End If - configFile.Save(ConfigurationSaveMode.Modified) - ConfigurationManager.RefreshSection(configFile.AppSettings.SectionInformation.Name) - Catch e As ConfigurationErrorsException - Console.WriteLine("Error writing app settings") - End Try - End Sub - -End Module -``` - - The previous example assumes your project has an App.config file as shown below. - -```xml - - - - - - - - - - -``` - + +## Examples + The first example shows a simple console application that reads application settings, adds a new setting, and updates an existing setting. + +```csharp +using System; +using System.Configuration; + +namespace ConsoleApplication1 +{ + class Program + { + static void Main(string[] args) + { + ReadAllSettings(); + ReadSetting("Setting1"); + ReadSetting("NotValid"); + AddUpdateAppSettings("NewSetting", "May 7, 2014"); + AddUpdateAppSettings("Setting1", "May 8, 2014"); + ReadAllSettings(); + } + + static void ReadAllSettings() + { + try + { + var appSettings = ConfigurationManager.AppSettings; + + if (appSettings.Count == 0) + { + Console.WriteLine("AppSettings is empty."); + } + else + { + foreach (var key in appSettings.AllKeys) + { + Console.WriteLine("Key: {0} Value: {1}", key, appSettings[key]); + } + } + } + catch (ConfigurationErrorsException) + { + Console.WriteLine("Error reading app settings"); + } + } + + static void ReadSetting(string key) + { + try + { + var appSettings = ConfigurationManager.AppSettings; + string result = appSettings[key] ?? "Not Found"; + Console.WriteLine(result); + } + catch (ConfigurationErrorsException) + { + Console.WriteLine("Error reading app settings"); + } + } + + static void AddUpdateAppSettings(string key, string value) + { + try + { + var configFile = ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None); + var settings = configFile.AppSettings.Settings; + if (settings[key] == null) + { + settings.Add(key, value); + } + else + { + settings[key].Value = value; + } + configFile.Save(ConfigurationSaveMode.Modified); + ConfigurationManager.RefreshSection(configFile.AppSettings.SectionInformation.Name); + } + catch (ConfigurationErrorsException) + { + Console.WriteLine("Error writing app settings"); + } + } + } +} +``` + +```vb +Imports System.Configuration +Module Module1 + + Sub Main() + ReadAllSettings() + ReadSetting("Setting1") + ReadSetting("NotValid") + AddUpdateAppSettings("NewSetting", "May 7, 2014") + AddUpdateAppSettings("Setting1", "May 8, 2014") + ReadAllSettings() + End Sub + + Sub ReadAllSettings() + Try + Dim appSettings = ConfigurationManager.AppSettings + + If appSettings.Count = 0 Then + Console.WriteLine("AppSettings is empty.") + Else + For Each key As String In appSettings.AllKeys + Console.WriteLine("Key: {0} Value: {1}", key, appSettings(key)) + Next + End If + Catch e As ConfigurationErrorsException + Console.WriteLine("Error reading app settings") + End Try + End Sub + + Sub ReadSetting(key As String) + Try + Dim appSettings = ConfigurationManager.AppSettings + Dim result As String = appSettings(key) + If IsNothing(result) Then + result = "Not found" + End If + Console.WriteLine(result) + Catch e As ConfigurationErrorsException + Console.WriteLine("Error reading app settings") + End Try + End Sub + + Sub AddUpdateAppSettings(key As String, value As String) + Try + Dim configFile = ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None) + Dim settings = configFile.AppSettings.Settings + If IsNothing(settings(key)) Then + settings.Add(key, value) + Else + settings(key).Value = value + End If + configFile.Save(ConfigurationSaveMode.Modified) + ConfigurationManager.RefreshSection(configFile.AppSettings.SectionInformation.Name) + Catch e As ConfigurationErrorsException + Console.WriteLine("Error writing app settings") + End Try + End Sub + +End Module +``` + + The previous example assumes your project has an App.config file as shown below. + +```xml + + + + + + + + + + +``` + ]]> Could not retrieve a object with the application settings data. @@ -564,90 +564,90 @@ End Module Gets the data for the current application's default configuration. The contents of the object for the current application's default configuration. - object contains the contents of the configuration file's `connectionStrings` section. - -## Examples - The following example shows how to use a connection string to read data from a database. - -```csharp -using System; -using System.Configuration; -using System.Data.SqlClient; - -namespace ConsoleApplication1 -{ - class Program - { - static void Main(string[] args) - { - ReadProducts(); - } - - static void ReadProducts() - { - var connectionString = ConfigurationManager.ConnectionStrings["WingtipToys"].ConnectionString; - string queryString = "SELECT Id, ProductName FROM dbo.Products;"; - using (var connection = new SqlConnection(connectionString)) - { - var command = new SqlCommand(queryString, connection); - connection.Open(); - using (var reader = command.ExecuteReader()) - { - while (reader.Read()) - { - Console.WriteLine(String.Format("{0}, {1}", reader[0], reader[1])); - } - } - } - } - } -} -``` - -```vb -Imports System.Configuration -Imports System.Data.SqlClient -Module Module1 - - Sub Main() - ReadProducts() - End Sub - - Sub ReadProducts() - Dim connectionString = ConfigurationManager.ConnectionStrings("WingtipToys").ConnectionString - Dim queryString = "SELECT Id, ProductName FROM dbo.Products;" - Using connection As New SqlConnection(connectionString) - Dim command = New SqlCommand(queryString, connection) - connection.Open() - - Using reader As SqlDataReader = command.ExecuteReader() - While reader.Read() - Console.WriteLine(String.Format("{0}, {1}", reader(0), reader(1))) - End While - End Using - End Using - End Sub - -End Module -``` - - The previous example assumes your project has an App.config as shown below. - -```xml - - - - - - - - - -``` - + +## Examples + The following example shows how to use a connection string to read data from a database. + +```csharp +using System; +using System.Configuration; +using System.Data.SqlClient; + +namespace ConsoleApplication1 +{ + class Program + { + static void Main(string[] args) + { + ReadProducts(); + } + + static void ReadProducts() + { + var connectionString = ConfigurationManager.ConnectionStrings["WingtipToys"].ConnectionString; + string queryString = "SELECT Id, ProductName FROM dbo.Products;"; + using (var connection = new SqlConnection(connectionString)) + { + var command = new SqlCommand(queryString, connection); + connection.Open(); + using (var reader = command.ExecuteReader()) + { + while (reader.Read()) + { + Console.WriteLine(String.Format("{0}, {1}", reader[0], reader[1])); + } + } + } + } + } +} +``` + +```vb +Imports System.Configuration +Imports System.Data.SqlClient +Module Module1 + + Sub Main() + ReadProducts() + End Sub + + Sub ReadProducts() + Dim connectionString = ConfigurationManager.ConnectionStrings("WingtipToys").ConnectionString + Dim queryString = "SELECT Id, ProductName FROM dbo.Products;" + Using connection As New SqlConnection(connectionString) + Dim command = New SqlCommand(queryString, connection) + connection.Open() + + Using reader As SqlDataReader = command.ExecuteReader() + While reader.Read() + Console.WriteLine(String.Format("{0}, {1}", reader(0), reader(1))) + End While + End Using + End Using + End Sub + +End Module +``` + + The previous example assumes your project has an App.config as shown below. + +```xml + + + + + + + + + +``` + ]]> Could not retrieve a object. @@ -689,30 +689,30 @@ End Module Retrieves a specified configuration section for the current application's default configuration. The specified object, or if the section does not exist. - method accesses run-time configuration information that it cannot change. To change the configuration, you use the method on the configuration file that you obtain by using one of the following methods: - -- - -- - + method accesses run-time configuration information that it cannot change. To change the configuration, you use the method on the configuration file that you obtain by using one of the following methods: + +- + +- + - - -## Examples - The following example shows how to use the method. The example is part of a larger example that is provided for the class. - + +## Examples + The following example shows how to use the method. The example is part of a larger example that is provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/CS/configurationmanager.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb" id="Snippet7"::: + ]]> A configuration file could not be loaded. - You must cast the return value to the expected configuration type. To avoid possible casting exceptions, you should use a conditional casting operation such as the operator in C# or the [TryCast](/dotnet/visual-basic/language-reference/operators/trycast-operator) function in Visual Basic. + You must cast the return value to the expected configuration type. To avoid possible casting exceptions, you should use a conditional casting operation such as the operator in C# or the TryCast function in Visual Basic. @@ -760,28 +760,28 @@ End Module Opens the configuration file for the current application as a object. The configuration file for the current application. - object that applies to all users, set `userLevel` to . - -- To get the local object that applies to the current user, set `userLevel` to . - -- To get the roaming object that applies to the current user, set `userLevel` to . - + object that applies to all users, set `userLevel` to . + +- To get the local object that applies to the current user, set `userLevel` to . + +- To get the roaming object that applies to the current user, set `userLevel` to . + > [!NOTE] > To get the object for a resource, your code must have read permissions on all the configuration files from which it inherits settings. To update a configuration file, your code must additionally have write permissions for both the configuration file and the directory in which it exists. - -## Examples - The following code example shows how to use the method. - + +## Examples + The following code example shows how to use the method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/CS/configurationmanager.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb" id="Snippet5"::: + ]]> A configuration file could not be loaded. @@ -823,18 +823,18 @@ End Module Opens the specified client configuration file as a object. The specified configuration file. - overload with the `preLoad` parameter set to `false`. - -## Examples - The following code example shows how to use the method. - + +## Examples + The following code example shows how to use the method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/CS/configurationmanager.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb" id="Snippet6"::: + ]]> A configuration file could not be loaded. @@ -873,22 +873,22 @@ Calling this method overload is equivalent to calling the Opens the machine configuration file on the current computer as a object. The machine configuration file. - [!NOTE] > To obtain the object for a resource, your code must have read permissions on all the configuration files from which it inherits settings. To update a configuration file, your code must additionally have write permissions for both the configuration file and the directory in which it exists. It is not possible to access the Machine.config file for other versions of the .NET Framework that might be installed on the computer. - -## Examples - The following code example shows how to use the method to obtain all sections that are contained in the configuration file. - + +## Examples + The following code example shows how to use the method to obtain all sections that are contained in the configuration file. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/CS/configurationmanager.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb" id="Snippet4"::: + ]]> A configuration file could not be loaded. @@ -940,20 +940,20 @@ Calling this method overload is equivalent to calling the Opens the specified client configuration file as a object that uses the specified file mapping and user level. The configuration object. - object determines the location of the configuration file being opened. It indicates whether the file has no user level (the configuration file is in the same directory as the application) or has a per-user level (the configuration file is in an application settings path determined by `userLevel`). - + object determines the location of the configuration file being opened. It indicates whether the file has no user level (the configuration file is in the same directory as the application) or has a per-user level (the configuration file is in an application settings path determined by `userLevel`). + > [!NOTE] > To obtain the object for a resource, your code must have read permissions on all the configuration files from which it inherits settings. To update a configuration file, your code must additionally have write permissions for both the configuration file and the directory in which it exists. - -## Examples - The following code example shows how to use the method to obtain all sections that are contained by the configuration file. - + +## Examples + The following code example shows how to use the method to obtain all sections that are contained by the configuration file. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/CS/configurationmanager.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb" id="Snippet9"::: + ]]> A configuration file could not be loaded. @@ -999,16 +999,16 @@ Calling this method overload is equivalent to calling the Opens the specified client configuration file as a object that uses the specified file mapping, user level, and preload option. The configuration object. - object determines the location of the configuration file that is being opened. It indicates whether the file has no user level (the configuration file is in the same directory as the application) or has a per-user level (the configuration file is in an application settings path that is determined by `userLevel`). - + object determines the location of the configuration file that is being opened. It indicates whether the file has no user level (the configuration file is in the same directory as the application) or has a per-user level (the configuration file is in an application settings path that is determined by `userLevel`). + > [!NOTE] -> To obtain the object for a resource, your code must have read permissions on all the configuration files from which it inherits settings. To update a configuration file, your code must additionally have write permissions for both the configuration file and the directory in which it exists. - - For a code example, see the overload. - +> To obtain the object for a resource, your code must have read permissions on all the configuration files from which it inherits settings. To update a configuration file, your code must additionally have write permissions for both the configuration file and the directory in which it exists. + + For a code example, see the overload. + ]]> A configuration file could not be loaded. @@ -1048,22 +1048,22 @@ Calling this method overload is equivalent to calling the Opens the machine configuration file as a object that uses the specified file mapping. The machine configuration file. - [!NOTE] > To obtain the object for a resource, your code must have read permissions on all the configuration files from which it inherits settings. To update a configuration file, your code must additionally have write permissions for both the configuration file and the directory in which it exists. It is not possible to access the Machine.config file for other versions of the .NET Framework that might be installed on the computer. - -## Examples - The following code example shows how to use the method to obtain all sections in the configuration file. - + +## Examples + The following code example shows how to use the method to obtain all sections in the configuration file. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/CS/configurationmanager.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb" id="Snippet4"::: + ]]> A configuration file could not be loaded. @@ -1104,17 +1104,17 @@ Calling this method overload is equivalent to calling the The configuration section name or the configuration path and section name of the section to refresh. Refreshes the named section so the next time that it is retrieved it will be re-read from disk. - method to refresh the application settings configuration section. - + +## Examples + The following code example shows how to use the method to refresh the application settings configuration section. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/CS/configurationmanager.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb" id="Snippet7"::: + ]]> diff --git a/xml/System.Deployment.Internal/InternalApplicationIdentityHelper.xml b/xml/System.Deployment.Internal/InternalApplicationIdentityHelper.xml index fd754e45619..31752d69d12 100644 --- a/xml/System.Deployment.Internal/InternalApplicationIdentityHelper.xml +++ b/xml/System.Deployment.Internal/InternalApplicationIdentityHelper.xml @@ -54,7 +54,7 @@ The object from which to extract the identifier. - Gets an [IDefinitionAppId Interface](/dotnet/framework/unmanaged-api/fusion/idefinitionappid-interface) representing the unique identifier of an object. + Gets an IDefinitionAppId Interface representing the unique identifier of an object. The unique identifier held by the object. To be added. IDefinitionAppId Interface diff --git a/xml/System.Diagnostics.Eventing.Reader/EventLogRecord.xml b/xml/System.Diagnostics.Eventing.Reader/EventLogRecord.xml index 5c1b26120ab..bae581c43a8 100644 --- a/xml/System.Diagnostics.Eventing.Reader/EventLogRecord.xml +++ b/xml/System.Diagnostics.Eventing.Reader/EventLogRecord.xml @@ -1143,7 +1143,7 @@ - Gets the XML representation of the event. All of the event properties are represented in the event's XML. The XML conforms to the [event schema](/windows/win32/wes/eventschema-schema). + Gets the XML representation of the event. All of the event properties are represented in the event's XML. The XML conforms to the event schema. Returns a string that contains the XML representation of the event. To be added. Technology Summary for Reading and Managing Event Logs diff --git a/xml/System.Diagnostics.SymbolStore/SymWriter.xml b/xml/System.Diagnostics.SymbolStore/SymWriter.xml index c5ab22c73ab..3a8837241c3 100644 --- a/xml/System.Diagnostics.SymbolStore/SymWriter.xml +++ b/xml/System.Diagnostics.SymbolStore/SymWriter.xml @@ -38,11 +38,11 @@ Represents a symbol writer for managed code. - class provides methods that define documents, sequence points, lexical scopes, and variables. - + class provides methods that define documents, sequence points, lexical scopes, and variables. + ]]> @@ -113,7 +113,7 @@ method to release resources. ]]> @@ -141,12 +141,12 @@ Use the method to relea Releases the resources held by the current instance of the object. - method to release resources. - + ]]> @@ -180,11 +180,11 @@ Use the method to relea Closes the and commits the symbols to the symbol store. - becomes invalid for further updates. - + becomes invalid for further updates. + ]]> @@ -217,11 +217,11 @@ Use the method to relea Closes the current method. - @@ -287,11 +287,11 @@ Use the method to relea The IL offset just past the last instruction in the scope. Closes the current lexical scope. - @@ -477,13 +477,13 @@ Use the method to relea The end offset for the variable. If zero, this parameter is ignored and the variable is defined throughout the entire scope. If nonzero, it falls within the offsets of the current scope. Defines a single variable in the current lexical scope. - multiple times for a variable of the same name that occurs multiple times in different offset ranges throughout a scope. (In this case, start and end offsets must not overlap.) - + multiple times for a variable of the same name that occurs multiple times in different offset ranges throughout a scope. (In this case, start and end offsets must not overlap.) + ]]> @@ -575,11 +575,11 @@ Use the method to relea The ending column numbers of the sequence points. Defines a group of sequence points within the current method. - object. Each element at a specific index of every array corresponds to a specific sequence point. Each line and each column defines the start of a statement within a method. The arrays should be sorted in the increasing order of offsets. The offset is always the offset from the start of the method, in bytes. - + object. Each element at a specific index of every array corresponds to a specific sequence point. Each line and each column defines the start of a statement within a method. The arrays should be sorted in the increasing order of offsets. The offset is always the offset from the start of the method, in bytes. + ]]> @@ -637,11 +637,11 @@ Use the method to relea to release managed and unmanaged resources; to release only unmanaged resources. Called by the and methods to release the managed and unmanaged resources used by the current instance of the class. - and methods; do not call this method directly. - + and methods; do not call this method directly. + ]]> @@ -668,11 +668,11 @@ Use the method to relea Releases unmanaged resources and performs other cleanup operations before the is reclaimed by garbage collection. - . 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. - + . 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. + ]]> @@ -742,11 +742,11 @@ Use the method to relea indicates that this is a full rebuild; indicates an incremental compilation. Sets the metadata emitter interface to associate with this writer. - also sets the output file name where the debugging symbols are written. This method can be called only once and must be called before any other writer methods are called. - + also sets the output file name where the debugging symbols are written. This method can be called only once and must be called before any other writer methods are called. + ]]> @@ -810,11 +810,11 @@ Use the method to relea The metadata token for the method to be opened. Opens a method in which to place symbol information. - @@ -850,11 +850,11 @@ Use the method to relea The name of the new namespace. Opens a new namespace. - @@ -891,13 +891,13 @@ Use the method to relea Opens a new lexical scope in the current method. An opaque scope identifier that can be used with to define the start and end offsets of a scope at a later time. In this case, the offsets passed to and are ignored. A scope identifier is valid only in the current method. - @@ -1018,11 +1018,11 @@ Use the method to relea The attribute value. Defines an attribute when given the attribute name and the attribute value. - method is only associated with symbolic information and is not a metadata custom attribute. - + method is only associated with symbolic information and is not a metadata custom attribute. + ]]> @@ -1056,13 +1056,13 @@ Use the method to relea An type pointer to code that is the underlying writer. - Sets the underlying [ISymUnmanagedWriter Interface](/dotnet/framework/unmanaged-api/diagnostics/isymunmanagedwriter-interface) (the corresponding unmanaged API) that a managed uses to emit symbols. + Sets the underlying ISymUnmanagedWriter Interface (the corresponding unmanaged API) that a managed uses to emit symbols. - @@ -1098,11 +1098,11 @@ Use the method to relea The metadata token for the method that is the user entry point. Identifies the user-defined method as the entry point for the current module. - @@ -1138,11 +1138,11 @@ Use the method to relea The fully qualified name of the namespace. Specifies that the given, fully qualified namespace name is used within the open lexical scope. - diff --git a/xml/System.Diagnostics.Tracing/EventSource.xml b/xml/System.Diagnostics.Tracing/EventSource.xml index 8c2a8e53d27..667cf42f810 100644 --- a/xml/System.Diagnostics.Tracing/EventSource.xml +++ b/xml/System.Diagnostics.Tracing/EventSource.xml @@ -696,9 +696,9 @@ - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier the Dispose Method call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier the Dispose Method call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + For more information about and , see Cleaning Up Unmanaged Resources. diff --git a/xml/System.Diagnostics/DiagnosticSource.xml b/xml/System.Diagnostics/DiagnosticSource.xml index 4686fca8940..c5aa0e73a74 100644 --- a/xml/System.Diagnostics/DiagnosticSource.xml +++ b/xml/System.Diagnostics/DiagnosticSource.xml @@ -35,7 +35,7 @@ An abstract class that allows code to be instrumented for production-time logging of rich data payloads for consumption within the process that was instrumented. - For more information, see [DiagnosticSource User's Guide](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md). + For more information, see DiagnosticSource User's Guide. @@ -151,9 +151,9 @@ If there is expensive setup for the notification, you can call IsEnabled before if the notification event is enabled, otherwise. @@ -194,7 +194,7 @@ If there is expensive setup for the notification, you can call this method and p An object that represents the outgoing request. Transfers state from an activity to some event or operation, such as an outgoing HTTP request, that will occur outside the process. - as well as a payload object that represents the outgoing request. A subscriber then has the ability to update the outgoing request before it is sent. - -Note that this method is rarely used at instrumentation sites (only those sites that are on an outgoing boundary of the process). Moreover, typically the default policy that the instrumentation site performs (for example, to transfer all activity state in a + +Note that this method is rarely used at instrumentation sites (only those sites that are on an outgoing boundary of the process). Moreover, typically the default policy that the instrumentation site performs (for example, to transfer all activity state in a particular outgoing convention) is likely to be fine. This method is only for cases where that is a problem. Thus, this method should be used very rarely and is mostly here for symetry with `OnActivityImport` and future-proofing. Note that `payload` is typed as an here, but any particular instrumentation site and subscriber should know the type of the payload and thus cast and decode it if necessary. @@ -248,11 +248,11 @@ Note that `payload` is typed as an here, but any particular A payload that represents the incoming request. Transfers state to an activity from some event or operation, such as an incoming request, that occurred outside the process. - and the incoming request logic at the instrumentation site. However, the instrumentation site can't handle policy. (For example, if sampling is done, exactly which requests should be sampled?) In these cases, the instrumentation site needs to call back out to the logging system and ask it to resolve policy (for example, to decide if the activity's "sampling" bit should be set). This is the purpose of the `OnActivityImport` method. It is given the activity as well as a payload object that represents the incoming request. The subscribers to the then have the opportunity to update this activity as desired. +To the extent possible, this should be done by the instrumentation site, because there is a contract between the and the incoming request logic at the instrumentation site. However, the instrumentation site can't handle policy. (For example, if sampling is done, exactly which requests should be sampled?) In these cases, the instrumentation site needs to call back out to the logging system and ask it to resolve policy (for example, to decide if the activity's "sampling" bit should be set). This is the purpose of the `OnActivityImport` method. It is given the activity as well as a payload object that represents the incoming request. The subscribers to the then have the opportunity to update this activity as desired. This method is rarely used at instrumentation sites (only those sites that are on the boundary of the process), and the instrumetation site implements some default policy (it sets the activity in *some* way), and so it is not necessary to override this method if that default policy is fine. In other words, this method should be overridden in very rare (but often important) cases. @@ -309,7 +309,7 @@ Note that `payload` is typed as here, but any particular in The started activity for convenient chaining. describes the logical operation, its context, and parent relation; the current flows through the operation processing. This method starts the given , maintains a global and activity for the given , and notifies consumers that a new was started. Consumers can access to add context and/or augment telemetry. @@ -411,11 +411,11 @@ Producers may pass additional details to the consumer in the payload. The activity to be stopped. An object that represents the value passed as a payload for the event. - Stops the given , maintains the global activity, and notifies consumers that the was stopped. - + Stops the given , maintains the global activity, and notifies consumers that the was stopped. + - The name of the event being written. An object that represents the value being passed as a payload for the event. This is often an anonymous type which contains several sub-values. - Provides a generic way of logging complex payloads. + Provides a generic way of logging complex payloads. - Provides interaction with Windows event logs. - lets you access or customize Windows event logs, which record information about important software or hardware events. Using , you can read from existing logs, write entries to logs, create or delete event sources, delete logs, and respond to log entries. You can also create new logs when creating an event source. - + lets you access or customize Windows event logs, which record information about important software or hardware events. Using , you can read from existing logs, write entries to logs, create or delete event sources, delete logs, and respond to log entries. You can also create new logs when creating an event source. + > [!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. - - In addition to providing access to individual event logs and their entries, the class lets you access the collection of all event logs. You can use the `static` members of to delete logs, get log lists, create or delete a source, or determine if a computer already contains a particular source. - - There are three default event logs: Application, System, and Security. A Security log is read-only. Other applications and services you install, such as Active Directory, might have additional event logs. - - There are security considerations when using the class. requires permissions for specific actions in the .NET Framework 2.0 and later versions, or full trust in the .NET Framework 1.0 and 1.1. We recommend that not be granted to partially trusted code. You should never pass any event log object, including and objects, to less trusted code. For example, creating an object, writing an entry, and then passing the object to partially trusted code can create a security issue, because the ability to read and write to the event log allows code to perform actions such as issuing event log messages in the name of another application. - - Starting with Windows Vista, User Account Control (UAC) determines the credentials 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. To run the code that accesses the Security log, you must first elevate your credentials from standard user to administrator. You can do this when you start an application by opening the shortcut menu for the application (if you're using a mouse, right-click the application icon) and indicating that you want to run as an administrator. - - You can use to create custom event logs that you can view through the server's Event Viewer. Use the method to display a localized name for your event log in the Event Viewer. Use the method to configure the behavior of your event log when it reaches its maximum log size. - - To read from an event log, specify the log name ( property) and server computer name ( property for the event log. If you don't specify the server computer name, the local computer, ".", is assumed. It's not necessary to specify the event source ( property), because a source is required only for writing to logs. The property is automatically populated with the event log's list of entries. - - To write to an event log, specify or create an event source ( property). You must have administrative credentials on the computer to create a new event source. The event source registers your application with the event log as a valid source of entries. You can use the event source to write to only one log at a time. The property can be any random string, but the name must be distinct from other sources on the computer. The event source is typically the name of the application or another identifying string. Trying to create a duplicate value throws an exception. However, a single event log can be associated with multiple sources. - - If the event source for the event log associated with the instance doesn't exist, a new event source is created. To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative credentials. - - This requirement is because all event logs, including Security logs, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the Security log; therefore, a is thrown. - +> 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. + + In addition to providing access to individual event logs and their entries, the class lets you access the collection of all event logs. You can use the `static` members of to delete logs, get log lists, create or delete a source, or determine if a computer already contains a particular source. + + There are three default event logs: Application, System, and Security. A Security log is read-only. Other applications and services you install, such as Active Directory, might have additional event logs. + + There are security considerations when using the class. requires permissions for specific actions in the .NET Framework 2.0 and later versions, or full trust in the .NET Framework 1.0 and 1.1. We recommend that not be granted to partially trusted code. You should never pass any event log object, including and objects, to less trusted code. For example, creating an object, writing an entry, and then passing the object to partially trusted code can create a security issue, because the ability to read and write to the event log allows code to perform actions such as issuing event log messages in the name of another application. + + Starting with Windows Vista, User Account Control (UAC) determines the credentials 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. To run the code that accesses the Security log, you must first elevate your credentials from standard user to administrator. You can do this when you start an application by opening the shortcut menu for the application (if you're using a mouse, right-click the application icon) and indicating that you want to run as an administrator. + + You can use to create custom event logs that you can view through the server's Event Viewer. Use the method to display a localized name for your event log in the Event Viewer. Use the method to configure the behavior of your event log when it reaches its maximum log size. + + To read from an event log, specify the log name ( property) and server computer name ( property for the event log. If you don't specify the server computer name, the local computer, ".", is assumed. It's not necessary to specify the event source ( property), because a source is required only for writing to logs. The property is automatically populated with the event log's list of entries. + + To write to an event log, specify or create an event source ( property). You must have administrative credentials on the computer to create a new event source. The event source registers your application with the event log as a valid source of entries. You can use the event source to write to only one log at a time. The property can be any random string, but the name must be distinct from other sources on the computer. The event source is typically the name of the application or another identifying string. Trying to create a duplicate value throws an exception. However, a single event log can be associated with multiple sources. + + If the event source for the event log associated with the instance doesn't exist, a new event source is created. To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative credentials. + + This requirement is because all event logs, including Security logs, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the Security log; therefore, a is thrown. + > [!IMPORTANT] -> Creating or deleting an event source requires synchronization of the underlying code by using a named mutex. If a highly privileged application locks the named mutex, trying to create or delete an event source causes the application to stop responding until the lock is released. To help prevent this problem, never grant permission to untrusted code. In addition, permission potentially allows other permissions to be bypassed and should only be granted to highly trusted code. - - Applications and services should write to the Application log or to a custom log. Device drivers should write to the System log. If you do not explicitly set the property, the event log defaults to the Application log. - +> Creating or deleting an event source requires synchronization of the underlying code by using a named mutex. If a highly privileged application locks the named mutex, trying to create or delete an event source causes the application to stop responding until the lock is released. To help prevent this problem, never grant permission to untrusted code. In addition, permission potentially allows other permissions to be bypassed and should only be granted to highly trusted code. + + Applications and services should write to the Application log or to a custom log. Device drivers should write to the System log. If you do not explicitly set the property, the event log defaults to the Application log. + > [!NOTE] -> There is nothing to protect an application from writing as any registered source. If an application is granted permission, it can write events for any valid source registered on the computer. - - Use the and methods to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. - - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system hasn't refreshed its list of event sources, and you try to write an event with the new source, the write operation will fail. You can configure a new source by using an object or the method. You must have administrative credentials on the computer to create a new event source. - - Each source can write to only one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration instead of deleting the existing source. - - You can register the event source with localized resources for your event category and message strings. Your application can write event log entries by using resource identifiers instead of specifying the actual string values. Refer to the and classes for more information about configuring your source with resource files. - - If your application writes string values directly to the event log, you do not have to set the resource file properties for the source. The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. - - When writing events, you must at least specify either a message string or the resource identifier for a message string. Other event properties are optional. Examples of optional event settings include the following: - -- You can set the to specify the icon that the Event Viewer displays for the entry. - -- You can specify a category identifier for the event, if your application uses categories for filtering the events. - -- You can attach binary data to your event entry if you want to associate additional information with a given event. - +> There is nothing to protect an application from writing as any registered source. If an application is granted permission, it can write events for any valid source registered on the computer. + + Use the and methods to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. + + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system hasn't refreshed its list of event sources, and you try to write an event with the new source, the write operation will fail. You can configure a new source by using an object or the method. You must have administrative credentials on the computer to create a new event source. + + Each source can write to only one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration instead of deleting the existing source. + + You can register the event source with localized resources for your event category and message strings. Your application can write event log entries by using resource identifiers instead of specifying the actual string values. Refer to the and classes for more information about configuring your source with resource files. + + If your application writes string values directly to the event log, you do not have to set the resource file properties for the source. The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + + When writing events, you must at least specify either a message string or the resource identifier for a message string. Other event properties are optional. Examples of optional event settings include the following: + +- You can set the to specify the icon that the Event Viewer displays for the entry. + +- You can specify a category identifier for the event, if your application uses categories for filtering the events. + +- You can attach binary data to your event entry if you want to associate additional information with a given event. + > [!IMPORTANT] -> Event logging consumes disk space, processor time, and other system resources. It is important to log only essential information. We recommend that you place event log calls in an error path, rather than in the main code path, so they don't adversely affect performance. - - For a list of initial property values for an instance of , see the constructor. - - - -## Examples - The following example creates the event source `MySource` if it doesn't already exist, and writes an entry to the event log `MyNewLog`. - +> Event logging consumes disk space, processor time, and other system resources. It is important to log only essential information. We recommend that you place event log calls in an error path, rather than in the main code path, so they don't adversely affect performance. + + For a list of initial property values for an instance of , see the constructor. + + + +## Examples + The following example creates the event source `MySource` if it doesn't already exist, and writes an entry to the event log `MyNewLog`. + > [!NOTE] -> Starting with Windows Vista, you must run this application as an administrator. - +> Starting with Windows Vista, you must run this application as an administrator. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.CreateEventSource Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.CreateEventSource Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.CreateEventSource Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -181,31 +181,31 @@ Initializes a new instance of the class. Does not associate the instance with any log. - , specify the property of the instance. If you are only reading from the log, you can alternatively specify only the and properties. - + , specify the property of the instance. If you are only reading from the log, you can alternatively specify only the and properties. + > [!NOTE] -> If you do not specify a , the local computer (".") is assumed. - - The following table shows initial property values for an instance of . - -|Property|Initial Value| -|--------------|-------------------| -||An empty string ("").| -||An empty string ("").| -||The local computer (".").| - - - -## Examples - The following example creates the source `MySource` if it does not already exist, and writes an entry to the event log `MyNewLog`. - +> If you do not specify a , the local computer (".") is assumed. + + The following table shows initial property values for an instance of . + +|Property|Initial Value| +|--------------|-------------------| +||An empty string ("").| +||An empty string ("").| +||The local computer (".").| + + + +## Examples + The following example creates the source `MySource` if it does not already exist, and writes an entry to the event log `MyNewLog`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.CreateEventSource Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.CreateEventSource Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.CreateEventSource Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -254,33 +254,33 @@ The name of the log on the local computer. Initializes a new instance of the class. Associates the instance with a log on the local computer. - property to the `logName` parameter. Before calling , specify the property of the instance. If you are only reading from the log, you can alternatively specify only the and properties. - + property to the `logName` parameter. Before calling , specify the property of the instance. If you are only reading from the log, you can alternatively specify only the and properties. + > [!NOTE] -> If you do not specify a , the local computer (".") is assumed. This overload of the constructor specifies the property, but you can change this before reading the property. - - If the source you specify in the property is unique from other sources on the computer, a subsequent call to creates a log with the specified name, if it does not already exist. - - The following table shows initial property values for an instance of . - -|Property|Initial Value| -|--------------|-------------------| -||An empty string ("").| -||The `logName` parameter.| -||The local computer (".").| - - - -## Examples - The following example reads entries in the event log, "myNewLog", on the local computer. - +> If you do not specify a , the local computer (".") is assumed. This overload of the constructor specifies the property, but you can change this before reading the property. + + If the source you specify in the property is unique from other sources on the computer, a subsequent call to creates a log with the specified name, if it does not already exist. + + The following table shows initial property values for an instance of . + +|Property|Initial Value| +|--------------|-------------------| +||An empty string ("").| +||The `logName` parameter.| +||The local computer (".").| + + + +## Examples + The following example reads entries in the event log, "myNewLog", on the local computer. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.EventLog1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.EventLog1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.EventLog1 Example/VB/source.vb" id="Snippet1"::: + ]]> The log name is . @@ -333,38 +333,38 @@ The computer on which the log exists. Initializes a new instance of the class. Associates the instance with a log on the specified computer. - property to the `logName` parameter and the property to the `machineName` parameter. Before calling , specify the property of the . If you are only reading from the log, you can alternatively specify only the and properties. - + property to the `logName` parameter and the property to the `machineName` parameter. Before calling , specify the property of the . If you are only reading from the log, you can alternatively specify only the and properties. + > [!NOTE] -> This overload of the constructor specifies the and properties, but you can change either before reading the property. - - The following table shows initial property values for an instance of . - -|Property|Initial Value| -|--------------|-------------------| -||An empty string ("").| -||The `logName` parameter.| -||The `machineName` parameter.| - - - -## Examples - The following example reads entries in the event log, "myNewLog", on the computer "myServer". - +> This overload of the constructor specifies the and properties, but you can change either before reading the property. + + The following table shows initial property values for an instance of . + +|Property|Initial Value| +|--------------|-------------------| +||An empty string ("").| +||The `logName` parameter.| +||The `machineName` parameter.| + + + +## Examples + The following example reads entries in the event log, "myNewLog", on the computer "myServer". + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.EventLog2 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/.ctor/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.EventLog2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.EventLog2 Example/VB/source.vb" id="Snippet1"::: + ]]> The log name is . - The log name is invalid. - - -or- - + The log name is invalid. + + -or- + The computer name is invalid. @@ -410,35 +410,35 @@ The source of event log entries. Initializes a new instance of the class. Associates the instance with a log on the specified computer and creates or assigns the specified source to the . - property to the `logName` parameter, the property to the `machineName` parameter, and the property to the `source` parameter. The property is required when writing to an event log. However, if you are only reading from an event log, only the and properties are required (as long as the event log on the server has a source already associated with it). If you are only reading from the event log, another overload of the constructor might suffice. - - The following table shows initial property values for an instance of . - -|Property|Initial Value| -|--------------|-------------------| -||The `source` parameter.| -||The `logName` parameter.| -||The `machineName` parameter.| - - - -## Examples - The following example writes an entry to an event log, "MyNewLog", on the local computer, using the source "MySource". - + property to the `logName` parameter, the property to the `machineName` parameter, and the property to the `source` parameter. The property is required when writing to an event log. However, if you are only reading from an event log, only the and properties are required (as long as the event log on the server has a source already associated with it). If you are only reading from the event log, another overload of the constructor might suffice. + + The following table shows initial property values for an instance of . + +|Property|Initial Value| +|--------------|-------------------| +||The `source` parameter.| +||The `logName` parameter.| +||The `machineName` parameter.| + + + +## Examples + The following example writes an entry to an event log, "MyNewLog", on the local computer, using the source "MySource". + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.EventLog3 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/.ctor/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.EventLog3 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.EventLog3 Example/VB/source.vb" id="Snippet1"::: + ]]> The log name is . - The log name is invalid. - - -or- - + The log name is invalid. + + -or- + The computer name is invalid. @@ -483,11 +483,11 @@ Begins the initialization of an used on a form or used by another component. The initialization occurs at runtime. - method ends the initialization. Using the and methods prevent the control from being used before it is fully initialized. - + method ends the initialization. Using the and methods prevent the control from being used before it is fully initialized. + ]]> @@ -526,31 +526,31 @@ Removes all entries from the event log. - closes the event log, releases the event handles, retrieves new read and write handles, and reopens the event log. Events received after the call to the method are not cleared along with the existing events. - - - -## Examples - The following example clears an event log. - + closes the event log, releases the event handles, retrieves new read and write handles, and reopens the event log. Events received after the call to the method are not cleared along with the existing events. + + + +## Examples + The following example clears an event log. + > [!CAUTION] -> Because Application, System, Security, and other non-custom logs can contain crucial information; be sure to specify a custom log before executing this example code. This example deletes the custom log `myNewLog`. - +> Because Application, System, Security, and other non-custom logs can contain crucial information; be sure to specify a custom log before executing this example code. This example deletes the custom log `myNewLog`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.Clear Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Clear/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.Clear Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.Clear Example/VB/source.vb" id="Snippet1"::: + ]]> - The event log was not cleared successfully. - - -or- - + The event log was not cleared successfully. + + -or- + The log cannot be opened. A Windows error code is not available. A value is not specified for the property. Make sure the log name is not an empty string. The log does not exist. @@ -589,11 +589,11 @@ Closes the event log and releases read and write handles. - method is called by the protected method. You do not need to invoke before calling . - + method is called by the protected method. You do not need to invoke before calling . + ]]> The event log's read handle or write handle was not released successfully. @@ -643,195 +643,195 @@ The configuration properties for the event source and its target event log. Establishes a valid event source for writing localized event messages, using the specified configuration properties for the event source and the corresponding event log. - method uses the input `sourceData` , and properties to create registry values on the target computer for the new source and its associated event log. A new source name cannot match an existing source name or an existing event log name on the target computer. If the property is not set, the source is registered for the Application event log. If the is not set, the source is registered on the local computer. - + method uses the input `sourceData` , and properties to create registry values on the target computer for the new source and its associated event log. A new source name cannot match an existing source name or an existing event log name on the target computer. If the property is not set, the source is registered for the Application event log. If the is not set, the source is registered on the local computer. + > [!NOTE] -> To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. -> -> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. -> -> Starting with 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. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. - - Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. - - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - - You can create an event source for an existing event log or a new event log. When you create a new source for a new event log, the system registers the source for that log, but the log is not created until the first entry is written to it. - - The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. - - Each source can only write to only one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. - - You can register the event source with localized resource file(s) for your event category and message strings. Your application can write event log entries using resource identifiers, rather than specifying the actual string. The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. You can register a separate file for event categories, messages and parameter insertion strings, or you can register the same resource file for all three types of strings. Use the , , , and properties to configure the source to write localized entries to the event log. If your application writes strings values directly to the event log, you do not need to set these properties. - - The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. - - To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration rather than deleting the existing source. - +> To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. +> +> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. +> +> Starting with 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. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. + + Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. + + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + + You can create an event source for an existing event log or a new event log. When you create a new source for a new event log, the system registers the source for that log, but the log is not created until the first entry is written to it. + + The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. + + Each source can only write to only one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. + + You can register the event source with localized resource file(s) for your event category and message strings. Your application can write event log entries using resource identifiers, rather than specifying the actual string. The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. You can register a separate file for event categories, messages and parameter insertion strings, or you can register the same resource file for all three types of strings. Use the , , , and properties to configure the source to write localized entries to the event log. If your application writes strings values directly to the event log, you do not need to set these properties. + + The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + + To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration rather than deleting the existing source. + > [!NOTE] -> If a source is configured for an event log, and you reconfigure it for another event log, you must restart the computer for the changes to take effect. - - - -## Examples - The following example determines whether the event source named `SampleApplicationSource` is registered on the local computer. If the event source does not exist, the example sets the message resource file for the source and creates the new event source. Finally, the example sets the localized display name for the event log, using the resource identifier value in `DisplayNameMsgId` and the resource file path in `messageFile`. - +> If a source is configured for an event log, and you reconfigure it for another event log, you must restart the computer for the changes to take effect. + + + +## Examples + The following example determines whether the event source named `SampleApplicationSource` is registered on the local computer. If the event source does not exist, the example sets the message resource file for the source and creates the new event source. Finally, the example sets the localized display name for the event log, using the resource identifier value in `DisplayNameMsgId` and the resource file path in `messageFile`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/eventlog_WriteEvent/CPP/source.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventInstance/Overview/source.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/eventlog_WriteEvent/VB/source.vb" id="Snippet6"::: - - The example uses the following message text file, built into the resource library EventLogMsgs.dll. A message text file is the source from which the message resource file is created. The message text file defines the resource identifiers and text for the category, event message, and parameter insertion strings. Specifically, resource identifier 5001 is defined for the localized name of the event log. - -``` -; // EventLogMsgs.mc -; // ******************************************************** - -; // Use the following commands to build this file: - -; // mc -s EventLogMsgs.mc -; // rc EventLogMsgs.rc -; // link /DLL /SUBSYSTEM:WINDOWS /NOENTRY /MACHINE:x86 EventLogMsgs.Res -; // ******************************************************** - -; // - Event categories - -; // Categories must be numbered consecutively starting at 1. -; // ******************************************************** - -MessageId=0x1 -Severity=Success -SymbolicName=INSTALL_CATEGORY -Language=English -Installation -. - -MessageId=0x2 -Severity=Success -SymbolicName=QUERY_CATEGORY -Language=English -Database Query -. - -MessageId=0x3 -Severity=Success -SymbolicName=REFRESH_CATEGORY -Language=English -Data Refresh -. - -; // - Event messages - -; // ********************************* - -MessageId = 1000 -Severity = Success -Facility = Application -SymbolicName = AUDIT_SUCCESS_MESSAGE_ID_1000 -Language=English -My application message text, in English, for message id 1000, called from %1. -. - -MessageId = 1001 -Severity = Warning -Facility = Application -SymbolicName = AUDIT_FAILED_MESSAGE_ID_1001 -Language=English -My application message text, in English, for message id 1001, called from %1. -. - -MessageId = 1002 -Severity = Success -Facility = Application -SymbolicName = GENERIC_INFO_MESSAGE_ID_1002 -Language=English -My generic information message in English, for message id 1002. -. - -MessageId = 1003 -Severity = Warning -Facility = Application -SymbolicName = GENERIC_WARNING_MESSAGE_ID_1003 -Language=English -My generic warning message in English, for message id 1003, called from %1. -. - -MessageId = 1004 -Severity = Success -Facility = Application -SymbolicName = UPDATE_CYCLE_COMPLETE_MESSAGE_ID_1004 -Language=English -The update cycle is complete for %%5002. -. - -MessageId = 1005 -Severity = Warning -Facility = Application -SymbolicName = SERVER_CONNECTION_DOWN_MESSAGE_ID_1005 -Language=English -The refresh operation did not complete because the connection to server %1 could not be established. -. - -; // - Event log display name - -; // ******************************************************** - -MessageId = 5001 -Severity = Success -Facility = Application -SymbolicName = EVENT_LOG_DISPLAY_NAME_MSGID -Language=English -Sample Event Log -. - -; // - Event message parameters - -; // Language independent insertion strings -; // ******************************************************** - -MessageId = 5002 -Severity = Success -Facility = Application -SymbolicName = EVENT_LOG_SERVICE_NAME_MSGID -Language=English -SVC_UPDATE.EXE -. -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/eventlog_WriteEvent/VB/source.vb" id="Snippet6"::: + + The example uses the following message text file, built into the resource library EventLogMsgs.dll. A message text file is the source from which the message resource file is created. The message text file defines the resource identifiers and text for the category, event message, and parameter insertion strings. Specifically, resource identifier 5001 is defined for the localized name of the event log. + +``` +; // EventLogMsgs.mc +; // ******************************************************** + +; // Use the following commands to build this file: + +; // mc -s EventLogMsgs.mc +; // rc EventLogMsgs.rc +; // link /DLL /SUBSYSTEM:WINDOWS /NOENTRY /MACHINE:x86 EventLogMsgs.Res +; // ******************************************************** + +; // - Event categories - +; // Categories must be numbered consecutively starting at 1. +; // ******************************************************** + +MessageId=0x1 +Severity=Success +SymbolicName=INSTALL_CATEGORY +Language=English +Installation +. + +MessageId=0x2 +Severity=Success +SymbolicName=QUERY_CATEGORY +Language=English +Database Query +. + +MessageId=0x3 +Severity=Success +SymbolicName=REFRESH_CATEGORY +Language=English +Data Refresh +. + +; // - Event messages - +; // ********************************* + +MessageId = 1000 +Severity = Success +Facility = Application +SymbolicName = AUDIT_SUCCESS_MESSAGE_ID_1000 +Language=English +My application message text, in English, for message id 1000, called from %1. +. + +MessageId = 1001 +Severity = Warning +Facility = Application +SymbolicName = AUDIT_FAILED_MESSAGE_ID_1001 +Language=English +My application message text, in English, for message id 1001, called from %1. +. + +MessageId = 1002 +Severity = Success +Facility = Application +SymbolicName = GENERIC_INFO_MESSAGE_ID_1002 +Language=English +My generic information message in English, for message id 1002. +. + +MessageId = 1003 +Severity = Warning +Facility = Application +SymbolicName = GENERIC_WARNING_MESSAGE_ID_1003 +Language=English +My generic warning message in English, for message id 1003, called from %1. +. + +MessageId = 1004 +Severity = Success +Facility = Application +SymbolicName = UPDATE_CYCLE_COMPLETE_MESSAGE_ID_1004 +Language=English +The update cycle is complete for %%5002. +. + +MessageId = 1005 +Severity = Warning +Facility = Application +SymbolicName = SERVER_CONNECTION_DOWN_MESSAGE_ID_1005 +Language=English +The refresh operation did not complete because the connection to server %1 could not be established. +. + +; // - Event log display name - +; // ******************************************************** + +MessageId = 5001 +Severity = Success +Facility = Application +SymbolicName = EVENT_LOG_DISPLAY_NAME_MSGID +Language=English +Sample Event Log +. + +; // - Event message parameters - +; // Language independent insertion strings +; // ******************************************************** + +MessageId = 5002 +Severity = Success +Facility = Application +SymbolicName = EVENT_LOG_SERVICE_NAME_MSGID +Language=English +SVC_UPDATE.EXE +. +``` + ]]> - The computer name specified in is not valid. - + The computer name specified in is not valid. + -or- - - The source name specified in is . - + + The source name specified in is . + -or- - - The log name specified in is not valid. Event log names must consist of printable characters and cannot include the characters '*', '?', or '\\'. - + + The log name specified in is not valid. Event log names must consist of printable characters and cannot include the characters '*', '?', or '\\'. + -or- - - The log name specified in is not valid for user log creation. The Event log names AppEvent, SysEvent, and SecEvent are reserved for system use. - + + The log name specified in is not valid for user log creation. The Event log names AppEvent, SysEvent, and SecEvent are reserved for system use. + -or- - - The log name matches an existing event source name. - + + The log name matches an existing event source name. + -or- - - The source name specified in results in a registry key path longer than 254 characters. - + + The source name specified in results in a registry key path longer than 254 characters. + -or- - - The first 8 characters of the log name specified in are not unique. - + + The first 8 characters of the log name specified in are not unique. + -or- - - The source name specified in is already registered. - + + The source name specified in is already registered. + -or- - + The source name specified in matches an existing event log name. The registry key for the event log could not be opened. @@ -879,82 +879,82 @@ SVC_UPDATE.EXE The name of the log the source's entries are written to. Possible values include Application, System, or a custom event log. Establishes the specified source name as a valid event source for writing entries to a log on the local computer. This method can also create a new custom log on the local computer. - to an existing log on the local computer. - - If `logName` is `null` or an empty string ("") when you call , the log defaults to the Application log. If the log does not exist on the local computer, the system creates a custom log and registers your application as a for that log. - + to an existing log on the local computer. + + If `logName` is `null` or an empty string ("") when you call , the log defaults to the Application log. If the log does not exist on the local computer, the system creates a custom log and registers your application as a for that log. + > [!NOTE] -> To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. -> -> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. -> -> In Windows Vista and later, 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. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. - - You only need to create an event source if you are writing to the event log. Before writing an entry to an event log, you must register the event source with the event log as a valid source of events. When you write a log entry, the system uses the to find the appropriate log in which to place your entry. If you are reading the event log, you can either specify the , or a and . - +> To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. +> +> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. +> +> In Windows Vista and later, 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. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. + + You only need to create an event source if you are writing to the event log. Before writing an entry to an event log, you must register the event source with the event log as a valid source of events. When you write a log entry, the system uses the to find the appropriate log in which to place your entry. If you are reading the event log, you can either specify the , or a and . + > [!NOTE] -> You are not required to specify the if you are connecting to a log on the local computer. If you do not specify the when reading from a log, the local computer (".") is assumed. - - Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. - - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - - You can create an event source for an existing event log or a new event log. When you create a new source for a new event log, the system registers the source for that log, but the log is not created until the first entry is written to it. - - The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. - - The source must be unique on the local computer; a new source name cannot match an existing source name or an existing event log name. Each source can write to only one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. - - The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. - - To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration rather than deleting the existing source. - +> You are not required to specify the if you are connecting to a log on the local computer. If you do not specify the when reading from a log, the local computer (".") is assumed. + + Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. + + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + + You can create an event source for an existing event log or a new event log. When you create a new source for a new event log, the system registers the source for that log, but the log is not created until the first entry is written to it. + + The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. + + The source must be unique on the local computer; a new source name cannot match an existing source name or an existing event log name. Each source can write to only one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. + + The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + + To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration rather than deleting the existing source. + > [!NOTE] -> If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. - - - -## Examples - The following example creates the source `MySource` if it does not already exist, and writes an entry to the event log `MyNewLog`. - +> If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. + + + +## Examples + The following example creates the source `MySource` if it does not already exist, and writes an entry to the event log `MyNewLog`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.CreateEventSource Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.CreateEventSource Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.CreateEventSource Example/VB/source.vb" id="Snippet1"::: + ]]> - is an empty string ("") or . - + is an empty string ("") or . + -or- - - is not a valid event log name. Event log names must consist of printable characters, and cannot include the characters '*', '?', or '\\'. - + + is not a valid event log name. Event log names must consist of printable characters, and cannot include the characters '*', '?', or '\\'. + -or- - - is not valid for user log creation. The event log names AppEvent, SysEvent, and SecEvent are reserved for system use. - + + is not valid for user log creation. The event log names AppEvent, SysEvent, and SecEvent are reserved for system use. + -or- - - The log name matches an existing event source name. - + + The log name matches an existing event source name. + -or- - - The source name results in a registry key path longer than 254 characters. - + + The source name results in a registry key path longer than 254 characters. + -or- - - The first 8 characters of match the first 8 characters of an existing event log name. - + + The first 8 characters of match the first 8 characters of an existing event log name. + -or- - - The source cannot be registered because it already exists on the local computer. - + + The source cannot be registered because it already exists on the local computer. + -or- - + The source name matches an existing event log name. The registry key for the event log could not be opened on the local computer. @@ -1016,82 +1016,82 @@ SVC_UPDATE.EXE The name of the computer to register this event source with, or "." for the local computer. Establishes the specified source name as a valid event source for writing entries to a log on the specified computer. This method can also be used to create a new custom log on the specified computer. - to an existing log on the specified computer. - - If `logName` is `null` or an empty string ("") when you call , the log defaults to the Application log. If the log does not exist on the specified computer, the system creates a custom log and registers your application as a for that log. - - You only need to create an event source if you are writing to the event log. Before writing an entry to an event log, you must register the event source with the event log as a valid source of events. When you write a log entry, the system uses the to find the appropriate log in which to place your entry. If you are reading the event log, you can either specify the , or a and . - + to an existing log on the specified computer. + + If `logName` is `null` or an empty string ("") when you call , the log defaults to the Application log. If the log does not exist on the specified computer, the system creates a custom log and registers your application as a for that log. + + You only need to create an event source if you are writing to the event log. Before writing an entry to an event log, you must register the event source with the event log as a valid source of events. When you write a log entry, the system uses the to find the appropriate log in which to place your entry. If you are reading the event log, you can either specify the , or a and . + > [!NOTE] -> To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. -> -> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. In Windows Vista and later, users do not have permission to access the security log; therefore, a is thrown. -> -> In Windows Vista and later, 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. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. - - Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. - - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - - You can create an event source for an existing event log or a new event log. When you create a new source for a new event log, the system registers the source for that log, but the log is not created until the first entry is written to it. - - The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. - - The source must be unique on the local computer; a new source name cannot match an existing source name or an existing event log name. Each source can write to only one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. - - The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. - - To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration rather than deleting the existing source. - +> To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. +> +> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. In Windows Vista and later, users do not have permission to access the security log; therefore, a is thrown. +> +> In Windows Vista and later, 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. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. + + Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. + + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + + You can create an event source for an existing event log or a new event log. When you create a new source for a new event log, the system registers the source for that log, but the log is not created until the first entry is written to it. + + The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. + + The source must be unique on the local computer; a new source name cannot match an existing source name or an existing event log name. Each source can write to only one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. + + The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + + To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration rather than deleting the existing source. + > [!NOTE] -> If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. - - - -## Examples - The following example creates the source `MySource` on the computer `MyServer`, and writes an entry to the event log `MyNewLog`. - +> If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. + + + +## Examples + The following example creates the source `MySource` on the computer `MyServer`, and writes an entry to the event log `MyNewLog`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.SourceExists1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/CreateEventSource/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.SourceExists1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.SourceExists1 Example/VB/source.vb" id="Snippet1"::: + ]]> - The is not a valid computer name. - + The is not a valid computer name. + -or- - - is an empty string ("") or . - + + is an empty string ("") or . + -or- - - is not a valid event log name. Event log names must consist of printable characters, and cannot include the characters '*', '?', or '\\'. - + + is not a valid event log name. Event log names must consist of printable characters, and cannot include the characters '*', '?', or '\\'. + -or- - - is not valid for user log creation. The event log names AppEvent, SysEvent, and SecEvent are reserved for system use. - + + is not valid for user log creation. The event log names AppEvent, SysEvent, and SecEvent are reserved for system use. + -or- - - The log name matches an existing event source name. - + + The log name matches an existing event source name. + -or- - - The source name results in a registry key path longer than 254 characters. - + + The source name results in a registry key path longer than 254 characters. + -or- - - The first 8 characters of match the first 8 characters of an existing event log name on the specified computer. - + + The first 8 characters of match the first 8 characters of an existing event log name on the specified computer. + -or- - - The source cannot be registered because it already exists on the specified computer. - + + The source cannot be registered because it already exists on the specified computer. + -or- - + The source name matches an existing event source name. The registry key for the event log could not be opened on the specified computer. @@ -1151,45 +1151,45 @@ SVC_UPDATE.EXE The name of the log to delete. Possible values include: Application, Security, System, and any custom event logs on the computer. Removes an event log from the local computer. - removes the log specified by `logName` from the local computer. If you want to delete only the source registered to a log, call . If you only want to delete the log entries, call . and are `static` methods, so they can be called on the class itself. It is not necessary to create a new instance of to call either method. - - The method first deletes the file that holds the contents of the log. It then accesses the registry and removes all the event sources registered for that log. If you recreate the log at a later point, you should register the event sources again, if they are to be reused. If you do not register the event sources and other users write to an event source without specifying a log name, the event source will be created in the Application event log. Therefore, applications that previously were able to write entries to the log you deleted and recreated will write to the Application log instead, because it now contains the event source. - + removes the log specified by `logName` from the local computer. If you want to delete only the source registered to a log, call . If you only want to delete the log entries, call . and are `static` methods, so they can be called on the class itself. It is not necessary to create a new instance of to call either method. + + The method first deletes the file that holds the contents of the log. It then accesses the registry and removes all the event sources registered for that log. If you recreate the log at a later point, you should register the event sources again, if they are to be reused. If you do not register the event sources and other users write to an event source without specifying a log name, the event source will be created in the Application event log. Therefore, applications that previously were able to write entries to the log you deleted and recreated will write to the Application log instead, because it now contains the event source. + > [!NOTE] -> Recreating an event log can be a difficult process. Avoid deleting any of the system-created event logs, such as the Application log. - - Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. - - - -## Examples - The following example deletes a log from the local computer. The example determines the log from its source. - +> Recreating an event log can be a difficult process. Avoid deleting any of the system-created event logs, such as the Application log. + + Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. + + + +## Examples + The following example deletes a log from the local computer. The example determines the log from its source. + > [!NOTE] -> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. - +> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.DeleteEventSource Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Delete/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.DeleteEventSource Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.DeleteEventSource Example/VB/source.vb" id="Snippet1"::: + ]]> is an empty string ("") or . - The registry key for the event log could not be opened on the local computer. - + The registry key for the event log could not be opened on the local computer. + -or- - + The log does not exist on the local computer. - The event log was not cleared successfully. - - -or- - + The event log was not cleared successfully. + + -or- + The log cannot be opened. A Windows error code is not available. @@ -1233,49 +1233,49 @@ SVC_UPDATE.EXE The name of the computer to delete the log from, or "." for the local computer. Removes an event log from the specified computer. - removes the log specified by `logName` from the computer specified by `machineName`. If you want to delete only the source registered to a log, call . If you only want to delete the log entries, call . and are `static` methods, so they can be called on the class itself. It is not necessary to create an instance of to call either method. - - This method first deletes the file that holds the contents of the log. It then accesses the registry and removes all the event sources registered for that log. If you recreate the log at a later point, you should register the event sources again, if they are to be reused. If you do not register the event sources and other users write to an event source without specifying a log name, the event source will be created in the Application event log. Therefore, applications that previously were able to write entries to the log you deleted and recreated will write to the Application log instead, because it now contains the event source. - + removes the log specified by `logName` from the computer specified by `machineName`. If you want to delete only the source registered to a log, call . If you only want to delete the log entries, call . and are `static` methods, so they can be called on the class itself. It is not necessary to create an instance of to call either method. + + This method first deletes the file that holds the contents of the log. It then accesses the registry and removes all the event sources registered for that log. If you recreate the log at a later point, you should register the event sources again, if they are to be reused. If you do not register the event sources and other users write to an event source without specifying a log name, the event source will be created in the Application event log. Therefore, applications that previously were able to write entries to the log you deleted and recreated will write to the Application log instead, because it now contains the event source. + > [!NOTE] -> Recreating an event log can be a difficult process. Avoid deleting any of the system-created event logs, such as the Application log. - - Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. - - - -## Examples - The following example deletes a log from the specified computer. The example determines the log from its source. - +> Recreating an event log can be a difficult process. Avoid deleting any of the system-created event logs, such as the Application log. + + Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. + + + +## Examples + The following example deletes a log from the specified computer. The example determines the log from its source. + > [!NOTE] -> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. - +> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.Delete1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Delete/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.Delete1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.Delete1 Example/VB/source.vb" id="Snippet1"::: + ]]> - is an empty string ("") or . - + is an empty string ("") or . + -or- - + is not a valid computer name. - The registry key for the event log could not be opened on the specified computer. - + The registry key for the event log could not be opened on the specified computer. + -or- - + The log does not exist on the specified computer. - The event log was not cleared successfully. - - -or- - + The event log was not cleared successfully. + + -or- + The log cannot be opened. A Windows error code is not available. @@ -1333,38 +1333,38 @@ SVC_UPDATE.EXE The name by which the application is registered in the event log system. Removes the event source registration from the event log of the local computer. - from the local computer. accesses the registry on the local computer and removes the registration of your application as a valid source of events. - - You can remove your component as a valid source of events if you no longer need it to write entries to that log. For example, you might do this if you need to change your component from one log to another. Because a source can only be registered to one log at a time, changing the log requires you to remove the current registration. - - removes only the source registered to a log. If you want to remove the log itself, call . If you only want to delete the log entries, call . and are `static` methods, so they can be called on the class itself. It is not necessary to create an instance of to call either method. - - Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. - + from the local computer. accesses the registry on the local computer and removes the registration of your application as a valid source of events. + + You can remove your component as a valid source of events if you no longer need it to write entries to that log. For example, you might do this if you need to change your component from one log to another. Because a source can only be registered to one log at a time, changing the log requires you to remove the current registration. + + removes only the source registered to a log. If you want to remove the log itself, call . If you only want to delete the log entries, call . and are `static` methods, so they can be called on the class itself. It is not necessary to create an instance of to call either method. + + Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. + > [!NOTE] -> If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. - - - -## Examples - The following example deletes a source from the local computer. The example determines the log from its source, and then deletes the log. - +> If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. + + + +## Examples + The following example deletes a source from the local computer. The example determines the log from its source, and then deletes the log. + > [!NOTE] -> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. - +> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.DeleteEventSource Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Delete/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.DeleteEventSource Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.DeleteEventSource Example/VB/source.vb" id="Snippet1"::: + ]]> - The parameter does not exist in the registry of the local computer. - + The parameter does not exist in the registry of the local computer. + -or- - + You do not have write access on the registry key for the event log. @@ -1409,42 +1409,42 @@ SVC_UPDATE.EXE The name of the computer to remove the registration from, or "." for the local computer. Removes the application's event source registration from the specified computer. - from a remote computer. accesses the registry on the computer specified by `machineName` and removes the registration of your application as a valid source of events. - - You can remove your component as a valid source of events if you no longer need it to write entries to that log. For example, you might do this if you need to change your component from one log to another. Because a source can only be registered to one log at a time, changing the log requires you to remove the current registration. - - removes only the source registered to a log. If you want to remove the log itself, call . If you only want to delete the log entries, call . and are `static` methods, so they can be called on the class itself. It is not necessary to create an instance of to call either method. - - Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. - + from a remote computer. accesses the registry on the computer specified by `machineName` and removes the registration of your application as a valid source of events. + + You can remove your component as a valid source of events if you no longer need it to write entries to that log. For example, you might do this if you need to change your component from one log to another. Because a source can only be registered to one log at a time, changing the log requires you to remove the current registration. + + removes only the source registered to a log. If you want to remove the log itself, call . If you only want to delete the log entries, call . and are `static` methods, so they can be called on the class itself. It is not necessary to create an instance of to call either method. + + Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. + > [!NOTE] -> If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. - - - -## Examples - The following example deletes a source from the specified computer. The example determines the log from its source, and then deletes the log. - +> If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. + + + +## Examples + The following example deletes a source from the specified computer. The example determines the log from its source, and then deletes the log. + > [!NOTE] -> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. - +> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.Delete1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Delete/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.Delete1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.Delete1 Example/VB/source.vb" id="Snippet1"::: + ]]> - The parameter is invalid. - + The parameter is invalid. + -or- - - The parameter does not exist in the registry of the specified computer. - + + The parameter does not exist in the registry of the specified computer. + -or- - + You do not have write access on the registry key for the event log. cannot be deleted because in the registry, the parent registry key for does not contain a subkey with the same name. @@ -1491,20 +1491,20 @@ SVC_UPDATE.EXE to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the , and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources. @@ -1554,23 +1554,23 @@ SVC_UPDATE.EXE if the receives notification when an entry is written to the log; otherwise, . - property determines whether the raises events when entries are written to the log. When the property is `true`, components that receive the event will receive notification any time an entry is written to the log that is specified in the property. If is `false`, no events are raised. - + property determines whether the raises events when entries are written to the log. When the property is `true`, components that receive the event will receive notification any time an entry is written to the log that is specified in the property. If is `false`, no events are raised. + > [!NOTE] -> You can receive event notifications only when entries are written on the local computer. You cannot receive notifications for entries written on remote computers. - - - -## Examples - The following example handles an event. - +> You can receive event notifications only when entries are written on the local computer. You cannot receive notifications for entries written on remote computers. + + + +## Examples + The following example handles an event. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.EnableRaisingEvents Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/EnableRaisingEvents/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.EnableRaisingEvents Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.EnableRaisingEvents Example/VB/source.vb" id="Snippet1"::: + ]]> The event log is on a remote computer. @@ -1611,11 +1611,11 @@ SVC_UPDATE.EXE Ends the initialization of an used on a form or by another component. The initialization occurs at runtime. - method starts the initialization. Using the and methods prevents the control from being used before it is fully initialized. - + method starts the initialization. Using the and methods prevents the control from being used before it is fully initialized. + ]]> @@ -1666,29 +1666,29 @@ SVC_UPDATE.EXE Gets the contents of the event log. An holding the entries in the event log. Each entry is associated with an instance of the class. - member when reading from the event log. - - Because the property is read-only, you cannot modify an entry or write to the log using . Instead, specify a and call to write a new log entry. You can use to count the number of entries in the event log, and view each in the collection. Use the indexed member to retrieve information about a specific entry, such as , , , or . - - It is not necessary to specify a when only reading from a log. You can specify only the name and (server computer name) properties for the instance. In either case, the member is automatically populated with the event log's list of entries. You can select the appropriate index for an item in this list to read individual entries. - - An important distinction between reading and writing log entries is that it is not necessary to explicitly call a read method. After the and are specified, the property is automatically populated. If you change the value of the or property, the property is repopulated the next time you read it. - + member when reading from the event log. + + Because the property is read-only, you cannot modify an entry or write to the log using . Instead, specify a and call to write a new log entry. You can use to count the number of entries in the event log, and view each in the collection. Use the indexed member to retrieve information about a specific entry, such as , , , or . + + It is not necessary to specify a when only reading from a log. You can specify only the name and (server computer name) properties for the instance. In either case, the member is automatically populated with the event log's list of entries. You can select the appropriate index for an item in this list to read individual entries. + + An important distinction between reading and writing log entries is that it is not necessary to explicitly call a read method. After the and are specified, the property is automatically populated. If you change the value of the or property, the property is repopulated the next time you read it. + > [!NOTE] -> You are not required to specify the if you are connecting to a log. If you do not specify the , the local computer, ".", is assumed. - - - -## Examples - The following example reads entries in the event log, "MyNewLog", on the local computer. - +> You are not required to specify the if you are connecting to a log. If you do not specify the , the local computer, ".", is assumed. + + + +## Examples + The following example reads entries in the event log, "MyNewLog", on the local computer. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.Entries Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Entries/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.Entries Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.Entries Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1735,24 +1735,24 @@ SVC_UPDATE.EXE Occurs when an entry is written to an event log on the local computer. - to `true`. You can only receive event notifications when entries are written on the local computer. You cannot receive notifications for entries written on remote computers. - - When you create an 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, until you remove the delegate. For more information about handling events with delegates, see [Handling and Raising Events](/dotnet/standard/events/). - - The system responds to only if the last write event occurred at least six seconds previously. This implies you will only receive one event notification within a six-second interval, even if more than one event log change occurs. If you insert a sufficiently long sleep interval (around 10 seconds) between calls to , you are less likely to miss an event. However, if write events occur more frequently, you might not receive the event notification until the next interval. Typically, missed event notifications are not lost, but delayed. - - - -## Examples - The following example handles an entry written event. - + to `true`. You can only receive event notifications when entries are written on the local computer. You cannot receive notifications for entries written on remote computers. + + When you create an 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, until you remove the delegate. For more information about handling events with delegates, see [Handling and Raising Events](/dotnet/standard/events/). + + The system responds to only if the last write event occurred at least six seconds previously. This implies you will only receive one event notification within a six-second interval, even if more than one event log change occurs. If you insert a sufficiently long sleep interval (around 10 seconds) between calls to , you are less likely to miss an event. However, if write events occur more frequently, you might not receive the event notification until the next interval. Typically, missed event notifications are not lost, but delayed. + + + +## Examples + The following example handles an entry written event. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.EntryWritten Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/EntryWritten/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.EntryWritten Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.EntryWritten Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1809,24 +1809,24 @@ SVC_UPDATE.EXE if the log exists on the local computer; otherwise, . - . - - Because this method accesses the registry, you must have the appropriate registry permissions on the local computer; otherwise, the query returns `false`. - - Because you cannot give a new log the name of an existing log on the same computer, use this method before creating a new log to determine if the specified `logName` already exists on the local computer. The `logName` parameter is not case sensitive. - - is a `static` method, so it can be called on the class itself. It is not necessary to create an instance of to call . - - - -## Examples + . + + Because this method accesses the registry, you must have the appropriate registry permissions on the local computer; otherwise, the query returns `false`. + + Because you cannot give a new log the name of an existing log on the same computer, use this method before creating a new log to determine if the specified `logName` already exists on the local computer. The `logName` parameter is not case sensitive. + + is a `static` method, so it can be called on the class itself. It is not necessary to create an instance of to call . + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EventLog_Exists_1/CPP/eventlog_exists_1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Exists/eventlog_exists_1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLog_Exists_1/VB/eventlog_exists_1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLog_Exists_1/VB/eventlog_exists_1.vb" id="Snippet1"::: + ]]> The logName is or the value is empty. @@ -1874,23 +1874,23 @@ SVC_UPDATE.EXE if the log exists on the specified computer; otherwise, . - . - - Because this method accesses the registry, you must have the appropriate registry permissions on the specified computer; otherwise, the query returns `false`. - - Because you cannot give a new log the name of an existing log on the same computer, use this method before creating a new log to determine if one with the specified `logName` already exists on the server specified by the `machineName` parameter. The `logName` and `machineName` parameters are not case sensitive. - - is a `static` method, so it can be called on the class itself. It is not necessary to create a new instance of to call . - + . + + Because this method accesses the registry, you must have the appropriate registry permissions on the specified computer; otherwise, the query returns `false`. + + Because you cannot give a new log the name of an existing log on the same computer, use this method before creating a new log to determine if one with the specified `logName` already exists on the server specified by the `machineName` parameter. The `logName` and `machineName` parameters are not case sensitive. + + is a `static` method, so it can be called on the class itself. It is not necessary to create a new instance of to call . + ]]> - The parameter is an invalid format. Make sure you have used proper syntax for the computer on which you are searching. - - -or- - + The parameter is an invalid format. Make sure you have used proper syntax for the computer on which you are searching. + + -or- + The is or the value is empty. @@ -1946,28 +1946,28 @@ SVC_UPDATE.EXE Searches for all event logs on the local computer and creates an array of objects that contain the list. An array of type that represents the logs on the local computer. - objects is a snapshot of all event logs on the local computer when the call to is made. This is not a dynamic collection, so it does not reflect the deletion or creation of logs in real time. You should verify that a log in the array exists before you read or write to it. The array usually includes at least three logs: Application, System, and Security. If you created custom logs on the local computer, they will appear in the array as well. - - To retrieve the list of event logs, you must have the appropriate registry permissions. These permissions are identical to those required to call and . - - - -## Examples - The following example enumerates the event logs defined on the local computer, and displays configuration details for each event log. - + objects is a snapshot of all event logs on the local computer when the call to is made. This is not a dynamic collection, so it does not reflect the deletion or creation of logs in real time. You should verify that a log in the array exists before you read or write to it. The array usually includes at least three logs: Application, System, and Security. If you created custom logs on the local computer, they will appear in the array as well. + + To retrieve the list of event logs, you must have the appropriate registry permissions. These permissions are identical to those required to call and . + + + +## Examples + The following example enumerates the event logs defined on the local computer, and displays configuration details for each event log. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EventLogProperties/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/GetEventLogs/source1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLogProperties/VB/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLogProperties/VB/source.vb" id="Snippet2"::: + ]]> - You do not have read access to the registry. - - -or- - + You do not have read access to the registry. + + -or- + There is no event log service on the computer. @@ -2008,31 +2008,31 @@ SVC_UPDATE.EXE Searches for all event logs on the given computer and creates an array of objects that contain the list. An array of type that represents the logs on the given computer. - objects is a snapshot of all event logs on the computer specified by the `machineName` parameter when the call to is made. This is not a dynamic collection, so it does not reflect the deletion or creation of logs in real time. You should verify that a log in the array exists before you read or write to it. The array usually includes at least three logs: Application, System, and Security. If you created custom logs on the specified computer, they will appear in the array as well. - - is a `static` method, so it can be called on the class itself. It is not necessary to create an instance of an object to make a call to the method. - - To retrieve the list of event logs, you must have the appropriate registry permissions. These permissions are identical to those required to call and . - - - -## Examples - The following example gets a list of logs on the computer "myServer". It then outputs the name of each log. - + objects is a snapshot of all event logs on the computer specified by the `machineName` parameter when the call to is made. This is not a dynamic collection, so it does not reflect the deletion or creation of logs in real time. You should verify that a log in the array exists before you read or write to it. The array usually includes at least three logs: Application, System, and Security. If you created custom logs on the specified computer, they will appear in the array as well. + + is a `static` method, so it can be called on the class itself. It is not necessary to create an instance of an object to make a call to the method. + + To retrieve the list of event logs, you must have the appropriate registry permissions. These permissions are identical to those required to call and . + + + +## Examples + The following example gets a list of logs on the computer "myServer". It then outputs the name of each log. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.GetEventLogs1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/GetEventLogs/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.GetEventLogs1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.GetEventLogs1 Example/VB/source.vb" id="Snippet1"::: + ]]> The parameter is an invalid computer name. - You do not have read access to the registry. - - -or- - + You do not have read access to the registry. + + -or- + There is no event log service on the computer. @@ -2104,41 +2104,41 @@ SVC_UPDATE.EXE Gets or sets the name of the log to read from or write to. The name of the log. This can be Application, System, Security, or a custom log name. The default is an empty string (""). - [!NOTE] -> Log names are limited to eight characters. According to the system, MyLogSample1 and MyLogSample2 are the same log. - - If you write to an event log, it is not enough to specify the property. You must associate a property with your event log resource to connect it to a particular log. It is not necessary to specify a when only reading from a log, but an event source must be associated with the event log resource in the server's registry. You can specify only the name and (server computer name) to read from it. - +> Log names are limited to eight characters. According to the system, MyLogSample1 and MyLogSample2 are the same log. + + If you write to an event log, it is not enough to specify the property. You must associate a property with your event log resource to connect it to a particular log. It is not necessary to specify a when only reading from a log, but an event source must be associated with the event log resource in the server's registry. You can specify only the name and (server computer name) to read from it. + > [!NOTE] -> You are not required to specify the if you are connecting to a log. If you do not specify the , the local computer (".") is assumed. - - If the property has not been specified, a call to returns an empty string if has not been explicitly set (by setting the property, or through the constructor). If the has been specified, returns the name of the log to which that source was registered. - - A source can only be registered to one log at a time. If the property was set for an instance of , you cannot change the property for that without changing the value of or calling first. If you change the property after the property has been set, writing a log entry throws an exception. - - The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. - - You cannot create a new log using the property alone (without specifying a source for the log). You can call , passing in a new log name as a parameter, and then call . However, the intent is usually either to create (and write entries to) new application-specific logs, or to read from existing logs. - - If the value changes, the event log is closed and all event handles are released. - +> You are not required to specify the if you are connecting to a log. If you do not specify the , the local computer (".") is assumed. + + If the property has not been specified, a call to returns an empty string if has not been explicitly set (by setting the property, or through the constructor). If the has been specified, returns the name of the log to which that source was registered. + + A source can only be registered to one log at a time. If the property was set for an instance of , you cannot change the property for that without changing the value of or calling first. If you change the property after the property has been set, writing a log entry throws an exception. + + The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. + + You cannot create a new log using the property alone (without specifying a source for the log). You can call , passing in a new log name as a parameter, and then call . However, the intent is usually either to create (and write entries to) new application-specific logs, or to read from existing logs. + + If the value changes, the event log is closed and all event handles are released. + > [!CAUTION] -> If you set the property to the name of a log that does not exist, the system attaches the to the Application log, but does not warn you that it is using a log other than the one you specified. - - - -## Examples - The following example reads entries in the event log, "NewEventLog", on the local computer. - +> If you set the property to the name of a log that does not exist, the system attaches the to the Application log, but does not warn you that it is using a log other than the one you specified. + + + +## Examples + The following example reads entries in the event log, "NewEventLog", on the local computer. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.Log Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Log/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.Log Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.Log Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2187,24 +2187,24 @@ SVC_UPDATE.EXE Gets the event log's friendly name. A name that represents the event log in the system's event viewer. - [!NOTE] -> In Windows Vista and later, users do not have permission to access the security log. If you are running Windows Vista or later as a user, you will get a when you attempt to access the display name for an event in the security log. -> -> In Windows Vista and later, 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. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. - - - -## Examples - The following example enumerates the event logs defined on the local computer and displays the for each event log. - +> In Windows Vista and later, users do not have permission to access the security log. If you are running Windows Vista or later as a user, you will get a when you attempt to access the display name for an event in the security log. +> +> In Windows Vista and later, 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. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. + + + +## Examples + The following example enumerates the event logs defined on the local computer and displays the for each event log. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EventLogProperties/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/GetEventLogs/source1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLogProperties/VB/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLogProperties/VB/source.vb" id="Snippet2"::: + ]]> The specified does not exist in the registry for this computer. @@ -2248,25 +2248,25 @@ SVC_UPDATE.EXE Gets the name of the log to which the specified source is registered. The name of the log associated with the specified source in the registry. - property can be any string, but the name cannot be used by other sources on the computer. An attempt to create a duplicated value throws an exception. However, a single event log can have many different sources writing to it. - - - -## Examples - The following example deletes a source from the local computer. The example determines the log from its source, and then deletes the log. - + property can be any string, but the name cannot be used by other sources on the computer. An attempt to create a duplicated value throws an exception. However, a single event log can have many different sources writing to it. + + + +## Examples + The following example deletes a source from the local computer. The example determines the log from its source, and then deletes the log. + > [!NOTE] -> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. - +> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.DeleteEventSource Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Delete/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.DeleteEventSource Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.DeleteEventSource Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2328,27 +2328,27 @@ SVC_UPDATE.EXE Gets or sets the name of the computer on which to read or write events. The name of the server on which the event log resides. The default is the local computer ("."). - with your event log object to connect it to a particular log. It is not necessary to specify the property when only reading from a log. You can specify only the name and (server computer name). - + with your event log object to connect it to a particular log. It is not necessary to specify the property when only reading from a log. You can specify only the name and (server computer name). + > [!NOTE] -> You need not specify the if you are connecting to a log. If you do not specify the , the local computer (".") is assumed. - - A source can only be registered to one log at a time. If the property was set for an instance of , you cannot change the property for that without changing the value of or calling first. If you change the property, the closes all handles and reattaches to the log and source on the new computer. - - The value cannot be an empty string. If it is not explicitly set, it defaults to the local computer ("."). - - - -## Examples - The following example reads entries in the event log, "NewEventLog", on a specified computer. - +> You need not specify the if you are connecting to a log. If you do not specify the , the local computer (".") is assumed. + + A source can only be registered to one log at a time. If the property was set for an instance of , you cannot change the property for that without changing the value of or calling first. If you change the property, the closes all handles and reattaches to the log and source on the new computer. + + The value cannot be an empty string. If it is not explicitly set, it defaults to the local computer ("."). + + + +## Examples + The following example reads entries in the event log, "NewEventLog", on a specified computer. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.MachineName Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/MachineName/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.MachineName Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.MachineName Example/VB/source.vb" id="Snippet1"::: + ]]> The computer name is invalid. @@ -2406,30 +2406,30 @@ SVC_UPDATE.EXE Gets or sets the maximum event log size in kilobytes. The maximum event log size in kilobytes. The default is 512, indicating a maximum file size of 512 kilobytes. - property represents the size limit of the event log file. When the event log reaches the size limit, the configured value determines whether new entries are discarded, or whether new entries overwrite older entries. - + property represents the size limit of the event log file. When the event log reaches the size limit, the configured value determines whether new entries are discarded, or whether new entries overwrite older entries. + > [!NOTE] -> This property represents a configuration setting for the event log represented by this instance. When the event log reaches its maximum size, this property specifies how the operating system handles new entries written by all event sources registered for the event log. - - - -## Examples - The following example enumerates the event logs defined on the local computer, and displays configuration details for each event log. - +> This property represents a configuration setting for the event log represented by this instance. When the event log reaches its maximum size, this property specifies how the operating system handles new entries written by all event sources registered for the event log. + + + +## Examples + The following example enumerates the event logs defined on the local computer, and displays configuration details for each event log. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EventLogProperties/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/GetEventLogs/source1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLogProperties/VB/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLogProperties/VB/source.vb" id="Snippet2"::: + ]]> The specified value is less than 64, or greater than 4194240, or not an even multiple of 64. - The value is not a valid log name. - + The value is not a valid log name. + -or- - + The registry key for the event log could not be opened on the target computer. @@ -2475,24 +2475,24 @@ SVC_UPDATE.EXE Gets the number of days to retain entries in the event log. The number of days that entries in the event log are retained. The default value is 7. - property to examine the current setting for an event log. Use to change the minimum number of days that each entry in the event log must be retained. - - The value depends on the configured overflow behavior of the event log. If the property for an event log is set to , then the value is 0. If the property for an event log is set to , then the value is -1. If the property for an event log is set to , then the value is greater than zero, and represents the number of days to retain event log entries when the event log is full. - - The overflow behavior only occurs when an event log reaches its size limit. When an has its set to , and the event log reaches its maximum size, then new entries are written only if they can replace entries whose age exceeds the period. Retaining event entries for a minimum period is appropriate when the event log is archived regularly. Otherwise, you risk losing new entries when the event log reaches its limit. To avoid losing new event information, set the minimum retention days for events based on your archive schedule for a particular event log. - - - -## Examples - The following example enumerates the event logs defined on the local computer, and displays configuration details for each event log. - + property to examine the current setting for an event log. Use to change the minimum number of days that each entry in the event log must be retained. + + The value depends on the configured overflow behavior of the event log. If the property for an event log is set to , then the value is 0. If the property for an event log is set to , then the value is -1. If the property for an event log is set to , then the value is greater than zero, and represents the number of days to retain event log entries when the event log is full. + + The overflow behavior only occurs when an event log reaches its size limit. When an has its set to , and the event log reaches its maximum size, then new entries are written only if they can replace entries whose age exceeds the period. Retaining event entries for a minimum period is appropriate when the event log is archived regularly. Otherwise, you risk losing new entries when the event log reaches its limit. To avoid losing new event information, set the minimum retention days for events based on your archive schedule for a particular event log. + + + +## Examples + The following example enumerates the event logs defined on the local computer, and displays configuration details for each event log. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EventLogProperties/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/GetEventLogs/source1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLogProperties/VB/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLogProperties/VB/source.vb" id="Snippet2"::: + ]]> @@ -2541,47 +2541,47 @@ SVC_UPDATE.EXE The minimum number of days each event log entry is retained. This parameter is used only if is set to . Changes the configured behavior for writing new entries when the event log reaches its maximum file size. - [!NOTE] -> The overflow behavior takes effect only when an event log reaches its maximum file size. The overflow behavior does not affect writing a new entry to a log that can accommodate additional event log entries. - - The method configures the overflow behavior of an event log. instance. After calling this method for the event log specified by the property, the and property values reflect the newly configured overflow behavior. - +> The overflow behavior takes effect only when an event log reaches its maximum file size. The overflow behavior does not affect writing a new entry to a log that can accommodate additional event log entries. + + The method configures the overflow behavior of an event log. instance. After calling this method for the event log specified by the property, the and property values reflect the newly configured overflow behavior. + > [!NOTE] -> This property represents a configuration setting for the event log represented by this instance. When the event log reaches its maximum size, this property specifies how the operating system handles new entries written by all event sources registered for the event log. - - Set the `action` parameter to to indicate that a new entry overwrites the oldest entry when the reaches its maximum size. If the `action` parameter is set to , the `retentionDays` parameter value is ignored. - - Set the `action` parameter to to indicate that each new entry overwrites older entries when the reaches its maximum size. Specify the number of days that events must be retained in the log using the `retentionDays` parameter. Events written within the retention range are not overwritten by new entries. - - Set the `action` parameter to to discard new events when the maximum log size is reached. If the `action` parameter is set to , the `retentionDays` parameter value is ignored. - +> This property represents a configuration setting for the event log represented by this instance. When the event log reaches its maximum size, this property specifies how the operating system handles new entries written by all event sources registered for the event log. + + Set the `action` parameter to to indicate that a new entry overwrites the oldest entry when the reaches its maximum size. If the `action` parameter is set to , the `retentionDays` parameter value is ignored. + + Set the `action` parameter to to indicate that each new entry overwrites older entries when the reaches its maximum size. Specify the number of days that events must be retained in the log using the `retentionDays` parameter. Events written within the retention range are not overwritten by new entries. + + Set the `action` parameter to to discard new events when the maximum log size is reached. If the `action` parameter is set to , the `retentionDays` parameter value is ignored. + > [!CAUTION] -> Setting the overflow policy to specifies that new entries are discarded when the event log is full. If you use this setting, ensure the event log is regularly archived and cleared to avoid reaching its maximum size limit. - - - -## Examples - The following example displays the configured overflow policy for a specified event log, and allows the user to select a new overflow policy setting for the event log. - +> Setting the overflow policy to specifies that new entries are discarded when the event log is full. If you use this setting, ensure the event log is regularly archived and cleared to avoid reaching its maximum size limit. + + + +## Examples + The following example displays the configured overflow policy for a specified event log, and allows the user to select a new overflow policy setting for the event log. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EventLogProperties/CPP/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/GetEventLogs/source1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLogProperties/VB/source.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLogProperties/VB/source.vb" id="Snippet3"::: + ]]> is not a valid value. is less than one, or larger than 365. - The value is not a valid log name. - + The value is not a valid log name. + -or- - + The registry key for the event log could not be opened on the target computer. @@ -2629,25 +2629,25 @@ SVC_UPDATE.EXE Gets the configured behavior for storing new entries when the event log reaches its maximum log file size. The value that specifies the configured behavior for storing new entries when the event log reaches its maximum log size. The default is . - property defines the maximum number of kilobytes allowed for the event log file size. - - Use the property value to examine the configured overflow behavior for an event log at its maximum size. Use the method to change the overflow behavior for an event log. - + property defines the maximum number of kilobytes allowed for the event log file size. + + Use the property value to examine the configured overflow behavior for an event log at its maximum size. Use the method to change the overflow behavior for an event log. + > [!NOTE] -> The overflow behavior takes effect only when an event log reaches its maximum file size. The overflow behavior does not affect writing a new entry to a log that can accommodate additional event log entries. - - - -## Examples - The following example enumerates the event logs defined on the local computer, and displays configuration details for each event log. - +> The overflow behavior takes effect only when an event log reaches its maximum file size. The overflow behavior does not affect writing a new entry to a log that can accommodate additional event log entries. + + + +## Examples + The following example enumerates the event logs defined on the local computer, and displays configuration details for each event log. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EventLogProperties/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/GetEventLogs/source1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLogProperties/VB/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLogProperties/VB/source.vb" id="Snippet2"::: + ]]> @@ -2697,146 +2697,146 @@ SVC_UPDATE.EXE The resource identifier that indexes a localized string within the resource file. Specifies the localized name of the event log, which is displayed in the server Event Viewer. - to register and display a localized name in the Event Viewer for custom event logs. - - The specified resource identifier must correspond to a localized string defined in the resource file. The Event Viewer displays the custom event log name using the localized string and the current culture settings. For example, you can define multiple event log names localized for different cultures in your resource file. The Event Viewer displays the localized string corresponding to the culture settings of the current user. - - If the Event Viewer cannot load the localized string from the resource file, or if no display name was registered for the event log, then the Event Viewer displays the event log name defined in . - + to register and display a localized name in the Event Viewer for custom event logs. + + The specified resource identifier must correspond to a localized string defined in the resource file. The Event Viewer displays the custom event log name using the localized string and the current culture settings. For example, you can define multiple event log names localized for different cultures in your resource file. The Event Viewer displays the localized string corresponding to the culture settings of the current user. + + If the Event Viewer cannot load the localized string from the resource file, or if no display name was registered for the event log, then the Event Viewer displays the event log name defined in . + > [!NOTE] -> You do not need to register a display name for the pre-defined event logs. The operating system registers the localized display names for the Application, System, and Security event logs. - - - -## Examples - The following example determines whether the event source named `SampleApplicationSource` is registered on the local computer. If the event source does not exist, the example sets the message resource file for the source and creates the new event source. Finally, the example sets the localized display name for the event log, using the resource identifier value in `DisplayNameMsgId` and the resource file path in `messageFile`. - +> You do not need to register a display name for the pre-defined event logs. The operating system registers the localized display names for the Application, System, and Security event logs. + + + +## Examples + The following example determines whether the event source named `SampleApplicationSource` is registered on the local computer. If the event source does not exist, the example sets the message resource file for the source and creates the new event source. Finally, the example sets the localized display name for the event log, using the resource identifier value in `DisplayNameMsgId` and the resource file path in `messageFile`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/eventlog_WriteEvent/CPP/source.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventInstance/Overview/source.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/eventlog_WriteEvent/VB/source.vb" id="Snippet6"::: - - The example uses the following message text file, built into the resource library EventLogMsgs.dll. A message text file is the source from which the message resource file is created. The message text file defines the resource identifiers and text for the category, event message, and parameter insertion strings. Specifically, resource identifier 5001 is defined for the localized name of the event log. - -``` -; // EventLogMsgs.mc -; // ******************************************************** - -; // Use the following commands to build this file: - -; // mc -s EventLogMsgs.mc -; // rc EventLogMsgs.rc -; // link /DLL /SUBSYSTEM:WINDOWS /NOENTRY /MACHINE:x86 EventLogMsgs.Res -; // ******************************************************** - -; // - Event categories - -; // Categories must be numbered consecutively starting at 1. -; // ******************************************************** - -MessageId=0x1 -Severity=Success -SymbolicName=INSTALL_CATEGORY -Language=English -Installation -. - -MessageId=0x2 -Severity=Success -SymbolicName=QUERY_CATEGORY -Language=English -Database Query -. - -MessageId=0x3 -Severity=Success -SymbolicName=REFRESH_CATEGORY -Language=English -Data Refresh -. - -; // - Event messages - -; // ********************************* - -MessageId = 1000 -Severity = Success -Facility = Application -SymbolicName = AUDIT_SUCCESS_MESSAGE_ID_1000 -Language=English -My application message text, in English, for message id 1000, called from %1. -. - -MessageId = 1001 -Severity = Warning -Facility = Application -SymbolicName = AUDIT_FAILED_MESSAGE_ID_1001 -Language=English -My application message text, in English, for message id 1001, called from %1. -. - -MessageId = 1002 -Severity = Success -Facility = Application -SymbolicName = GENERIC_INFO_MESSAGE_ID_1002 -Language=English -My generic information message in English, for message id 1002. -. - -MessageId = 1003 -Severity = Warning -Facility = Application -SymbolicName = GENERIC_WARNING_MESSAGE_ID_1003 -Language=English -My generic warning message in English, for message id 1003, called from %1. -. - -MessageId = 1004 -Severity = Success -Facility = Application -SymbolicName = UPDATE_CYCLE_COMPLETE_MESSAGE_ID_1004 -Language=English -The update cycle is complete for %%5002. -. - -MessageId = 1005 -Severity = Warning -Facility = Application -SymbolicName = SERVER_CONNECTION_DOWN_MESSAGE_ID_1005 -Language=English -The refresh operation did not complete because the connection to server %1 could not be established. -. - -; // - Event log display name - -; // ******************************************************** - -MessageId = 5001 -Severity = Success -Facility = Application -SymbolicName = EVENT_LOG_DISPLAY_NAME_MSGID -Language=English -Sample Event Log -. - -; // - Event message parameters - -; // Language independent insertion strings -; // ******************************************************** - -MessageId = 5002 -Severity = Success -Facility = Application -SymbolicName = EVENT_LOG_SERVICE_NAME_MSGID -Language=English -SVC_UPDATE.EXE -. -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/eventlog_WriteEvent/VB/source.vb" id="Snippet6"::: + + The example uses the following message text file, built into the resource library EventLogMsgs.dll. A message text file is the source from which the message resource file is created. The message text file defines the resource identifiers and text for the category, event message, and parameter insertion strings. Specifically, resource identifier 5001 is defined for the localized name of the event log. + +``` +; // EventLogMsgs.mc +; // ******************************************************** + +; // Use the following commands to build this file: + +; // mc -s EventLogMsgs.mc +; // rc EventLogMsgs.rc +; // link /DLL /SUBSYSTEM:WINDOWS /NOENTRY /MACHINE:x86 EventLogMsgs.Res +; // ******************************************************** + +; // - Event categories - +; // Categories must be numbered consecutively starting at 1. +; // ******************************************************** + +MessageId=0x1 +Severity=Success +SymbolicName=INSTALL_CATEGORY +Language=English +Installation +. + +MessageId=0x2 +Severity=Success +SymbolicName=QUERY_CATEGORY +Language=English +Database Query +. + +MessageId=0x3 +Severity=Success +SymbolicName=REFRESH_CATEGORY +Language=English +Data Refresh +. + +; // - Event messages - +; // ********************************* + +MessageId = 1000 +Severity = Success +Facility = Application +SymbolicName = AUDIT_SUCCESS_MESSAGE_ID_1000 +Language=English +My application message text, in English, for message id 1000, called from %1. +. + +MessageId = 1001 +Severity = Warning +Facility = Application +SymbolicName = AUDIT_FAILED_MESSAGE_ID_1001 +Language=English +My application message text, in English, for message id 1001, called from %1. +. + +MessageId = 1002 +Severity = Success +Facility = Application +SymbolicName = GENERIC_INFO_MESSAGE_ID_1002 +Language=English +My generic information message in English, for message id 1002. +. + +MessageId = 1003 +Severity = Warning +Facility = Application +SymbolicName = GENERIC_WARNING_MESSAGE_ID_1003 +Language=English +My generic warning message in English, for message id 1003, called from %1. +. + +MessageId = 1004 +Severity = Success +Facility = Application +SymbolicName = UPDATE_CYCLE_COMPLETE_MESSAGE_ID_1004 +Language=English +The update cycle is complete for %%5002. +. + +MessageId = 1005 +Severity = Warning +Facility = Application +SymbolicName = SERVER_CONNECTION_DOWN_MESSAGE_ID_1005 +Language=English +The refresh operation did not complete because the connection to server %1 could not be established. +. + +; // - Event log display name - +; // ******************************************************** + +MessageId = 5001 +Severity = Success +Facility = Application +SymbolicName = EVENT_LOG_DISPLAY_NAME_MSGID +Language=English +Sample Event Log +. + +; // - Event message parameters - +; // Language independent insertion strings +; // ******************************************************** + +MessageId = 5002 +Severity = Success +Facility = Application +SymbolicName = EVENT_LOG_SERVICE_NAME_MSGID +Language=English +SVC_UPDATE.EXE +. +``` + ]]> - The value is not a valid log name. - + The value is not a valid log name. + -or- - + The registry key for the event log could not be opened on the target computer. is . @@ -2908,42 +2908,42 @@ SVC_UPDATE.EXE Gets or sets the source name to register and use when writing to the event log. The name registered with the event log as a source of entries. The default is an empty string (""). - property to find the appropriate log in which to place your entry. If you are reading the event log, you can either specify the , or a and . - + property to find the appropriate log in which to place your entry. If you are reading the event log, you can either specify the , or a and . + > [!NOTE] -> You are not required to specify the if you are connecting to a log on the local computer. If you do not specify the , the local computer (".") is assumed. - - Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. - - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - - You can create an event source for an existing event log or a new event log. When you create a new source for a new event log, the system registers the source for that log, but the log is not created until the first entry is written to it. - - The source must be unique on the local computer; a new source name cannot match an existing source name or an existing event log name. Each source can write to only one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. - - If you change the value, the to which it is registered is closed and all event handles are released. - - The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. - - To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration rather than deleting the existing source. - +> You are not required to specify the if you are connecting to a log on the local computer. If you do not specify the , the local computer (".") is assumed. + + Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. + + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + + You can create an event source for an existing event log or a new event log. When you create a new source for a new event log, the system registers the source for that log, but the log is not created until the first entry is written to it. + + The source must be unique on the local computer; a new source name cannot match an existing source name or an existing event log name. Each source can write to only one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. + + If you change the value, the to which it is registered is closed and all event handles are released. + + The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + + To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration rather than deleting the existing source. + > [!NOTE] -> If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. - - - -## Examples - The following example creates the source `MySource` if it does not already exist, and writes an entry to the event log `MyNewLog`. - +> If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. + + + +## Examples + The following example creates the source `MySource` if it does not already exist, and writes an entry to the event log `MyNewLog`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.Source Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Source/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.Source Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.Source Example/VB/source.vb" id="Snippet1"::: + ]]> The source name results in a registry key path longer than 254 characters. @@ -3005,34 +3005,34 @@ SVC_UPDATE.EXE if the event source is registered on the local computer; otherwise, . - . - - Because this method accesses the registry, you must have the appropriate registry permissions on the local computer; otherwise, a will be thrown. - + . + + Because this method accesses the registry, you must have the appropriate registry permissions on the local computer; otherwise, a will be thrown. + > [!NOTE] -> To search for an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. -> -> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. -> -> Starting with 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. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. - +> To search for an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. +> +> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. +> +> Starting with 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. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. + > [!NOTE] -> A service that is executing under the account does not have the privileges required to execute this method. The solution is to check whether the event source exists in the , and if it does not exist, to create the source in the installer. - - Because you cannot give a new source the name of an existing source on the same computer, use this method before attempting to call to ensure that a source with the name specified by `source` does not already exist on the local computer. The `source` parameter is not case-sensitive. - - - -## Examples - The following example creates the source `MySource` if it does not already exist, and writes an entry to the event log `MyNewLog`. - +> A service that is executing under the account does not have the privileges required to execute this method. The solution is to check whether the event source exists in the , and if it does not exist, to create the source in the installer. + + Because you cannot give a new source the name of an existing source on the same computer, use this method before attempting to call to ensure that a source with the name specified by `source` does not already exist on the local computer. The `source` parameter is not case-sensitive. + + + +## Examples + The following example creates the source `MySource` if it does not already exist, and writes an entry to the event log `MyNewLog`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.Source Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Source/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.Source Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.Source Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -3087,36 +3087,36 @@ SVC_UPDATE.EXE if the event source is registered on the given computer; otherwise, . - . - - Because this method accesses the registry, you must have the appropriate registry permissions on the given server; otherwise, a will be thrown. - + . + + Because this method accesses the registry, you must have the appropriate registry permissions on the given server; otherwise, a will be thrown. + > [!NOTE] -> To search for an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. -> -> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. -> -> Starting with 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. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. - +> To search for an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. +> +> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. +> +> Starting with 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. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. + > [!NOTE] -> A service that is executing under the account does not have the privileges required to execute this method. The solution is to check whether the event source exists in the , and if it does not exist, to create the source in the installer. - - Because you cannot give a new source the name of an existing source on the same computer, use this method before attempting to call to ensure that a source with the name specified by `source` does not already exist on the computer. The `source` and `machineName` parameters are not case sensitive. - - is a `static` method, so it can be called on the class itself. It is not necessary to create an instance of to call . - - - -## Examples - The following example creates the source `MySource` on the computer `MyServer`, and writes an entry to the event log `MyNewLog`. - +> A service that is executing under the account does not have the privileges required to execute this method. The solution is to check whether the event source exists in the , and if it does not exist, to create the source in the installer. + + Because you cannot give a new source the name of an existing source on the same computer, use this method before attempting to call to ensure that a source with the name specified by `source` does not already exist on the computer. The `source` and `machineName` parameters are not case sensitive. + + is a `static` method, so it can be called on the class itself. It is not necessary to create an instance of to call . + + + +## Examples + The following example creates the source `MySource` on the computer `MyServer`, and writes an entry to the event log `MyNewLog`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.SourceExists1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/CreateEventSource/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.SourceExists1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.SourceExists1 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -3175,15 +3175,15 @@ SVC_UPDATE.EXE Gets or sets the object used to marshal the event handler calls issued as a result of an entry written event. The used to marshal event-handler calls issued as a result of an event on the event log. - is `null`, methods handling the event are 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 not work, or might result in an exception. Avoid this by setting to a Windows Forms component, which causes the methods handling the event to be called on the same thread on which the component was created. - - If the is used inside Visual Studio 2005 in a Windows Forms designer, is automatically set to the control containing the . For example, if you place an on a designer for Form1 (which inherits from ) the property of is set to the instance of Form1. - + is `null`, methods handling the event are 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 not work, or might result in an exception. Avoid this by setting to a Windows Forms component, which causes the methods handling the event to be called on the same thread on which the component was created. + + If the is used inside Visual Studio 2005 in a Windows Forms designer, is automatically set to the control containing the . For example, if you place an on a designer for Form1 (which inherits from ) the property of is set to the instance of Form1. + ]]> @@ -3239,65 +3239,65 @@ SVC_UPDATE.EXE The string to write to the event log. Writes an information type entry, with the given message text, to the event log. - instance. If you want to specify any other , use a different overload of . - + instance. If you want to specify any other , use a different overload of . + > [!NOTE] -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. - - You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. - - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - - If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. - +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. + + You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. + + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + + If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. + > [!NOTE] -> If you do not specify a for your instance before you call or , the local computer (".") is assumed. - - If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. - +> If you do not specify a for your instance before you call or , the local computer (".") is assumed. + + If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. + > [!NOTE] -> Many of the exceptions listed above are generated by errors raised during the process of registering the . - - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. - +> Many of the exceptions listed above are generated by errors raised during the process of registering the . + + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + > [!NOTE] -> If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. - +> If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. + > [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. - - - -## Examples - The following example creates the source `MySource` if it does not already exist, and writes an entry to the event log `MyNewLog`. - +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. + + + +## Examples + The following example creates the source `MySource` if it does not already exist, and writes an entry to the event log `MyNewLog`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.CreateEventSource Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.CreateEventSource Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.CreateEventSource Example/VB/source.vb" id="Snippet1"::: + ]]> - The property of the has not been set. - - -or- - - The method attempted to register a new event source, but the computer name in is not valid. - + The property of the has not been set. + + -or- + + The method attempted to register a new event source, but the computer name in is not valid. + -or- - - The source is already registered for a different event log. - + + The source is already registered for a different event log. + -or- - - The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). - + + The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). + -or- - + The source name results in a registry key path longer than 254 characters. The registry key for the event log could not be opened. The operating system reported an error when writing the event entry to the event log. A Windows error code is not available. @@ -3350,65 +3350,65 @@ SVC_UPDATE.EXE One of the values. Writes an error, warning, information, success audit, or failure audit entry with the given message text to the event log. - to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. - + to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. + > [!NOTE] -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. - - You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. - - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - - If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. - +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. + + You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. + + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + + If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. + > [!NOTE] -> If you do not specify a for your instance before you call or , the local computer (".") is assumed. - - If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. - +> If you do not specify a for your instance before you call or , the local computer (".") is assumed. + + If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. + > [!NOTE] -> Many exceptions listed above are generated by errors raised during the process of registering the . - - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. - +> Many exceptions listed above are generated by errors raised during the process of registering the . + + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + > [!NOTE] -> If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. - +> If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. + > [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. - - - -## Examples - The following example writes a warning entry to an event log, "MyNewLog", on the local computer. - +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. + + + +## Examples + The following example writes a warning entry to an event log, "MyNewLog", on the local computer. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.WriteEntry2 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/WriteEntry/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.WriteEntry2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.WriteEntry2 Example/VB/source.vb" id="Snippet1"::: + ]]> - The property of the has not been set. - - -or- - - The method attempted to register a new event source, but the computer name in is not valid. - + The property of the has not been set. + + -or- + + The method attempted to register a new event source, but the computer name in is not valid. + -or- - - The source is already registered for a different event log. - + + The source is already registered for a different event log. + -or- - - The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). - + + The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). + -or- - + The source name results in a registry key path longer than 254 characters. is not a valid . @@ -3464,45 +3464,45 @@ SVC_UPDATE.EXE The string to write to the event log. Writes an information type entry with the given message text to the event log, using the specified registered event source. - , use a different overload of . - - You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. - + , use a different overload of . + + You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + > [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. -> -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. - - - -## Examples - The following example creates the source `MySource` if it does not already exist, and writes an entry to the event log `MyNewLog`. - +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. +> +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. + + + +## Examples + The following example creates the source `MySource` if it does not already exist, and writes an entry to the event log `MyNewLog`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.WriteEntry1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/WriteEntry/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.WriteEntry1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.WriteEntry1 Example/VB/source.vb" id="Snippet1"::: + ]]> - The value is an empty string (""). - + The value is an empty string (""). + -or- - - The value is . - + + The value is . + -or- - - The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). - + + The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). + -or- - + The source name results in a registry key path longer than 254 characters. The registry key for the event log could not be opened. The operating system reported an error when writing the event entry to the event log. A Windows error code is not available. @@ -3557,69 +3557,69 @@ SVC_UPDATE.EXE The application-specific identifier for the event. Writes an entry with the given message text and application-defined event identifier to the event log. - [!NOTE] -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. - - In addition to the event identifier, you can specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. - - You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. - - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - - If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. - +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. + + In addition to the event identifier, you can specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. + + You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. + + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + + If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. + > [!NOTE] -> If you do not specify a for your instance before you call or , the local computer (".") is assumed. - - If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. - +> If you do not specify a for your instance before you call or , the local computer (".") is assumed. + + If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. + > [!NOTE] -> Many exceptions listed above are generated by errors raised during the process of registering the . - - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. - +> Many exceptions listed above are generated by errors raised during the process of registering the . + + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + > [!NOTE] -> If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. - +> If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. + > [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. - - - -## Examples +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EventLog_WriteEntry_1_3/CPP/eventlog_writeentry_1_3.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/WriteEntry/eventlog_writeentry_1_3.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLog_WriteEntry_1_3/VB/eventlog_writeentry_1_3.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLog_WriteEntry_1_3/VB/eventlog_writeentry_1_3.vb" id="Snippet3"::: + ]]> - The property of the has not been set. - - -or- - - The method attempted to register a new event source, but the computer name in is not valid. - + The property of the has not been set. + + -or- + + The method attempted to register a new event source, but the computer name in is not valid. + -or- - - The source is already registered for a different event log. - + + The source is already registered for a different event log. + -or- - - is less than zero or greater than UInt16.MaxValue. - + + is less than zero or greater than UInt16.MaxValue. + -or- - - The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). - + + The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). + -or- - + The source name results in a registry key path longer than 254 characters. The registry key for the event log could not be opened. @@ -3677,46 +3677,46 @@ SVC_UPDATE.EXE One of the values. Writes an error, warning, information, success audit, or failure audit entry with the given message text to the event log, using the specified registered event source. - to the event log, using a source already registered as an event source for the appropriate log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. - + to the event log, using a source already registered as an event source for the appropriate log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. + > [!NOTE] -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. - - You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. - +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. + + You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + > [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. - - - -## Examples - The following example writes a warning entry to an event log, "MyNewLog", on the local computer. - +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. + + + +## Examples + The following example writes a warning entry to an event log, "MyNewLog", on the local computer. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLog.WriteEntry3 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/WriteEntry/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.WriteEntry3 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic EventLog.WriteEntry3 Example/VB/source.vb" id="Snippet1"::: + ]]> - The value is an empty string (""). - + The value is an empty string (""). + -or- - - The value is . - + + The value is . + -or- - - The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). - + + The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). + -or- - + The source name results in a registry key path longer than 254 characters. The registry key for the event log could not be opened. @@ -3776,76 +3776,76 @@ SVC_UPDATE.EXE The application-specific subcategory associated with the message. Writes an entry with the given message text, application-defined event identifier, and application-defined category to the event log. - [!NOTE] -> The `category` parameter should be a positive value. Negative category values appear as a complementary positive number in the Event Viewer. For example, a -10 appears as 65,526, a -1 as 65,535. - +> The `category` parameter should be a positive value. Negative category values appear as a complementary positive number in the Event Viewer. For example, a -10 appears as 65,526, a -1 as 65,535. + > [!NOTE] -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. - - To display localized category strings in the Event Viewer, you must use an event source configured with a category resource file, and set the `category` to a resource identifier in the category resource file. If the event source does not have a configured category resource file, or the specified `category` does not index a string in the category resource file, then the Event Viewer displays the numeric category value for that entry. Configure the category resource file, along with the number of category strings in the resource file, using the or the class. - - In addition to the category, you can specify an event identifier for the event being written to the event log. Event identifiers, along with the event source, uniquely identify an event. Each application can define its own numbered events and the description strings to which they map. Event viewers display these string values to help the user understand what went wrong and suggest what actions to take. - - Finally, you can specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. - - You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. - - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - - If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. - +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. + + To display localized category strings in the Event Viewer, you must use an event source configured with a category resource file, and set the `category` to a resource identifier in the category resource file. If the event source does not have a configured category resource file, or the specified `category` does not index a string in the category resource file, then the Event Viewer displays the numeric category value for that entry. Configure the category resource file, along with the number of category strings in the resource file, using the or the class. + + In addition to the category, you can specify an event identifier for the event being written to the event log. Event identifiers, along with the event source, uniquely identify an event. Each application can define its own numbered events and the description strings to which they map. Event viewers display these string values to help the user understand what went wrong and suggest what actions to take. + + Finally, you can specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. + + You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. + + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + + If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. + > [!NOTE] -> If you do not specify a for your instance before you call or , the local computer (".") is assumed. - - If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. - +> If you do not specify a for your instance before you call or , the local computer (".") is assumed. + + If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. + > [!NOTE] -> Many exceptions listed above are generated by errors raised during the process of registering the . - - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. - +> Many exceptions listed above are generated by errors raised during the process of registering the . + + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + > [!NOTE] -> If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. - +> If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. + > [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. - - - -## Examples +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EventLog_WriteEntry_1_3/CPP/eventlog_writeentry_1_3.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/WriteEntry/eventlog_writeentry_1_3.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLog_WriteEntry_1_3/VB/eventlog_writeentry_1_3.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLog_WriteEntry_1_3/VB/eventlog_writeentry_1_3.vb" id="Snippet3"::: + ]]> - The property of the has not been set. - - -or- - - The method attempted to register a new event source, but the computer name in is not valid. - + The property of the has not been set. + + -or- + + The method attempted to register a new event source, but the computer name in is not valid. + -or- - - The source is already registered for a different event log. - + + The source is already registered for a different event log. + -or- - - is less than zero or greater than UInt16.MaxValue. - + + is less than zero or greater than UInt16.MaxValue. + -or- - - The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). - + + The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). + -or- - + The source name results in a registry key path longer than 254 characters. The registry key for the event log could not be opened. @@ -3905,50 +3905,50 @@ SVC_UPDATE.EXE The application-specific identifier for the event. Writes an entry with the given message text and application-defined event identifier to the event log, using the specified registered event source. - [!NOTE] -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. - - In addition to the event identifier, this overload of lets you specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. - - You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. - +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. + + In addition to the event identifier, this overload of lets you specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. + + You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + > [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. - - - -## Examples +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EventLog_WriteEntry_4/CPP/eventlog_writeentry_4.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/WriteEntry/eventlog_writeentry_4.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLog_WriteEntry_4/VB/eventlog_writeentry_4.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLog_WriteEntry_4/VB/eventlog_writeentry_4.vb" id="Snippet1"::: + ]]> - The value is an empty string (""). - + The value is an empty string (""). + -or- - - The value is . - + + The value is . + -or- - - is less than zero or greater than UInt16.MaxValue. - + + is less than zero or greater than UInt16.MaxValue. + -or- - - The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). - + + The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). + -or- - + The source name results in a registry key path longer than 254 characters. The registry key for the event log could not be opened. @@ -4004,78 +4004,78 @@ SVC_UPDATE.EXE An array of bytes that holds the binary data associated with the entry. Writes an entry with the given message text, application-defined event identifier, and application-defined category to the event log, and appends binary data to the message. - [!NOTE] -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. - +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. + > [!NOTE] -> The `category` parameter should be a positive value. Negative category values appear as a complementary positive number in the Event Viewer. For example, a -10 appears as 65,526, a -1 as 65,535. - - To display localized category strings in the Event Viewer, you must use an event source configured with a category resource file, and set the `category` to a resource identifier in the category resource file. If the event source does not have a configured category resource file, or the specified `category` does not index a string in the category resource file, then the Event Viewer displays the numeric category value for that entry. Configure the category resource file, along with the number of category strings in the resource file, using the or the class. - - Event identifiers, along with the event source, uniquely identify an event. Each application can define its own numbered events and the description strings to which they map. Event viewers display these string values to help the user understand what went wrong and suggest what actions to take. - - Finally, you can specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. - - You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. - - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - - If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. - +> The `category` parameter should be a positive value. Negative category values appear as a complementary positive number in the Event Viewer. For example, a -10 appears as 65,526, a -1 as 65,535. + + To display localized category strings in the Event Viewer, you must use an event source configured with a category resource file, and set the `category` to a resource identifier in the category resource file. If the event source does not have a configured category resource file, or the specified `category` does not index a string in the category resource file, then the Event Viewer displays the numeric category value for that entry. Configure the category resource file, along with the number of category strings in the resource file, using the or the class. + + Event identifiers, along with the event source, uniquely identify an event. Each application can define its own numbered events and the description strings to which they map. Event viewers display these string values to help the user understand what went wrong and suggest what actions to take. + + Finally, you can specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. + + You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. + + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + + If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. + > [!NOTE] -> If you do not specify a for your instance before you call or , the local computer (".") is assumed. - - If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. - +> If you do not specify a for your instance before you call or , the local computer (".") is assumed. + + If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. + > [!NOTE] -> Many exceptions listed above are generated by errors raised during the process of registering the . - - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. - +> Many exceptions listed above are generated by errors raised during the process of registering the . + + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + > [!NOTE] -> If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. - +> If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. + > [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. - - - -## Examples +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EventLog_WriteEntry_5/CPP/eventlog_writeentry_5.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/WriteEntry/eventlog_writeentry_5.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLog_WriteEntry_5/VB/eventlog_writeentry_5.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLog_WriteEntry_5/VB/eventlog_writeentry_5.vb" id="Snippet1"::: + ]]> - The property of the has not been set. - - -or- - - The method attempted to register a new event source, but the computer name in is not valid. - + The property of the has not been set. + + -or- + + The method attempted to register a new event source, but the computer name in is not valid. + -or- - - The source is already registered for a different event log. - + + The source is already registered for a different event log. + -or- - - is less than zero or greater than UInt16.MaxValue. - + + is less than zero or greater than UInt16.MaxValue. + -or- - - The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). - + + The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). + -or- - + The source name results in a registry key path longer than 254 characters. The registry key for the event log could not be opened. @@ -4137,56 +4137,56 @@ SVC_UPDATE.EXE The application-specific subcategory associated with the message. Writes an entry with the given message text, application-defined event identifier, and application-defined category to the event log, using the specified registered event source. The can be used by the Event Viewer to filter events in the log. - [!NOTE] -> The `category` parameter should be a positive value. Negative category values appear as a complementary positive number in the Event Viewer. For example, a -10 appears as 65,526, a -1 as 65,535. - - To display localized category strings in the Event Viewer, you must use an event source configured with a category resource file, and set the `category` to a resource identifier in the category resource file. If the event source does not have a configured category resource file, or the specified `category` does not index a string in the category resource file, then the Event Viewer displays the numeric category value for that entry. Configure the category resource file, along with the number of category strings in the resource file, using the or the class. - - In addition to the category, you can specify an event identifier for the event being written to the event log. Event identifiers, along with the event source, uniquely identify an event. Each application can define its own numbered events and the description strings to which they map. Event viewers display these string values to help the user understand what went wrong and suggest what actions to take. - - Finally, you can specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. - - You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. - +> The `category` parameter should be a positive value. Negative category values appear as a complementary positive number in the Event Viewer. For example, a -10 appears as 65,526, a -1 as 65,535. + + To display localized category strings in the Event Viewer, you must use an event source configured with a category resource file, and set the `category` to a resource identifier in the category resource file. If the event source does not have a configured category resource file, or the specified `category` does not index a string in the category resource file, then the Event Viewer displays the numeric category value for that entry. Configure the category resource file, along with the number of category strings in the resource file, using the or the class. + + In addition to the category, you can specify an event identifier for the event being written to the event log. Event identifiers, along with the event source, uniquely identify an event. Each application can define its own numbered events and the description strings to which they map. Event viewers display these string values to help the user understand what went wrong and suggest what actions to take. + + Finally, you can specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. + + You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + > [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. -> -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. - - - -## Examples +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. +> +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EventLog_WriteEntry_1_3/CPP/eventlog_writeentry_1_3.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/WriteEntry/eventlog_writeentry_1_3.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLog_WriteEntry_1_3/VB/eventlog_writeentry_1_3.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLog_WriteEntry_1_3/VB/eventlog_writeentry_1_3.vb" id="Snippet1"::: + ]]> - The value is an empty string (""). - + The value is an empty string (""). + -or- - - The value is . - + + The value is . + -or- - - is less than zero or greater than UInt16.MaxValue. - + + is less than zero or greater than UInt16.MaxValue. + -or- - - The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). - + + The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). + -or- - + The source name results in a registry key path longer than 254 characters. The registry key for the event log could not be opened. @@ -4244,58 +4244,58 @@ SVC_UPDATE.EXE An array of bytes that holds the binary data associated with the entry. Writes an entry with the given message text, application-defined event identifier, and application-defined category to the event log (using the specified registered event source) and appends binary data to the message. - [!NOTE] -> The `category` parameter should be a positive value. Negative category values appear as a complementary positive number in the Event Viewer. For example, a -10 will appear as 65,526, a -1 as 65,535. - - To display localized category strings in the Event Viewer, you must use an event source configured with a category resource file, and set the `category` to a resource identifier in the category resource file. If the event source does not have a configured category resource file, or the specified `category` does not index a string in the category resource file, then the Event Viewer displays the numeric category value for that entry. Configure the category resource file, along with the number of category strings in the resource file, using the or the class. - - Event identifiers, together with the event source, uniquely identify an event. Each application can define its own numbered events and the description strings to which they map. Event viewers display these string values to help the user understand what went wrong and suggest what actions to take. - - Finally, you can specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. - - You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. - +> The `category` parameter should be a positive value. Negative category values appear as a complementary positive number in the Event Viewer. For example, a -10 will appear as 65,526, a -1 as 65,535. + + To display localized category strings in the Event Viewer, you must use an event source configured with a category resource file, and set the `category` to a resource identifier in the category resource file. If the event source does not have a configured category resource file, or the specified `category` does not index a string in the category resource file, then the Event Viewer displays the numeric category value for that entry. Configure the category resource file, along with the number of category strings in the resource file, using the or the class. + + Event identifiers, together with the event source, uniquely identify an event. Each application can define its own numbered events and the description strings to which they map. Event viewers display these string values to help the user understand what went wrong and suggest what actions to take. + + Finally, you can specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. + + You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + > [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. -> -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. - - - -## Examples +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. +> +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EventLog_WriteEntry_1_3/CPP/eventlog_writeentry_1_3.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/WriteEntry/eventlog_writeentry_1_3.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLog_WriteEntry_1_3/VB/eventlog_writeentry_1_3.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventLog_WriteEntry_1_3/VB/eventlog_writeentry_1_3.vb" id="Snippet2"::: + ]]> - The value is an empty string (""). - + The value is an empty string (""). + -or- - - The value is . - + + The value is . + -or- - - is less than zero or greater than UInt16.MaxValue. - + + is less than zero or greater than UInt16.MaxValue. + -or- - - The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). - + + The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista). + -or- - + The source name results in a registry key path longer than 254 characters. is not a valid . @@ -4370,172 +4370,172 @@ SVC_UPDATE.EXE An array of strings to merge into the message text of the event log entry. Writes a localized entry to the event log. - . You must register the source with the corresponding resource file before you write events using resource identifiers. - - The input `instance` instance specifies the event message and properties. Set the of the `instance` input for the defined message in the source message resource file. You can optionally set the and of the `instance` input to define the category and event type of your event entry. You can also specify an array of language-independent strings to insert into the localized message text. Set `values` to `null` if the event message does not contain formatting placeholders for replacement strings. - - You must set the property on your component before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. - - You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - - The source must be configured either for writing localized entries or for writing direct strings. Use the method if your application writes string values directly to the event log. - - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. - + . You must register the source with the corresponding resource file before you write events using resource identifiers. + + The input `instance` instance specifies the event message and properties. Set the of the `instance` input for the defined message in the source message resource file. You can optionally set the and of the `instance` input to define the category and event type of your event entry. You can also specify an array of language-independent strings to insert into the localized message text. Set `values` to `null` if the event message does not contain formatting placeholders for replacement strings. + + You must set the property on your component before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. + + You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + + The source must be configured either for writing localized entries or for writing direct strings. Use the method if your application writes string values directly to the event log. + + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + > [!NOTE] -> If you write an entry to a remote computer, the value of the `message` string might not be what you expect if the remote computer is not running the .NET Framework. Also, the `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. - - - -## Examples - The following example writes two audit entries to the event log `myNewLog`. The example creates a new event source and a new event log if they do not exist on the local computer. The event message text is specified using a resource identifier in a resource file. - +> If you write an entry to a remote computer, the value of the `message` string might not be what you expect if the remote computer is not running the .NET Framework. Also, the `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. + + + +## Examples + The following example writes two audit entries to the event log `myNewLog`. The example creates a new event source and a new event log if they do not exist on the local computer. The event message text is specified using a resource identifier in a resource file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/eventlog_WriteEvent/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventInstance/Overview/source.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/eventlog_WriteEvent/VB/source.vb" id="Snippet7"::: - - The example uses the following message text file, built into the resource library EventLogMsgs.dll. A message text file is the source from which the message resource file is created. The message text file defines the resource identifiers and text for the category, event message, and parameter insertion strings. - -``` -; // EventLogMsgs.mc -; // ******************************************************** - -; // Use the following commands to build this file: - -; // mc -s EventLogMsgs.mc -; // rc EventLogMsgs.rc -; // link /DLL /SUBSYSTEM:WINDOWS /NOENTRY /MACHINE:x86 EventLogMsgs.Res -; // ******************************************************** - -; // - Event categories - -; // Categories must be numbered consecutively starting at 1. -; // ******************************************************** - -MessageId=0x1 -Severity=Success -SymbolicName=INSTALL_CATEGORY -Language=English -Installation -. - -MessageId=0x2 -Severity=Success -SymbolicName=QUERY_CATEGORY -Language=English -Database Query -. - -MessageId=0x3 -Severity=Success -SymbolicName=REFRESH_CATEGORY -Language=English -Data Refresh -. - -; // - Event messages - -; // ********************************* - -MessageId = 1000 -Severity = Success -Facility = Application -SymbolicName = AUDIT_SUCCESS_MESSAGE_ID_1000 -Language=English -My application message text, in English, for message id 1000, called from %1. -. - -MessageId = 1001 -Severity = Warning -Facility = Application -SymbolicName = AUDIT_FAILED_MESSAGE_ID_1001 -Language=English -My application message text, in English, for message id 1001, called from %1. -. - -MessageId = 1002 -Severity = Success -Facility = Application -SymbolicName = GENERIC_INFO_MESSAGE_ID_1002 -Language=English -My generic information message in English, for message id 1002. -. - -MessageId = 1003 -Severity = Warning -Facility = Application -SymbolicName = GENERIC_WARNING_MESSAGE_ID_1003 -Language=English -My generic warning message in English, for message id 1003, called from %1. -. - -MessageId = 1004 -Severity = Success -Facility = Application -SymbolicName = UPDATE_CYCLE_COMPLETE_MESSAGE_ID_1004 -Language=English -The update cycle is complete for %%5002. -. - -MessageId = 1005 -Severity = Warning -Facility = Application -SymbolicName = SERVER_CONNECTION_DOWN_MESSAGE_ID_1005 -Language=English -The refresh operation did not complete because the connection to server %1 could not be established. -. - -; // - Event log display name - -; // ******************************************************** - -MessageId = 5001 -Severity = Success -Facility = Application -SymbolicName = EVENT_LOG_DISPLAY_NAME_MSGID -Language=English -Sample Event Log -. - -; // - Event message parameters - -; // Language independent insertion strings -; // ******************************************************** - -MessageId = 5002 -Severity = Success -Facility = Application -SymbolicName = EVENT_LOG_SERVICE_NAME_MSGID -Language=English -SVC_UPDATE.EXE -. -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/eventlog_WriteEvent/VB/source.vb" id="Snippet7"::: + + The example uses the following message text file, built into the resource library EventLogMsgs.dll. A message text file is the source from which the message resource file is created. The message text file defines the resource identifiers and text for the category, event message, and parameter insertion strings. + +``` +; // EventLogMsgs.mc +; // ******************************************************** + +; // Use the following commands to build this file: + +; // mc -s EventLogMsgs.mc +; // rc EventLogMsgs.rc +; // link /DLL /SUBSYSTEM:WINDOWS /NOENTRY /MACHINE:x86 EventLogMsgs.Res +; // ******************************************************** + +; // - Event categories - +; // Categories must be numbered consecutively starting at 1. +; // ******************************************************** + +MessageId=0x1 +Severity=Success +SymbolicName=INSTALL_CATEGORY +Language=English +Installation +. + +MessageId=0x2 +Severity=Success +SymbolicName=QUERY_CATEGORY +Language=English +Database Query +. + +MessageId=0x3 +Severity=Success +SymbolicName=REFRESH_CATEGORY +Language=English +Data Refresh +. + +; // - Event messages - +; // ********************************* + +MessageId = 1000 +Severity = Success +Facility = Application +SymbolicName = AUDIT_SUCCESS_MESSAGE_ID_1000 +Language=English +My application message text, in English, for message id 1000, called from %1. +. + +MessageId = 1001 +Severity = Warning +Facility = Application +SymbolicName = AUDIT_FAILED_MESSAGE_ID_1001 +Language=English +My application message text, in English, for message id 1001, called from %1. +. + +MessageId = 1002 +Severity = Success +Facility = Application +SymbolicName = GENERIC_INFO_MESSAGE_ID_1002 +Language=English +My generic information message in English, for message id 1002. +. + +MessageId = 1003 +Severity = Warning +Facility = Application +SymbolicName = GENERIC_WARNING_MESSAGE_ID_1003 +Language=English +My generic warning message in English, for message id 1003, called from %1. +. + +MessageId = 1004 +Severity = Success +Facility = Application +SymbolicName = UPDATE_CYCLE_COMPLETE_MESSAGE_ID_1004 +Language=English +The update cycle is complete for %%5002. +. + +MessageId = 1005 +Severity = Warning +Facility = Application +SymbolicName = SERVER_CONNECTION_DOWN_MESSAGE_ID_1005 +Language=English +The refresh operation did not complete because the connection to server %1 could not be established. +. + +; // - Event log display name - +; // ******************************************************** + +MessageId = 5001 +Severity = Success +Facility = Application +SymbolicName = EVENT_LOG_DISPLAY_NAME_MSGID +Language=English +Sample Event Log +. + +; // - Event message parameters - +; // Language independent insertion strings +; // ******************************************************** + +MessageId = 5002 +Severity = Success +Facility = Application +SymbolicName = EVENT_LOG_SERVICE_NAME_MSGID +Language=English +SVC_UPDATE.EXE +. +``` + ]]> - The property of the has not been set. - - -or- - - The method attempted to register a new event source, but the computer name in is not valid. - + The property of the has not been set. + + -or- + + The method attempted to register a new event source, but the computer name in is not valid. + -or- - - The source is already registered for a different event log. - + + The source is already registered for a different event log. + -or- - - is less than zero or greater than UInt16.MaxValue. - + + is less than zero or greater than UInt16.MaxValue. + -or- - - has more than 256 elements. - + + has more than 256 elements. + -or- - - One of the elements is longer than 32766 bytes. - + + One of the elements is longer than 32766 bytes. + -or- - + The source name results in a registry key path longer than 254 characters. is . @@ -4597,177 +4597,177 @@ SVC_UPDATE.EXE An array of strings to merge into the message text of the event log entry. Writes an event log entry with the given event data, message replacement strings, and associated binary data. - . You must register the source with the corresponding resource file before you write events using resource identifiers. - - The input `instance` instance specifies the event message and properties. Set the of the `instance` input for the defined message in the source message resource file. You can optionally set the and of the `instance` input to define the category and event type of your event entry. You can also specify an array of language-independent strings to insert into the localized message text. Set `values` to `null` if the event message does not contain formatting placeholders for replacement strings. - - Specify binary data with an event when it is necessary to provide additional details for the event. For example, use the `data` parameter to include information on a specific error. The Event Viewer does not interpret the associated event data; it displays the data in a combined hexadecimal and text format. Use event-specific data sparingly; include it only if you are sure it will be useful. You can also use event-specific data to store information the application can process independently of the Event Viewer. For example, you could write a viewer specifically for your events, or write a program that scans the event log and creates reports that include information from the event-specific data. - - You must set the property on your component before component before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. - - You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - + . You must register the source with the corresponding resource file before you write events using resource identifiers. + + The input `instance` instance specifies the event message and properties. Set the of the `instance` input for the defined message in the source message resource file. You can optionally set the and of the `instance` input to define the category and event type of your event entry. You can also specify an array of language-independent strings to insert into the localized message text. Set `values` to `null` if the event message does not contain formatting placeholders for replacement strings. + + Specify binary data with an event when it is necessary to provide additional details for the event. For example, use the `data` parameter to include information on a specific error. The Event Viewer does not interpret the associated event data; it displays the data in a combined hexadecimal and text format. Use event-specific data sparingly; include it only if you are sure it will be useful. You can also use event-specific data to store information the application can process independently of the Event Viewer. For example, you could write a viewer specifically for your events, or write a program that scans the event log and creates reports that include information from the event-specific data. + + You must set the property on your component before component before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. + + You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + > [!NOTE] -> If you do not specify a for your instance before you call , the local computer (".") is assumed. - - The source must be configured either for writing localized entries or for writing direct strings. Use the method if your application writes string values directly to the event log. - - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. - +> If you do not specify a for your instance before you call , the local computer (".") is assumed. + + The source must be configured either for writing localized entries or for writing direct strings. Use the method if your application writes string values directly to the event log. + + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + > [!NOTE] -> If you write an entry to a remote computer, the value of the `message` string might not be what you expect if the remote computer is not running the .NET Framework. Also, the `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. - - - -## Examples - The following example writes two audit entries to the event log `myNewLog`. The example creates a new event source and a new event log if they do not exist on the local computer. The event message text is specified using a resource identifier in a resource file. - +> If you write an entry to a remote computer, the value of the `message` string might not be what you expect if the remote computer is not running the .NET Framework. Also, the `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. + + + +## Examples + The following example writes two audit entries to the event log `myNewLog`. The example creates a new event source and a new event log if they do not exist on the local computer. The event message text is specified using a resource identifier in a resource file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/eventlog_WriteEvent/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventInstance/Overview/source.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/eventlog_WriteEvent/VB/source.vb" id="Snippet7"::: - - The example uses the following message text file, built into the resource library EventLogMsgs.dll. A message text file is the source from which the message resource file is created. The message text file defines the resource identifiers and text for the category, event message, and parameter insertion strings. - -``` -; // EventLogMsgs.mc -; // ******************************************************** - -; // Use the following commands to build this file: - -; // mc -s EventLogMsgs.mc -; // rc EventLogMsgs.rc -; // link /DLL /SUBSYSTEM:WINDOWS /NOENTRY /MACHINE:x86 EventLogMsgs.Res -; // ******************************************************** - -; // - Event categories - -; // Categories must be numbered consecutively starting at 1. -; // ******************************************************** - -MessageId=0x1 -Severity=Success -SymbolicName=INSTALL_CATEGORY -Language=English -Installation -. - -MessageId=0x2 -Severity=Success -SymbolicName=QUERY_CATEGORY -Language=English -Database Query -. - -MessageId=0x3 -Severity=Success -SymbolicName=REFRESH_CATEGORY -Language=English -Data Refresh -. - -; // - Event messages - -; // ********************************* - -MessageId = 1000 -Severity = Success -Facility = Application -SymbolicName = AUDIT_SUCCESS_MESSAGE_ID_1000 -Language=English -My application message text, in English, for message id 1000, called from %1. -. - -MessageId = 1001 -Severity = Warning -Facility = Application -SymbolicName = AUDIT_FAILED_MESSAGE_ID_1001 -Language=English -My application message text, in English, for message id 1001, called from %1. -. - -MessageId = 1002 -Severity = Success -Facility = Application -SymbolicName = GENERIC_INFO_MESSAGE_ID_1002 -Language=English -My generic information message in English, for message id 1002. -. - -MessageId = 1003 -Severity = Warning -Facility = Application -SymbolicName = GENERIC_WARNING_MESSAGE_ID_1003 -Language=English -My generic warning message in English, for message id 1003, called from %1. -. - -MessageId = 1004 -Severity = Success -Facility = Application -SymbolicName = UPDATE_CYCLE_COMPLETE_MESSAGE_ID_1004 -Language=English -The update cycle is complete for %%5002. -. - -MessageId = 1005 -Severity = Warning -Facility = Application -SymbolicName = SERVER_CONNECTION_DOWN_MESSAGE_ID_1005 -Language=English -The refresh operation did not complete because the connection to server %1 could not be established. -. - -; // - Event log display name - -; // ******************************************************** - -MessageId = 5001 -Severity = Success -Facility = Application -SymbolicName = EVENT_LOG_DISPLAY_NAME_MSGID -Language=English -Sample Event Log -. - -; // - Event message parameters - -; // Language independent insertion strings -; // ******************************************************** - -MessageId = 5002 -Severity = Success -Facility = Application -SymbolicName = EVENT_LOG_SERVICE_NAME_MSGID -Language=English -SVC_UPDATE.EXE -. -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/eventlog_WriteEvent/VB/source.vb" id="Snippet7"::: + + The example uses the following message text file, built into the resource library EventLogMsgs.dll. A message text file is the source from which the message resource file is created. The message text file defines the resource identifiers and text for the category, event message, and parameter insertion strings. + +``` +; // EventLogMsgs.mc +; // ******************************************************** + +; // Use the following commands to build this file: + +; // mc -s EventLogMsgs.mc +; // rc EventLogMsgs.rc +; // link /DLL /SUBSYSTEM:WINDOWS /NOENTRY /MACHINE:x86 EventLogMsgs.Res +; // ******************************************************** + +; // - Event categories - +; // Categories must be numbered consecutively starting at 1. +; // ******************************************************** + +MessageId=0x1 +Severity=Success +SymbolicName=INSTALL_CATEGORY +Language=English +Installation +. + +MessageId=0x2 +Severity=Success +SymbolicName=QUERY_CATEGORY +Language=English +Database Query +. + +MessageId=0x3 +Severity=Success +SymbolicName=REFRESH_CATEGORY +Language=English +Data Refresh +. + +; // - Event messages - +; // ********************************* + +MessageId = 1000 +Severity = Success +Facility = Application +SymbolicName = AUDIT_SUCCESS_MESSAGE_ID_1000 +Language=English +My application message text, in English, for message id 1000, called from %1. +. + +MessageId = 1001 +Severity = Warning +Facility = Application +SymbolicName = AUDIT_FAILED_MESSAGE_ID_1001 +Language=English +My application message text, in English, for message id 1001, called from %1. +. + +MessageId = 1002 +Severity = Success +Facility = Application +SymbolicName = GENERIC_INFO_MESSAGE_ID_1002 +Language=English +My generic information message in English, for message id 1002. +. + +MessageId = 1003 +Severity = Warning +Facility = Application +SymbolicName = GENERIC_WARNING_MESSAGE_ID_1003 +Language=English +My generic warning message in English, for message id 1003, called from %1. +. + +MessageId = 1004 +Severity = Success +Facility = Application +SymbolicName = UPDATE_CYCLE_COMPLETE_MESSAGE_ID_1004 +Language=English +The update cycle is complete for %%5002. +. + +MessageId = 1005 +Severity = Warning +Facility = Application +SymbolicName = SERVER_CONNECTION_DOWN_MESSAGE_ID_1005 +Language=English +The refresh operation did not complete because the connection to server %1 could not be established. +. + +; // - Event log display name - +; // ******************************************************** + +MessageId = 5001 +Severity = Success +Facility = Application +SymbolicName = EVENT_LOG_DISPLAY_NAME_MSGID +Language=English +Sample Event Log +. + +; // - Event message parameters - +; // Language independent insertion strings +; // ******************************************************** + +MessageId = 5002 +Severity = Success +Facility = Application +SymbolicName = EVENT_LOG_SERVICE_NAME_MSGID +Language=English +SVC_UPDATE.EXE +. +``` + ]]> - The property of the has not been set. - - -or- - - The method attempted to register a new event source, but the computer name in is not valid. - + The property of the has not been set. + + -or- + + The method attempted to register a new event source, but the computer name in is not valid. + -or- - - The source is already registered for a different event log. - + + The source is already registered for a different event log. + -or- - - is less than zero or greater than UInt16.MaxValue. - + + is less than zero or greater than UInt16.MaxValue. + -or- - - has more than 256 elements. - + + has more than 256 elements. + -or- - - One of the elements is longer than 32766 bytes. - + + One of the elements is longer than 32766 bytes. + -or- - + The source name results in a registry key path longer than 254 characters. is . @@ -4823,165 +4823,165 @@ SVC_UPDATE.EXE An array of strings to merge into the message text of the event log entry. Writes an event log entry with the given event data and message replacement strings, using the specified registered event source. - of the `instance` input for the defined message in the source message resource file. You can optionally set the and of the `instance` input to define the category and event type of your event entry. You can also specify an array of language-independent strings to insert into the localized message text. Set `values` to `null` if the event message does not contain formatting placeholders for replacement strings. - - The specified source must be registered for an event log before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. - - You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - - The source must be configured either for writing localized entries or for writing direct strings. Use the method if your application writes string values directly to the event log. - - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. - - - -## Examples - The following example writes an informational event entry and a warning event entry to an existing event log. The event message text is specified using a resource identifier in a resource file. The example assumes the corresponding resource file has been registered for the source. - + of the `instance` input for the defined message in the source message resource file. You can optionally set the and of the `instance` input to define the category and event type of your event entry. You can also specify an array of language-independent strings to insert into the localized message text. Set `values` to `null` if the event message does not contain formatting placeholders for replacement strings. + + The specified source must be registered for an event log before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. + + You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + + The source must be configured either for writing localized entries or for writing direct strings. Use the method if your application writes string values directly to the event log. + + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + + + +## Examples + The following example writes an informational event entry and a warning event entry to an existing event log. The event message text is specified using a resource identifier in a resource file. The example assumes the corresponding resource file has been registered for the source. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/eventlog_WriteEvent/CPP/source.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventInstance/Overview/source.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/eventlog_WriteEvent/VB/source.vb" id="Snippet8"::: - - The example uses the following message text file, built into the resource library EventLogMsgs.dll. A message text file is the source from which the message resource file is created. The message text file defines the resource identifiers and text for the category, event message, and parameter insertion strings. - -``` -; // EventLogMsgs.mc -; // ******************************************************** - -; // Use the following commands to build this file: - -; // mc -s EventLogMsgs.mc -; // rc EventLogMsgs.rc -; // link /DLL /SUBSYSTEM:WINDOWS /NOENTRY /MACHINE:x86 EventLogMsgs.Res -; // ******************************************************** - -; // - Event categories - -; // Categories must be numbered consecutively starting at 1. -; // ******************************************************** - -MessageId=0x1 -Severity=Success -SymbolicName=INSTALL_CATEGORY -Language=English -Installation -. - -MessageId=0x2 -Severity=Success -SymbolicName=QUERY_CATEGORY -Language=English -Database Query -. - -MessageId=0x3 -Severity=Success -SymbolicName=REFRESH_CATEGORY -Language=English -Data Refresh -. - -; // - Event messages - -; // ********************************* - -MessageId = 1000 -Severity = Success -Facility = Application -SymbolicName = AUDIT_SUCCESS_MESSAGE_ID_1000 -Language=English -My application message text, in English, for message id 1000, called from %1. -. - -MessageId = 1001 -Severity = Warning -Facility = Application -SymbolicName = AUDIT_FAILED_MESSAGE_ID_1001 -Language=English -My application message text, in English, for message id 1001, called from %1. -. - -MessageId = 1002 -Severity = Success -Facility = Application -SymbolicName = GENERIC_INFO_MESSAGE_ID_1002 -Language=English -My generic information message in English, for message id 1002. -. - -MessageId = 1003 -Severity = Warning -Facility = Application -SymbolicName = GENERIC_WARNING_MESSAGE_ID_1003 -Language=English -My generic warning message in English, for message id 1003, called from %1. -. - -MessageId = 1004 -Severity = Success -Facility = Application -SymbolicName = UPDATE_CYCLE_COMPLETE_MESSAGE_ID_1004 -Language=English -The update cycle is complete for %%5002. -. - -MessageId = 1005 -Severity = Warning -Facility = Application -SymbolicName = SERVER_CONNECTION_DOWN_MESSAGE_ID_1005 -Language=English -The refresh operation did not complete because the connection to server %1 could not be established. -. - -; // - Event log display name - -; // ******************************************************** - -MessageId = 5001 -Severity = Success -Facility = Application -SymbolicName = EVENT_LOG_DISPLAY_NAME_MSGID -Language=English -Sample Event Log -. - -; // - Event message parameters - -; // Language independent insertion strings -; // ******************************************************** - -MessageId = 5002 -Severity = Success -Facility = Application -SymbolicName = EVENT_LOG_SERVICE_NAME_MSGID -Language=English -SVC_UPDATE.EXE -. -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/eventlog_WriteEvent/VB/source.vb" id="Snippet8"::: + + The example uses the following message text file, built into the resource library EventLogMsgs.dll. A message text file is the source from which the message resource file is created. The message text file defines the resource identifiers and text for the category, event message, and parameter insertion strings. + +``` +; // EventLogMsgs.mc +; // ******************************************************** + +; // Use the following commands to build this file: + +; // mc -s EventLogMsgs.mc +; // rc EventLogMsgs.rc +; // link /DLL /SUBSYSTEM:WINDOWS /NOENTRY /MACHINE:x86 EventLogMsgs.Res +; // ******************************************************** + +; // - Event categories - +; // Categories must be numbered consecutively starting at 1. +; // ******************************************************** + +MessageId=0x1 +Severity=Success +SymbolicName=INSTALL_CATEGORY +Language=English +Installation +. + +MessageId=0x2 +Severity=Success +SymbolicName=QUERY_CATEGORY +Language=English +Database Query +. + +MessageId=0x3 +Severity=Success +SymbolicName=REFRESH_CATEGORY +Language=English +Data Refresh +. + +; // - Event messages - +; // ********************************* + +MessageId = 1000 +Severity = Success +Facility = Application +SymbolicName = AUDIT_SUCCESS_MESSAGE_ID_1000 +Language=English +My application message text, in English, for message id 1000, called from %1. +. + +MessageId = 1001 +Severity = Warning +Facility = Application +SymbolicName = AUDIT_FAILED_MESSAGE_ID_1001 +Language=English +My application message text, in English, for message id 1001, called from %1. +. + +MessageId = 1002 +Severity = Success +Facility = Application +SymbolicName = GENERIC_INFO_MESSAGE_ID_1002 +Language=English +My generic information message in English, for message id 1002. +. + +MessageId = 1003 +Severity = Warning +Facility = Application +SymbolicName = GENERIC_WARNING_MESSAGE_ID_1003 +Language=English +My generic warning message in English, for message id 1003, called from %1. +. + +MessageId = 1004 +Severity = Success +Facility = Application +SymbolicName = UPDATE_CYCLE_COMPLETE_MESSAGE_ID_1004 +Language=English +The update cycle is complete for %%5002. +. + +MessageId = 1005 +Severity = Warning +Facility = Application +SymbolicName = SERVER_CONNECTION_DOWN_MESSAGE_ID_1005 +Language=English +The refresh operation did not complete because the connection to server %1 could not be established. +. + +; // - Event log display name - +; // ******************************************************** + +MessageId = 5001 +Severity = Success +Facility = Application +SymbolicName = EVENT_LOG_DISPLAY_NAME_MSGID +Language=English +Sample Event Log +. + +; // - Event message parameters - +; // Language independent insertion strings +; // ******************************************************** + +MessageId = 5002 +Severity = Success +Facility = Application +SymbolicName = EVENT_LOG_SERVICE_NAME_MSGID +Language=English +SVC_UPDATE.EXE +. +``` + ]]> - The value is an empty string (""). - + The value is an empty string (""). + -or- - - The value is . - + + The value is . + -or- - - is less than zero or greater than UInt16.MaxValue. - + + is less than zero or greater than UInt16.MaxValue. + -or- - - has more than 256 elements. - + + has more than 256 elements. + -or- - - One of the elements is longer than 32766 bytes. - + + One of the elements is longer than 32766 bytes. + -or- - + The source name results in a registry key path longer than 254 characters. is . @@ -5039,167 +5039,167 @@ SVC_UPDATE.EXE An array of strings to merge into the message text of the event log entry. Writes an event log entry with the given event data, message replacement strings, and associated binary data, and using the specified registered event source. - of the `instance` input for the defined message in the source message resource file. You can optionally set the and of the `instance` input to define the category and event type of your event entry. You can also specify an array of language-independent strings to insert into the localized message text. Set `values` to `null` if the event message does not contain formatting placeholders for replacement strings. - - Specify binary data with an event when it is necessary to provide additional details for the event. For example, use the `data` parameter to include information on a specific error. The Event Viewer does not interpret the associated event data; it displays the data in a combined hexadecimal and text format. Use event-specific data sparingly; include it only if you are sure it will be useful. You can also use event-specific data to store information the application can process independently of the Event Viewer. For example, you could write a viewer specifically for your events, or write a program that scans the event log and creates reports that include information from the event-specific data. - - The specified source must be registered for an event log before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. - - You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - - The source must be configured either for writing localized entries or for writing direct strings. Use the method if your application writes string values directly to the event log. - - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. - - - -## Examples - The following example writes an informational event entry and a warning event entry to an existing event log. The event message text is specified using a resource identifier in a resource file. The example assumes the corresponding resource file has been registered for the source. - + of the `instance` input for the defined message in the source message resource file. You can optionally set the and of the `instance` input to define the category and event type of your event entry. You can also specify an array of language-independent strings to insert into the localized message text. Set `values` to `null` if the event message does not contain formatting placeholders for replacement strings. + + Specify binary data with an event when it is necessary to provide additional details for the event. For example, use the `data` parameter to include information on a specific error. The Event Viewer does not interpret the associated event data; it displays the data in a combined hexadecimal and text format. Use event-specific data sparingly; include it only if you are sure it will be useful. You can also use event-specific data to store information the application can process independently of the Event Viewer. For example, you could write a viewer specifically for your events, or write a program that scans the event log and creates reports that include information from the event-specific data. + + The specified source must be registered for an event log before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. + + You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + + The source must be configured either for writing localized entries or for writing direct strings. Use the method if your application writes string values directly to the event log. + + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + + + +## Examples + The following example writes an informational event entry and a warning event entry to an existing event log. The event message text is specified using a resource identifier in a resource file. The example assumes the corresponding resource file has been registered for the source. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/eventlog_WriteEvent/CPP/source.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventInstance/Overview/source.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/eventlog_WriteEvent/VB/source.vb" id="Snippet8"::: - - The example uses the following message text file, built into the resource library EventLogMsgs.dll. A message text file is the source from which the message resource file is created. The message text file defines the resource identifiers and text for the category, event message, and parameter insertion strings. - -``` -; // EventLogMsgs.mc -; // ******************************************************** - -; // Use the following commands to build this file: - -; // mc -s EventLogMsgs.mc -; // rc EventLogMsgs.rc -; // link /DLL /SUBSYSTEM:WINDOWS /NOENTRY /MACHINE:x86 EventLogMsgs.Res -; // ******************************************************** - -; // - Event categories - -; // Categories must be numbered consecutively starting at 1. -; // ******************************************************** - -MessageId=0x1 -Severity=Success -SymbolicName=INSTALL_CATEGORY -Language=English -Installation -. - -MessageId=0x2 -Severity=Success -SymbolicName=QUERY_CATEGORY -Language=English -Database Query -. - -MessageId=0x3 -Severity=Success -SymbolicName=REFRESH_CATEGORY -Language=English -Data Refresh -. - -; // - Event messages - -; // ********************************* - -MessageId = 1000 -Severity = Success -Facility = Application -SymbolicName = AUDIT_SUCCESS_MESSAGE_ID_1000 -Language=English -My application message text, in English, for message id 1000, called from %1. -. - -MessageId = 1001 -Severity = Warning -Facility = Application -SymbolicName = AUDIT_FAILED_MESSAGE_ID_1001 -Language=English -My application message text, in English, for message id 1001, called from %1. -. - -MessageId = 1002 -Severity = Success -Facility = Application -SymbolicName = GENERIC_INFO_MESSAGE_ID_1002 -Language=English -My generic information message in English, for message id 1002. -. - -MessageId = 1003 -Severity = Warning -Facility = Application -SymbolicName = GENERIC_WARNING_MESSAGE_ID_1003 -Language=English -My generic warning message in English, for message id 1003, called from %1. -. - -MessageId = 1004 -Severity = Success -Facility = Application -SymbolicName = UPDATE_CYCLE_COMPLETE_MESSAGE_ID_1004 -Language=English -The update cycle is complete for %%5002. -. - -MessageId = 1005 -Severity = Warning -Facility = Application -SymbolicName = SERVER_CONNECTION_DOWN_MESSAGE_ID_1005 -Language=English -The refresh operation did not complete because the connection to server %1 could not be established. -. - -; // - Event log display name - -; // ******************************************************** - -MessageId = 5001 -Severity = Success -Facility = Application -SymbolicName = EVENT_LOG_DISPLAY_NAME_MSGID -Language=English -Sample Event Log -. - -; // - Event message parameters - -; // Language independent insertion strings -; // ******************************************************** - -MessageId = 5002 -Severity = Success -Facility = Application -SymbolicName = EVENT_LOG_SERVICE_NAME_MSGID -Language=English -SVC_UPDATE.EXE -. -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/eventlog_WriteEvent/VB/source.vb" id="Snippet8"::: + + The example uses the following message text file, built into the resource library EventLogMsgs.dll. A message text file is the source from which the message resource file is created. The message text file defines the resource identifiers and text for the category, event message, and parameter insertion strings. + +``` +; // EventLogMsgs.mc +; // ******************************************************** + +; // Use the following commands to build this file: + +; // mc -s EventLogMsgs.mc +; // rc EventLogMsgs.rc +; // link /DLL /SUBSYSTEM:WINDOWS /NOENTRY /MACHINE:x86 EventLogMsgs.Res +; // ******************************************************** + +; // - Event categories - +; // Categories must be numbered consecutively starting at 1. +; // ******************************************************** + +MessageId=0x1 +Severity=Success +SymbolicName=INSTALL_CATEGORY +Language=English +Installation +. + +MessageId=0x2 +Severity=Success +SymbolicName=QUERY_CATEGORY +Language=English +Database Query +. + +MessageId=0x3 +Severity=Success +SymbolicName=REFRESH_CATEGORY +Language=English +Data Refresh +. + +; // - Event messages - +; // ********************************* + +MessageId = 1000 +Severity = Success +Facility = Application +SymbolicName = AUDIT_SUCCESS_MESSAGE_ID_1000 +Language=English +My application message text, in English, for message id 1000, called from %1. +. + +MessageId = 1001 +Severity = Warning +Facility = Application +SymbolicName = AUDIT_FAILED_MESSAGE_ID_1001 +Language=English +My application message text, in English, for message id 1001, called from %1. +. + +MessageId = 1002 +Severity = Success +Facility = Application +SymbolicName = GENERIC_INFO_MESSAGE_ID_1002 +Language=English +My generic information message in English, for message id 1002. +. + +MessageId = 1003 +Severity = Warning +Facility = Application +SymbolicName = GENERIC_WARNING_MESSAGE_ID_1003 +Language=English +My generic warning message in English, for message id 1003, called from %1. +. + +MessageId = 1004 +Severity = Success +Facility = Application +SymbolicName = UPDATE_CYCLE_COMPLETE_MESSAGE_ID_1004 +Language=English +The update cycle is complete for %%5002. +. + +MessageId = 1005 +Severity = Warning +Facility = Application +SymbolicName = SERVER_CONNECTION_DOWN_MESSAGE_ID_1005 +Language=English +The refresh operation did not complete because the connection to server %1 could not be established. +. + +; // - Event log display name - +; // ******************************************************** + +MessageId = 5001 +Severity = Success +Facility = Application +SymbolicName = EVENT_LOG_DISPLAY_NAME_MSGID +Language=English +Sample Event Log +. + +; // - Event message parameters - +; // Language independent insertion strings +; // ******************************************************** + +MessageId = 5002 +Severity = Success +Facility = Application +SymbolicName = EVENT_LOG_SERVICE_NAME_MSGID +Language=English +SVC_UPDATE.EXE +. +``` + ]]> - The value is an empty string (""). - + The value is an empty string (""). + -or- - - The value is . - + + The value is . + -or- - - is less than zero or greater than UInt16.MaxValue. - + + is less than zero or greater than UInt16.MaxValue. + -or- - - has more than 256 elements. - + + has more than 256 elements. + -or- - - One of the elements is longer than 32766 bytes. - + + One of the elements is longer than 32766 bytes. + -or- - + The source name results in a registry key path longer than 254 characters. is . diff --git a/xml/System.Diagnostics/TraceListener.xml b/xml/System.Diagnostics/TraceListener.xml index 6f6d2a59160..8e495cf59f0 100644 --- a/xml/System.Diagnostics/TraceListener.xml +++ b/xml/System.Diagnostics/TraceListener.xml @@ -63,34 +63,34 @@ Provides the base class for the listeners who monitor trace and debug output. - , see the , and the classes. - - You must enable tracing or debugging to use a trace listener. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. - -- To enable debugging in C#, add the `/d:DEBUG` flag to the compiler command line when you compile your code, or you can add `#define DEBUG` to the top of your file. In Visual Basic, add the `/d:DEBUG=True` flag to the compiler command line. - -- To enable tracing in C#, add the `/d:TRACE` flag to the compiler command line when you compile your code, or add `#define TRACE` to the top of your file. In Visual Basic, add the `/d:TRACE=True` flag to the compiler command line. - - To add a trace listener, edit the configuration file that corresponds to the name of your application. Within this file, you can add a listener, set its type and set its parameter, remove a listener, or clear all the listeners previously set by the application. The configuration file should be formatted similar to the following example. - -```xml - - - - - - - - - - -``` - - For more information on using configuration files for tracing, see [<system.diagnostics>](/dotnet/framework/configure-apps/file-schema/trace-debug/system-diagnostics-element). - + , see the , and the classes. + + You must enable tracing or debugging to use a trace listener. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. + +- To enable debugging in C#, add the `/d:DEBUG` flag to the compiler command line when you compile your code, or you can add `#define DEBUG` to the top of your file. In Visual Basic, add the `/d:DEBUG=True` flag to the compiler command line. + +- To enable tracing in C#, add the `/d:TRACE` flag to the compiler command line when you compile your code, or add `#define TRACE` to the top of your file. In Visual Basic, add the `/d:TRACE=True` flag to the compiler command line. + + To add a trace listener, edit the configuration file that corresponds to the name of your application. Within this file, you can add a listener, set its type and set its parameter, remove a listener, or clear all the listeners previously set by the application. The configuration file should be formatted similar to the following example. + +```xml + + + + + + + + + + +``` + + For more information on using configuration files for tracing, see [<system.diagnostics>](/dotnet/framework/configure-apps/file-schema/trace-debug/system-diagnostics-element). + ]]> This type is thread safe. @@ -151,17 +151,17 @@ Initializes a new instance of the class. - . - -|Property|Default Value| -|--------------|-------------------| -|Name|The empty string ("").| -|Indent|Zero.| -|IndentSize|Four spaces.| - + . + +|Property|Default Value| +|--------------|-------------------| +|Name|The empty string ("").| +|Indent|Zero.| +|IndentSize|Four spaces.| + ]]> @@ -269,24 +269,24 @@ Gets the custom trace listener attributes defined in the application configuration file. A containing the custom attributes for the trace listener. - class can add custom attributes by overriding the method and returning a string array of custom attribute names. The property identifies the custom attributes that are referenced in the application's configuration file. For example, in the following configuration file excerpt the custom attribute "delimiter" is referenced. In this case, the property returns a containing the string "delimiter". - -```xml - - - - -``` - - Unreferenced custom attributes are not enumerated. For more information, see the method. - + class can add custom attributes by overriding the method and returning a string array of custom attribute names. The property identifies the custom attributes that are referenced in the application's configuration file. For example, in the following configuration file excerpt the custom attribute "delimiter" is referenced. In this case, the property returns a containing the string "delimiter". + +```xml + + + + +``` + + Unreferenced custom attributes are not enumerated. For more information, see the method. + ]]> @@ -329,11 +329,11 @@ When overridden in a derived class, closes the output stream so it no longer receives tracing or debugging output. - . After a call to this method, you must reinitialize the object. - + . After a call to this method, you must reinitialize the object. + ]]> @@ -397,11 +397,11 @@ Releases all resources used by the . - allows the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - + allows the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + ]]> Cleaning Up Unmanaged Resources @@ -450,20 +450,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method and the method, if it has been overridden. `Dispose` 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. - + method and the method, if it has been overridden. `Dispose` 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. + ]]> - can be called multiple times by other objects. When overriding this method, be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + can be called multiple times by other objects. When overriding this method, be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources. Implementing a Dispose method Cleaning Up Unmanaged Resources @@ -528,11 +528,11 @@ A message to emit. Emits an error message to the listener you create when you implement the class. - instances in a collection. By default, the collection has an instance of a . You can customize this behavior by adding a to or removing one from the collection. - + instances in a collection. By default, the collection has an instance of a . You can customize this behavior by adding a to or removing one from the collection. + ]]> @@ -589,11 +589,11 @@ A detailed message to emit. Emits an error message and a detailed error message to the listener you create when you implement the class. - instances in a collection. By default, the collection has an instance of a . You can customize this behavior by adding a to or removing one from the collection. - + instances in a collection. By default, the collection has an instance of a . You can customize this behavior by adding a to or removing one from the collection. + ]]> @@ -658,19 +658,19 @@ Gets or sets the trace filter for the trace listener. An object derived from the base class. - can be added to a trace listener to control the event types that are output by the listener. Listeners that are called because the switch criteria are met can query their filter, if present, to determine if a trace is to be sent to output. - - - -## Examples - The following code example shows how to use the property to add a source filter to a console trace listener. This code example is part of a larger example provided for the class. - + can be added to a trace listener to control the event types that are output by the listener. Listeners that are called because the switch criteria are met can query their filter, if present, to determine if a trace is to be sent to output. + + + +## Examples + The following code example shows how to use the property to add a source filter to a console trace listener. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet28"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.TraceSource2/VB/program.vb" id="Snippet28"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.TraceSource2/VB/program.vb" id="Snippet28"::: + ]]> @@ -773,19 +773,19 @@ Gets the custom attributes supported by the trace listener. A string array naming the custom attributes supported by the trace listener, or if there are no custom attributes. - returns `null`. - - - -## Examples - The following code sample shows an override of the method for a custom trace listener. - + returns `null`. + + + +## Examples + The following code sample shows an override of the method for a custom trace listener. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceListener/GetSupportedAttributes/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.TraceListener.CustomAttributes/vb/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.TraceListener.CustomAttributes/vb/program.vb" id="Snippet1"::: + ]]> @@ -838,11 +838,11 @@ Gets or sets the indent level. The indent level. The default is zero. - property represents the number of times that the indent specified by the property is applied. This property is stored on per-thread/per-request basis. - + property represents the number of times that the indent specified by the property is applied. This property is stored on per-thread/per-request basis. + ]]> @@ -899,11 +899,11 @@ Gets or sets the number of spaces in an indent. The number of spaces in an indent. The default is four spaces. - Set operation failed because the value is less than zero. @@ -955,11 +955,11 @@ if the trace listener is thread safe; otherwise, . The default is . - is used to determine whether to use a global lock when writing to the listener. If the value of is `false`, the global lock is used regardless of the value of . The global lock is not used only if the value of is `true` and the value of is `false`. The default behavior is to use the global lock whenever writing to the listener. - + is used to determine whether to use a global lock when writing to the listener. If the value of is `false`, the global lock is used regardless of the value of . The global lock is not used only if the value of is `true` and the value of is `false`. The default behavior is to use the global lock whenever writing to the listener. + ]]> @@ -1021,11 +1021,11 @@ Gets or sets a name for this . A name for this . The default is an empty string (""). - collection. - + collection. + ]]> @@ -1087,11 +1087,11 @@ if the output should be indented; otherwise, . - method, called by the and classes, sets the property value to `false` to prevent later, unnecessary indents. You must set the property to `true` each time you wish to indent trace output. - + method, called by the and classes, sets the property value to `false` to prevent later, unnecessary indents. You must set the property to `true` each time you wish to indent trace output. + ]]> @@ -1176,15 +1176,15 @@ The trace data to emit. Writes trace information, a data object and event information to the listener specific output. - [!IMPORTANT] -> This method is not intended to be called directly by application code but by members of the , , and classes to write trace data to output. - - The default implementation writes the `eventCache`, `source`, `eventType` and `id` parameters in the header and footer of the trace. The `data` parameter is written as the body of the trace message. The `ToString` method of the data object is used to convert the object to a . - +> This method is not intended to be called directly by application code but by members of the , , and classes to write trace data to output. + + The default implementation writes the `eventCache`, `source`, `eventType` and `id` parameters in the header and footer of the trace. The `data` parameter is written as the body of the trace message. The `ToString` method of the data object is used to convert the object to a . + ]]> @@ -1266,15 +1266,15 @@ An array of objects to emit as data. Writes trace information, an array of data objects and event information to the listener specific output. - [!IMPORTANT] -> This method is not intended to be called directly by application code but by members of the , , and classes to write trace data to output. - - The default implementation writes the values of the `source`, `eventType` and `id` parameters as a header. The data objects are converted to strings using the `ToString` method of each object. The `eventCache` data is written as a footer, the nature of the output data being dependent on the value of the property. - +> This method is not intended to be called directly by application code but by members of the , , and classes to write trace data to output. + + The default implementation writes the values of the `source`, `eventType` and `id` parameters as a header. The data objects are converted to strings using the `ToString` method of each object. The `eventCache` data is written as a footer, the nature of the output data being dependent on the value of the property. + ]]> @@ -1361,15 +1361,15 @@ A numeric identifier for the event. Writes trace and event information to the listener specific output. - [!IMPORTANT] -> This method is not intended to be called directly by application code but by members of the , , and classes to write trace data to output. - - The default implementation writes the values of the `source`, `eventType` and `id` parameters as a header. The `eventCache` data is written as a footer, the nature of the output data being dependent on the value of the property. - +> This method is not intended to be called directly by application code but by members of the , , and classes to write trace data to output. + + The default implementation writes the values of the `source`, `eventType` and `id` parameters as a header. The `eventCache` data is written as a footer, the nature of the output data being dependent on the value of the property. + ]]> @@ -1444,15 +1444,15 @@ A message to write. Writes trace information, a message, and event information to the listener specific output. - [!IMPORTANT] -> This method is not intended to be called directly by application code but by members of the , , and classes to write trace data to output. - - The default implementation writes the values of the `source`, `eventType` and `id` parameters as a header, followed by the `message` data. The `eventCache` data is written as a footer, the nature of the output data being dependent on the value of the property. - +> This method is not intended to be called directly by application code but by members of the , , and classes to write trace data to output. + + The default implementation writes the values of the `source`, `eventType` and `id` parameters as a header, followed by the `message` data. The `eventCache` data is written as a footer, the nature of the output data being dependent on the value of the property. + ]]> @@ -1544,15 +1544,15 @@ An array containing zero or more objects to format. Writes trace information, a formatted array of objects and event information to the listener specific output. - [!IMPORTANT] -> This method is not intended to be called directly by application code but by members of the , , and classes to write trace data to output. - - The default implementation writes the values of the `source`, `eventType` and `id` parameters as a header. The `args` object array is converted to a string using the method, passing the `format` string and `args` array to format the string as the message portion of the trace. The `eventCache` data is written as a footer, the nature of the output data being dependent on the value of the property. - +> This method is not intended to be called directly by application code but by members of the , , and classes to write trace data to output. + + The default implementation writes the values of the `source`, `eventType` and `id` parameters as a header. The `args` object array is converted to a string using the method, passing the `format` string and `args` array to format the string as the message portion of the trace. The `eventCache` data is written as a footer, the nature of the output data being dependent on the value of the property. + ]]> @@ -1612,27 +1612,27 @@ Gets or sets the trace output options. A bitwise combination of the enumeration values. The default is . - property determines the optional content of trace output. The property can be set in the configuration file or programmatically during execution to include additional data specifically for a section of code. For example, you can set the property for the console trace listener to to add call stack information to the trace output. - - The enumeration is not used by the following classes and methods: - -- The class, because it can cause a large volume of data to be written to the log. - -- The `Write` and `WriteLine` methods of the , , and classes. - -- The and methods of the class when they are not overridden in a derived class. - - - -## Examples - The following example shows the setting of the property for a console trace listener. The console trace listener is one of the listeners enumerated in the property of a trace source. This code example is part of a larger example provided for the class. - + property determines the optional content of trace output. The property can be set in the configuration file or programmatically during execution to include additional data specifically for a section of code. For example, you can set the property for the console trace listener to to add call stack information to the trace output. + + The enumeration is not used by the following classes and methods: + +- The class, because it can cause a large volume of data to be written to the log. + +- The `Write` and `WriteLine` methods of the , , and classes. + +- The and methods of the class when they are not overridden in a derived class. + + + +## Examples + The following example shows the setting of the property for a console trace listener. The console trace listener is one of the listeners enumerated in the property of a trace source. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.TraceSource2/VB/program.vb" id="Snippet16"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.TraceSource2/VB/program.vb" id="Snippet16"::: + ]]> Set operation failed because the value is invalid. @@ -1700,15 +1700,15 @@ A object identifying a related activity. Writes trace information, a message, a related activity identity and event information to the listener specific output. - [!IMPORTANT] -> This method is not intended to be called directly by application code but by members of the , , and classes to write trace data to output. - - The method is used for the correlation of related traces. The method calls the method to process the call, with the eventType level set to and the `relatedActivityId` as a string appended to the message. - +> This method is not intended to be called directly by application code but by members of the , , and classes to write trace data to output. + + The method is used for the correlation of related traces. The method calls the method to process the call, with the eventType level set to and the `relatedActivityId` as a string appended to the message. + ]]> @@ -1984,11 +1984,11 @@ Writes the indent to the listener you create when you implement this class, and resets the property to . - property to `false`. Call this method if is `true` when you are overriding the and methods. By default, this method uses blank spaces for indentation. The size of the indent is determined by the values of the and properties. The property represents the number of times the indent of the size specified by the property is applied. This method is called by the and classes. - + property to `false`. Call this method if is `true` when you are overriding the and methods. By default, this method uses blank spaces for indentation. The size of the indent is determined by the values of the and properties. The property represents the number of times the indent of the size specified by the property is applied. This method is called by the and classes. + ]]> @@ -2053,11 +2053,11 @@ An whose fully qualified class name you want to write. Writes the value of the object's method to the listener you create when you implement the class, followed by a line terminator. - @@ -2112,11 +2112,11 @@ A message to write. When overridden in a derived class, writes a message to the listener you create in the derived class, followed by a line terminator. - @@ -2176,11 +2176,11 @@ A category name used to organize the output. Writes a category name and the value of the object's method to the listener you create when you implement the class, followed by a line terminator. - @@ -2237,11 +2237,11 @@ A category name used to organize the output. Writes a category name and a message to the listener you create when you implement the class, followed by a line terminator. - diff --git a/xml/System.DirectoryServices.AccountManagement/AdvancedFilters.xml b/xml/System.DirectoryServices.AccountManagement/AdvancedFilters.xml index 1fcf71db5dd..e06c2ed659f 100644 --- a/xml/System.DirectoryServices.AccountManagement/AdvancedFilters.xml +++ b/xml/System.DirectoryServices.AccountManagement/AdvancedFilters.xml @@ -17,18 +17,18 @@ - This class provides writable access to certain attributes so that users can modify read-only properties of the "dummy" principal object that is passed to a object when using [Query By Example](https://msdn.microsoft.com/library/84ac40bb-04c4-4d0b-adaf-0ddb9253599e). + This class provides writable access to certain attributes so that users can modify read-only properties of the "dummy" principal object that is passed to a object when using Query By Example. - class is accessed from a object through the property, and is effectually treated like a property of the object, and isn't intended to be used on its own. - - - -## Examples - See the [Query By Example](https://msdn.microsoft.com/library/84ac40bb-04c4-4d0b-adaf-0ddb9253599e) topic for example code. - + class is accessed from a object through the property, and is effectually treated like a property of the object, and isn't intended to be used on its own. + + + +## Examples + See the [Query By Example](https://msdn.microsoft.com/library/84ac40bb-04c4-4d0b-adaf-0ddb9253599e) topic for example code. + ]]> @@ -62,11 +62,11 @@ A object. Instantiates a new object. Not intended to be called directly. - through the property of the user object. - + through the property of the user object. + ]]> @@ -99,39 +99,39 @@ A that specifies how should be used in the comparison. Sets the query filter for the attribute to the specified time and comparison type. - property of your object as . - - - -## Examples - -```csharp - -// Create the principal context for the usr object. -PrincipalContext ctx = new PrincipalContext(ContextType.Domain, "fabrikam.com", "CN=Users,DC=fabrikam,DC=com", "administrator", "SecurelyStoredPassword"); - -// Create the principal user object from the context -UserPrincipal usr = new UserPrincipal(ctx); - -// Set the advanced query filter -usr.AdvancedSearchFilter.AccountExpirationDate(DateTime.Now, MatchType.LessThan); - -// Create a PrincipalSearcher object. -PrincipalSearcher ps = new PrincipalSearcher(usr); - -PrincipalSearchResult results = ps.FindAll(); - -Console.WriteLine("The following users' accounts have expired:"); - -foreach (UserPrincipal u in results) -{ - Console.WriteLine(u.Name); -} -``` - + property of your object as . + + + +## Examples + +```csharp + +// Create the principal context for the usr object. +PrincipalContext ctx = new PrincipalContext(ContextType.Domain, "fabrikam.com", "CN=Users,DC=fabrikam,DC=com", "administrator", "SecurelyStoredPassword"); + +// Create the principal user object from the context +UserPrincipal usr = new UserPrincipal(ctx); + +// Set the advanced query filter +usr.AdvancedSearchFilter.AccountExpirationDate(DateTime.Now, MatchType.LessThan); + +// Create a PrincipalSearcher object. +PrincipalSearcher ps = new PrincipalSearcher(usr); + +PrincipalSearchResult results = ps.FindAll(); + +Console.WriteLine("The following users' accounts have expired:"); + +foreach (UserPrincipal u in results) +{ + Console.WriteLine(u.Name); +} +``` + ]]> @@ -164,39 +164,39 @@ foreach (UserPrincipal u in results) A that specifies how should be used in the comparison. Sets the query filter to the specified time and comparison type. - property of your object as . - - - -## Examples - -```csharp - -// Create the principal context for the usr object. -PrincipalContext ctx = new PrincipalContext(ContextType.Domain, "fabrikam.com", "CN=Users,DC=fabrikam,DC=com", "administrator", "SecurelyStoredPassword"); - -// Create the principal user object from the context -UserPrincipal usr = new UserPrincipal(ctx); - -// Set the advanced query filter -usr.AdvancedSearchFilter.AccountLockoutTime(DateTime.Now.AddDays(-1), MatchType.GreaterThan); - -// Create a PrincipalSearcher object. -PrincipalSearcher ps = new PrincipalSearcher(usr); - -PrincipalSearchResult results = ps.FindAll(); - -//Print user names of all accounts locked within the last 24 hours. - -foreach (UserPrincipal u in results) -{ - Console.WriteLine(u.Name); - } -``` - + property of your object as . + + + +## Examples + +```csharp + +// Create the principal context for the usr object. +PrincipalContext ctx = new PrincipalContext(ContextType.Domain, "fabrikam.com", "CN=Users,DC=fabrikam,DC=com", "administrator", "SecurelyStoredPassword"); + +// Create the principal user object from the context +UserPrincipal usr = new UserPrincipal(ctx); + +// Set the advanced query filter +usr.AdvancedSearchFilter.AccountLockoutTime(DateTime.Now.AddDays(-1), MatchType.GreaterThan); + +// Create a PrincipalSearcher object. +PrincipalSearcher ps = new PrincipalSearcher(usr); + +PrincipalSearchResult results = ps.FindAll(); + +//Print user names of all accounts locked within the last 24 hours. + +foreach (UserPrincipal u in results) +{ + Console.WriteLine(u.Name); + } +``` + ]]> @@ -239,24 +239,24 @@ foreach (UserPrincipal u in results) A that specifies how should be compared to the attribute's value. Creates a query filter for a property in an extended class. - @@ -289,32 +289,32 @@ public class InetOrgPersonSearchFilter : AdvancedFilters A that specifies how should be compared to the attribute's value. Sets the query filter for the attribute to the specified value and comparison type. - results = ps.FindAll(); -Console.WriteLine("The following users have logged on unsuccessfully at more than " + badLogonThreshold.toString + " times:"); -foreach (UserPrincipal u in results) -{ - Console.WriteLine(u.Name); -} -``` - + results = ps.FindAll(); +Console.WriteLine("The following users have logged on unsuccessfully at more than " + badLogonThreshold.toString + " times:"); +foreach (UserPrincipal u in results) +{ + Console.WriteLine(u.Name); +} +``` + ]]> @@ -347,39 +347,39 @@ foreach (UserPrincipal u in results) A that specifies how should be used in the comparison. Sets the query filter for the attribute to the specified and the specified comparison value. - property of your object as . - - - -## Examples - -```csharp - -// Create the principal context for the usr object. -PrincipalContext ctx = new PrincipalContext(ContextType.Domain, "fabrikam.com", "CN=Users,DC=fabrikam,DC=com", "administrator", "SecurelyStoredPassword"); - -// Create the principal user object from the context -UserPrincipal usr = new UserPrincipal(ctx); - -// Set the advanced query filter -usr.AdvancedSearchFilter.LastBadPasswordAttempt(DateTime.Now.AddDays(-1), MatchType.GreaterThan); - -// Create a PrincipalSearcher object. -PrincipalSearcher ps = new PrincipalSearcher(usr); -PrincipalSearchResult results = ps.FindAll(); - -//Write the name of all users whose most recent incorrect -//password entry was within the last day - -foreach (UserPrincipal u in results) -{ - Console.WriteLine(u.Name); -} -``` - + property of your object as . + + + +## Examples + +```csharp + +// Create the principal context for the usr object. +PrincipalContext ctx = new PrincipalContext(ContextType.Domain, "fabrikam.com", "CN=Users,DC=fabrikam,DC=com", "administrator", "SecurelyStoredPassword"); + +// Create the principal user object from the context +UserPrincipal usr = new UserPrincipal(ctx); + +// Set the advanced query filter +usr.AdvancedSearchFilter.LastBadPasswordAttempt(DateTime.Now.AddDays(-1), MatchType.GreaterThan); + +// Create a PrincipalSearcher object. +PrincipalSearcher ps = new PrincipalSearcher(usr); +PrincipalSearchResult results = ps.FindAll(); + +//Write the name of all users whose most recent incorrect +//password entry was within the last day + +foreach (UserPrincipal u in results) +{ + Console.WriteLine(u.Name); +} +``` + ]]> @@ -412,37 +412,37 @@ foreach (UserPrincipal u in results) A that specifies how should be used in the comparison. Sets the query filter for the attribute to the specified and the specified comparison value. - property of your object as . - - - -## Examples - -```csharp - -// Create the principal context for the usr object. -PrincipalContext ctx = new PrincipalContext(ContextType.Domain, "fabrikam.com", "CN=Users,DC=fabrikam,DC=com", "administrator", "SecurelyStoredPassword"); - -// Create the principal user object from the context -UserPrincipal usr = new UserPrincipal(ctx); - -// Set the advanced query filter -usr.AdvancedSearchFilter.LastLogonTime(DateTime.Now.AddDays(-1), MatchType.GreaterThan); - -// Create a PrincipalSearcher object. -PrincipalSearcher ps = new PrincipalSearcher(usr); -PrincipalSearchResult results = ps.FindAll(); - -//Write the names of all users who have logged on since yesterday -foreach (UserPrincipal u in results) -{ - Console.WriteLine(u.Name); -} -``` - + property of your object as . + + + +## Examples + +```csharp + +// Create the principal context for the usr object. +PrincipalContext ctx = new PrincipalContext(ContextType.Domain, "fabrikam.com", "CN=Users,DC=fabrikam,DC=com", "administrator", "SecurelyStoredPassword"); + +// Create the principal user object from the context +UserPrincipal usr = new UserPrincipal(ctx); + +// Set the advanced query filter +usr.AdvancedSearchFilter.LastLogonTime(DateTime.Now.AddDays(-1), MatchType.GreaterThan); + +// Create a PrincipalSearcher object. +PrincipalSearcher ps = new PrincipalSearcher(usr); +PrincipalSearchResult results = ps.FindAll(); + +//Write the names of all users who have logged on since yesterday +foreach (UserPrincipal u in results) +{ + Console.WriteLine(u.Name); +} +``` + ]]> @@ -475,39 +475,39 @@ foreach (UserPrincipal u in results) A that specifies how should be used in the comparison. Sets the query filter for the attribute to the specified and the specified comparison value. - property of your object as . - - - -## Examples - -```csharp - -// Create the principal context for the usr object. -PrincipalContext ctx = new PrincipalContext(ContextType.Domain, "fabrikam.com", "CN=Users,DC=fabrikam,DC=com", "administrator", "SecurelyStoredPassword"); - -// Create the principal user object from the context -UserPrincipal usr = new UserPrincipal(ctx); - -// Set the advanced query filter -usr.AdvancedSearchFilter.LastPasswordSetTime(DateTime.Now.AddDays(-30), MatchType.LessThan); - -// Create a PrincipalSearcher object. -PrincipalSearcher ps = new PrincipalSearcher(usr); -PrincipalSearchResult results = ps.FindAll(); - -//Force users who have not changed their password in the last -//30 days to do so at next logon -foreach (UserPrincipal u in results) -{ - u.ExpirePasswordNow(); - u.Save(); -} -``` - + property of your object as . + + + +## Examples + +```csharp + +// Create the principal context for the usr object. +PrincipalContext ctx = new PrincipalContext(ContextType.Domain, "fabrikam.com", "CN=Users,DC=fabrikam,DC=com", "administrator", "SecurelyStoredPassword"); + +// Create the principal user object from the context +UserPrincipal usr = new UserPrincipal(ctx); + +// Set the advanced query filter +usr.AdvancedSearchFilter.LastPasswordSetTime(DateTime.Now.AddDays(-30), MatchType.LessThan); + +// Create a PrincipalSearcher object. +PrincipalSearcher ps = new PrincipalSearcher(usr); +PrincipalSearchResult results = ps.FindAll(); + +//Force users who have not changed their password in the last +//30 days to do so at next logon +foreach (UserPrincipal u in results) +{ + u.ExpirePasswordNow(); + u.Save(); +} +``` + ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/AuthenticablePrincipal.xml b/xml/System.DirectoryServices.AccountManagement/AuthenticablePrincipal.xml index 63d2ee2bc4f..09360a18d7e 100644 --- a/xml/System.DirectoryServices.AccountManagement/AuthenticablePrincipal.xml +++ b/xml/System.DirectoryServices.AccountManagement/AuthenticablePrincipal.xml @@ -39,11 +39,11 @@ Initializes a new instance of the class. This constructor is called by derived-class constructors to initialize the base class and is not intended for use directly from your code. - @@ -70,11 +70,11 @@ The that specifies the server or domain against which operations are performed. Initializes a new instance of the class by using the specified context. This constructor is called by derived-class constructors to initialize the base class and is not intended for use directly from your code. - @@ -107,11 +107,11 @@ A Boolean value that specifies whether the account is enabled. Initializes a new instance of the class by using the specified context, SAM account name, password, and enabled value. This constructor is called by derived-class constructors to initialize the base class and is not intended for use directly from your code. - @@ -138,13 +138,13 @@ Gets or sets a Nullable that specifies the date and time that the account expires. A that specifies the date and time that the account expires, or null if the account never expires. - properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. - - When you set the , the time will default to UTC. If you want to write in local time, then specify the property of your object as . - + properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. + + When you set the , the time will default to UTC. If you want to write in local time, then specify the property of your object as . + ]]> The underlying store does not support this property. @@ -172,15 +172,15 @@ Gets the Nullable that specifies the date and time that the account was locked out. A that specifies the date and time that the account was locked out, or null if no lockout time is set on the account. - method. - - It is possible that an account may not be locked out when the returns a non-null value. Applications should use the method to determine whether the account is locked out. - - As with all properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. - + method. + + It is possible that an account may not be locked out when the returns a non-null value. Applications should use the method to determine whether the account is locked out. + + As with all properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. + ]]> The underlying store does not support this property. @@ -211,14 +211,14 @@ System.DirectoryServices.AccountManagement.AdvancedFilters - Returns an object for use with [Query By Example](https://msdn.microsoft.com/library/84ac40bb-04c4-4d0b-adaf-0ddb9253599e) to set read-only properties before passing the object to the . + Returns an object for use with Query By Example to set read-only properties before passing the object to the . An object to use to set read-only properties before passing it to the . - @@ -328,11 +328,11 @@ The new password. Changes the account password from the old password to the new password. Do not use this with a . - will cause a to be thrown. - + will cause a to be thrown. + ]]> The principal has not been persisted. @@ -389,11 +389,11 @@ if the principal is enabled, or null if the account has not been persisted; otherwise . - The underlying store does not support this property. @@ -422,11 +422,11 @@ Expires the password for this account. This will force the user to change his/her password at the next logon. - An exception occurred when saving the changes to the store. @@ -468,11 +468,11 @@ Returns a collection of authentication principal objects that have an incorrect password try recorded in the specified date and time range. A that contains one or more objects, or an empty collection if no results are found. - property of the `time` object as . - + property of the `time` object as . + ]]> @@ -511,11 +511,11 @@ Returns a collection of objects that have a bad password attempt within the specified date and time range. This is the template function for extended classes that wish to implement this functionality. A that contains one or more objects of the appropriate principal type, or an empty collection if no matches are found. - property of the `time` object as . - + property of the `time` object as . + ]]> @@ -556,11 +556,11 @@ Returns a collection of authentication principal objects that have an account expiration time recorded in the specified date and time range. A that contains one or more objects. - property of the `time` object as . - + property of the `time` object as . + ]]> @@ -599,11 +599,11 @@ Returns a collection of objects that have an expiration time within the specified date and time range. This is the template function for extended classes that wish to implement this functionality. A that contains one or more objects of the appropriate principal type, or an empty collection if no matches are found. - property of the `time` object as . - + property of the `time` object as . + ]]> @@ -644,11 +644,11 @@ Returns a collection of authentication principal objects that have an account lockout time recorded in the specified date and time range. A that contains one or more objects. - property of the `time` object as . - + property of the `time` object as . + ]]> @@ -687,11 +687,11 @@ Returns a collection of objects that have a lockout time within the specified date and time range. This is the template function for extended classes that wish to implement this functionality. A that contains one or more objects of the appropriate principal type, or an empty collection if no matches are found. - property of the `time` object as . - + property of the `time` object as . + ]]> @@ -732,40 +732,40 @@ Returns a collection of authentication principal objects that have an account logon recorded in the specified date and time range. A that contains one or more objects. - property of the `time` object as . - - - -## Examples - The following code connects to the ADAM instance hosted by the server "adamHost1.fabrikam.com" on port number "5000." The username (adamAdmin), and password (SecretPwd123) are specified in the constructor. - - A search is performed for all authenticable principals under the container "DC=adamApp1,DC=fabrikam,DC=com" that have not logged on to this ADAM instance for the last 45 days. The principals returned by the search are then deleted. - -``` -PrincipalContext ctx = new PrincipalContext( - ContextType.ApplicationDirectory, - "adamHost1.fabrikam.com:5000", - "DC=adamApp1,DC=fabrikam,DC=com", - "adamAdmin", "SecretPwd123"); - -PrincipalSearchResult oldPrincipals = - AuthenticablePrincipal.FindByLogonTime(ctx, - (DateTime.Now - new TimeSpan(45, 0, 0, 0)), - MatchType.LessThan); - -foreach (Principal p in oldPrincipals) -{ - p.Delete(); -} - -oldPrincipals.Dispose(); -ctx.Dispose(); - -``` - + property of the `time` object as . + + + +## Examples + The following code connects to the ADAM instance hosted by the server "adamHost1.fabrikam.com" on port number "5000." The username (adamAdmin), and password (SecretPwd123) are specified in the constructor. + + A search is performed for all authenticable principals under the container "DC=adamApp1,DC=fabrikam,DC=com" that have not logged on to this ADAM instance for the last 45 days. The principals returned by the search are then deleted. + +``` +PrincipalContext ctx = new PrincipalContext( + ContextType.ApplicationDirectory, + "adamHost1.fabrikam.com:5000", + "DC=adamApp1,DC=fabrikam,DC=com", + "adamAdmin", "SecretPwd123"); + +PrincipalSearchResult oldPrincipals = + AuthenticablePrincipal.FindByLogonTime(ctx, + (DateTime.Now - new TimeSpan(45, 0, 0, 0)), + MatchType.LessThan); + +foreach (Principal p in oldPrincipals) +{ + p.Delete(); +} + +oldPrincipals.Dispose(); +ctx.Dispose(); + +``` + ]]> @@ -804,11 +804,11 @@ ctx.Dispose(); Returns a collection of objects that have a logon time within the specified date and time range. This is the template function for extended classes that wish to implement this functionality. A that contains one or more objects of the appropriate principal type, or an empty collection if no matches are found. - property of the `time` object as . - + property of the `time` object as . + ]]> @@ -849,11 +849,11 @@ ctx.Dispose(); Returns a collection of authentication principal objects that have an account password set recorded in the specified date and time range. A that contains one or more objects. - property of the `time` object as . - + property of the `time` object as . + ]]> @@ -892,11 +892,11 @@ ctx.Dispose(); Returns a collection of objects that have a password set time within the specified date and time range. This is the template function for extended classes that wish to implement this functionality. A that contains one or more objects of the appropriate principal type, or an empty collection if no matches are found. - property of the `time` object as . - + property of the `time` object as . + ]]> @@ -975,11 +975,11 @@ ctx.Dispose(); if the account is locked out; otherwise . - returns a non-null value. This method computes the correct store-specific lockout value to determine whether the account is locked out. - + returns a non-null value. This method computes the correct store-specific lockout value to determine whether the account is locked out. + ]]> @@ -1006,11 +1006,11 @@ ctx.Dispose(); Gets the Nullable that specifies the date and time of the last incorrect password attempt on this account. A Nullable that specifies the date and time of the last incorrect password attempt on this account, or null if no incorrect password tries are recorded. - properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. - + properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. + ]]> The underlying store does not support this property. @@ -1038,11 +1038,11 @@ ctx.Dispose(); Gets the Nullable that specifies the date and time of the last logon for this account. A Nullable that specifies the date and time of the last logon for this account. - properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. - + properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. + ]]> The underlying store does not support this property. @@ -1070,11 +1070,11 @@ ctx.Dispose(); Gets the Nullable that specifies the last date and time that the password was set for this account. A Nullable that specifies the last date and time that the password was set for this account. - properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. - + properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. + ]]> The underlying store does not support this property. @@ -1308,31 +1308,31 @@ ctx.Dispose(); Unlocks the account if it is currently locked out. - constructor. - - A search is performed to find the user with name "John Smith" under the container specified in the constructor: "CN=Users,DC=fabrikam,DC=com." If the user is found, a check is performed to determine whether this user's account has been locked out. If the account has been locked out, the code example unlocks the account. - -``` -PrincipalContext ctx = new PrincipalContext(ContextType.Domain, - "fabrikam.com", - "CN=Users,DC=fabrikam,DC=com", - "administrator", - "SecretPwd123"); - -UserPrincipal usr = UserPrincipal.FindByIdentity(ctx, "John Smith"); -if (usr != null) -{ - if (usr.IsAccountLockedOut()) - usr.UnlockAccount(); - - usr.Dispose(); -} -ctx.Dispose(); -``` - + constructor. + + A search is performed to find the user with name "John Smith" under the container specified in the constructor: "CN=Users,DC=fabrikam,DC=com." If the user is found, a check is performed to determine whether this user's account has been locked out. If the account has been locked out, the code example unlocks the account. + +``` +PrincipalContext ctx = new PrincipalContext(ContextType.Domain, + "fabrikam.com", + "CN=Users,DC=fabrikam,DC=com", + "administrator", + "SecretPwd123"); + +UserPrincipal usr = UserPrincipal.FindByIdentity(ctx, "John Smith"); +if (usr != null) +{ + if (usr.IsAccountLockedOut()) + usr.UnlockAccount(); + + usr.Dispose(); +} +ctx.Dispose(); +``` + ]]> @@ -1366,11 +1366,11 @@ An exception occurred when saving the changes to the store. if the user is not permitted to change the password; otherwise . - will cause a to be thrown. - + will cause a to be thrown. + ]]> The underlying store does not support this property. diff --git a/xml/System.DirectoryServices.AccountManagement/PrincipalSearcher.xml b/xml/System.DirectoryServices.AccountManagement/PrincipalSearcher.xml index daf1b917a53..a6acf64edcb 100644 --- a/xml/System.DirectoryServices.AccountManagement/PrincipalSearcher.xml +++ b/xml/System.DirectoryServices.AccountManagement/PrincipalSearcher.xml @@ -265,7 +265,7 @@ ]]> - The contains referential properties. For more information, see the [Query by Example](https://learn.microsoft.com/previous-versions/bb384378(v=vs.90)) overview topic. + The contains referential properties. For more information, see the Query by Example overview topic. The is a persisted principal. A must first be assigned to the principal searcher before the query can be performed. @@ -310,7 +310,7 @@ A must first be assigned to the principal searcher before the query can be performed. - The contains referential properties. For more information, see the [Query by Example](https://learn.microsoft.com/previous-versions/bb384378(v=vs.90)) overview topic. + The contains referential properties. For more information, see the Query by Example overview topic. The is a persisted principal. Query by Example diff --git a/xml/System.DirectoryServices.Protocols/LdapSessionOptions.xml b/xml/System.DirectoryServices.Protocols/LdapSessionOptions.xml index fb197990990..39f9e48c9a7 100644 --- a/xml/System.DirectoryServices.Protocols/LdapSessionOptions.xml +++ b/xml/System.DirectoryServices.Protocols/LdapSessionOptions.xml @@ -298,11 +298,11 @@ The property contains a object that specifies the default callback function used to specify client certificates when establishing an SSL connection. A object that specifies the default callback function used to specify client certificates when establishing an SSL connection. - property on the object is also set, the certificate specified in the property is ignored. - + property on the object is also set, the certificate specified in the property is ignored. + ]]> The object is already disposed. @@ -605,7 +605,7 @@ System.Int32 - The property specifies the flags to pass to the Security Support Provider Interface (SSPI) InitializeSecurityContext function. For more information about the InitializeSecurityContext function, see the [InitializeSecurityContext function](/windows/win32/api/sspi/nf-sspi-initializesecuritycontexta) article. + The property specifies the flags to pass to the Security Support Provider Interface (SSPI) InitializeSecurityContext function. For more information about the InitializeSecurityContext function, see the InitializeSecurityContext function article. The flags to pass to the SSPI InitializeSecurityContext function. To be added. The object is already disposed. diff --git a/xml/System.DirectoryServices/DirectoryEntry.xml b/xml/System.DirectoryServices/DirectoryEntry.xml index fc493dad85d..74fffc9438d 100644 --- a/xml/System.DirectoryServices/DirectoryEntry.xml +++ b/xml/System.DirectoryServices/DirectoryEntry.xml @@ -42,24 +42,24 @@ The class encapsulates a node or object in the Active Directory Domain Services hierarchy. - , along with helper classes, provides support for life-cycle management and navigation methods. These include creating, deleting, renaming, moving a child node, and enumerating children. After you modify a node, you must commit your changes in order for them to be saved to the tree. For more information, see the property. - - can be used to access regular entries and some, but not all, information from schema entries. - - The Active Directory Domain Services hierarchy contains up to several thousand nodes. Each node represents an object, such as a network printer or a user in a domain. Corporate networks constantly change as new employees are hired and objects such as network printers and computers are added. Active Directory Service Interfaces (ADSI) technology provides ways to programmatically add these objects to the directory tree. - - To create a directory entry in the hierarchy, use the property. The property is a collection that provides an method, through which you add a node to the collection directly below the parent node that you are currently bound to. When adding a node to the collection, you must specify a name for the new node and the name of a schema template that you want to associate with the node. For example, you might want to use a schema titled "Computer" to add new computers to the hierarchy. - - This class also contains attribute caching, which can be useful for optimizing network traffic. To use attribute caching, see the property. - - The classes associated with the component can be used with any of the Active Directory Domain Services service providers. Some of the current providers are Internet Information Services (IIS), Lightweight Directory Access Protocol (LDAP), Novell NetWare Directory Service (NDS), and WinNT. - + , along with helper classes, provides support for life-cycle management and navigation methods. These include creating, deleting, renaming, moving a child node, and enumerating children. After you modify a node, you must commit your changes in order for them to be saved to the tree. For more information, see the property. + + can be used to access regular entries and some, but not all, information from schema entries. + + The Active Directory Domain Services hierarchy contains up to several thousand nodes. Each node represents an object, such as a network printer or a user in a domain. Corporate networks constantly change as new employees are hired and objects such as network printers and computers are added. Active Directory Service Interfaces (ADSI) technology provides ways to programmatically add these objects to the directory tree. + + To create a directory entry in the hierarchy, use the property. The property is a collection that provides an method, through which you add a node to the collection directly below the parent node that you are currently bound to. When adding a node to the collection, you must specify a name for the new node and the name of a schema template that you want to associate with the node. For example, you might want to use a schema titled "Computer" to add new computers to the hierarchy. + + This class also contains attribute caching, which can be useful for optimizing network traffic. To use attribute caching, see the property. + + The classes associated with the component can be used with any of the Active Directory Domain Services service providers. Some of the current providers are Internet Information Services (IIS), Lightweight Directory Access Protocol (LDAP), Novell NetWare Directory Service (NDS), and WinNT. + > [!NOTE] -> It is assumed that you have a general understanding of Active Directory Domain Services before using this class. For more information, see the namespace overview. - +> It is assumed that you have a general understanding of Active Directory Domain Services before using this class. For more information, see the namespace overview. + ]]> @@ -117,11 +117,11 @@ The name of the native Active Directory Domain Services object to bind to. Initializes a new instance of the class that binds to the specified native Active Directory Domain Services object. - class on a native Active Directory Domain Services object that implements the IADs interface through a native API. For more information about the IADs interface, see the [IADs](/windows/win32/api/iads/nn-iads-iads) article. - + class on a native Active Directory Domain Services object that implements the IADs interface through a native API. For more information about the IADs interface, see the [IADs](/windows/win32/api/iads/nn-iads-iads) article. + ]]> @@ -156,76 +156,76 @@ The path at which to bind the to the directory. The property is initialized to this value. Initializes a new instance of the class that binds this instance to the node in Active Directory Domain Services located at the specified path. - object to the directory entry at the specified path, and displays the property of each child entry that is specified by the node's property. - -```vb -Public Class PrintChildren - - 'Entry point which delegates to C-style main Private Function. - Public Overloads Shared Sub Main() - Main(System.Environment.GetCommandLineArgs()) - End Sub - - Overloads Public Shared Sub Main(args() As String) - Dim objDE As DirectoryEntry - Dim strPath As String = "LDAP://DC=onecity,DC=corp,DC=fabrikam,DC=com" - If args.Length > 0 Then - strPath = args(1) - End If - ' Create a new DirectoryEntry with the given path. - objDE = New DirectoryEntry(strPath) - - Dim objChildDE As DirectoryEntry - For Each objChildDE In objDE.Children - Console.WriteLine(objChildDE.Path) - Next objChildDE - End Sub 'Main -End Class 'PrintChildren -``` - -```csharp -public class PrintChildren{ - public static void Main(String[] args) - { - DirectoryEntry objDE; - String strPath="LDAP://DC=onecity,DC=corp,DC=fabrikam,DC=com"; - if(args.Length>0)strPath=args[1]; - - // Create a new DirectoryEntry with the given path. - objDE=new DirectoryEntry(strPath); - - foreach(DirectoryEntry objChildDE in objDE.Children) - Console.WriteLine(objChildDE.Path); - } - } -``` - -```cpp -int main() -{ - String^ args[] = Environment::GetCommandLineArgs(); - DirectoryEntry^ objDE; - String^ strPath = "LDAP://DC=onecity,DC=corp,DC=fabrikam,DC=com"; - if(args->Length>1) - { - strPath=args[1]; - } - - // Create a new DirectoryEntry with the given path. - objDE = gcnew DirectoryEntry(strPath); - - System::Collections::IEnumerator^ enum0 = objDE->Children->GetEnumerator(); - while (enum0->MoveNext()) - { - DirectoryEntry^ objChildDE = safe_cast(enum0->Current); - Console::WriteLine(objChildDE->Path); - } -} -``` - + object to the directory entry at the specified path, and displays the property of each child entry that is specified by the node's property. + +```vb +Public Class PrintChildren + + 'Entry point which delegates to C-style main Private Function. + Public Overloads Shared Sub Main() + Main(System.Environment.GetCommandLineArgs()) + End Sub + + Overloads Public Shared Sub Main(args() As String) + Dim objDE As DirectoryEntry + Dim strPath As String = "LDAP://DC=onecity,DC=corp,DC=fabrikam,DC=com" + If args.Length > 0 Then + strPath = args(1) + End If + ' Create a new DirectoryEntry with the given path. + objDE = New DirectoryEntry(strPath) + + Dim objChildDE As DirectoryEntry + For Each objChildDE In objDE.Children + Console.WriteLine(objChildDE.Path) + Next objChildDE + End Sub 'Main +End Class 'PrintChildren +``` + +```csharp +public class PrintChildren{ + public static void Main(String[] args) + { + DirectoryEntry objDE; + String strPath="LDAP://DC=onecity,DC=corp,DC=fabrikam,DC=com"; + if(args.Length>0)strPath=args[1]; + + // Create a new DirectoryEntry with the given path. + objDE=new DirectoryEntry(strPath); + + foreach(DirectoryEntry objChildDE in objDE.Children) + Console.WriteLine(objChildDE.Path); + } + } +``` + +```cpp +int main() +{ + String^ args[] = Environment::GetCommandLineArgs(); + DirectoryEntry^ objDE; + String^ strPath = "LDAP://DC=onecity,DC=corp,DC=fabrikam,DC=com"; + if(args->Length>1) + { + strPath=args[1]; + } + + // Create a new DirectoryEntry with the given path. + objDE = gcnew DirectoryEntry(strPath); + + System::Collections::IEnumerator^ enum0 = objDE->Children->GetEnumerator(); + while (enum0->MoveNext()) + { + DirectoryEntry^ objChildDE = safe_cast(enum0->Current); + Console::WriteLine(objChildDE->Path); + } +} +``` + ]]> @@ -346,11 +346,11 @@ int main() Gets or sets the type of authentication to use. One of the values. - . Beginning with .NET Framework 2.0, the default value is . - + . Beginning with .NET Framework 2.0, the default value is . + ]]> @@ -393,16 +393,16 @@ int main() Gets the child entries of this node in the Active Directory Domain Services hierarchy. A object containing the child entries of this node in the Active Directory Domain Services hierarchy. - method through which you add a node to the collection directly below the parent node that you are currently bound to. When adding a node to the collection, you must specify a name for the new node and the name of a schema template that you want to associate with the node. For example, you might want to use a schema titled "Computer" to add new computers to the hierarchy. - + method through which you add a node to the collection directly below the parent node that you are currently bound to. When adding a node to the collection, you must specify a name for the new node and the name of a schema template that you want to associate with the node. For example, you might want to use a schema titled "Computer" to add new computers to the hierarchy. + > [!NOTE] -> By default, changes are made locally to a cache. After you modify or add a node, you must call the method to commit your changes in order for them to be saved to the tree. If you call before calling , any uncommitted changes to the property cache will be lost. For more information, see the and methods, and the property. - +> By default, changes are made locally to a cache. After you modify or add a node, you must call the method to commit your changes in order for them to be saved to the tree. If you call before calling , any uncommitted changes to the property cache will be lost. For more information, see the and methods, and the property. + ]]> @@ -435,13 +435,13 @@ int main() Closes the object and releases any system resources that are associated with this component. - , any operations on the might raise exceptions. - + , any operations on the might raise exceptions. + ]]> @@ -469,20 +469,20 @@ int main() Saves changes that are made to a directory entry to the underlying directory store. - . - - Changes made to the cache include changes to the properties as well as calls to (if this is the newly created entry). - + . + + Changes made to the cache include changes to the properties as well as calls to (if this is the newly created entry). + > [!CAUTION] -> If you call before calling , any uncommitted changes to the property cache will be lost. - -## Security - -- Use the class for reading, writing, deleting, changing, and adding to the Active Directory Domain Services hierarchy. Associated enumeration: . - +> If you call before calling , any uncommitted changes to the property cache will be lost. + +## Security + +- Use the class for reading, writing, deleting, changing, and adding to the Active Directory Domain Services hierarchy. Associated enumeration: . + ]]> @@ -527,13 +527,13 @@ int main() Creates a copy of this entry as a child of the specified parent. A object that represents the copy of this entry as a child of the new parent. - is `true`, call on the new object to make the copy permanent. - - The Lightweight Directory Access Protocol (LDAP) provider does not currently support the method. - + is `true`, call on the new object to make the copy permanent. + + The Lightweight Directory Access Protocol (LDAP) provider does not currently support the method. + ]]> The specified is not a container. @@ -576,13 +576,13 @@ int main() Creates a copy of this object, as a child of the specified parent object, with the specified new name. A renamed copy of this entry as a child of the specified parent. - is `true`, call on the new object to make the copy permanent. - + is `true`, call on the new object to make the copy permanent. + ]]> The specified object is not a container. @@ -613,18 +613,18 @@ int main() Deletes this entry and its entire subtree from the Active Directory Domain Services hierarchy. - [!CAUTION] -> The entry and its entire subtree are deleted from the Active Directory Domain Services hierarchy. - -## Security - -- Use for deleting entries from the Active Directory Domain Services hierarchy. Associated enumeration: . - +> The entry and its entire subtree are deleted from the Active Directory Domain Services hierarchy. + +## Security + +- Use for deleting entries from the Active Directory Domain Services hierarchy. Associated enumeration: . + ]]> The specified is not a container. @@ -657,18 +657,18 @@ int main() to release both managed and unmanaged resources; to release only unmanaged resources. Disposes of the resources (other than memory) that are used by the . - 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`. - + 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 that are held by any managed objects that this object references. This method invokes the `Dispose()` method of each referenced object. - + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement `Dispose`, see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement `Dispose`, see Implementing a Dispose Method. @@ -701,48 +701,48 @@ int main() if the specified path represents a valid entry in the directory service; otherwise, . - . - -```vb -Dim myADSPath As String = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com" -' Determine whether the given path is correct for the DirectoryEntry. -If DirectoryEntry.Exists(myADSPath) Then - Console.WriteLine("The path {0} is valid",myADSPath) -Else - Console.WriteLine("The path {0} is invalid",myADSPath) -End If -``` - -```csharp -string myADSPath ="LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; - -// Determine whether the given path is correct for the DirectoryEntry. -if (DirectoryEntry.Exists(myADSPath)) -{ - Console.WriteLine("The path {0} is valid",myADSPath); -} - else -{ - Console.WriteLine("The path {0} is invalid",myADSPath); -} -``` - + . + +```vb +Dim myADSPath As String = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com" +' Determine whether the given path is correct for the DirectoryEntry. +If DirectoryEntry.Exists(myADSPath) Then + Console.WriteLine("The path {0} is valid",myADSPath) +Else + Console.WriteLine("The path {0} is invalid",myADSPath) +End If +``` + +```csharp +string myADSPath ="LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; + +// Determine whether the given path is correct for the DirectoryEntry. +if (DirectoryEntry.Exists(myADSPath)) +{ + Console.WriteLine("The path {0} is valid",myADSPath); +} + else +{ + Console.WriteLine("The path {0} is invalid",myADSPath); +} +``` + ```cpp -String^ myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; -// Determine whether the given path is correct for the DirectoryEntry. -if (DirectoryEntry::Exists(myADSPath)) -{ - Console::WriteLine("The path {0} is valid", myADSPath); -} -else -{ - Console::WriteLine("The path {0} is invalid", myADSPath); -} -``` - +String^ myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; +// Determine whether the given path is correct for the DirectoryEntry. +if (DirectoryEntry::Exists(myADSPath)) +{ + Console::WriteLine("The path {0} is valid", myADSPath); +} +else +{ + Console::WriteLine("The path {0} is invalid", myADSPath); +} +``` + ]]> @@ -784,46 +784,46 @@ else Gets the GUID of the . A structure that represents the GUID of the . - property. - - - -## Examples - The following example demonstrates the and properties of the class. This example gets the user-specified and displays its and properties. - -```vb -Dim myADSPath As [String] = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com" -Dim myDirectoryEntry As New DirectoryEntry(myADSPath) - -' Display the Guid and NativeGuid. -Console.WriteLine("The GUID of the ADS object:" + myDirectoryEntry.Guid.ToString) -Console.WriteLine("The Native GUID of the ADS" + "object:" + myDirectoryEntry.NativeGuid) -``` - -```csharp -String myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; -DirectoryEntry myDirectoryEntry=new DirectoryEntry(myADSPath); - -// Display the Guid and NativeGuid. -Console.WriteLine("The GUID of the ADS object:"+ - myDirectoryEntry.Guid); -Console.WriteLine("The Native GUID of the ADS"+ - "object:"+myDirectoryEntry.NativeGuid); -``` - + property. + + + +## Examples + The following example demonstrates the and properties of the class. This example gets the user-specified and displays its and properties. + +```vb +Dim myADSPath As [String] = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com" +Dim myDirectoryEntry As New DirectoryEntry(myADSPath) + +' Display the Guid and NativeGuid. +Console.WriteLine("The GUID of the ADS object:" + myDirectoryEntry.Guid.ToString) +Console.WriteLine("The Native GUID of the ADS" + "object:" + myDirectoryEntry.NativeGuid) +``` + +```csharp +String myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; +DirectoryEntry myDirectoryEntry=new DirectoryEntry(myADSPath); + +// Display the Guid and NativeGuid. +Console.WriteLine("The GUID of the ADS object:"+ + myDirectoryEntry.Guid); +Console.WriteLine("The Native GUID of the ADS"+ + "object:"+myDirectoryEntry.NativeGuid); +``` + ```cpp -String^ myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; -DirectoryEntry^ myDirectoryEntry = gcnew DirectoryEntry(myADSPath); - -// Display the Guid and NativeGuid. -Console::WriteLine("The GUID of the ADS object: {0}", myDirectoryEntry->Guid); -Console::WriteLine("The Native GUID of the ADS object: {0}", - myDirectoryEntry->NativeGuid); -``` - +String^ myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; +DirectoryEntry^ myDirectoryEntry = gcnew DirectoryEntry(myADSPath); + +// Display the Guid and NativeGuid. +Console::WriteLine("The GUID of the ADS object: {0}", myDirectoryEntry->Guid); +Console::WriteLine("The Native GUID of the ADS object: {0}", + myDirectoryEntry->NativeGuid); +``` + ]]> @@ -879,11 +879,11 @@ Console::WriteLine("The Native GUID of the ADS object: {0}", Calls a method on the native Active Directory Domain Services object. The return value of the invoked method. - is returned. For more information about the IADs interface, see the [IADs](/windows/win32/api/iads/nn-iads-iads) article. - + ]]> The native method threw a exception. @@ -923,11 +923,11 @@ Console::WriteLine("The Native GUID of the ADS object: {0}", Gets a property from the native Active Directory Domain Services object. An object that represents the requested property. - property should be used to access the properties of the object. - + property should be used to access the properties of the object. + ]]> @@ -978,11 +978,11 @@ Console::WriteLine("The Native GUID of the ADS object: {0}", The Active Directory Domain Services object to set. Sets a property on the native Active Directory Domain Services object. - property should be used to access the properties of the object. - + property should be used to access the properties of the object. + ]]> @@ -1023,11 +1023,11 @@ Console::WriteLine("The Native GUID of the ADS object: {0}", The parent to which you want to move this entry. Moves this object to the specified parent. - is `true`, call the method on the new object to make the move permanent. - + is `true`, call the method on the new object to make the move permanent. + ]]> The specified is not a container. @@ -1071,11 +1071,11 @@ Console::WriteLine("The Native GUID of the ADS object: {0}", The new name of this entry. Moves this object to the specified parent and changes its name to the specified value. - is `true`, call on the new object to make the move permanent. - + is `true`, call on the new object to make the move permanent. + ]]> The specified is not a container. @@ -1120,62 +1120,62 @@ Console::WriteLine("The Native GUID of the ADS object: {0}", Gets the name of the object as named with the underlying directory service. The name of the object as named with the underlying directory service. - , distinguishes this entry from its siblings and must be unique among its siblings in each container. - - - -## Examples - The following example creates a for the node in the Active Directory Domain Services. It then displays the and properties of its child nodes. - -```vb -Dim myADSPath As String = "LDAP://onecity/CN=Users,DC=onecity, - _DC=corp,DC=fabrikam,DC=com" -Dim myDirectoryEntry As New DirectoryEntry(myADSPath) - -Console.WriteLine("DirectoryEntry Name :" + myDirectoryEntry.Name) -Console.WriteLine(ControlChars.NewLine _ - + "The child entries for this node in the Active Directory Domain Services hierarchy") - -Dim myDirectoryEntryChild As DirectoryEntry -For Each myDirectoryEntryChild In myDirectoryEntry.Children - Console.WriteLine(myDirectoryEntryChild.Path) -Next myDirectoryEntryChild -``` - -```csharp -String myADSPath = "LDAP://onecity/CN=Users, - DC=onecity,DC=corp,DC=fabrikam,DC=com"; -DirectoryEntry myDirectoryEntry=new DirectoryEntry(myADSPath); - -Console.WriteLine("DirectoryEntry Name :"+ myDirectoryEntry.Name); -Console.WriteLine("\nThe child entries for this node "+ - "in the Active Directory Domain Services hierarchy"); - -foreach(DirectoryEntry myDirectoryEntryChild in - myDirectoryEntry.Children) -{ - Console.WriteLine(myDirectoryEntryChild.Path); -} -``` - + , distinguishes this entry from its siblings and must be unique among its siblings in each container. + + + +## Examples + The following example creates a for the node in the Active Directory Domain Services. It then displays the and properties of its child nodes. + +```vb +Dim myADSPath As String = "LDAP://onecity/CN=Users,DC=onecity, + _DC=corp,DC=fabrikam,DC=com" +Dim myDirectoryEntry As New DirectoryEntry(myADSPath) + +Console.WriteLine("DirectoryEntry Name :" + myDirectoryEntry.Name) +Console.WriteLine(ControlChars.NewLine _ + + "The child entries for this node in the Active Directory Domain Services hierarchy") + +Dim myDirectoryEntryChild As DirectoryEntry +For Each myDirectoryEntryChild In myDirectoryEntry.Children + Console.WriteLine(myDirectoryEntryChild.Path) +Next myDirectoryEntryChild +``` + +```csharp +String myADSPath = "LDAP://onecity/CN=Users, + DC=onecity,DC=corp,DC=fabrikam,DC=com"; +DirectoryEntry myDirectoryEntry=new DirectoryEntry(myADSPath); + +Console.WriteLine("DirectoryEntry Name :"+ myDirectoryEntry.Name); +Console.WriteLine("\nThe child entries for this node "+ + "in the Active Directory Domain Services hierarchy"); + +foreach(DirectoryEntry myDirectoryEntryChild in + myDirectoryEntry.Children) +{ + Console.WriteLine(myDirectoryEntryChild.Path); +} +``` + ```cpp -String^ myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; -DirectoryEntry^ myDirectoryEntry = gcnew DirectoryEntry(myADSPath); - -Console::WriteLine("DirectoryEntry Name : {0}", myDirectoryEntry->Name); -Console::WriteLine("\nThe child entries for this node in the Active Directory Domain Services hierarchy"); - -Collections::IEnumerator^ myEnumerator = myDirectoryEntry->Children->GetEnumerator(); -while (myEnumerator->MoveNext()) -{ - DirectoryEntry^ myDirectoryEntryChild = safe_cast(myEnumerator->Current); - Console::WriteLine(myDirectoryEntryChild->Path); -} -``` - +String^ myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; +DirectoryEntry^ myDirectoryEntry = gcnew DirectoryEntry(myADSPath); + +Console::WriteLine("DirectoryEntry Name : {0}", myDirectoryEntry->Name); +Console::WriteLine("\nThe child entries for this node in the Active Directory Domain Services hierarchy"); + +Collections::IEnumerator^ myEnumerator = myDirectoryEntry->Children->GetEnumerator(); +while (myEnumerator->MoveNext()) +{ + DirectoryEntry^ myDirectoryEntryChild = safe_cast(myEnumerator->Current); + Console::WriteLine(myDirectoryEntryChild->Path); +} +``` + ]]> @@ -1217,52 +1217,52 @@ while (myEnumerator->MoveNext()) Gets the GUID of the , as returned from the provider. A structure that represents the GUID of the , as returned from the provider. - property when binding an object in Active Directory Domain Services. - + property when binding an object in Active Directory Domain Services. + > [!NOTE] -> The Lightweight Directory Access Protocol (LDAP) provider returns the globally unique identifier of a in a different format than the Internet Information Services (IIS), Novell NetWare Directory Server (NDS), and WinNT providers. - - - -## Examples - The following example demonstrates the and properties of the class. This example gets the user-specified and displays its and properties. - -```vb -Dim myADSPath As [String] = "LDAP://onecity/CN=Users, - DC=onecity,DC=corp,DC=fabrikam,DC=com" -Dim myDirectoryEntry As New DirectoryEntry(myADSPath) - -' Display the Guid and NativeGuid. -Console.WriteLine("The GUID of the ADS object:" + myDirectoryEntry.Guid.ToString) -Console.WriteLine("The Native GUID of the ADS" + "object:" + - myDirectoryEntry.NativeGuid) -``` - -```csharp -String myADSPath = "LDAP://onecity/CN=Users, - DC=onecity,DC=corp,DC=fabrikam,DC=com"; -DirectoryEntry myDirectoryEntry=new DirectoryEntry(myADSPath); - -// Display the Guid and NativeGuid. -Console.WriteLine("The GUID of the ADS object:"+ - myDirectoryEntry.Guid); -Console.WriteLine("The Native GUID of the ADS"+ - "object:"+myDirectoryEntry.NativeGuid); -``` - +> The Lightweight Directory Access Protocol (LDAP) provider returns the globally unique identifier of a in a different format than the Internet Information Services (IIS), Novell NetWare Directory Server (NDS), and WinNT providers. + + + +## Examples + The following example demonstrates the and properties of the class. This example gets the user-specified and displays its and properties. + +```vb +Dim myADSPath As [String] = "LDAP://onecity/CN=Users, + DC=onecity,DC=corp,DC=fabrikam,DC=com" +Dim myDirectoryEntry As New DirectoryEntry(myADSPath) + +' Display the Guid and NativeGuid. +Console.WriteLine("The GUID of the ADS object:" + myDirectoryEntry.Guid.ToString) +Console.WriteLine("The Native GUID of the ADS" + "object:" + + myDirectoryEntry.NativeGuid) +``` + +```csharp +String myADSPath = "LDAP://onecity/CN=Users, + DC=onecity,DC=corp,DC=fabrikam,DC=com"; +DirectoryEntry myDirectoryEntry=new DirectoryEntry(myADSPath); + +// Display the Guid and NativeGuid. +Console.WriteLine("The GUID of the ADS object:"+ + myDirectoryEntry.Guid); +Console.WriteLine("The Native GUID of the ADS"+ + "object:"+myDirectoryEntry.NativeGuid); +``` + ```cpp -String^ myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; -DirectoryEntry^ myDirectoryEntry = gcnew DirectoryEntry(myADSPath); - -// Display the Guid and NativeGuid. -Console::WriteLine("The GUID of the ADS object: {0}", myDirectoryEntry->Guid)); -Console::WriteLine("The Native GUID of the ADS object: {0}", - myDirectoryEntry->NativeGuid); -``` - +String^ myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; +DirectoryEntry^ myDirectoryEntry = gcnew DirectoryEntry(myADSPath); + +// Display the Guid and NativeGuid. +Console::WriteLine("The GUID of the ADS object: {0}", myDirectoryEntry->Guid)); +Console::WriteLine("The Native GUID of the ADS object: {0}", + myDirectoryEntry->NativeGuid); +``` + ]]> @@ -1305,13 +1305,13 @@ Console::WriteLine("The Native GUID of the ADS object: {0}", Gets the native Active Directory Service Interfaces (ADSI) object. The native ADSI object. - classes alone. To use it, you need to import one of the COM interfaces from the IADs family, then cast this property to that interface. - + + This object is for advanced scenarios that cannot be accomplished with the classes alone. To use it, you need to import one of the COM interfaces from the IADs family, then cast this property to that interface. + ]]> @@ -1443,33 +1443,33 @@ Console::WriteLine("The Native GUID of the ADS object: {0}", Gets this entry's parent in the Active Directory Domain Services hierarchy. A object that represents the parent of this entry. - and displays the and of the result. - -```vb -Dim myADSPath As String = _ - "LDAP://onecity/CN=user,CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com" -Dim myDirectoryEntry As New DirectoryEntry(myADSPath, UserName, SecurelyStoredPassword) - -Console.WriteLine("Parent is :" + myDirectoryEntry.Parent.Path) -``` - -```csharp -String myADSPath = "LDAP://onecity/CN=user,CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; -DirectoryEntry myDirectoryEntry=new DirectoryEntry(myADSPath, UserName, SecurelyStoredPassword); - -Console.WriteLine("Parent is :"+myDirectoryEntry.Parent.Path); -``` - -```cpp -String^ myADSPath = "LDAP://onecity/CN=user,CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; -DirectoryEntry^ myDirectoryEntry = gcnew DirectoryEntry(myADSPath, UserName, SecurelyStoredPassword); - -Console::WriteLine("Parent is :{0}", myDirectoryEntry->Parent->Path); -``` - + and displays the and of the result. + +```vb +Dim myADSPath As String = _ + "LDAP://onecity/CN=user,CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com" +Dim myDirectoryEntry As New DirectoryEntry(myADSPath, UserName, SecurelyStoredPassword) + +Console.WriteLine("Parent is :" + myDirectoryEntry.Parent.Path) +``` + +```csharp +String myADSPath = "LDAP://onecity/CN=user,CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; +DirectoryEntry myDirectoryEntry=new DirectoryEntry(myADSPath, UserName, SecurelyStoredPassword); + +Console.WriteLine("Parent is :"+myDirectoryEntry.Parent.Path); +``` + +```cpp +String^ myADSPath = "LDAP://onecity/CN=user,CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; +DirectoryEntry^ myDirectoryEntry = gcnew DirectoryEntry(myADSPath, UserName, SecurelyStoredPassword); + +Console::WriteLine("Parent is :{0}", myDirectoryEntry->Parent->Path); +``` + ]]> @@ -1523,67 +1523,67 @@ Console::WriteLine("Parent is :{0}", myDirectoryEntry->Parent->Path); Sets the password to use when authenticating the client. The password to use when authenticating the client. - and properties to specify alternate credentials with which to access the information in Active Directory Domain Services. Any other objects retrieved from this instance (for example, through ) are automatically created with the same alternate credentials. - - - -## Examples - The following example demonstrates the and properties of the class. This example gets the user-specified and the of all its . - -```vb -Dim myADSPath As String = _ - "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com" - -' Create an Instance of DirectoryEntry. -Dim myDirectoryEntry As New DirectoryEntry(myADSPath) -myDirectoryEntry.Username = UserName -myDirectoryEntry.Password = SecurelyStoredPassword - -' Get the Child ADS objects. -Console.WriteLine("The Child ADS objects are:") -Dim myChildDirectoryEntry As DirectoryEntry -For Each myChildDirectoryEntry In myDirectoryEntry.Children - Console.WriteLine(myChildDirectoryEntry.Path) -Next myChildDirectoryEntry -``` - -```csharp -String myADSPath = "LDAP://onecity/CN=Users, - DC=onecity,DC=corp,DC=fabrikam,DC=com"; - -// Create an Instance of DirectoryEntry. -DirectoryEntry myDirectoryEntry = new DirectoryEntry(myADSPath); -myDirectoryEntry.Username = UserName; -myDirectoryEntry.Password = SecurelyStoredPassword; - -// Get the Child ADS objects. -Console.WriteLine("The Child ADS objects are:"); -foreach(DirectoryEntry myChildDirectoryEntry in myDirectoryEntry.Children) - Console.WriteLine(myChildDirectoryEntry.Path); -``` - + and properties to specify alternate credentials with which to access the information in Active Directory Domain Services. Any other objects retrieved from this instance (for example, through ) are automatically created with the same alternate credentials. + + + +## Examples + The following example demonstrates the and properties of the class. This example gets the user-specified and the of all its . + +```vb +Dim myADSPath As String = _ + "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com" + +' Create an Instance of DirectoryEntry. +Dim myDirectoryEntry As New DirectoryEntry(myADSPath) +myDirectoryEntry.Username = UserName +myDirectoryEntry.Password = SecurelyStoredPassword + +' Get the Child ADS objects. +Console.WriteLine("The Child ADS objects are:") +Dim myChildDirectoryEntry As DirectoryEntry +For Each myChildDirectoryEntry In myDirectoryEntry.Children + Console.WriteLine(myChildDirectoryEntry.Path) +Next myChildDirectoryEntry +``` + +```csharp +String myADSPath = "LDAP://onecity/CN=Users, + DC=onecity,DC=corp,DC=fabrikam,DC=com"; + +// Create an Instance of DirectoryEntry. +DirectoryEntry myDirectoryEntry = new DirectoryEntry(myADSPath); +myDirectoryEntry.Username = UserName; +myDirectoryEntry.Password = SecurelyStoredPassword; + +// Get the Child ADS objects. +Console.WriteLine("The Child ADS objects are:"); +foreach(DirectoryEntry myChildDirectoryEntry in myDirectoryEntry.Children) + Console.WriteLine(myChildDirectoryEntry.Path); +``` + ```cpp -String^ myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; - -// Create an Instance of DirectoryEntry. -DirectoryEntry^ myDirectoryEntry = gcnew DirectoryEntry(myADSPath); -myDirectoryEntry->Username = UserName; -myDirectoryEntry->Password = SecurelyStoredPassword; - -// Get the Child ADS objects. -Console::WriteLine("The Child ADS objects are:"); -Collections::IEnumerator^ myEnum = myDirectoryEntry->Children->GetEnumerator(); -while (myEnum->MoveNext()) -{ - DirectoryEntry^ myChildDirectoryEntry = safe_cast - (myEnum->Current); - Console::WriteLine(myChildDirectoryEntry->Path); -} -``` - +String^ myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; + +// Create an Instance of DirectoryEntry. +DirectoryEntry^ myDirectoryEntry = gcnew DirectoryEntry(myADSPath); +myDirectoryEntry->Username = UserName; +myDirectoryEntry->Password = SecurelyStoredPassword; + +// Get the Child ADS objects. +Console::WriteLine("The Child ADS objects are:"); +Collections::IEnumerator^ myEnum = myDirectoryEntry->Children->GetEnumerator(); +while (myEnum->MoveNext()) +{ + DirectoryEntry^ myChildDirectoryEntry = safe_cast + (myEnum->Current); + Console::WriteLine(myChildDirectoryEntry->Path); +} +``` + ]]> @@ -1642,51 +1642,51 @@ while (myEnum->MoveNext()) Gets or sets the path for this . The path of this object. The default is an empty string (""). - property uniquely identifies this entry in a networked environment. This entry can always be retrieved using this . - - Setting the retrieves a new entry from the directory store; it does not change the path of the currently bound entry. - - The classes associated with the component can be used with any of the Active Directory Domain Services service providers. Some of the current providers are Internet Information Services (IIS), Lightweight Directory Access Protocol (LDAP), Novell NetWare Directory Service (NDS), and WinNT. - + property uniquely identifies this entry in a networked environment. This entry can always be retrieved using this . + + Setting the retrieves a new entry from the directory store; it does not change the path of the currently bound entry. + + The classes associated with the component can be used with any of the Active Directory Domain Services service providers. Some of the current providers are Internet Information Services (IIS), Lightweight Directory Access Protocol (LDAP), Novell NetWare Directory Service (NDS), and WinNT. + > [!NOTE] -> The section of the that identifies the provider (precedes "://") is case-sensitive. For example, "LDAP://" or "WinNT://". - - The syntax for the property varies according to the provider. Some common scenarios are: - - WinNT - -- Connect to a group on a computer. For example, "WinNT://**\/\/\**". If you are connecting to a local computer, "WinNT://**\/\**". - -- Connect to a user on a computer. For example, "WinNT://**\/\/\**". If you are connecting to a local computer, "WinNT://**\/\**". - -- Connect to services on a computer. For example, "WinNT://**\/\/\**". If you are connecting to a local computer, "WinNT://**\/\**". - -- Discover all domains on the network. For example, "WinNT:" The domains can be found by enumerating the children of this entry. - - LDAP - -- Connect to a group in a domain. For example, "LDAP://CN=\, CN =\, DC=\, DC=\,...". - -- Connect to a user in a domain. For example, "LDAP://CN=\, CN=\, DC=\, DC=\,...". - -- Connect to computers in a domain. For example, "LDAP://CN=\, CN=\, DC=\, DC=\,...". - - IIS - -- Connect to a Web directory. For example, "IIS://LocalHost/W3SVC/1/ROOT/\". - - To bind to the current domain using LDAP, use the path "LDAP://RootDSE", then get the default naming context and rebind the entry. For example: - -```csharp -String str = ent.Properties["defaultNamingContext"][0]; -DirectoryEntry domain = new DirectoryEntry("LDAP://" + str); -``` - - For more information, see the documentation for your provider and the [Using Active Directory Service Interfaces](/windows/desktop/adsi/using-adsi) article. - +> The section of the that identifies the provider (precedes "://") is case-sensitive. For example, "LDAP://" or "WinNT://". + + The syntax for the property varies according to the provider. Some common scenarios are: + + WinNT + +- Connect to a group on a computer. For example, "WinNT://**\/\/\**". If you are connecting to a local computer, "WinNT://**\/\**". + +- Connect to a user on a computer. For example, "WinNT://**\/\/\**". If you are connecting to a local computer, "WinNT://**\/\**". + +- Connect to services on a computer. For example, "WinNT://**\/\/\**". If you are connecting to a local computer, "WinNT://**\/\**". + +- Discover all domains on the network. For example, "WinNT:" The domains can be found by enumerating the children of this entry. + + LDAP + +- Connect to a group in a domain. For example, "LDAP://CN=\, CN =\, DC=\, DC=\,...". + +- Connect to a user in a domain. For example, "LDAP://CN=\, CN=\, DC=\, DC=\,...". + +- Connect to computers in a domain. For example, "LDAP://CN=\, CN=\, DC=\, DC=\,...". + + IIS + +- Connect to a Web directory. For example, "IIS://LocalHost/W3SVC/1/ROOT/\". + + To bind to the current domain using LDAP, use the path "LDAP://RootDSE", then get the default naming context and rebind the entry. For example: + +```csharp +String str = ent.Properties["defaultNamingContext"][0]; +DirectoryEntry domain = new DirectoryEntry("LDAP://" + str); +``` + + For more information, see the documentation for your provider and the [Using Active Directory Service Interfaces](/windows/desktop/adsi/using-adsi) article. + ]]> @@ -1728,13 +1728,13 @@ DirectoryEntry domain = new DirectoryEntry("LDAP://" + str); Gets the Active Directory Domain Services properties for this object. A object that contains the properties that are set on this entry. - calls the ADSI interface [IADs::Get](/windows/win32/api/iads/nf-iads-iads-get) method to retrieve the value from the cache. If the underling cache has not been loaded, [IADs::Get](/windows/win32/api/iads/nf-iads-iads-get) implicitly calls [IADs::GetInfo](/windows/win32/api/iads/nf-iads-iads-getinfo). This method loads the values of the supported properties that have not been set in the cache from the underlying directory store. Subsequent calls to retrieves the property values in the cache only. To control property cache loading, call . - - **Note** The property is not supported for use with the Active Directory Client Extension (DSClient) for Windows NT 4.0. - + calls the ADSI interface [IADs::Get](/windows/win32/api/iads/nf-iads-iads-get) method to retrieve the value from the cache. If the underling cache has not been loaded, [IADs::Get](/windows/win32/api/iads/nf-iads-iads-get) implicitly calls [IADs::GetInfo](/windows/win32/api/iads/nf-iads-iads-getinfo). This method loads the values of the supported properties that have not been set in the cache from the underlying directory store. Subsequent calls to retrieves the property values in the cache only. To control property cache loading, call . + + **Note** The property is not supported for use with the Active Directory Client Extension (DSClient) for Windows NT 4.0. + ]]> @@ -1778,13 +1778,13 @@ DirectoryEntry domain = new DirectoryEntry("LDAP://" + str); Loads the property values for this object into the property cache. - [!CAUTION] -> Any uncommitted changes to the property cache will be lost. Use the method to persist changes to the directory store. - +> Any uncommitted changes to the property cache will be lost. Use the method to persist changes to the directory store. + ]]> @@ -1816,13 +1816,13 @@ DirectoryEntry domain = new DirectoryEntry("LDAP://" + str); An array of the specified properties. Loads the values of the specified properties into the property cache. - [!CAUTION] -> Any uncommitted changes to the property cache will be lost. Use to persist changes to the directory store. - +> Any uncommitted changes to the property cache will be lost. Use to persist changes to the directory store. + ]]> @@ -1861,15 +1861,15 @@ DirectoryEntry domain = new DirectoryEntry("LDAP://" + str); The new name of the entry. Changes the name of this object. - [!NOTE] -> This will also affect the path that is used to refer to this entry. - - If is `true`, be sure to call the method on the new object to make the move permanent. - +> This will also affect the path that is used to refer to this entry. + + If is `true`, be sure to call the method on the new object to make the move permanent. + ]]> @@ -1913,79 +1913,79 @@ DirectoryEntry domain = new DirectoryEntry("LDAP://" + str); Gets the name of the schema class for this object. The name of the schema class for this object. - property of the property. - - A object's schema defines its properties and methods. - - - -## Examples - The following example demonstrates the and properties of the class. This example gets the user-specified and gets all of its children if the is a container object. The is a container object if the of that object is "container". - -```vb -Dim myADSPath As String = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com" - -' Creates an Instance of DirectoryEntry. -Dim myDirectoryEntry As New DirectoryEntry(myADSPath, UserName, SecurelyStoredPassword) - -' Display the 'SchemaClassName'. -Console.WriteLine("Schema class name:" + myDirectoryEntry.SchemaClassName) - -' Gets the SchemaEntry of the ADS object. -Dim mySchemaEntry As DirectoryEntry = myDirectoryEntry.SchemaEntry - -If String.Compare(mySchemaEntry.Name, "container") = 0 Then - Dim myChildDirectoryEntry As DirectoryEntry - For Each myChildDirectoryEntry In myDirectoryEntry.Children - Console.WriteLine(myChildDirectoryEntry.Path) - Next -``` - -```csharp -String myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; - -// Creates an Instance of DirectoryEntry. -DirectoryEntry myDirectoryEntry=new DirectoryEntry(myADSPath, UserName, SecurelyStoredPassword); - -// Display the 'SchemaClassName'. -Console.WriteLine("Schema class name:" + myDirectoryEntry.SchemaClassName); - -// Gets the SchemaEntry of the ADS object. -DirectoryEntry mySchemaEntry = myDirectoryEntry.SchemaEntry; - -if (string.Compare(mySchemaEntry.Name, "container") == 0) -{ - foreach(DirectoryEntry myChildDirectoryEntry in myDirectoryEntry.Children) - Console.WriteLine(myChildDirectoryEntry.Path); -} -``` - + property of the property. + + A object's schema defines its properties and methods. + + + +## Examples + The following example demonstrates the and properties of the class. This example gets the user-specified and gets all of its children if the is a container object. The is a container object if the of that object is "container". + +```vb +Dim myADSPath As String = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com" + +' Creates an Instance of DirectoryEntry. +Dim myDirectoryEntry As New DirectoryEntry(myADSPath, UserName, SecurelyStoredPassword) + +' Display the 'SchemaClassName'. +Console.WriteLine("Schema class name:" + myDirectoryEntry.SchemaClassName) + +' Gets the SchemaEntry of the ADS object. +Dim mySchemaEntry As DirectoryEntry = myDirectoryEntry.SchemaEntry + +If String.Compare(mySchemaEntry.Name, "container") = 0 Then + Dim myChildDirectoryEntry As DirectoryEntry + For Each myChildDirectoryEntry In myDirectoryEntry.Children + Console.WriteLine(myChildDirectoryEntry.Path) + Next +``` + +```csharp +String myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; + +// Creates an Instance of DirectoryEntry. +DirectoryEntry myDirectoryEntry=new DirectoryEntry(myADSPath, UserName, SecurelyStoredPassword); + +// Display the 'SchemaClassName'. +Console.WriteLine("Schema class name:" + myDirectoryEntry.SchemaClassName); + +// Gets the SchemaEntry of the ADS object. +DirectoryEntry mySchemaEntry = myDirectoryEntry.SchemaEntry; + +if (string.Compare(mySchemaEntry.Name, "container") == 0) +{ + foreach(DirectoryEntry myChildDirectoryEntry in myDirectoryEntry.Children) + Console.WriteLine(myChildDirectoryEntry.Path); +} +``` + ```cpp -String^ myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; - -// Creates an Instance of DirectoryEntry. -DirectoryEntry^ myDirectoryEntry = gcnew DirectoryEntry(myADSPath, UserName, SecurelyStoredPassword); - -// Display the 'SchemaClassName'. -Console::WriteLine("Schema class name:{0}", myDirectoryEntry->SchemaClassName); - -// Gets the SchemaEntry of the ADS Object. -DirectoryEntry^ mySchemaEntry = myDirectoryEntry->SchemaEntry; - -if (!String::Compare(mySchemaEntry->Name, "container")) -{ - Collections::IEnumerator^ myEnum = myDirectoryEntry->Children->GetEnumerator(); - while (myEnum->MoveNext()) - { - DirectoryEntry^ myChildDirectoryEntry = safe_cast(myEnum->Current); - Console::WriteLine(myChildDirectoryEntry->Path); - } -} -``` - +String^ myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; + +// Creates an Instance of DirectoryEntry. +DirectoryEntry^ myDirectoryEntry = gcnew DirectoryEntry(myADSPath, UserName, SecurelyStoredPassword); + +// Display the 'SchemaClassName'. +Console::WriteLine("Schema class name:{0}", myDirectoryEntry->SchemaClassName); + +// Gets the SchemaEntry of the ADS Object. +DirectoryEntry^ mySchemaEntry = myDirectoryEntry->SchemaEntry; + +if (!String::Compare(mySchemaEntry->Name, "container")) +{ + Collections::IEnumerator^ myEnum = myDirectoryEntry->Children->GetEnumerator(); + while (myEnum->MoveNext()) + { + DirectoryEntry^ myChildDirectoryEntry = safe_cast(myEnum->Current); + Console::WriteLine(myChildDirectoryEntry->Path); + } +} +``` + ]]> @@ -2028,80 +2028,80 @@ if (!String::Compare(mySchemaEntry->Name, "container")) Gets the schema object for this entry. A object that represents the schema class for this entry. - and properties of the class. This example gets the user-specified object and gets all of its children if the object is a container object. The is a container object if the of that object is "container". - -```vb -Dim myADSPath As String = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com" - -' Creates an Instance of DirectoryEntry. -Dim myDirectoryEntry As New DirectoryEntry(myADSPath, UserName, SecurelyStoredPassword) - -' Display the 'SchemaClassName'. -Console.WriteLine("Schema class name:" + myDirectoryEntry.SchemaClassName) - -' Gets the SchemaEntry of the ADS object. -Dim mySchemaEntry As DirectoryEntry = myDirectoryEntry.SchemaEntry - -If String.Compare(mySchemaEntry.Name, "container") = 0 Then - Dim myChildDirectoryEntry As DirectoryEntry - For Each myChildDirectoryEntry In myDirectoryEntry.Children - Console.WriteLine(myChildDirectoryEntry.Path) - Next -``` - -```csharp -String myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; - -// Creates an Instance of DirectoryEntry. -DirectoryEntry myDirectoryEntry=new DirectoryEntry(myADSPath, UserName, SecurelyStoredPassword); - -// Display the 'SchemaClassName'. -Console.WriteLine("Schema class name:"+myDirectoryEntry.SchemaClassName); - -// Gets the SchemaEntry of the ADS object. -DirectoryEntry mySchemaEntry = myDirectoryEntry.SchemaEntry; - -if (string.Compare(mySchemaEntry.Name,"container") == 0) -{ - foreach(DirectoryEntry myChildDirectoryEntry in myDirectoryEntry.Children) - Console.WriteLine(myChildDirectoryEntry.Path); -} - -``` - + and properties of the class. This example gets the user-specified object and gets all of its children if the object is a container object. The is a container object if the of that object is "container". + +```vb +Dim myADSPath As String = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com" + +' Creates an Instance of DirectoryEntry. +Dim myDirectoryEntry As New DirectoryEntry(myADSPath, UserName, SecurelyStoredPassword) + +' Display the 'SchemaClassName'. +Console.WriteLine("Schema class name:" + myDirectoryEntry.SchemaClassName) + +' Gets the SchemaEntry of the ADS object. +Dim mySchemaEntry As DirectoryEntry = myDirectoryEntry.SchemaEntry + +If String.Compare(mySchemaEntry.Name, "container") = 0 Then + Dim myChildDirectoryEntry As DirectoryEntry + For Each myChildDirectoryEntry In myDirectoryEntry.Children + Console.WriteLine(myChildDirectoryEntry.Path) + Next +``` + +```csharp +String myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; + +// Creates an Instance of DirectoryEntry. +DirectoryEntry myDirectoryEntry=new DirectoryEntry(myADSPath, UserName, SecurelyStoredPassword); + +// Display the 'SchemaClassName'. +Console.WriteLine("Schema class name:"+myDirectoryEntry.SchemaClassName); + +// Gets the SchemaEntry of the ADS object. +DirectoryEntry mySchemaEntry = myDirectoryEntry.SchemaEntry; + +if (string.Compare(mySchemaEntry.Name,"container") == 0) +{ + foreach(DirectoryEntry myChildDirectoryEntry in myDirectoryEntry.Children) + Console.WriteLine(myChildDirectoryEntry.Path); +} + +``` + ```cpp -String^ myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; - -// Creates an Instance of DirectoryEntry. -DirectoryEntry^ myDirectoryEntry = gcnew DirectoryEntry(myADSPath, UserName, SecurelyStoredPassword); - -// Display the 'SchemaClassName'. -Console::WriteLine("Schema class name:{0}", myDirectoryEntry->SchemaClassName); - -// Gets the SchemaEntry of the ADS Object*. -DirectoryEntry^ mySchemaEntry = myDirectoryEntry->SchemaEntry; - -if (!String::Compare(mySchemaEntry->Name, S"container")) -{ - Collections::IEnumerator^ myEnum = myDirectoryEntry->Children->GetEnumerator(); - while (myEnum->MoveNext()) - { - DirectoryEntry^ myChildDirectoryEntry = safe_cast(myEnum->Current); - Console::WriteLine(myChildDirectoryEntry->Path); - } -} -``` - +String^ myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; + +// Creates an Instance of DirectoryEntry. +DirectoryEntry^ myDirectoryEntry = gcnew DirectoryEntry(myADSPath, UserName, SecurelyStoredPassword); + +// Display the 'SchemaClassName'. +Console::WriteLine("Schema class name:{0}", myDirectoryEntry->SchemaClassName); + +// Gets the SchemaEntry of the ADS Object*. +DirectoryEntry^ mySchemaEntry = myDirectoryEntry->SchemaEntry; + +if (!String::Compare(mySchemaEntry->Name, S"container")) +{ + Collections::IEnumerator^ myEnum = myDirectoryEntry->Children->GetEnumerator(); + while (myEnum->MoveNext()) + { + DirectoryEntry^ myChildDirectoryEntry = safe_cast(myEnum->Current); + Console::WriteLine(myChildDirectoryEntry->Path); + } +} +``` + ]]> @@ -2141,19 +2141,19 @@ if (!String::Compare(mySchemaEntry->Name, S"container")) if the cache should not be committed after each operation; otherwise, . The default is . - property is `true`, access to the object's properties is faster. Setting this to `false` will cause the cache to be committed after each operation. - - If the property is `true` and you want to commit cached changes, call the method. To update values in the cache after changes to the directory are made, call the method. - + property is `true`, access to the object's properties is faster. Setting this to `false` will cause the cache to be committed after each operation. + + If the property is `true` and you want to commit cached changes, call the method. To update values in the cache after changes to the directory are made, call the method. + > [!CAUTION] -> If you call before calling , any uncommitted changes to the property cache will be lost. - +> If you call before calling , any uncommitted changes to the property cache will be lost. + > [!NOTE] -> The Internet Information Services (IIS) provider does not support committing the cache after each operation. - +> The Internet Information Services (IIS) provider does not support committing the cache after each operation. + ]]> @@ -2222,65 +2222,65 @@ if (!String::Compare(mySchemaEntry->Name, S"container")) Gets or sets the user name to use when authenticating the client. The user name to use when authenticating the client. - and in order to specify alternate credentials with which to access the information in Active Directory Domain Services. Any other objects retrieved from this instance (for example, through ) are automatically created with the same alternate credentials. - - - -## Examples - The following example demonstrates the and properties of the class. This example gets the user-specified and the of all its . - -```vb -Dim myADSPath As String = _ - "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com" - -' Create an Instance of DirectoryEntry. -Dim myDirectoryEntry As New DirectoryEntry(myADSPath) -myDirectoryEntry.Username = UserName -myDirectoryEntry.Password = SecurelyStoredPassword - -' Get the Child ADS objects. -Console.WriteLine("The Child ADS objects are:") -Dim myChildDirectoryEntry As DirectoryEntry -For Each myChildDirectoryEntry In myDirectoryEntry.Children - Console.WriteLine(myChildDirectoryEntry.Path) -Next myChildDirectoryEntry -``` - -```csharp -String myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; - -// Create an Instance of DirectoryEntry. -DirectoryEntry myDirectoryEntry = new DirectoryEntry(myADSPath); -myDirectoryEntry.Username = UserName; -myDirectoryEntry.Password = SecurelyStoredPassword; - -// Get the Child ADS objects. -Console.WriteLine("The Child ADS objects are:"); -foreach(DirectoryEntry myChildDirectoryEntry in myDirectoryEntry.Children) - Console.WriteLine(myChildDirectoryEntry.Path); -``` - + and in order to specify alternate credentials with which to access the information in Active Directory Domain Services. Any other objects retrieved from this instance (for example, through ) are automatically created with the same alternate credentials. + + + +## Examples + The following example demonstrates the and properties of the class. This example gets the user-specified and the of all its . + +```vb +Dim myADSPath As String = _ + "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com" + +' Create an Instance of DirectoryEntry. +Dim myDirectoryEntry As New DirectoryEntry(myADSPath) +myDirectoryEntry.Username = UserName +myDirectoryEntry.Password = SecurelyStoredPassword + +' Get the Child ADS objects. +Console.WriteLine("The Child ADS objects are:") +Dim myChildDirectoryEntry As DirectoryEntry +For Each myChildDirectoryEntry In myDirectoryEntry.Children + Console.WriteLine(myChildDirectoryEntry.Path) +Next myChildDirectoryEntry +``` + +```csharp +String myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; + +// Create an Instance of DirectoryEntry. +DirectoryEntry myDirectoryEntry = new DirectoryEntry(myADSPath); +myDirectoryEntry.Username = UserName; +myDirectoryEntry.Password = SecurelyStoredPassword; + +// Get the Child ADS objects. +Console.WriteLine("The Child ADS objects are:"); +foreach(DirectoryEntry myChildDirectoryEntry in myDirectoryEntry.Children) + Console.WriteLine(myChildDirectoryEntry.Path); +``` + ```cpp -String^ myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; - -// Create an Instance of DirectoryEntry. -DirectoryEntry^ myDirectoryEntry = new DirectoryEntry(myADSPath); -myDirectoryEntry->Username = UserName; -myDirectoryEntry->Password = SecurelyStoredPassword; - -// Get the Child ADS objects. -Console::WriteLine("The Child ADS objects are:"); -Collections::IEnumerator^ myEnum = myDirectoryEntry->Children->GetEnumerator(); -while (myEnum->MoveNext()) -{ - DirectoryEntry^ myChildDirectoryEntry = safe_cast(myEnum->Current); - Console::WriteLine(myChildDirectoryEntry->Path); -} -``` - +String^ myADSPath = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com"; + +// Create an Instance of DirectoryEntry. +DirectoryEntry^ myDirectoryEntry = new DirectoryEntry(myADSPath); +myDirectoryEntry->Username = UserName; +myDirectoryEntry->Password = SecurelyStoredPassword; + +// Get the Child ADS objects. +Console::WriteLine("The Child ADS objects are:"); +Collections::IEnumerator^ myEnum = myDirectoryEntry->Children->GetEnumerator(); +while (myEnum->MoveNext()) +{ + DirectoryEntry^ myChildDirectoryEntry = safe_cast(myEnum->Current); + Console::WriteLine(myChildDirectoryEntry->Path); +} +``` + ]]> diff --git a/xml/System.DirectoryServices/SearchResultCollection.xml b/xml/System.DirectoryServices/SearchResultCollection.xml index afefd6f7c62..70e23514761 100644 --- a/xml/System.DirectoryServices/SearchResultCollection.xml +++ b/xml/System.DirectoryServices/SearchResultCollection.xml @@ -40,11 +40,11 @@ The class contains the instances that the Active Directory hierarchy returned during a query. - class cannot release all of its unmanaged resources when it is garbage collected. To prevent a memory leak, you must call the method when the object is no longer needed. - + class cannot release all of its unmanaged resources when it is garbage collected. To prevent a memory leak, you must call the method when the object is no longer needed. + ]]> @@ -172,13 +172,13 @@ Releases all resources that are used by the object. - method, it allows the resources that are used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - - The garbage collector does not release memory for a object. Therefore, an application must call the method explicitly to prevent a memory leak. - + method, it allows the resources that are used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + + The garbage collector does not release memory for a object. Therefore, an application must call the method explicitly to prevent a memory leak. + ]]> @@ -210,23 +210,23 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources that are used by the object and optionally releases the managed resources. - method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with the `disposing` parameter set to `false`. - - When the `disposing` parameter is `true`, this method releases all resources that are held by any managed objects that this references. - - The garbage collector does not release memory for a object. Therefore, you must call the method explicitly to prevent a memory leak. - - This method invokes the method of each object in the collection. - - For more information about and , see [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)). - + method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with the `disposing` parameter set to `false`. + + When the `disposing` parameter is `true`, this method releases all resources that are held by any managed objects that this references. + + The garbage collector does not release memory for a object. Therefore, you must call the method explicitly to prevent a memory leak. + + This method invokes the method of each object in the collection. + + For more information about and , see [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)). + ]]> - The method can be called multiple times by other objects. When overriding the method be careful not to reference objects that have been previously disposed of in an earlier call to the method. For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + The method can be called multiple times by other objects. When overriding the method be careful not to reference objects that have been previously disposed of in an earlier call to the method. For more information about how to implement , see Implementing a Dispose Method. @@ -308,13 +308,13 @@ Gets the handle that is returned by the IDirectorySearch::ExecuteSearch method that performs the actual search. For more information, see the IDirectorySearch::ExecuteSearch article. The ADS_SEARCH_HANDLE value that this collection uses. - that created this collection calls the `IDirectorySearch::ExecuteSearch` method, which makes the query results available to the object. For more information, see the [IDirectorySearch::ExecuteSearch](/windows/win32/api/iads/nf-iads-idirectorysearch-executesearch) article. - - Each time that a query is performed, a handle for the results of that query is associated with its object. This handle corresponds to the search handle in ADSI. This handle persists until you call the method on the object, so you must call to prevent a memory leak. The garbage collector does not free memory for this particular object. - + that created this collection calls the `IDirectorySearch::ExecuteSearch` method, which makes the query results available to the object. For more information, see the [IDirectorySearch::ExecuteSearch](/windows/win32/api/iads/nf-iads-idirectorysearch-executesearch) article. + + Each time that a query is performed, a handle for the results of that query is associated with its object. This handle corresponds to the search handle in ADSI. This handle persists until you call the method on the object, so you must call to prevent a memory leak. The garbage collector does not free memory for this particular object. + ]]> @@ -375,13 +375,13 @@ Gets the object that is located at a specified index in this collection. The object that is located at the specified index. - class. - - In JScript, you can use the default indexed properties defined by a type, but you cannot explicitly define your own. However, specifying the expando attribute on a class automatically provides a default indexed property whose type is Object and with an index type of . - + class. + + In JScript, you can use the default indexed properties defined by a type, but you cannot explicitly define your own. However, specifying the expando attribute on a class automatically provides a default indexed property whose type is Object and with an index type of . + ]]> @@ -447,10 +447,10 @@ is less than zero. - is multidimensional. - - -or- - + is multidimensional. + + -or- + The number of elements in the source is greater than the available space from to the end of the destination . The type of the source cannot be cast automatically to the type of the destination . @@ -481,37 +481,37 @@ if access to the is synchronized (thread safe); otherwise, . - returns an object, which can be used to synchronize access to the . - - Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. - - 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. - - - The following code example shows how to lock the collection using the during the entire enumeration: - -```csharp -ICollection myCollection = new ICollection(); - lock(myCollection.SyncRoot) { - foreach (Object item in myCollection) { - // Insert your code here. - } - } -``` - -```vb -Dim myCollection As New ICollection() - Dim item As Object - SyncLock myCollection.SyncRoot - For Each item In myCollection - ' Insert your code here. - Next item - End SyncLock -``` - + returns an object, which can be used to synchronize access to the . + + Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. + + 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. + + + The following code example shows how to lock the collection using the during the entire enumeration: + +```csharp +ICollection myCollection = new ICollection(); + lock(myCollection.SyncRoot) { + foreach (Object item in myCollection) { + // Insert your code here. + } + } +``` + +```vb +Dim myCollection As New ICollection() + Dim item As Object + SyncLock myCollection.SyncRoot + For Each item In myCollection + ' Insert your code here. + Next item + End SyncLock +``` + ]]> @@ -542,53 +542,53 @@ Dim myCollection As New ICollection() Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . - namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the 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 instance. - - In the absence of a `Synchronized` method on a collection, the expected usage for looks like this: - -```csharp -ICollection MyCollection =... - lock(MyCollection.SyncRoot) { - // Some operation on the collection, which is now thread safe. - } -``` - -```vb -Dim myCollection as New ICollection() - SyncLock myCollection.SyncRoot - ' Some operation on the collection, which is now thread safe. - End SyncLock -``` - - 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. - - - The following code example shows how to lock the collection using the during the entire enumeration: - -```csharp -ICollection myCollection = new ICollection(); - lock(myCollection.SyncRoot) { - foreach (Object item in myCollection) { - // Insert your code here. - } - } -``` - -```vb -Dim myCollection As New ICollection() - Dim item As Object - SyncLock myCollection.SyncRoot - For Each item In myCollection - ' Insert your code here. - Next item - End SyncLock -``` - + namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the 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 instance. + + In the absence of a `Synchronized` method on a collection, the expected usage for looks like this: + +```csharp +ICollection MyCollection =... + lock(MyCollection.SyncRoot) { + // Some operation on the collection, which is now thread safe. + } +``` + +```vb +Dim myCollection as New ICollection() + SyncLock myCollection.SyncRoot + ' Some operation on the collection, which is now thread safe. + End SyncLock +``` + + 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. + + + The following code example shows how to lock the collection using the during the entire enumeration: + +```csharp +ICollection myCollection = new ICollection(); + lock(myCollection.SyncRoot) { + foreach (Object item in myCollection) { + // Insert your code here. + } + } +``` + +```vb +Dim myCollection As New ICollection() + Dim item As Object + SyncLock myCollection.SyncRoot + For Each item In myCollection + ' Insert your code here. + Next item + End SyncLock +``` + ]]> diff --git a/xml/System.Drawing.Text/FontCollection.xml b/xml/System.Drawing.Text/FontCollection.xml index 49c25c6547c..8f1fc44700d 100644 --- a/xml/System.Drawing.Text/FontCollection.xml +++ b/xml/System.Drawing.Text/FontCollection.xml @@ -151,9 +151,9 @@ - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [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)). + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. diff --git a/xml/System.Drawing/Brush.xml b/xml/System.Drawing/Brush.xml index 4ea9ebf1c2e..03fcc585af6 100644 --- a/xml/System.Drawing/Brush.xml +++ b/xml/System.Drawing/Brush.xml @@ -234,9 +234,9 @@ - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [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)). + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. diff --git a/xml/System.EnterpriseServices/ServicedComponent.xml b/xml/System.EnterpriseServices/ServicedComponent.xml index 00da8201db7..f148d25275f 100644 --- a/xml/System.EnterpriseServices/ServicedComponent.xml +++ b/xml/System.EnterpriseServices/ServicedComponent.xml @@ -34,30 +34,30 @@ Represents the base class of all classes using COM+ services. - that runs in a COM+ application may stop responding. This problem is caused by an Activity deadlock. Activities can deadlock on multithreaded applications because of an asynchronous cleanup of component references. To work around this problem, call the method when you complete work with objects derived from . - + > [!NOTE] -> Client code must call `Dispose` on serviced components to ensure proper operation. - - - -## Examples - The following code example demonstrates how to expose a class as a configured COM component. - +> Client code must call `Dispose` on serviced components to ensure proper operation. + + + +## Examples + The following code example demonstrates how to expose a class as a configured COM component. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServices_Basic/CPP/calculator.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ActivationOption/Overview/calculator.cs" id="Snippet1"::: - - To deploy this class as a configured COM component, you must generate a strong key, compile the class as a library, and register the library. These three steps are accomplished by the following three commands. - -``` -sn -k Calculator.snk -csc /t:library Calculator.cs -regsvcs Calculator.dll -``` - + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ActivationOption/Overview/calculator.cs" id="Snippet1"::: + + To deploy this class as a configured COM component, you must generate a strong key, compile the class as a library, and register the library. These three steps are accomplished by the following three commands. + +``` +sn -k Calculator.snk +csc /t:library Calculator.cs +regsvcs Calculator.dll +``` + ]]> @@ -79,11 +79,11 @@ regsvcs Calculator.dll Initializes a new instance of the class. - @@ -109,15 +109,15 @@ regsvcs Calculator.dll Called by the infrastructure when the object is created or allocated from a pool. Override this method to add custom initialization code to objects. - @@ -145,15 +145,15 @@ regsvcs Calculator.dll if the serviced component can be pooled; otherwise, . - @@ -205,15 +205,15 @@ regsvcs Calculator.dll Called by the infrastructure when the object is about to be deactivated. Override this method to add custom finalization code to objects when just-in-time (JIT) compiled code or object pooling is used. - @@ -251,15 +251,15 @@ regsvcs Calculator.dll Releases all resources used by the . - method. - - Calling allows the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - + method. + + Calling allows the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + ]]> @@ -292,20 +292,20 @@ regsvcs Calculator.dll to release both managed and unmanaged resources; otherwise, to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + This method is called by the public `Dispose()` method and the method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -333,11 +333,11 @@ regsvcs Calculator.dll The object to dispose. Finalizes the object and removes the associated COM+ reference. - . - + . + ]]> @@ -378,8 +378,8 @@ regsvcs Calculator.dll method does not belong to the published interface of the class and does not need to be implemented elsewhere. +## Remarks +The method does not belong to the published interface of the class and does not need to be implemented elsewhere. ]]> @@ -420,11 +420,11 @@ The m Does not ensure that, in the COM+ context, the class object's bit is set to after a remote method invocation. A string converted from a response object that implements the interface. - method does not belong to the published interface of the class and does not need to be implemented elsewhere. - + method does not belong to the published interface of the class and does not need to be implemented elsewhere. + ]]> @@ -458,11 +458,11 @@ The m A string array that may contain any or all of the following, in order: the serviced component's process ID, the application domain ID, and the serviced component's remote URI. Obtains certain information about the class instance. - method does not belong to the published interface of the class and does not need to be implemented elsewhere. - + method does not belong to the published interface of the class and does not need to be implemented elsewhere. + ]]> diff --git a/xml/System.Globalization/CharUnicodeInfo.xml b/xml/System.Globalization/CharUnicodeInfo.xml index 1618c8a9d73..937891c222b 100644 --- a/xml/System.Globalization/CharUnicodeInfo.xml +++ b/xml/System.Globalization/CharUnicodeInfo.xml @@ -114,13 +114,13 @@ When using this class in your applications, keep in mind the following programmi | .NET Framework version | Unicode Standard version | | - | - | -| .NET Framework 4 | [5.0.0](https://www.unicode.org/versions/Unicode5.0.0/) | -| .NET Framework 4.5 | [5.0.0](https://www.unicode.org/versions/Unicode5.0.0/) | -| .NET Framework 4.5.1 | [5.0.0](https://www.unicode.org/versions/Unicode5.0.0/) | -| .NET Framework 4.5.2 | [5.0.0](https://www.unicode.org/versions/Unicode5.0.0/) | -| .NET Framework 4.6 | [6.3.0](https://www.unicode.org/versions/Unicode6.3.0/) | -| .NET Framework 4.6.1 | [6.3.0](https://www.unicode.org/versions/Unicode6.3.0/) | -| .NET Framework 4.6.2 | [8.0.0](https://www.unicode.org/versions/Unicode8.0.0/) | +| .NET Framework 4 | 5.0.0 | +| .NET Framework 4.5 | 5.0.0 | +| .NET Framework 4.5.1 | 5.0.0 | +| .NET Framework 4.5.2 | 5.0.0 | +| .NET Framework 4.6 | 6.3.0 | +| .NET Framework 4.6.1 | 6.3.0 | +| .NET Framework 4.6.2 | 8.0.0 | Each version of the Unicode standard includes information on changes to the Unicode character database since the previous version. The Unicode character database is used by the class for categorizing characters. diff --git a/xml/System.Globalization/CultureTypes.xml b/xml/System.Globalization/CultureTypes.xml index 753529041fa..72ef851eec5 100644 --- a/xml/System.Globalization/CultureTypes.xml +++ b/xml/System.Globalization/CultureTypes.xml @@ -56,41 +56,41 @@ Defines the types of culture lists that can be retrieved using the method. - property, and also serve as a filter that limits the cultures returned by the method. For more information on cultures, see . - -Generally, you enumerate all cultures by using the `CultureTypes.AllCultures` value. This allows enumeration of custom cultures as well as the other culture types. - -Note that all `CultureTypes` members have been deprecated except for `CultureTypes.AllCultures`, `CultureTypes.NeutralCultures`, and `CultureTypes.SpecificCultures`. +These culture type values are returned by the property, and also serve as a filter that limits the cultures returned by the method. For more information on cultures, see . + +Generally, you enumerate all cultures by using the `CultureTypes.AllCultures` value. This allows enumeration of custom cultures as well as the other culture types. + +Note that all `CultureTypes` members have been deprecated except for `CultureTypes.AllCultures`, `CultureTypes.NeutralCultures`, and `CultureTypes.SpecificCultures`. .NET recognizes the following culture types, all of which are included in enumerations returned by the `CultureTypes.AllTypes` enumeration member: -- **Specific cultures**, which specify a country/region and a language. The names of these cultures follow RFC 4646. The format is `-`, where `` is a lowercase two-letter code derived from ISO 639-1, and `` is an uppercase two-letter code derived from ISO 3166. For example, "en-US" for English (United States) is a specific culture. Custom specific cultures (that is, cultures that are application- rather than system-defined) can have any user-specified name, not just a standards-compliant one. +- **Specific cultures**, which specify a country/region and a language. The names of these cultures follow RFC 4646. The format is `-`, where `` is a lowercase two-letter code derived from ISO 639-1, and `` is an uppercase two-letter code derived from ISO 3166. For example, "en-US" for English (United States) is a specific culture. Custom specific cultures (that is, cultures that are application- rather than system-defined) can have any user-specified name, not just a standards-compliant one. - **Neutral cultures**, which specify a language without respect to a country/region. The names of neutral cultures consist of the lowercase two-letter code derived from ISO 639-1. For example: "en" (English) is a neutral culture. Custom neutral cultures (that is, cultures that are application- rather than system-defined) can have any user-specified name, not just a two-letter code. - - The invariant culture is included in the array of cultures returned by the method that specifies this value. -- **Custom cultures**, which are application-defined cultures. Custom cultures can represent either specific cultures or neutral cultures and can have any application-specified name. + The invariant culture is included in the array of cultures returned by the method that specifies this value. - In Windows versions prior to Windows 10, the `UserCustomCulture` value is assigned to custom cultures created by the developer. In Windows 10, the `UserCustomCulture` value is also assigned to system cultures that are not backed by a complete set of cultural data and that do not have unique local identifiers. (All cultures of type `UserCustomCulture` share a value of `LOCALE_CUSTOM_UNSPECIFIED` (0x1000, or 4096)). As a result, the `CultureInfo.GetCultures(CultureTypes.UserCustomCulture)` method returns different sets of cultures on different Windows versions. +- **Custom cultures**, which are application-defined cultures. Custom cultures can represent either specific cultures or neutral cultures and can have any application-specified name. -## Examples + In Windows versions prior to Windows 10, the `UserCustomCulture` value is assigned to custom cultures created by the developer. In Windows 10, the `UserCustomCulture` value is also assigned to system cultures that are not backed by a complete set of cultural data and that do not have unique local identifiers. (All cultures of type `UserCustomCulture` share a value of `LOCALE_CUSTOM_UNSPECIFIED` (0x1000, or 4096)). As a result, the `CultureInfo.GetCultures(CultureTypes.UserCustomCulture)` method returns different sets of cultures on different Windows versions. + +## Examples + +The following example demonstrates the `CultureTypes.AllCultures` enumeration member and the property. -The following example demonstrates the `CultureTypes.AllCultures` enumeration member and the property. - :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/CultureTypes/ct.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureTypes/vb/ct.vb" id="Snippet1"::: - - The following example displays several properties of the neutral cultures. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureTypes/vb/ct.vb" id="Snippet1"::: + + The following example displays several properties of the neutral cultures. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.CultureInfo.GetCultures/CPP/getcultures.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/DisplayName/getcultures.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CultureInfo.GetCultures/VB/getcultures.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CultureInfo.GetCultures/VB/getcultures.vb" id="Snippet1"::: + ]]> @@ -135,8 +135,8 @@ The following example demonstrates the `CultureTypes.AllCultures` enumeration me All cultures that are recognized by .NET, including neutral and specific cultures and custom cultures created by the user. -On .NET Framework 4 and later versions and .NET Core running on Windows, it includes the culture data available from the Windows operating system. On .NET Core running on Linux and macOS, it includes culture data defined in the [ICU libraries](https://icu.unicode.org/). - +On .NET Framework 4 and later versions and .NET Core running on Windows, it includes the culture data available from the Windows operating system. On .NET Core running on Linux and macOS, it includes culture data defined in the ICU libraries. + is a composite field that includes the , , and values. @@ -427,9 +427,9 @@ On .NET Framework 4 and later versions and .NET Core running on Windows, it incl 32 **This member is deprecated** and is ignored. - method on .NET Framework 4 and later versions, the method returns an empty array. diff --git a/xml/System.Globalization/IdnMapping.xml b/xml/System.Globalization/IdnMapping.xml index c887b2e9304..d4881f05a2d 100644 --- a/xml/System.Globalization/IdnMapping.xml +++ b/xml/System.Globalization/IdnMapping.xml @@ -64,33 +64,33 @@ Supports the use of non-ASCII characters for Internet domain names. This class cannot be inherited. - [!IMPORTANT] -> In the .NET Framework 4.5, the class supports different versions of the IDNA standard, depending on the operating system in use: -> +> In the .NET Framework 4.5, the class supports different versions of the IDNA standard, depending on the operating system in use: +> > - When run on Windows 8, it supports the 2008 version of the IDNA standard outlined by [RFC 5891: Internationalized Domain Names in Applications (IDNA): Protocol](https://go.microsoft.com/fwlink/?LinkId=231875). > - When run on earlier versions of the Windows operating system, it supports the 2003 version of the standard outlined by [RFC 3490: Internationalizing Domain Names in Applications (IDNA)](https://go.microsoft.com/fwlink/?LinkId=158110). -> -> See [Unicode Technical Standard #46: IDNA Compatibility Processing](https://go.microsoft.com/fwlink/?LinkId=232459) for the differences in the way these standards handle particular sets of characters. - - The method normalizes a domain name, converts the normalized name to a representation that consists of displayable Unicode characters in the US-ASCII code point range (U+0020 to U+007E), and prepends an ASCII-compatible encoding (ACE) prefix ("xn--") to each label. The method restores the domain name labels converted by the method. - - If the string to be converted includes the label separator characters IDEOGRAPHIC FULL STOP (U+3002), FULLWIDTH FULL STOP (U+FF0E), and HALFWIDTH IDEOGRAPHIC FULL STOP (U+FF61), the method converts them to the label separator FULL STOP (period, U+002E). The method, however, does not restore the original label separator character. - - - -## Examples - The following example uses the method to convert an array of internationalized domain names to Punycode. The method then converts the Punycode domain name back to the original domain name, but replaces the original label separators with the standard label separator. - +> +> See [Unicode Technical Standard #46: IDNA Compatibility Processing](https://go.microsoft.com/fwlink/?LinkId=232459) for the differences in the way these standards handle particular sets of characters. + + The method normalizes a domain name, converts the normalized name to a representation that consists of displayable Unicode characters in the US-ASCII code point range (U+0020 to U+007E), and prepends an ASCII-compatible encoding (ACE) prefix ("xn--") to each label. The method restores the domain name labels converted by the method. + + If the string to be converted includes the label separator characters IDEOGRAPHIC FULL STOP (U+3002), FULLWIDTH FULL STOP (U+FF0E), and HALFWIDTH IDEOGRAPHIC FULL STOP (U+FF61), the method converts them to the label separator FULL STOP (period, U+002E). The method, however, does not restore the original label separator character. + + + +## Examples + The following example uses the method to convert an array of internationalized domain names to Punycode. The method then converts the Punycode domain name back to the original domain name, but replaces the original label separators with the standard label separator. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/IdnMapping/Overview/conversion1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.idnmapping.class/vb/conversion1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.idnmapping.class/vb/conversion1.vb" id="Snippet1"::: + ]]> All public methods of are thread-safe and may be used concurrently from multiple threads, as long as the instance's properties are not also set concurrently. @@ -135,11 +135,11 @@ Initializes a new instance of the class. - and properties are initialized to `false`. A small subset of ASCII characters other than A-Z, 0-9, the hyphen (-) character (U+002D), and the period (.) character are permitted in domain names, but unassigned Unicode code points are not. - + and properties are initialized to `false`. A small subset of ASCII characters other than A-Z, 0-9, the hyphen (-) character (U+002D), and the period (.) character are permitted in domain names, but unassigned Unicode code points are not. + ]]> @@ -187,14 +187,14 @@ if unassigned code points are used in operations; otherwise, . - property is `false`. The IDNA specification permits unassigned code points only in queries for matching strings (that is, in domain name lookup). For more information about the use of unassigned code points in domain names, see [RFC 3454, "Preparation of Internationalized Strings (stringprep)"](https://go.microsoft.com/fwlink/?LinkId=231873) and [RFC 5891, "Internationalized Domain Names in Applications (IDNA): Protocol"](https://go.microsoft.com/fwlink/?LinkId=231875). - + property is `false`. The IDNA specification permits unassigned code points only in queries for matching strings (that is, in domain name lookup). For more information about the use of unassigned code points in domain names, see [RFC 3454, "Preparation of Internationalized Strings (stringprep)"](https://go.microsoft.com/fwlink/?LinkId=231873) and [RFC 5891, "Internationalized Domain Names in Applications (IDNA): Protocol"](https://go.microsoft.com/fwlink/?LinkId=231875). + > [!IMPORTANT] -> If the property is `false`, the behavior associated with the property depends on the underlying operating system. On Windows 8, the class conforms to IDNA 2008, which is based on the Unicode 6.0 standard. On previous versions of Windows, the class is based on IDNA 2003, which is based on Unicode 3.*x*. Some code points that were unassigned in IDNA 2003 have been assigned characters and are supported in IDNA 2008. For example, U+0221 was introduced in Unicode 4.0. On Windows 8, it is encoded as "xn—6la". On previous versions of Windows, it throws an exception. - +> If the property is `false`, the behavior associated with the property depends on the underlying operating system. On Windows 8, the class conforms to IDNA 2008, which is based on the Unicode 6.0 standard. On previous versions of Windows, the class is based on IDNA 2003, which is based on Unicode 3.*x*. Some code points that were unassigned in IDNA 2003 have been assigned characters and are supported in IDNA 2008. For example, U+0221 was introduced in Unicode 4.0. On Windows 8, it is encoded as "xn—6la". On previous versions of Windows, it throws an exception. + ]]> @@ -317,33 +317,33 @@ Encodes a string of domain name labels that consist of Unicode characters to a string of displayable Unicode characters in the US-ASCII character range. The string is formatted according to the IDNA standard. The equivalent of the string specified by the parameter, consisting of displayable Unicode characters in the US-ASCII character range (U+0020 to U+007E) and formatted according to the IDNA standard. - property is `false`. - -- Non-standard characters in the US-ASCII character range, such as the SPACE (U+0020), EXCLAMATION MARK (U+0021), and LOW LINE (U+005F) characters, if the value of the property is `true`. - -- Characters that are prohibited by a specific version of the IDNA standard. For more information about prohibited characters, see [RFC 3454: Preparation of Internationalized Strings ("stringprep")](https://go.microsoft.com/fwlink/?LinkId=231873) for IDNA 2003, and [RFC 5982: The Unicode Code Points and Internationalized Domain Names for Applications](https://go.microsoft.com/fwlink/?LinkId=231877) for IDNA 2008. - - The method converts all label separators to FULL STOP (period, U+002E). - - If `unicode` contains no characters outside the US-ASCII character range and no characters within the US-ASCII character range are prohibited, the method returns `unicode` unchanged. - - - -## Examples - The following example uses the method to convert an array of internationalized domain names to Punycode, which is an encoded equivalent that consists of characters in the US-ASCII character range. The method then converts the Punycode domain name back into the original domain name, but replaces the original label separators with the standard label separator. - + property is `false`. + +- Non-standard characters in the US-ASCII character range, such as the SPACE (U+0020), EXCLAMATION MARK (U+0021), and LOW LINE (U+005F) characters, if the value of the property is `true`. + +- Characters that are prohibited by a specific version of the IDNA standard. For more information about prohibited characters, see [RFC 3454: Preparation of Internationalized Strings ("stringprep")](https://go.microsoft.com/fwlink/?LinkId=231873) for IDNA 2003, and [RFC 5982: The Unicode Code Points and Internationalized Domain Names for Applications](https://go.microsoft.com/fwlink/?LinkId=231877) for IDNA 2008. + + The method converts all label separators to FULL STOP (period, U+002E). + + If `unicode` contains no characters outside the US-ASCII character range and no characters within the US-ASCII character range are prohibited, the method returns `unicode` unchanged. + + + +## Examples + The following example uses the method to convert an array of internationalized domain names to Punycode, which is an encoded equivalent that consists of characters in the US-ASCII character range. The method then converts the Punycode domain name back into the original domain name, but replaces the original label separators with the standard label separator. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/IdnMapping/Overview/conversion1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.idnmapping.class/vb/conversion1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.idnmapping.class/vb/conversion1.vb" id="Snippet1"::: + ]]> @@ -351,13 +351,13 @@ is invalid based on the and properties, and the IDNA standard. - In the .NET Framework 4.5, the class supports different versions of the IDNA standard, depending on the operating system in use: - -- When run on Windows 8, it supports the 2008 version of the IDNA standard outlined by [RFC 5891: Internationalized Domain Names in Applications (IDNA): Protocol](https://go.microsoft.com/fwlink/?LinkId=231875). - -- When run on earlier versions of the Windows operating system, it supports the 2003 version of the standard outlined by [RFC 3490: Internationalizing Domain Names in Applications (IDNA)](https://go.microsoft.com/fwlink/?LinkId=158110). - - See [Unicode Technical Standard #46: IDNA Compatibility Processing](https://go.microsoft.com/fwlink/?LinkId=232459) for the differences in the way these standards handle particular sets of characters. + In the .NET Framework 4.5, the class supports different versions of the IDNA standard, depending on the operating system in use: + +- When run on Windows 8, it supports the 2008 version of the IDNA standard outlined by RFC 5891: Internationalized Domain Names in Applications (IDNA): Protocol. + +- When run on earlier versions of the Windows operating system, it supports the 2003 version of the standard outlined by RFC 3490: Internationalizing Domain Names in Applications (IDNA). + + See Unicode Technical Standard #46: IDNA Compatibility Processing for the differences in the way these standards handle particular sets of characters. @@ -409,47 +409,47 @@ Encodes a substring of domain name labels that include Unicode characters outside the US-ASCII character range. The substring is converted to a string of displayable Unicode characters in the US-ASCII character range and is formatted according to the IDNA standard. The equivalent of the substring specified by the and parameters, consisting of displayable Unicode characters in the US-ASCII character range (U+0020 to U+007E) and formatted according to the IDNA standard. - property. - -- Non-standard characters in the US-ASCII character range, such as the SPACE (U+0020), EXCLAMATION MARK (U+0021), and LOW LINE (U+005F) characters, depending on the value of the property. - -- Characters that are prohibited by a specific version of the IDNA standard. For more information about prohibited characters, see [RFC 3454: Preparation of Internationalized Strings ("stringprep")](https://go.microsoft.com/fwlink/?LinkId=231873) for IDNA 2003, and [RFC 5982: The Unicode Code Points and Internationalized Domain Names for Applications](https://go.microsoft.com/fwlink/?LinkId=231877) for IDNA 2008. - - The method converts all label separators to FULL STOP (period, U+002E). - - If `unicode` contains no characters outside the US-ASCII character range and no characters within the US-ASCII character range are prohibited, the method returns `unicode` unchanged. - - - + property. + +- Non-standard characters in the US-ASCII character range, such as the SPACE (U+0020), EXCLAMATION MARK (U+0021), and LOW LINE (U+005F) characters, depending on the value of the property. + +- Characters that are prohibited by a specific version of the IDNA standard. For more information about prohibited characters, see [RFC 3454: Preparation of Internationalized Strings ("stringprep")](https://go.microsoft.com/fwlink/?LinkId=231873) for IDNA 2003, and [RFC 5982: The Unicode Code Points and Internationalized Domain Names for Applications](https://go.microsoft.com/fwlink/?LinkId=231877) for IDNA 2008. + + The method converts all label separators to FULL STOP (period, U+002E). + + If `unicode` contains no characters outside the US-ASCII character range and no characters within the US-ASCII character range are prohibited, the method returns `unicode` unchanged. + + + ]]> is . - is less than zero. - - -or- - + is less than zero. + + -or- + is greater than the length of . is invalid based on the and properties, and the IDNA standard. - In the .NET Framework 4.5, the class supports different versions of the IDNA standard, depending on the operating system in use: - -- When run on Windows 8, it supports the 2008 version of the IDNA standard outlined by [RFC 5891: Internationalized Domain Names in Applications (IDNA): Protocol](https://go.microsoft.com/fwlink/?LinkId=231875). - -- When run on earlier versions of the Windows operating system, it supports the 2003 version of the standard outlined by [RFC 3490: Internationalizing Domain Names in Applications (IDNA)](https://go.microsoft.com/fwlink/?LinkId=158110). - - See [Unicode Technical Standard #46: IDNA Compatibility Processing](https://go.microsoft.com/fwlink/?LinkId=232459) for the differences in the way these standards handle particular sets of characters. + In the .NET Framework 4.5, the class supports different versions of the IDNA standard, depending on the operating system in use: + +- When run on Windows 8, it supports the 2008 version of the IDNA standard outlined by RFC 5891: Internationalized Domain Names in Applications (IDNA): Protocol. + +- When run on earlier versions of the Windows operating system, it supports the 2003 version of the standard outlined by RFC 3490: Internationalizing Domain Names in Applications (IDNA). + + See Unicode Technical Standard #46: IDNA Compatibility Processing for the differences in the way these standards handle particular sets of characters. @@ -503,55 +503,55 @@ Encodes the specified number of characters in a substring of domain name labels that include Unicode characters outside the US-ASCII character range. The substring is converted to a string of displayable Unicode characters in the US-ASCII character range and is formatted according to the IDNA standard. The equivalent of the substring specified by the , , and parameters, consisting of displayable Unicode characters in the US-ASCII character range (U+0020 to U+007E) and formatted according to the IDNA standard. - property. - -- Non-standard characters in the US-ASCII character range, such as the SPACE (U+0020), EXCLAMATION MARK (U+0021), and LOW LINE (U+005F) characters, depending on the value of the property. - -- Characters that are prohibited by a specific version of the IDNA standard. For more information about prohibited characters, see [RFC 3454: Preparation of Internationalized Strings ("stringprep")](https://go.microsoft.com/fwlink/?LinkId=231873) for IDNA 2003, and [RFC 5982: The Unicode Code Points and Internationalized Domain Names for Applications](https://go.microsoft.com/fwlink/?LinkId=231877) for IDNA 2008. - - The method converts all label separators to FULL STOP (period, U+002E). If the substring contains no characters outside the US-ASCII character range, and no characters within the US-ASCII character range are prohibited, the method returns the substring unchanged. - - - -## Examples - The following example uses the method to convert an internationalized domain name to a domain name that complies with the IDNA standard. The method then converts the standardized domain name back into the original domain name, but replaces the original label separators with the standard label separator. - + property. + +- Non-standard characters in the US-ASCII character range, such as the SPACE (U+0020), EXCLAMATION MARK (U+0021), and LOW LINE (U+005F) characters, depending on the value of the property. + +- Characters that are prohibited by a specific version of the IDNA standard. For more information about prohibited characters, see [RFC 3454: Preparation of Internationalized Strings ("stringprep")](https://go.microsoft.com/fwlink/?LinkId=231873) for IDNA 2003, and [RFC 5982: The Unicode Code Points and Internationalized Domain Names for Applications](https://go.microsoft.com/fwlink/?LinkId=231877) for IDNA 2008. + + The method converts all label separators to FULL STOP (period, U+002E). If the substring contains no characters outside the US-ASCII character range, and no characters within the US-ASCII character range are prohibited, the method returns the substring unchanged. + + + +## Examples + The following example uses the method to convert an internationalized domain name to a domain name that complies with the IDNA standard. The method then converts the standardized domain name back into the original domain name, but replaces the original label separators with the standard label separator. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/IdnMapping/GetAscii/getx.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IdnMapping.GetX/VB/getx.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IdnMapping.GetX/VB/getx.vb" id="Snippet1"::: + ]]> is . - or is less than zero. - - -or- - - is greater than the length of . - - -or- - + or is less than zero. + + -or- + + is greater than the length of . + + -or- + is greater than the length of minus . is invalid based on the and properties, and the IDNA standard. - In the .NET Framework 4.5, the class supports different versions of the IDNA standard, depending on the operating system in use: - -- When run on Windows 8, it supports the 2008 version of the IDNA standard outlined by [RFC 5891: Internationalized Domain Names in Applications (IDNA): Protocol](https://go.microsoft.com/fwlink/?LinkId=231875). - -- When run on earlier versions of the Windows operating system, it supports the 2003 version of the standard outlined by [RFC 3490: Internationalizing Domain Names in Applications (IDNA)](https://go.microsoft.com/fwlink/?LinkId=158110). - - See [Unicode Technical Standard #46: IDNA Compatibility Processing](https://go.microsoft.com/fwlink/?LinkId=232459) for the differences in the way these standards handle particular sets of characters. + In the .NET Framework 4.5, the class supports different versions of the IDNA standard, depending on the operating system in use: + +- When run on Windows 8, it supports the 2008 version of the IDNA standard outlined by RFC 5891: Internationalized Domain Names in Applications (IDNA): Protocol. + +- When run on earlier versions of the Windows operating system, it supports the 2003 version of the standard outlined by RFC 3490: Internationalizing Domain Names in Applications (IDNA). + + See Unicode Technical Standard #46: IDNA Compatibility Processing for the differences in the way these standards handle particular sets of characters. @@ -598,19 +598,19 @@ Returns a hash code for this object. One of four 32-bit signed constants derived from the properties of an object. The return value has no special meaning and is not suitable for use in a hash code algorithm. - method if your application needs to implement a meaningful hash code algorithm. - - - -## Examples - The following example assumes that a single string can contain multiple email addresses separated by spaces. It removes the local part and the @ character from each email address, and passes the resulting domain name to the or method to create a Punycode domain name. The method then converts the Punycode domain name back into the original domain name. - + method if your application needs to implement a meaningful hash code algorithm. + + + +## Examples + The following example assumes that a single string can contain multiple email addresses separated by spaces. It removes the local part and the @ character from each email address, and passes the resulting domain name to the or method to create a Punycode domain name. The method then converts the Punycode domain name back into the original domain name. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/IdnMapping/GetHashCode/conversion1b.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.idnmapping.getascii/vb/conversion1b.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.idnmapping.getascii/vb/conversion1b.vb" id="Snippet3"::: + ]]> @@ -670,19 +670,19 @@ Decodes a string of one or more domain name labels, encoded according to the IDNA standard, to a string of Unicode characters. The Unicode equivalent of the IDNA substring specified by the parameter. - method. - - - -## Examples - The following example uses the method to convert an array of internationalized domain names to Punycode. The method then converts the Punycode domain name back into the original domain name, but replaces the original label separators with the standard label separator. - + method. + + + +## Examples + The following example uses the method to convert an array of internationalized domain names to Punycode. The method then converts the Punycode domain name back into the original domain name, but replaces the original label separators with the standard label separator. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/IdnMapping/Overview/conversion1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.idnmapping.class/vb/conversion1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.idnmapping.class/vb/conversion1.vb" id="Snippet1"::: + ]]> @@ -739,20 +739,20 @@ Decodes a substring of one or more domain name labels, encoded according to the IDNA standard, to a string of Unicode characters. The Unicode equivalent of the IDNA substring specified by the and parameters. - method. - + method. + ]]> is . - is less than zero. - - -or- - + is less than zero. + + -or- + is greater than the length of . is invalid based on the and properties, and the IDNA standard. @@ -808,24 +808,24 @@ Decodes a substring of a specified length that contains one or more domain name labels, encoded according to the IDNA standard, to a string of Unicode characters. The Unicode equivalent of the IDNA substring specified by the , , and parameters. - method. - + method. + ]]> is . - or is less than zero. - - -or- - - is greater than the length of . - - -or- - + or is less than zero. + + -or- + + is greater than the length of . + + -or- + is greater than the length of minus . is invalid based on the and properties, and the IDNA standard. @@ -874,24 +874,24 @@ if standard naming conventions are used in operations; otherwise, . - is `true`, only standard characters can appear in a label returned by the method. - - By default, the value of the property is `false`, and an expanded subset of ASCII characters is permitted in a label. - + is `true`, only standard characters can appear in a label returned by the method. + + By default, the value of the property is `false`, and an expanded subset of ASCII characters is permitted in a label. + > [!NOTE] -> The class prohibits the use of the nondisplayable characters U+0000 through U+001F, and U+007F in domain name labels regardless of the setting of the property. This prohibition reduces the risk of security attacks such as name spoofing. - - - -## Examples - The following example generates URLs that contain characters in the ASCII range from U+0000 to U+007F and passes them to the method of two objects. One object has its property set to `true`, and the other object has it set to `false`. The output displays the characters that are invalid when the property is `true` but valid when it is `false`. - +> The class prohibits the use of the nondisplayable characters U+0000 through U+001F, and U+007F in domain name labels regardless of the setting of the property. This prohibition reduces the risk of security attacks such as name spoofing. + + + +## Examples + The following example generates URLs that contain characters in the ASCII range from U+0000 to U+007F and passes them to the method of two objects. One object has its property set to `true`, and the other object has it set to `false`. The output displays the characters that are invalid when the property is `true` but valid when it is `false`. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/IdnMapping/UseStd3AsciiRules/usestd3asciirules1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.idnmapping.usestd3asciirules/vb/usestd3asciirules1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.idnmapping.usestd3asciirules/vb/usestd3asciirules1.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Globalization/NumberFormatInfo.xml b/xml/System.Globalization/NumberFormatInfo.xml index f5b8a09be13..e4490fb34d1 100644 --- a/xml/System.Globalization/NumberFormatInfo.xml +++ b/xml/System.Globalization/NumberFormatInfo.xml @@ -1289,7 +1289,7 @@ -or- - In a set operation, an element of the value array is not a number digit as defined by the [Unicode Standard](https://go.microsoft.com/fwlink/?linkid=37123). That is, the digit in the array element does not have the Unicode (Nd) General Category value. + In a set operation, an element of the value array is not a number digit as defined by the Unicode Standard. That is, the digit in the array element does not have the Unicode (Nd) General Category value. -or- diff --git a/xml/System.Globalization/StringInfo.xml b/xml/System.Globalization/StringInfo.xml index e7f2dd3f85e..2a08dcc41ee 100644 --- a/xml/System.Globalization/StringInfo.xml +++ b/xml/System.Globalization/StringInfo.xml @@ -117,7 +117,7 @@ This example uses the - Internally, the methods of the class call the methods of the class to determine character categories. Starting with the .NET Framework 4.6.2, character classification is based on [The Unicode Standard, Version 8.0.0](https://unicode.org/versions/Unicode8.0.0). For the .NET Framework 4 through the .NET Framework 4.6.1, it is based on [The Unicode Standard, Version 6.3.0](https://www.unicode.org/versions/Unicode6.3.0/). In .NET Core, it is based on [The Unicode Standard, Version 8.0.0](https://unicode.org/versions/Unicode8.0.0). + Internally, the methods of the class call the methods of the class to determine character categories. Starting with the .NET Framework 4.6.2, character classification is based on The Unicode Standard, Version 8.0.0. For the .NET Framework 4 through the .NET Framework 4.6.1, it is based on The Unicode Standard, Version 6.3.0. In .NET Core, it is based on The Unicode Standard, Version 8.0.0. Sorting Weight Tables for Windows operating systems Default Unicode Collation Element Table, for Linux and macOS diff --git a/xml/System.IO.Compression/BrotliStream.xml b/xml/System.IO.Compression/BrotliStream.xml index 49bd1399a25..46d3a757d1c 100644 --- a/xml/System.IO.Compression/BrotliStream.xml +++ b/xml/System.IO.Compression/BrotliStream.xml @@ -506,7 +506,7 @@ The `DisposeAsync` method lets you perform a resource-intensive dispose operation without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the and keywords in Visual Basic and C#. This method disposes the Brotli stream by writing any changes to the backing store and closing the stream to release resources. - Calling `DisposeAsync` allows the resources used by the to be reallocated for other purposes. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + Calling `DisposeAsync` allows the resources used by the to be reallocated for other purposes. For more information, see Cleaning Up Unmanaged Resources. diff --git a/xml/System.IO.Compression/DeflateStream.xml b/xml/System.IO.Compression/DeflateStream.xml index b010c797969..3ef174f8f43 100644 --- a/xml/System.IO.Compression/DeflateStream.xml +++ b/xml/System.IO.Compression/DeflateStream.xml @@ -863,9 +863,9 @@ When the `disposing` parameter is `true`, this method releases all resources hel - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + For more information about and , see Cleaning Up Unmanaged Resources. diff --git a/xml/System.IO.Compression/GZipStream.xml b/xml/System.IO.Compression/GZipStream.xml index e5e879833f4..0f1f8e1a265 100644 --- a/xml/System.IO.Compression/GZipStream.xml +++ b/xml/System.IO.Compression/GZipStream.xml @@ -886,9 +886,9 @@ When the `disposing` parameter is `true`, this method releases all resources hel - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + For more information about and , see Cleaning Up Unmanaged Resources. diff --git a/xml/System.IO.Compression/ZipFileExtensions.xml b/xml/System.IO.Compression/ZipFileExtensions.xml index e31d8a701d6..d8bce2ef927 100644 --- a/xml/System.IO.Compression/ZipFileExtensions.xml +++ b/xml/System.IO.Compression/ZipFileExtensions.xml @@ -120,45 +120,45 @@ Archives a file by compressing it and adding it to the zip archive. A wrapper for the new entry in the zip archive. - property of the entry is set to the last time the file on the file system was changed. - - When `ZipArchiveMode.Update` is present, the size limit of an entry is limited to . This limit is because update mode uses a internally to allow the seeking required when updating an archive, and has a maximum equal to the size of an int. - - -## Examples - The following example shows how to create a new entry in a zip archive from an existing file. - + property of the entry is set to the last time the file on the file system was changed. + + When `ZipArchiveMode.Update` is present, the size limit of an entry is limited to . This limit is because update mode uses a internally to allow the seeking required when updating an archive, and has a maximum equal to the size of an int. + + +## Examples + The following example shows how to create a new entry in a zip archive from an existing file. + :::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/Entries/program3.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchive/vb/program3.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchive/vb/program3.vb" id="Snippet3"::: + ]]> - is , contains only white space, or contains at least one invalid character. - - -or- - + is , contains only white space, or contains at least one invalid character. + + -or- + is . or is . In , the specified path, file name, or both exceed the system-defined maximum length. is invalid (for example, it is on an unmapped drive). - The file specified by cannot be opened, or is too large to be updated (current limit is Int32.MaxValue). + The file specified by cannot be opened, or is too large to be updated (current limit is Int32.MaxValue. - specifies a directory. - - -or- - + specifies a directory. + + -or- + The caller does not have the required permission to access the file specified by . The file specified by is not found. - The parameter is in an invalid format. - - -or- - + The parameter is in an invalid format. + + -or- + The zip archive does not support writing. The zip archive has been disposed. @@ -211,44 +211,44 @@ Archives a file by compressing it using the specified compression level and adding it to the zip archive. A wrapper for the new entry in the zip archive. - property of the entry is set to the last time the file on the file system was changed. - - When `ZipArchiveMode.Update` is present, the size limit of an entry is limited to . This limit is because update mode uses a internally to allow the seeking required when updating an archive, and has a maximum equal to the size of an int. - -## Examples - The following example shows how to create a new entry in a zip archive from an existing file, and specify the compression level. - + property of the entry is set to the last time the file on the file system was changed. + + When `ZipArchiveMode.Update` is present, the size limit of an entry is limited to . This limit is because update mode uses a internally to allow the seeking required when updating an archive, and has a maximum equal to the size of an int. + +## Examples + The following example shows how to create a new entry in a zip archive from an existing file, and specify the compression level. + :::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/Entries/program4.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchive/vb/program4.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchive/vb/program4.vb" id="Snippet4"::: + ]]> - is , contains only white space, or contains at least one invalid character. - - -or- - + is , contains only white space, or contains at least one invalid character. + + -or- + is . or is . is invalid (for example, it is on an unmapped drive). In , the specified path, file name, or both exceed the system-defined maximum length. - The file specified by cannot be opened, or is too large to be updated (current limit is Int32.MaxValue). + The file specified by cannot be opened, or is too large to be updated (current limit is Int32.MaxValue. - specifies a directory. - - -or- - + specifies a directory. + + -or- + The caller does not have the required permission to access the file specified by . The file specified by is not found. - The parameter is in an invalid format. - - -or- - + The parameter is in an invalid format. + + -or- + The zip archive does not support writing. The zip archive has been disposed. @@ -296,18 +296,18 @@ The path to the directory to place the extracted files in. You can specify either a relative or an absolute path. A relative path is interpreted as relative to the current working directory. Extracts all the files in the zip archive to a directory on the file system. - @@ -316,22 +316,22 @@ This method creates the directory specified by `destinationDirectoryName`. The m is . The specified path exceeds the system-defined maximum length. The specified path is invalid (for example, it is on an unmapped drive). - The name of an entry in the archive is , contains only white space, or contains at least one invalid character. - - -or- - - Extracting an entry from the archive would create a file that is outside the directory specified by . (For example, this might happen if the entry name contains parent directory accessors.) - - -or- - + The name of an entry in the archive is , contains only white space, or contains at least one invalid character. + + -or- + + Extracting an entry from the archive would create a file that is outside the directory specified by . (For example, this might happen if the entry name contains parent directory accessors.) + + -or- + Two or more entries in the archive have the same name. The caller does not have the required permission to write to the destination directory. contains an invalid format. - An archive entry cannot be found or is corrupt. - - -or- - + An archive entry cannot be found or is corrupt. + + -or- + An archive entry was compressed by using a compression method that is not supported. @@ -381,11 +381,11 @@ This method creates the directory specified by `destinationDirectoryName`. The m The specified directory may already exist. This method creates the specified directory and all subdirectories if necessary. If there is an error while extracting the archive, the archive will remain partially extracted. - + Each entry is extracted such that the extracted file has the same relative path to `destinationDirectoryName` as the entry has to the root of the archive. - + If a file to be archived has an invalid last modified time, the first date and time representable in the Zip timestamp format (midnight on January 1, 1980) is used. - + ]]> @@ -467,59 +467,59 @@ A has been compressed usi The path of the file to create from the contents of the entry. You can specify either a relative or an absolute path. A relative path is interpreted as relative to the current working directory. Extracts an entry in the zip archive to a file. - exception. To overwrite an existing file, use the method overload instead. - - The last write time of the file is set to the last time the entry in the zip archive was changed; this value is stored in the property. - + exception. To overwrite an existing file, use the method overload instead. + + The last write time of the file is set to the last time the entry in the zip archive was changed; this value is stored in the property. + You cannot use this method to extract a directory; use the method instead. -## Examples - The following example shows how to iterate through the contents of a zip archive file and extract files that have a .txt extension. - +## Examples + The following example shows how to iterate through the contents of a zip archive file and extract files that have a .txt extension. + :::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/Entries/program1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchive/vb/program1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchive/vb/program1.vb" id="Snippet1"::: + ]]> - is a zero-length string, contains only white space, or contains one or more invalid characters as defined by . - - -or- - + is a zero-length string, contains only white space, or contains one or more invalid characters as defined by . + + -or- + specifies a directory. is . The specified path, file name, or both exceed the system-defined maximum length. The specified path is invalid (for example, it is on an unmapped drive). - already exists. - - -or- - - An I/O error occurred. - - -or- - - The entry is currently open for writing. - - -or- - + already exists. + + -or- + + An I/O error occurred. + + -or- + + The entry is currently open for writing. + + -or- + The entry has been deleted from the archive. The caller does not have the required permission to create the new file. - The entry is missing from the archive, or is corrupt and cannot be read. - - -or- - + The entry is missing from the archive, or is corrupt and cannot be read. + + -or- + The entry has been compressed by using a compression method that is not supported. The zip archive that this entry belongs to has been disposed. - is in an invalid format. - - -or- - + is in an invalid format. + + -or- + The zip archive for this entry was opened in mode, which does not permit the retrieval of entries. @@ -569,57 +569,57 @@ A has been compressed usi to overwrite an existing file that has the same name as the destination file; otherwise, . Extracts an entry in the zip archive to a file, and optionally overwrites an existing file that has the same name. - property. - + property. + You cannot use this method to extract a directory; use the method instead. - -## Examples - The following example shows how to iterate through the contents of a zip archive file, and extract files that have a .txt extension. It overwrites an existing file that has the same name in the destination folder. In order to compiler this code example, you must reference the `System.IO.Compression` and `System.IO.Compression.FileSystem` assemblies in your project. - + +## Examples + The following example shows how to iterate through the contents of a zip archive file, and extract files that have a .txt extension. It overwrites an existing file that has the same name in the destination folder. In order to compiler this code example, you must reference the `System.IO.Compression` and `System.IO.Compression.FileSystem` assemblies in your project. + :::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/Entries/program2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchive/vb/program2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchive/vb/program2.vb" id="Snippet2"::: + ]]> - is a zero-length string, contains only white space, or contains one or more invalid characters as defined by . - - -or- - + is a zero-length string, contains only white space, or contains one or more invalid characters as defined by . + + -or- + specifies a directory. is . The specified path, file name, or both exceed the system-defined maximum length. The specified path is invalid (for example, it is on an unmapped drive). - already exists and is . - - -or- - - An I/O error occurred. - - -or- - - The entry is currently open for writing. - - -or- - + already exists and is . + + -or- + + An I/O error occurred. + + -or- + + The entry is currently open for writing. + + -or- + The entry has been deleted from the archive. The caller does not have the required permission to create the new file. - The entry is missing from the archive or is corrupt and cannot be read. - - -or- - + The entry is missing from the archive or is corrupt and cannot be read. + + -or- + The entry has been compressed by using a compression method that is not supported. The zip archive that this entry belongs to has been disposed. - is in an invalid format. - - -or- - + is in an invalid format. + + -or- + The zip archive for this entry was opened in mode, which does not permit the retrieval of entries. diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml index 5944c1e8454..fd89a2b18d2 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml @@ -1148,9 +1148,9 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + For more information about and , see Cleaning Up Unmanaged Resources. diff --git a/xml/System.IO.Packaging/EncryptedPackageEnvelope.xml b/xml/System.IO.Packaging/EncryptedPackageEnvelope.xml index 220993cf619..581f66d48d0 100644 --- a/xml/System.IO.Packaging/EncryptedPackageEnvelope.xml +++ b/xml/System.IO.Packaging/EncryptedPackageEnvelope.xml @@ -26,11 +26,11 @@ Represents an OLE compound file that contains an encrypted package. - has no public constructors. An is created by use of the static , , or methods. - + has no public constructors. An is created by use of the static , , or methods. + ]]> @@ -66,14 +66,14 @@ Closes the encrypted package and the OLE compound file that holds it. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubencrypt"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: + ]]> @@ -122,11 +122,11 @@ Creates and returns an on the specified stream. The newly created . - @@ -169,13 +169,13 @@ Creates and returns an and gives it the specified file name. The newly created . - @@ -191,14 +191,14 @@ Creates and returns an that uses an existing unencrypted package as the source of its content. - method to instantiate an . - + method to instantiate an . + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubencrypt"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: + ]]> @@ -239,19 +239,19 @@ Creates and returns an (on the specified stream) that uses the specified unencrypted package as its content. The newly created . - method to instantiate an . - + method to instantiate an . + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubencrypt"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: + ]]> @@ -296,21 +296,21 @@ Creates and returns an that uses the specified unencrypted package as its content, and gives it the specified file name. The newly created . - method to instantiate an . - + method to instantiate an . + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubencrypt"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: + ]]> @@ -355,14 +355,14 @@ Releases all resources used by the . - when finished with a . 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). - + when finished with a . 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. + ]]> @@ -396,20 +396,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -568,14 +568,14 @@ if the specified file is an OLE compound file with an encrypted package stream; otherwise, . - @@ -621,11 +621,11 @@ Open the encrypted package in the specified stream. The that is opened. - @@ -665,13 +665,13 @@ Open the encrypted package in the specified file as read only and unshared. The that is opened. - @@ -714,13 +714,13 @@ Open the encrypted package in the specified file as unshared and with the specified access. The that is opened. - @@ -759,11 +759,11 @@ Open the encrypted package in the specified file and gives it the specified access and sharing. The that is opened. - @@ -794,11 +794,11 @@ Gets the core package properties (such as Title and Subject) of the rights managed document. The for the package. - @@ -828,14 +828,14 @@ Gets the rights management information stored in the ; specifically, the and the s stored in the OLE compound file that embodies the rights-management protected package. The for the package. - for an encrypted package by use the property. - + for an encrypted package by use the property. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubencrypt"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: + ]]> diff --git a/xml/System.IO.Packaging/PackageProperties.xml b/xml/System.IO.Packaging/PackageProperties.xml index 4307e1f9e53..9dffe76c151 100644 --- a/xml/System.IO.Packaging/PackageProperties.xml +++ b/xml/System.IO.Packaging/PackageProperties.xml @@ -122,11 +122,11 @@ When overridden in a derived class, gets or sets the category of the . The category of the content that is contained in the . - value is typically used as part of the application user interface (UI) to create labels for navigation controls. - + value is typically used as part of the application user interface (UI) to create labels for navigation controls. + ]]> @@ -164,11 +164,11 @@ When overridden in a derived class, gets or sets a value that represents the status of the . The status of the content. - values include "Draft", "Reviewed", and "Final". - + values include "Draft", "Reviewed", and "Final". + ]]> @@ -205,13 +205,13 @@ When overridden in a derived class, gets or sets a value that represents the type of content that is contained in the . The type of content that is contained in the . - values include "Whitepaper", "Security Bulletin", and "Exam". - - This property is distinct from Multipurpose Internet Mail Extensions (MIME) content types as defined in RFC 2616. - + values include "Whitepaper", "Security Bulletin", and "Exam". + + This property is distinct from Multipurpose Internet Mail Extensions (MIME) content types as defined in RFC 2616. + ]]> @@ -319,11 +319,11 @@ When overridden in a derived class, gets or sets a description of the content contained in the . A description of the content contained in the . - may include but is not limited to: an abstract, table of contents, reference to a graphical representation of content, or a free-text account of the content. - + may include but is not limited to: an abstract, table of contents, reference to a graphical representation of content, or a free-text account of the content. + ]]> @@ -371,14 +371,14 @@ Releases all resources used by the instance. - 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). - + 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. + ]]> @@ -418,20 +418,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the instance and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -501,11 +501,11 @@ When overridden in a derived class, gets or sets a value that define a delimited set of keywords to support searching and indexing the and its content. A delimited set of keywords to support searching and indexing the and content. - property typically contains a list of terms that are not available elsewhere in . - + property typically contains a list of terms that are not available elsewhere in . + ]]> @@ -680,13 +680,13 @@ When overridden in a derived class, gets or sets the revision number of the . The revision number of the . - property indicates the number of changed saves or revisions. - - The application is responsible for updating the property value after each revision. - + property indicates the number of changed saves or revisions. + + The application is responsible for updating the property value after each revision. + ]]> diff --git a/xml/System.IO.Pipes/PipeStream.xml b/xml/System.IO.Pipes/PipeStream.xml index bfe61313f79..d1ccec4fda6 100644 --- a/xml/System.IO.Pipes/PipeStream.xml +++ b/xml/System.IO.Pipes/PipeStream.xml @@ -728,9 +728,9 @@ When the disposing parameter is `true`, this method releases all resources held In derived classes, put all cleanup logic in the method. - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + For more information about and , see Cleaning Up Unmanaged Resources. diff --git a/xml/System.IO.Ports/SerialPort.xml b/xml/System.IO.Ports/SerialPort.xml index b68653566fb..973946e94b4 100644 --- a/xml/System.IO.Ports/SerialPort.xml +++ b/xml/System.IO.Ports/SerialPort.xml @@ -35,26 +35,26 @@ Represents a serial port resource. - object, accessible through the property, and passed to classes that wrap or use streams. - - The class supports the following encodings: , , , , and any encoding defined in mscorlib.dll where the code page is less than 50000 or the code page is 54936. You can use alternate encodings, but you must use the or method and perform the encoding yourself. - - You use the method to retrieve the valid ports for the current computer. - - If a object becomes blocked during a read operation, do not abort the thread. Instead, either close the base stream or dispose of the object. - - - -## Examples - The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. Both computers must be executing the program to achieve full functionality of this example. - + object, accessible through the property, and passed to classes that wrap or use streams. + + The class supports the following encodings: , , , , and any encoding defined in mscorlib.dll where the code page is less than 50000 or the code page is 54936. You can use alternate encodings, but you must use the or method and perform the encoding yourself. + + You use the method to retrieve the valid ports for the current computer. + + If a object becomes blocked during a read operation, do not abort the thread. Instead, either close the base stream or dispose of the object. + + + +## Examples + The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. Both computers must be executing the program to achieve full functionality of this example. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/cpp/serialport.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/SerialPort.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet10"::: + ]]> @@ -89,20 +89,20 @@ Initializes a new instance of the class. - property defaults to 8, the property defaults to the `None` enumeration value, the property defaults to 1, and a default port name of COM1. - - - -## Examples - The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. - + property defaults to 8, the property defaults to the `None` enumeration value, the property defaults to 1, and a default port name of COM1. + + + +## Examples + The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/cpp/serialport.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/SerialPort.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: + ]]> @@ -132,11 +132,11 @@ An interface to a container. Initializes a new instance of the class using the specified object. - property defaults to 8, the property defaults to the `None` enumeration value, the property defaults to 1, and a default port name of COM1. - + property defaults to 8, the property defaults to the `None` enumeration value, the property defaults to 1, and a default port name of COM1. + ]]> The specified port could not be found or opened. @@ -173,11 +173,11 @@ The port to use (for example, COM1). Initializes a new instance of the class using the specified port name. - class when you want to specify the port name. - + class when you want to specify the port name. + ]]> The specified port could not be found or opened. @@ -216,11 +216,11 @@ The baud rate. Initializes a new instance of the class using the specified port name and baud rate. - class when you want to specify the port name and the baud rate. - + class when you want to specify the port name and the baud rate. + ]]> The specified port could not be found or opened. @@ -261,11 +261,11 @@ One of the values. Initializes a new instance of the class using the specified port name, baud rate, and parity bit. - class when you want to specify the port name, the baud rate, and the parity bit. - + class when you want to specify the port name, the baud rate, and the parity bit. + ]]> The specified port could not be found or opened. @@ -308,11 +308,11 @@ The data bits value. Initializes a new instance of the class using the specified port name, baud rate, parity bit, and data bits. - class when you want to specify the port name, the baud rate, the parity bit, and data bits. - + class when you want to specify the port name, the baud rate, the parity bit, and data bits. + ]]> The specified port could not be found or opened. @@ -351,11 +351,11 @@ One of the values. Initializes a new instance of the class using the specified port name, baud rate, parity bit, data bits, and stop bit. - class when you want to specify the port name, the baud rate, the parity bit, data bits, and stop bit. - + class when you want to specify the port name, the baud rate, the parity bit, data bits, and stop bit. + ]]> The specified port could not be found or opened. @@ -396,22 +396,22 @@ Gets the underlying object for a object. A object. - object to a wrapper class such as . - - Any open serial port's property returns an object that derives from the abstract class, and implements read and write methods using the prototypes inherited from the class: , , , , , and . These methods can be useful when passing a wrapped serial resource to a wrapper class. - - Due to the inaccessibility of the wrapped file handle, the and properties are not supported, and the and methods are not supported. - + object to a wrapper class such as . + + Any open serial port's property returns an object that derives from the abstract class, and implements read and write methods using the prototypes inherited from the class: , , , , , and . These methods can be useful when passing a wrapped serial resource to a wrapper class. + + Due to the inaccessibility of the wrapped file handle, the and properties are not supported, and the and methods are not supported. + ]]> The stream is closed. This can occur because the method has not been called or the method has been called. - The stream is in a .NET Compact Framework application and one of the following methods was called: - - - + The stream is in a .NET Compact Framework application and one of the following methods was called: + + + The .NET Compact Framework does not support the asynchronous model with base streams. @@ -458,33 +458,33 @@ Gets or sets the serial baud rate. The baud rate. - property to `9600`. - + property to `9600`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/cpp/datareceived.cpp" id="Snippet20"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/datareceived.cs" id="Snippet20"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/datareceived.vb" id="Snippet20"::: - - The following example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/datareceived.vb" id="Snippet20"::: + + The following example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/cpp/serialport.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/SerialPort.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: + ]]> The baud rate specified is less than or equal to zero, or is greater than the maximum allowable baud rate for the device. - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. @@ -524,17 +524,17 @@ if the port is in a break state; otherwise, . - object while is `true`. - + object while is `true`. + ]]> - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. The stream is closed. This can occur because the method has not been called or the method has been called. @@ -574,13 +574,13 @@ Gets the number of bytes of data in the receive buffer. The number of bytes of data in the receive buffer. - object itself. - - Because the property represents both the buffer and the Windows-created buffer, it can return a greater value than the property, which represents only the Windows-created buffer. - + object itself. + + Because the property represents both the buffer and the Windows-created buffer, it can return a greater value than the property, which represents only the Windows-created buffer. + ]]> The port is not open. @@ -621,11 +621,11 @@ Gets the number of bytes of data in the send buffer. The number of bytes of data in the send buffer. - object itself. - + object itself. + ]]> The port is in an invalid state. @@ -668,17 +668,17 @@ if the carrier is detected; otherwise, . - - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. The stream is closed. This can occur because the method has not been called or the method has been called. @@ -708,28 +708,28 @@ Closes the port connection, sets the property to , and disposes of the internal object. - object and clears both the receive and transmit buffers. This method calls the method, which invokes the protected method with the `disposing` parameter set to `true`. - - The best practice for any application is to wait for some amount of time after calling the method before attempting to call the method, as the port may not be closed instantly. - - - -## Examples - The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. - + object and clears both the receive and transmit buffers. This method calls the method, which invokes the protected method with the `disposing` parameter set to `true`. + + The best practice for any application is to wait for some amount of time after calling the method before attempting to call the method, as the port may not be closed instantly. + + + +## Examples + The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/cpp/serialport.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/SerialPort.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: + ]]> - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. @@ -769,17 +769,17 @@ if the Clear-to-Send line is detected; otherwise, . - - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. The stream is closed. This can occur because the method has not been called or the method has been called. @@ -827,26 +827,26 @@ Gets or sets the standard length of data bits per byte. The data bits length. - class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. - + class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/cpp/serialport.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/SerialPort.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: + ]]> - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. The data bits value is less than 5 or more than 8. @@ -882,30 +882,30 @@ Indicates that data has been received through a port represented by the object. - enumeration. Because the operating system determines whether to raise this event or not, not all parity errors may be reported. - - The event is also raised if an Eof character is received, regardless of the number of bytes in the internal input buffer and the value of the property. - - , , and events may be called out of order, and there may be a slight delay between when the underlying stream reports the error and when the event handler is executed. Only one event handler can execute at a time. - - The event is not guaranteed to be raised for every byte received. Use the property to determine how much data is left to be read in the buffer. - - The event is raised on a secondary thread when data is received from the object. Because this event is raised on a secondary thread, and not the main thread, attempting to modify some elements in the main thread, such as UI elements, could raise a threading exception. If it is necessary to modify elements in the main or , post change requests back using , which will do the work on the proper thread. - - For more information about handling events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - This example adds a to to read all the available data received on the COM1 port. Note that to test this code it is necessary to have hardware attached to COM1 that will send data. - + enumeration. Because the operating system determines whether to raise this event or not, not all parity errors may be reported. + + The event is also raised if an Eof character is received, regardless of the number of bytes in the internal input buffer and the value of the property. + + , , and events may be called out of order, and there may be a slight delay between when the underlying stream reports the error and when the event handler is executed. Only one event handler can execute at a time. + + The event is not guaranteed to be raised for every byte received. Use the property to determine how much data is left to be read in the buffer. + + The event is raised on a secondary thread when data is received from the object. Because this event is raised on a secondary thread, and not the main thread, attempting to modify some elements in the main thread, such as UI elements, could raise a threading exception. If it is necessary to modify elements in the main or , post change requests back using , which will do the work on the proper thread. + + For more information about handling events, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + This example adds a to to read all the available data received on the COM1 port. Note that to test this code it is necessary to have hardware attached to COM1 that will send data. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/cpp/datareceived.cpp" id="Snippet06"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/datareceived.cs" id="Snippet06"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/datareceived.vb" id="Snippet06"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/datareceived.vb" id="Snippet06"::: + ]]> @@ -935,17 +935,17 @@ Discards data from the serial driver's receive buffer. - - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. The stream is closed. This can occur because the method has not been called or the method has been called. @@ -994,17 +994,17 @@ if null bytes are ignored; otherwise . The default is . - - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. The stream is closed. This can occur because the method has not been called or the method has been called. @@ -1034,17 +1034,17 @@ Discards data from the serial driver's transmit buffer. - - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. The stream is closed. This can occur because the method has not been called or the method has been called. @@ -1078,27 +1078,27 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. - - When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. - - This method flushes and closes the stream object in the property. - + method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. + + When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. + + This method flushes and closes the stream object in the property. + ]]> - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources. @@ -1138,17 +1138,17 @@ if a Data Set Ready signal has been sent to the port; otherwise, . - - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. The stream is closed. This can occur because the method has not been called or the method has been called. @@ -1193,17 +1193,17 @@ to enable Data Terminal Ready (DTR); otherwise, . The default is . - - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. @@ -1285,19 +1285,19 @@ Indicates that an error has occurred with a port represented by a object. - enumeration. Because the operating system determines whether to raise this event or not, not all parity errors may be reported. - - , , and events may be called out of order, and there may be a slight delay between when the underlying stream reports the error and when code can when the event handler is executed. Only one event handler can execute at a time. - - If a parity error occurs on the trailing byte of a stream, an extra byte will be added to the input buffer with a value of 126. - - The event is raised on a secondary thread when an error is received from the object. Because this event is raised on a secondary thread, and not the main thread, attempting to modify some elements in the main thread, such as UI elements, could raise a threading exception. If it is necessary to modify elements in the main or , post change requests back using , which will do the work on the proper thread. - - For more information about handling events, see [Handling and Raising Events](/dotnet/standard/events/). - + enumeration. Because the operating system determines whether to raise this event or not, not all parity errors may be reported. + + , , and events may be called out of order, and there may be a slight delay between when the underlying stream reports the error and when code can when the event handler is executed. Only one event handler can execute at a time. + + If a parity error occurs on the trailing byte of a stream, an extra byte will be added to the input buffer with a value of 126. + + The event is raised on a secondary thread when an error is received from the object. Because this event is raised on a secondary thread, and not the main thread, attempting to modify some elements in the main thread, such as UI elements, could raise a threading exception. If it is necessary to modify elements in the main or , post change requests back using , which will do the work on the proper thread. + + For more information about handling events, see [Handling and Raising Events](/dotnet/standard/events/). + ]]> @@ -1328,24 +1328,24 @@ Gets an array of serial port names for the current computer. An array of serial port names for the current computer. - is not specified. - - Use the method to query the current computer for a list of valid serial port names. For example, you can use this method to determine whether COM1 and COM2 are valid serial ports for the current computer. - - The port names are obtained from the system registry (for example, HKEY_LOCAL_MACHINE\HARDWARE\DEVICEMAP\SERIALCOMM). If the registry contains stale or otherwise incorrect data then the method will return incorrect data. - - - -## Examples - The following code example uses the method to display serial port names to the console. - + is not specified. + + Use the method to query the current computer for a list of valid serial port names. For example, you can use this method to determine whether COM1 and COM2 are valid serial ports for the current computer. + + The port names are obtained from the system registry (for example, HKEY_LOCAL_MACHINE\HARDWARE\DEVICEMAP\SERIALCOMM). If the registry contains stale or otherwise incorrect data then the method will return incorrect data. + + + +## Examples + The following code example uses the method to display serial port names to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IO.Ports.GetPortNames/cpp/example.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/SerialPort/GetPortNames/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.Ports.GetPortNames/VB/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.Ports.GetPortNames/VB/example.vb" id="Snippet1"::: + ]]> The serial port names could not be queried. @@ -1394,28 +1394,28 @@ Gets or sets the handshaking protocol for serial port transmission of data using a value from . One of the values. The default is . - object is instructed to stop sending data when there is at least (-1024) bytes in the buffer. The device is instructed to start sending data again when there are 1024 or fewer bytes in the buffer. If the device is sending data in blocks that are larger than 1024 bytes, this may cause the buffer to overflow. - - If the property is set to and is set to `false`, the XOff character will not be sent. If is then set to `true`, more data must be sent before the XOff character will be sent. - - - -## Examples - The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. - + object is instructed to stop sending data when there is at least (-1024) bytes in the buffer. The device is instructed to start sending data again when there are 1024 or fewer bytes in the buffer. If the device is sending data in blocks that are larger than 1024 bytes, this may cause the buffer to overflow. + + If the property is set to and is set to `false`, the XOff character will not be sent. If is then set to `true`, more data must be sent before the XOff character will be sent. + + + +## Examples + The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/cpp/serialport.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/SerialPort.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: + ]]> - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. The value passed is not a valid value in the enumeration. @@ -1445,11 +1445,11 @@ Indicates that no time-out should occur. - and properties. - + and properties. + ]]> @@ -1486,11 +1486,11 @@ if the serial port is open; otherwise, . The default is . - property tracks whether the port is open for use by the caller, not whether the port is open by any application on the machine. - + property tracks whether the port is open for use by the caller, not whether the port is open by any application on the machine. + ]]> @@ -1538,11 +1538,11 @@ Gets or sets the value used to interpret the end of a call to the and methods. A value that represents the end of a line. The default is a line feed ("\n" in C# or in Visual Basic). - and methods. By default the end-of-line value is a line feed character (`\n` in C#, in Visual Basic). You would change this to a different value if the particular serial device you're working with uses a different value for the same purpose. - + and methods. By default the end-of-line value is a line feed character (`\n` in C#, in Visual Basic). You would change this to a different value if the particular serial device you're working with uses a different value for the same purpose. + ]]> The property value is empty. @@ -1574,39 +1574,39 @@ Opens a new serial port connection. - object. - - The best practice for any application is to wait for some amount of time after calling the method before attempting to call the method, as the port may not be closed instantly. - - - -## Examples - The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. - + object. + + The best practice for any application is to wait for some amount of time after calling the method before attempting to call the method, as the port may not be closed instantly. + + + +## Examples + The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/cpp/serialport.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/SerialPort.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: + ]]> - Access is denied to the port. - + Access is denied to the port. + -or- - + The current process, or another process on the system, already has the specified COM port open either by a instance or in unmanaged code. One or more of the properties for this instance are invalid. For example, the , , or properties are not valid values; the is less than or equal to zero; the or property is less than zero and is not . - The port name does not begin with "COM". - + The port name does not begin with "COM". + -or- - + The file type of the port is not supported. - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. The specified port on the current instance of the is already open. @@ -1654,28 +1654,28 @@ Gets or sets the parity-checking protocol. One of the enumeration values that represents the parity-checking protocol. The default is . - class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. - + class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/cpp/serialport.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/SerialPort.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: + ]]> - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. The value passed is not a valid value in the enumeration. @@ -1723,17 +1723,17 @@ Gets or sets the byte that replaces invalid bytes in a data stream when a parity error occurs. A byte that replaces invalid bytes. - - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. @@ -1768,19 +1768,19 @@ Indicates that a non-data signal event has occurred on the port represented by the object. - enumeration. Because the operating system determines whether to raise this event or not, not all parity errors may be reported. As part of the event, the new value of the pin is set. - - The event is raised when a object enters the , but not when the port exits the . This behavior does not apply to other values in the enumeration. - - , , and events may be called out of order, and there may be a slight delay between when the underlying stream reports the error and when the event handler is executed. Only one event handler can execute at a time. - - The event is raised on a secondary thread. Because this event is raised on a secondary thread, and not the main thread, attempting to modify some elements in the main thread, such as UI elements, could raise a threading exception. If it is necessary to modify elements in the main or , post change requests back using , which will do the work on the proper thread. - - For more information about handling events, see [Handling and Raising Events](/dotnet/standard/events/). - + enumeration. Because the operating system determines whether to raise this event or not, not all parity errors may be reported. As part of the event, the new value of the pin is set. + + The event is raised when a object enters the , but not when the port exits the . This behavior does not apply to other values in the enumeration. + + , , and events may be called out of order, and there may be a slight delay between when the underlying stream reports the error and when the event handler is executed. Only one event handler can execute at a time. + + The event is raised on a secondary thread. Because this event is raised on a secondary thread, and not the main thread, attempting to modify some elements in the main thread, such as UI elements, could raise a threading exception. If it is necessary to modify elements in the main or , post change requests back using , which will do the work on the proper thread. + + For more information about handling events, see [Handling and Raising Events](/dotnet/standard/events/). + ]]> @@ -1828,30 +1828,30 @@ Gets or sets the port for communications, including but not limited to all available COM ports. The communications port. The default is COM1. - method. - - - -## Examples - The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. - + method. + + + +## Examples + The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/cpp/serialport.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/SerialPort.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: + ]]> - The property was set to a value with a length of zero. - - -or- - - The property was set to a value that starts with "\\\\". - - -or- - + The property was set to a value with a length of zero. + + -or- + + The property was set to a value that starts with "\\\\". + + -or- + The port name was not valid. The property was set to . The specified port is open. @@ -1899,15 +1899,15 @@ Reads a number of bytes from the input buffer and writes those bytes into a byte array at the specified offset. The number of bytes read. - class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. - - The method does not block other operations when the number of bytes read equals `count` but there are still unread bytes available on the serial port. - + class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. + + The method does not block other operations when the number of bytes read equals `count` but there are still unread bytes available on the serial port. + ]]> The buffer passed is . @@ -1951,24 +1951,24 @@ Reads a number of characters from the input buffer and writes them into an array of characters at a given offset. The number of characters read. - class buffers data, and the stream contained in the property does not, the two might conflict about how many characters are available to read. The property can indicate that there are characters to read, but these characters might not be accessible to the stream contained in the property because they have been buffered to the class. - - The method does not block other operations when the number of bytes read equals `count` but there are still unread bytes available on the serial port. - + class buffers data, and the stream contained in the property does not, the two might conflict about how many characters are available to read. The property can indicate that there are characters to read, but these characters might not be accessible to the stream contained in the property because they have been buffered to the class. + + The method does not block other operations when the number of bytes read equals `count` but there are still unread bytes available on the serial port. + ]]> - plus is greater than the length of the buffer. - + plus is greater than the length of the buffer. + -or- - + is 1 and there is a surrogate character in the buffer. The passed is . The or parameters are outside a valid region of the being passed. Either or is less than zero. @@ -2019,13 +2019,13 @@ Gets or sets the size of the input buffer. The buffer size, in bytes. The default value is 4096; the maximum value is that of a positive int, or 2147483647. - property ignores any value smaller than 4096. - - Because the property represents only the Windows-created buffer, it can return a smaller value than the property, which represents both the buffer and the Windows-created buffer. - + property ignores any value smaller than 4096. + + Because the property represents only the Windows-created buffer, it can return a smaller value than the property, which represents both the buffer and the Windows-created buffer. + ]]> The value set is less than or equal to zero. @@ -2059,23 +2059,23 @@ Synchronously reads one byte from the input buffer. The byte, cast to an , or -1 if the end of the stream has been read. - and together. Switching between reading bytes and reading characters can cause extra data to be read and/or other unintended behavior. If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. - + and together. Switching between reading bytes and reading characters can cause extra data to be read and/or other unintended behavior. If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. + > [!NOTE] -> Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. - +> Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. + ]]> The specified port is not open. - The operation did not complete before the time-out period ended. - + The operation did not complete before the time-out period ended. + -or- - + No byte was read. @@ -2105,23 +2105,23 @@ Synchronously reads one character from the input buffer. The character that was read. - and together. Switching between reading bytes and reading characters can cause extra data to be read and/or other unintended behavior. If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. - + and together. Switching between reading bytes and reading characters can cause extra data to be read and/or other unintended behavior. If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. + > [!NOTE] -> Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. - +> Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. + ]]> The specified port is not open. - The operation did not complete before the time-out period ended. - + The operation did not complete before the time-out period ended. + -or- - + No character was available in the allotted time-out period. @@ -2151,16 +2151,16 @@ Reads all immediately available bytes, based on the encoding, in both the stream and the input buffer of the object. The contents of the stream and the input buffer of the object. - object as a string. This method does not use a time-out. Note that this method can leave trailing lead bytes in the internal buffer, which makes the value greater than zero. - - If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. - + object as a string. This method does not use a time-out. Note that this method can leave trailing lead bytes in the internal buffer, which makes the value greater than zero. + + If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. + > [!NOTE] -> The class buffers data, but the stream object contained in the property does not. Therefore, the object and the stream object might differ on the number of bytes that are available to read. When bytes are buffered to the object, the property includes these bytes in its value; however, these bytes might not be accessible to the stream contained in the property. - +> The class buffers data, but the stream object contained in the property does not. Therefore, the object and the stream object might differ on the number of bytes that are available to read. When bytes are buffered to the object, the property includes these bytes in its value; however, these bytes might not be accessible to the stream contained in the property. + ]]> The specified port is not open. @@ -2192,34 +2192,34 @@ Reads up to the value in the input buffer. The contents of the input buffer up to the first occurrence of a value. - value, the value is removed from the input buffer. - - By default, the method will block until a line is received. If this behavior is undesirable, set the property to any non-zero value to force the method to throw a if a line is not available on the port. - - If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. - + value, the value is removed from the input buffer. + + By default, the method will block until a line is received. If this behavior is undesirable, set the property to any non-zero value to force the method to throw a if a line is not available on the port. + + If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. + > [!NOTE] -> Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. - - - -## Examples - The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. This code example is part of a larger code example provided for the class. - +> Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. + + + +## Examples + The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. This code example is part of a larger code example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/cpp/serialport.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/SerialPort.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: + ]]> The specified port is not open. - The operation did not complete before the time-out period ended. - + The operation did not complete before the time-out period ended. + -or- - + No bytes were read. @@ -2266,31 +2266,31 @@ Gets or sets the number of milliseconds before a time-out occurs when a read operation does not finish. The number of milliseconds before a time-out occurs when a read operation does not finish. - , in which case no time-out occurs. is the default. - + , in which case no time-out occurs. is the default. + > [!NOTE] -> Users of the unmanaged `COMMTIMEOUTS` structure might expect to set the time-out value to zero to suppress time-outs. To suppress time-outs with the property, however, you must specify . - - This property does not affect the method of the stream returned by the property. - - - -## Examples - The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. - +> Users of the unmanaged `COMMTIMEOUTS` structure might expect to set the time-out value to zero to suppress time-outs. To suppress time-outs with the property, however, you must specify . + + This property does not affect the method of the stream returned by the property. + + + +## Examples + The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/cpp/serialport.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/SerialPort.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: + ]]> - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. The read time-out value is less than zero and not equal to . @@ -2324,16 +2324,16 @@ Reads a string up to the specified in the input buffer. The contents of the input buffer up to the specified . - [!NOTE] -> Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. - +> Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. + ]]> The length of the parameter is 0. @@ -2385,11 +2385,11 @@ Gets or sets the number of bytes in the internal input buffer before a event occurs. The number of bytes in the internal input buffer before a event is fired. The default is 1. - event is also raised if an character is received, regardless of the number of bytes in the internal input buffer and the value of the property. - + event is also raised if an character is received, regardless of the number of bytes in the internal input buffer and the value of the property. + ]]> The value is less than or equal to zero. @@ -2435,18 +2435,18 @@ to enable Request to Transmit (RTS); otherwise, . The default is . - The value of the property was set or retrieved while the property is set to the value or the value. - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. @@ -2493,35 +2493,35 @@ Gets or sets the standard number of stopbits per byte. One of the values. - is . - - The value is not supported. - - - -## Examples - The following example shows how to set the property to `One`. - + is . + + The value is not supported. + + + +## Examples + The following example shows how to set the property to `One`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/cpp/datareceived.cpp" id="Snippet20"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/datareceived.cs" id="Snippet20"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/datareceived.vb" id="Snippet20"::: - - The following example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger example provided for the class. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/datareceived.vb" id="Snippet20"::: + + The following example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/cpp/serialport.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/SerialPort.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: + ]]> The value is . - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. @@ -2562,15 +2562,15 @@ The string for output. Writes the specified string to the serial port. - is set to then the object may raise a while it waits for the device to be ready to accept more data. - - By default, uses to encode the characters. encodes all characters greater than 127 as (char)63 or '?'. To support additional characters in that range, set to , , or . - + is set to then the object may raise a while it waits for the device to be ready to accept more data. + + By default, uses to encode the characters. encodes all characters greater than 127 as (char)63 or '?'. To support additional characters in that range, set to , , or . + ]]> The specified port is not open. @@ -2611,12 +2611,12 @@ The number of bytes to write. Writes a specified number of bytes to the serial port using data from a buffer. - is set to then the object may raise a while it waits for the device to be ready to accept more data. + is set to then the object may raise a while it waits for the device to be ready to accept more data. ]]> The passed is . @@ -2659,15 +2659,15 @@ The number of characters to write. Writes a specified number of characters to the serial port using data from a buffer. - is set to then the object may raise a while it waits for the device to be ready to accept more data. - - By default, uses to encode the characters. encodes all characters greater than 127 as (char)63 or '?'. To support additional characters in that range, set to , , or . - + is set to then the object may raise a while it waits for the device to be ready to accept more data. + + By default, uses to encode the characters. encodes all characters greater than 127 as (char)63 or '?'. To support additional characters in that range, set to , , or . + ]]> The passed is . @@ -2721,11 +2721,11 @@ Gets or sets the size of the serial port output buffer. The size of the output buffer. The default is 2048. - property ignores any value smaller than 2048. - + property ignores any value smaller than 2048. + ]]> The value is less than or equal to zero. @@ -2761,22 +2761,22 @@ The string to write to the output buffer. Writes the specified string and the value to the output buffer. - is set to then the object may raise a while it waits for the device to be ready to accept more data. - - The written output includes the string. - - - -## Examples - The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. This code example is part of a larger code example provided for the class. - + is set to then the object may raise a while it waits for the device to be ready to accept more data. + + The written output includes the string. + + + +## Examples + The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. This code example is part of a larger code example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/cpp/serialport.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/SerialPort.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: + ]]> The parameter is . @@ -2827,31 +2827,31 @@ Gets or sets the number of milliseconds before a time-out occurs when a write operation does not finish. The number of milliseconds before a time-out occurs. The default is . - , in which case no time-out occurs. is the default. - + , in which case no time-out occurs. is the default. + > [!NOTE] -> Users of the unmanaged `COMMTIMEOUTS` structure might expect to set the time-out value to zero to suppress time-outs. To suppress time-outs with the property, however, you must specify . - - This property does not affect the method of the stream returned by the property. - - - -## Examples - The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. - +> Users of the unmanaged `COMMTIMEOUTS` structure might expect to set the time-out value to zero to suppress time-outs. To suppress time-outs with the property, however, you must specify . + + This property does not affect the method of the stream returned by the property. + + + +## Examples + The following code example demonstrates the use of the class to allow two users to chat from two separate computers connected by a null modem cable. In this example, the users are prompted for the port settings and a username before chatting. This code example is part of a larger code example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/cpp/serialport.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/SerialPort.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Ports.SerialPort/vb/SerialPort.vb" id="Snippet01"::: + ]]> - The port is in an invalid state. - + The port is in an invalid state. + -or- - + An attempt to set the state of the underlying port failed. For example, the parameters passed from this object were invalid. The value is less than zero and not equal to . diff --git a/xml/System.IO/BinaryReader.xml b/xml/System.IO/BinaryReader.xml index 18b8fe69371..e8c56a2019b 100644 --- a/xml/System.IO/BinaryReader.xml +++ b/xml/System.IO/BinaryReader.xml @@ -84,25 +84,25 @@ Reads primitive data types as binary values in a specific encoding. - class provides methods that simplify reading primitive data types from a stream. For example, you can use the method to read the next byte as a Boolean value and advance the current position in the stream by one byte. The class includes read methods that support different data types. - - When you create a new instance of the class, you provide the stream to read from, and optionally specify the type of encoding and whether to leave the stream open after disposing the object. If you do not specify an encoding type, UTF-8 is used. - + class provides methods that simplify reading primitive data types from a stream. For example, you can use the method to read the next byte as a Boolean value and advance the current position in the stream by one byte. The class includes read methods that support different data types. + + When you create a new instance of the class, you provide the stream to read from, and optionally specify the type of encoding and whether to leave the stream open after disposing the object. If you do not specify an encoding type, UTF-8 is used. + > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - - - -## Examples - The following code example demonstrates how to store and retrieve application settings in a file. - +> 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 demonstrates how to store and retrieve application settings in a file. + :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/Overview/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter/VB/source.vb" id="Snippet1"::: + ]]> How to: Read and Write to a Newly Created Data File @@ -175,20 +175,20 @@ The input stream. Initializes a new instance of the class based on the specified stream and using UTF-8 encoding. - The stream does not support reading, is , or is already closed. @@ -247,11 +247,11 @@ The character encoding to use. Initializes a new instance of the class based on the specified stream and character encoding. - The stream does not support reading, is , or is already closed. @@ -367,25 +367,25 @@ Exposes access to the underlying stream of the . The underlying stream associated with the . - [!CAUTION] -> Using the underlying stream while reading or while using the `BinaryReader` can cause data loss and corruption. For example, the same bytes might be read more than once, bytes might be skipped, or character reading might become unpredictable. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example shows how to read and write `Double` data to memory by using the `BinaryReader` and classes on top of the class. `MemoryStream` only reads and writes `Byte` data. - +> Using the underlying stream while reading or while using the `BinaryReader` can cause data loss and corruption. For example, the same bytes might be read more than once, bytes might be skipped, or character reading might become unpredictable. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example shows how to read and write `Double` data to memory by using the `BinaryReader` and classes on top of the class. `MemoryStream` only reads and writes `Byte` data. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWDouble/CPP/rwdouble.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/BaseStream/rwdouble.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/BaseStream/rwdouble.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWDouble/VB/rwdouble.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWDouble/VB/rwdouble.vb" id="Snippet1"::: + ]]> File and Stream I/O @@ -437,13 +437,13 @@ Closes the current reader and the underlying stream. - method passing a `true` value. - - Flushing the stream will not flush its underlying encoder unless you explicitly call or `Close`. 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. - + method passing a `true` value. + + Flushing the stream will not flush its underlying encoder unless you explicitly call or `Close`. 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. + ]]> File and Stream I/O @@ -516,16 +516,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. + ]]> @@ -581,20 +581,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the class and optionally releases the managed resources. - . By default, this method specifies the `disposing` parameter as `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. - + . By default, this method specifies the `disposing` parameter as `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. + ]]> - can be called multiple times by other objects. When overriding this method, be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement this method, see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + can be called multiple times by other objects. When overriding this method, be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement this method, see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources. File and Stream I/O How to: Read Text from a File @@ -651,13 +651,13 @@ The number of bytes to be read. Fills the internal buffer with the specified number of bytes read from the stream. - for the specified encoding. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + for the specified encoding. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The end of the stream is reached before could be read. @@ -716,13 +716,13 @@ Returns the next available character and does not advance the byte or character position. The next available character, or -1 if no more characters are available or the stream does not support seeking. - method, then set the stream back to the original position. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + method, then set the stream back to the original position. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> An I/O error occurred. @@ -791,23 +791,23 @@ Reads characters from the underlying stream and advances the current position of the stream in accordance with the used and the specific character being read from the stream. The next character from the input stream, or -1 if no characters are currently available. - does not restore the file position after an unsuccessful read. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example shows how to read and write data using memory as a backing store. This example displays a list of invalid file path characters to the console. Although the code tries to display a list of all invalid file path characters, not all of the characters are within the displayable set of characters. Because the list of invalid characters can vary based on the system, output for this code may also vary. - + does not restore the file position after an unsuccessful read. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example shows how to read and write data using memory as a backing store. This example displays a list of invalid file path characters to the console. Although the code tries to display a list of all invalid file path characters, not all of the characters are within the displayable set of characters. Because the list of invalid characters can vary based on the system, output for this code may also vary. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWChar2/CPP/rwreadchar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/Read/rwreadchar.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/Read/rwreadchar.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWChar2/VB/rwreadchar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWChar2/VB/rwreadchar.vb" id="Snippet1"::: + ]]> An I/O error occurred. @@ -977,34 +977,34 @@ Reads the specified number of bytes from the stream, starting from a specified point in the byte array. The number of bytes read into . This might be less than the number of bytes requested if that many bytes are not available, or it might be zero if the end of the stream is reached. - does not restore the file position after an unsuccessful read operation. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example shows how to write binary data by using memory as a backing store. It displays a message to the console that indicates whether the data was written correctly. - + does not restore the file position after an unsuccessful read operation. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example shows how to write binary data by using memory as a backing store. It displays a message to the console that indicates whether the data was written correctly. + :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/Read/rwreadbytes.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/Read/rwreadbytes.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWBytes2/VB/rwreadbytes.vb" id="Snippet1"::: - - This example reads the contents of a file and displays each byte's numeric value in 16-column format. The end of the file that is being read is detected when the method returns zero bytes. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWBytes2/VB/rwreadbytes.vb" id="Snippet1"::: + + This example reads the contents of a file and displays each byte's numeric value in 16-column format. The end of the file that is being read is detected when the method returns zero bytes. + :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/Overview/source5.cs" id="Snippet6"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/Overview/source5.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter/VB/source5.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter/VB/source5.vb" id="Snippet6"::: + ]]> - The buffer length minus is less than . - - -or- - + The buffer length minus is less than . + + -or- + The number of decoded characters to read is greater than . This can happen if a Unicode decoder returns fallback characters or a surrogate pair. is . @@ -1078,29 +1078,29 @@ Reads the specified number of characters from the stream, starting from a specified point in the character array. The total number of characters read into the buffer. This might be less than the number of characters requested if that many characters are not currently available, or it might be zero if the end of the stream is reached. - does not restore the file position after an unsuccessful read operation. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example shows how to read and write data using memory as a backing store. This example displays a list of invalid file path characters to the console. Although the code tries to display a list of all invalid file path characters, not all of the characters are within the displayable set of characters. Because the list of invalid characters can vary based on the system, output for this code may also vary. - + does not restore the file position after an unsuccessful read operation. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example shows how to read and write data using memory as a backing store. This example displays a list of invalid file path characters to the console. Although the code tries to display a list of all invalid file path characters, not all of the characters are within the displayable set of characters. Because the list of invalid characters can vary based on the system, output for this code may also vary. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWChars2/CPP/rwreadchars.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/Read/rwreadchars.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/Read/rwreadchars.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWChars2/VB/rwreadchars.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWChars2/VB/rwreadchars.vb" id="Snippet1"::: + ]]> - The buffer length minus is less than . - - -or- - + The buffer length minus is less than . + + -or- + The number of decoded characters to read is greater than . This can happen if a Unicode decoder returns fallback characters or a surrogate pair. is . @@ -1169,15 +1169,15 @@ Reads in a 32-bit integer in compressed format. A 32-bit integer in compressed format. - does not restore the file position after an unsuccessful read. - - If the integer will fit in seven bits, the integer takes only one byte of space. The integer is expected to have been written through . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + does not restore the file position after an unsuccessful read. + + If the integer will fit in seven bits, the integer takes only one byte of space. The integer is expected to have been written through . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The end of the stream is reached. @@ -1282,22 +1282,22 @@ if the byte is nonzero; otherwise, . - does not restore the file position after an unsuccessful read. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example demonstrates how to store and retrieve application settings in a file. - + does not restore the file position after an unsuccessful read. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example demonstrates how to store and retrieve application settings in a file. + :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/Overview/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter/VB/source.vb" id="Snippet1"::: + ]]> The end of the stream is reached. @@ -1356,31 +1356,31 @@ Reads the next byte from the current stream and advances the current position of the stream by one byte. The next byte read from the current stream. - does not restore the file position after an unsuccessful read. - - Because of data formatting conflicts, using this method with the following encodings is not recommended: - -- UTF-7 - -- ISO-2022-JP - -- ISCII - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example shows how to write binary data using memory as a backing store, and then verify that the data was written correctly. - + does not restore the file position after an unsuccessful read. + + Because of data formatting conflicts, using this method with the following encodings is not recommended: + +- UTF-7 + +- ISO-2022-JP + +- ISCII + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example shows how to write binary data using memory as a backing store, and then verify that the data was written correctly. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWByte/CPP/rwbyte.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/ReadByte/rwbyte.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/ReadByte/rwbyte.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWByte/VB/rwbyte.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWByte/VB/rwbyte.vb" id="Snippet1"::: + ]]> The end of the stream is reached. @@ -1448,29 +1448,29 @@ Reads the specified number of bytes from the current stream into a byte array and advances the current position by that number of bytes. A byte array containing data read from the underlying stream. This might be less than the number of bytes requested if the end of the stream is reached. - does not restore the file position after an unsuccessful read operation. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example shows how to write binary data using memory as a backing store, and then verify that the data was written correctly. - + does not restore the file position after an unsuccessful read operation. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example shows how to write binary data using memory as a backing store, and then verify that the data was written correctly. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWBytes1/CPP/rwbytes.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/ReadBytes/rwbytes.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/ReadBytes/rwbytes.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWBytes1/VB/rwbytes.vb" id="Snippet1"::: - - This example reads the contents of a file and displays it to the console as dump text. The end of the file that is being read is detected when the length of the array returned from is zero. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWBytes1/VB/rwbytes.vb" id="Snippet1"::: + + This example reads the contents of a file and displays it to the console as dump text. The end of the file that is being read is detected when the length of the array returned from is zero. + :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/Overview/source5.cs" id="Snippet6"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/Overview/source5.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter/VB/source5.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter/VB/source5.vb" id="Snippet6"::: + ]]> The number of decoded characters to read is greater than . This can happen if a Unicode decoder returns fallback characters or a surrogate pair. @@ -1531,31 +1531,31 @@ Reads the next character from the current stream and advances the current position of the stream in accordance with the used and the specific character being read from the stream. A character read from the current stream. - method attempts to read a surrogate character in the stream an exception will be raised and the position in the stream will advance. The position is restored to the original location before was called if the stream is seekable; however, if the stream is unseekable, the position will not be corrected. If surrogate characters can be expected in the stream, use the method instead. - - Because of data formatting conflicts, using this method with the following encodings is not recommended: - -- UTF-7 - -- ISO-2022-JP - -- ISCII - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example shows how to read and write data using memory as a backing store. - + method attempts to read a surrogate character in the stream an exception will be raised and the position in the stream will advance. The position is restored to the original location before was called if the stream is seekable; however, if the stream is unseekable, the position will not be corrected. If surrogate characters can be expected in the stream, use the method instead. + + Because of data formatting conflicts, using this method with the following encodings is not recommended: + +- UTF-7 + +- ISO-2022-JP + +- ISCII + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example shows how to read and write data using memory as a backing store. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWChar1/CPP/rwchar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/ReadChar/rwchar.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/ReadChar/rwchar.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWChar1/VB/rwchar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWChar1/VB/rwchar.vb" id="Snippet1"::: + ]]> The end of the stream is reached. @@ -1625,23 +1625,23 @@ Reads the specified number of characters from the current stream, returns the data in a character array, and advances the current position in accordance with the used and the specific character being read from the stream. A character array containing data read from the underlying stream. This might be less than the number of characters requested if the end of the stream is reached. - does not restore the file position after an unsuccessful read operation. - - When reading from network streams, in some rare cases, the method might read an extra character from the stream if the was constructed with Unicode encoding. If this occurs, you can use the method to read a fixed-length byte array, and then pass that array to the method. - - - -## Examples - The following code example shows how to read and write data using memory as a backing store. - + does not restore the file position after an unsuccessful read operation. + + When reading from network streams, in some rare cases, the method might read an extra character from the stream if the was constructed with Unicode encoding. If this occurs, you can use the method to read a fixed-length byte array, and then pass that array to the method. + + + +## Examples + The following code example shows how to read and write data using memory as a backing store. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWChars1/CPP/rwchars.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/ReadChars/rwchars.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/ReadChars/rwchars.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWChars1/VB/rwchars.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWChars1/VB/rwchars.vb" id="Snippet1"::: + ]]> The number of decoded characters to read is greater than . This can happen if a Unicode decoder returns fallback characters or a surrogate pair. @@ -1703,13 +1703,13 @@ Reads a decimal value from the current stream and advances the current position of the stream by sixteen bytes. A decimal value read from the current stream. - does not restore the file position after an unsuccessful read. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + does not restore the file position after an unsuccessful read. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The end of the stream is reached. @@ -1774,25 +1774,25 @@ Reads an 8-byte floating point value from the current stream and advances the current position of the stream by eight bytes. An 8-byte floating point value read from the current stream. - does not restore the file position after an unsuccessful read. - - `BinaryReader` reads this data type in little-endian format. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example shows how to read and write `Double` data to memory by using the `BinaryReader` and classes on top of the class. `MemoryStream` only reads and writes `Byte` data. - + does not restore the file position after an unsuccessful read. + + `BinaryReader` reads this data type in little-endian format. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example shows how to read and write `Double` data to memory by using the `BinaryReader` and classes on top of the class. `MemoryStream` only reads and writes `Byte` data. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWDouble/CPP/rwdouble.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/BaseStream/rwdouble.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/BaseStream/rwdouble.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWDouble/VB/rwdouble.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWDouble/VB/rwdouble.vb" id="Snippet1"::: + ]]> The end of the stream is reached. @@ -1838,15 +1838,15 @@ Reads a 2-byte floating point value from the current stream and advances the current position of the stream by two bytes. A 2-byte floating point value read from the current stream. - does not restore the file position after an unsuccessful read. - - `BinaryReader` reads this data type in little-endian format. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + does not restore the file position after an unsuccessful read. + + `BinaryReader` reads this data type in little-endian format. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The end of the stream is reached. @@ -1911,15 +1911,15 @@ Reads a 2-byte signed integer from the current stream and advances the current position of the stream by two bytes. A 2-byte signed integer read from the current stream. - does not restore the file position after an unsuccessful read. - - `BinaryReader` reads this data type in little-endian format. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + does not restore the file position after an unsuccessful read. + + `BinaryReader` reads this data type in little-endian format. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The end of the stream is reached. @@ -1978,24 +1978,24 @@ Reads a 4-byte signed integer from the current stream and advances the current position of the stream by four bytes. A 4-byte signed integer read from the current stream. - does not restore the file position after an unsuccessful read. - - reads this data type in little-endian format. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example demonstrates how to store and retrieve application settings in a file. - + does not restore the file position after an unsuccessful read. + + reads this data type in little-endian format. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example demonstrates how to store and retrieve application settings in a file. + :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/Overview/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter/VB/source.vb" id="Snippet1"::: + ]]> The end of the stream is reached. @@ -2054,15 +2054,15 @@ Reads an 8-byte signed integer from the current stream and advances the current position of the stream by eight bytes. An 8-byte signed integer read from the current stream. - does not restore the file position after an unsuccessful read. - - `BinaryReader` reads this data type in little-endian format. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + does not restore the file position after an unsuccessful read. + + `BinaryReader` reads this data type in little-endian format. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The end of the stream is reached. @@ -2131,13 +2131,13 @@ Reads a signed byte from this stream and advances the current position of the stream by one byte. A signed byte read from the current stream. - does not restore the file position after an unsuccessful read. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + does not restore the file position after an unsuccessful read. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The end of the stream is reached. @@ -2202,24 +2202,24 @@ Reads a 4-byte floating point value from the current stream and advances the current position of the stream by four bytes. A 4-byte floating point value read from the current stream. - does not restore the file position after an unsuccessful read. - - `BinaryReader` reads this data type in little-endian format. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example demonstrates how to store and retrieve application settings in a file. - + does not restore the file position after an unsuccessful read. + + `BinaryReader` reads this data type in little-endian format. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example demonstrates how to store and retrieve application settings in a file. + :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/Overview/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter/VB/source.vb" id="Snippet1"::: + ]]> The end of the stream is reached. @@ -2284,22 +2284,22 @@ Reads a string from the current stream. The string is prefixed with the length, encoded as an integer seven bits at a time. The string being read. - does not restore the file position after an unsuccessful read. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example demonstrates how to store and retrieve application settings in a file. - + does not restore the file position after an unsuccessful read. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example demonstrates how to store and retrieve application settings in a file. + :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/Overview/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter/VB/source.vb" id="Snippet1"::: + ]]> The end of the stream is reached. @@ -2364,15 +2364,15 @@ Reads a 2-byte unsigned integer from the current stream using little-endian encoding and advances the position of the stream by two bytes. A 2-byte unsigned integer read from this stream. - does not restore the file position after an unsuccessful read. - - `BinaryReader` reads this data type in little-endian format. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + does not restore the file position after an unsuccessful read. + + `BinaryReader` reads this data type in little-endian format. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The end of the stream is reached. @@ -2437,15 +2437,15 @@ Reads a 4-byte unsigned integer from the current stream and advances the position of the stream by four bytes. A 4-byte unsigned integer read from this stream. - does not restore the file position after an unsuccessful read. - - `BinaryReader` reads this data type in little-endian format. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + does not restore the file position after an unsuccessful read. + + `BinaryReader` reads this data type in little-endian format. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The end of the stream is reached. @@ -2510,15 +2510,15 @@ Reads an 8-byte unsigned integer from the current stream and advances the position of the stream by eight bytes. An 8-byte unsigned integer read from this stream. - does not restore the file position after an unsuccessful read. - - `BinaryReader` reads this data type in little-endian format. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + does not restore the file position after an unsuccessful read. + + `BinaryReader` reads this data type in little-endian format. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The end of the stream is reached. @@ -2566,7 +2566,7 @@ allows the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). ]]> diff --git a/xml/System.IO/DirectoryInfo.xml b/xml/System.IO/DirectoryInfo.xml index e75d0ea6db1..341cb973f40 100644 --- a/xml/System.IO/DirectoryInfo.xml +++ b/xml/System.IO/DirectoryInfo.xml @@ -625,7 +625,7 @@ namespace ConsoleApp -or- - There is an open handle on the directory, and the operating system is Windows XP or earlier. This open handle can result from enumerating directories. For more information, see [How to: Enumerate Directories and Files](/dotnet/standard/io/how-to-enumerate-directories-and-files). + There is an open handle on the directory, and the operating system is Windows XP or earlier. This open handle can result from enumerating directories. For more information, see How to: Enumerate Directories and Files. The caller does not have the required permission. File and Stream I/O How to: Read Text from a File @@ -718,7 +718,7 @@ namespace ConsoleApp -or- - There is an open handle on the directory or on one of its files, and the operating system is Windows XP or earlier. This open handle can result from enumerating directories and files. For more information, see [How to: Enumerate Directories and Files](/dotnet/standard/io/how-to-enumerate-directories-and-files). + There is an open handle on the directory or on one of its files, and the operating system is Windows XP or earlier. This open handle can result from enumerating directories and files. For more information, see How to: Enumerate Directories and Files. The caller does not have the required permission. File and Stream I/O How to: Read Text from a File diff --git a/xml/System.IO/File.xml b/xml/System.IO/File.xml index 7151504094b..36859ba730c 100644 --- a/xml/System.IO/File.xml +++ b/xml/System.IO/File.xml @@ -2236,7 +2236,7 @@ An I/O error occurred. -or- - There is an open handle on the file, and the operating system is Windows XP or earlier. This open handle can result from enumerating directories and files. For more information, see [How to: Enumerate Directories and Files](/dotnet/standard/io/how-to-enumerate-directories-and-files). + There is an open handle on the file, and the operating system is Windows XP or earlier. This open handle can result from enumerating directories and files. For more information, see How to: Enumerate Directories and Files. is in an invalid format. The specified path, file name, or both exceed the system-defined maximum length. diff --git a/xml/System.IO/FileInfo.xml b/xml/System.IO/FileInfo.xml index 200048e4232..31e8a5a339e 100644 --- a/xml/System.IO/FileInfo.xml +++ b/xml/System.IO/FileInfo.xml @@ -810,7 +810,7 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. -or- - There is an open handle on the file, and the operating system is Windows XP or earlier. This open handle can result from enumerating directories and files. For more information, see [How to: Enumerate Directories and Files](/dotnet/standard/io/how-to-enumerate-directories-and-files). + There is an open handle on the file, and the operating system is Windows XP or earlier. This open handle can result from enumerating directories and files. For more information, see How to: Enumerate Directories and Files. The caller does not have the required permission. The path is a directory. File and Stream I/O diff --git a/xml/System.IO/FileStream.xml b/xml/System.IO/FileStream.xml index 19b7a098825..9554acde241 100644 --- a/xml/System.IO/FileStream.xml +++ b/xml/System.IO/FileStream.xml @@ -2350,9 +2350,9 @@ For an example of copying between two streams, see the - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + For more information about and , see Cleaning Up Unmanaged Resources. File and Stream I/O How to: Read Text from a File @@ -3795,7 +3795,7 @@ The following example shows how to read from a file asynchronously. The default implementation on creates a new single-byte array and then calls . While this is formally correct, it is inefficient. Any stream with an internal buffer should override this method and provide a much more efficient version that reads the buffer directly, avoiding the extra array allocation on every call. - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + For a list of common file and directory operations, see Common I/O Tasks. File and Stream I/O How to: Read Text from a File @@ -4578,7 +4578,7 @@ This method stores in the task it returns all non-usage exceptions that the meth The default implementation on creates a new single-byte array and then calls . While this is formally correct, it is inefficient. Any stream with an internal buffer should override this method and provide a much more efficient version that reads the buffer directly, avoiding the extra array allocation on every call. - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + For a list of common file and directory operations, see Common I/O Tasks. File and Stream I/O How to: Read Text from a File diff --git a/xml/System.IO/FileSystemInfo.xml b/xml/System.IO/FileSystemInfo.xml index 654d96eaa23..afbb5c8a7f0 100644 --- a/xml/System.IO/FileSystemInfo.xml +++ b/xml/System.IO/FileSystemInfo.xml @@ -646,7 +646,7 @@ On Unix platforms that do not support creation or birth time, this property retu Deletes a file or directory. To be added. The specified path is invalid; for example, it is on an unmapped drive. - There is an open handle on the file or directory, and the operating system is Windows XP or earlier. This open handle can result from enumerating directories and files. For more information, see [How to: Enumerate Directories and Files](/dotnet/standard/io/how-to-enumerate-directories-and-files). + There is an open handle on the file or directory, and the operating system is Windows XP or earlier. This open handle can result from enumerating directories and files. For more information, see How to: Enumerate Directories and Files. File and Stream I/O How to: Read Text from a File @@ -905,7 +905,7 @@ The `Extension` property returns the extension, Classes derived from can use the field to determine the full path of the object being manipulated. - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + For a list of common I/O tasks, see Common I/O Tasks. File and Stream I/O diff --git a/xml/System.IO/FileSystemWatcher.xml b/xml/System.IO/FileSystemWatcher.xml index 4982d16a4e4..2cac8527682 100644 --- a/xml/System.IO/FileSystemWatcher.xml +++ b/xml/System.IO/FileSystemWatcher.xml @@ -724,9 +724,9 @@ - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + For more information about and , see Cleaning Up Unmanaged Resources. diff --git a/xml/System.IO/MemoryStream.xml b/xml/System.IO/MemoryStream.xml index 8462f2e9f22..5218c0530bb 100644 --- a/xml/System.IO/MemoryStream.xml +++ b/xml/System.IO/MemoryStream.xml @@ -85,28 +85,28 @@ Creates a stream whose backing store is memory. - method. When a new instance of is created, the current position is set to zero. - + method. When a new instance of is created, the current position is set to zero. + [!INCLUDE[note_unnecessary_dispose](~/includes/note-unnecessary-dispose.md)] - - Memory streams created with an unsigned byte array provide a non-resizable stream of the data. When using a byte array, you can neither append to nor shrink the stream, although you might be able to modify the existing contents depending on the parameters passed into the constructor. Empty memory streams are resizable, and can be written to and read from. - - If a object is added to a ResX file or a .resources file, call the method at runtime to retrieve it. - - If a object is serialized to a resource file it will actually be serialized as an . This behavior provides better performance, as well as the ability to get a pointer to the data directly, without having to go through methods. - - - -## Examples - The following code example shows how to read and write data using memory as a backing store. - + + Memory streams created with an unsigned byte array provide a non-resizable stream of the data. When using a byte array, you can neither append to nor shrink the stream, although you might be able to modify the existing contents depending on the parameters passed into the constructor. Empty memory streams are resizable, and can be written to and read from. + + If a object is added to a ResX file or a .resources file, call the method at runtime to retrieve it. + + If a object is serialized to a resource file it will actually be serialized as an . This behavior provides better performance, as well as the ability to get a pointer to the data directly, without having to go through methods. + + + +## Examples + The following code example shows how to read and write data using memory as a backing store. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.MemoryStream/CPP/memstream.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/MemoryStream/Overview/memstream.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet1"::: + ]]> File and Stream I/O @@ -168,15 +168,15 @@ Initializes a new instance of the class with an expandable capacity initialized to zero. - , , and properties are all set to `true`. - - The capacity of the current stream automatically increases when you use the method to set the length to a value larger than the capacity of the current stream. - - This constructor exposes the underlying stream, which returns. - + , , and properties are all set to `true`. + + The capacity of the current stream automatically increases when you use the method to set the length to a value larger than the capacity of the current stream. + + This constructor exposes the underlying stream, which returns. + ]]> File and Stream I/O @@ -237,15 +237,15 @@ The array of unsigned bytes from which to create the current stream. Initializes a new non-resizable instance of the class based on the specified byte array. - , , and properties are all set to `true`. is set to the length of the specified byte array. The new stream can be written to, but is not resizable. - - The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). - - This constructor does not expose the underlying stream. throws . - + , , and properties are all set to `true`. is set to the length of the specified byte array. The new stream can be written to, but is not resizable. + + The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). + + This constructor does not expose the underlying stream. throws . + ]]> @@ -302,24 +302,24 @@ The initial size of the internal array in bytes. Initializes a new instance of the class with an expandable capacity initialized as specified. - , , and properties are all set to `true`. - - The capacity automatically increases when you use the method to set the length to a value larger than the capacity of the current stream. Except for a `MemoryStream` constructed with a byte[] parameter, write operations at the end of a `MemoryStream` expand the `MemoryStream`. - - This constructor exposes the underlying stream that returns. - - - -## Examples - This code example is part of a larger example provided for the class. - + , , and properties are all set to `true`. + + The capacity automatically increases when you use the method to set the length to a value larger than the capacity of the current stream. Except for a `MemoryStream` constructed with a byte[] parameter, write operations at the end of a `MemoryStream` expand the `MemoryStream`. + + This constructor exposes the underlying stream that returns. + + + +## Examples + This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.MemoryStream/CPP/memstream.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.IO/MemoryStream/Overview/memstream.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet2"::: + ]]> @@ -378,15 +378,15 @@ The setting of the property, which determines whether the stream supports writing. Initializes a new non-resizable instance of the class based on the specified byte array with the property set as specified. - and properties are both set to `true`. is set to the length of the specified byte array. - - The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). - - This constructor does not expose the underlying stream. throws . - + and properties are both set to `true`. is set to the length of the specified byte array. + + The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). + + This constructor does not expose the underlying stream. throws . + ]]> @@ -447,15 +447,15 @@ The length of the stream in bytes. Initializes a new non-resizable instance of the class based on the specified region (index) of a byte array. - , , and properties are all set to `true`, but the capacity cannot be changed. is set to `count`. - - The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). - - This constructor does not expose the underlying stream. throws . However, you can write to the stream. - + , , and properties are all set to `true`, but the capacity cannot be changed. is set to `count`. + + The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). + + This constructor does not expose the underlying stream. throws . However, you can write to the stream. + ]]> @@ -521,15 +521,15 @@ The setting of the property, which determines whether the stream supports writing. Initializes a new non-resizable instance of the class based on the specified region of a byte array, with the property set as specified. - and properties are both set to `true`. is set to `count`. - - The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). - - This constructor does not expose the underlying stream. throws . However, you can write to the stream if `writable` is `true`. - + and properties are both set to `true`. is set to `count`. + + The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). + + This constructor does not expose the underlying stream. throws . However, you can write to the stream if `writable` is `true`. + ]]> @@ -597,13 +597,13 @@ to enable , which returns the unsigned byte array from which the stream was created; otherwise, . Initializes a new instance of the class based on the specified region of a byte array, with the property set as specified, and the ability to call set as specified. - and properties are both set to `true`. is set to `count`. - - The new stream instance can be written to, but the of the underlying byte array cannot be changed. The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). - + and properties are both set to `true`. is set to `count`. + + The new stream instance can be written to, but the of the underlying byte array cannot be changed. The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). + ]]> @@ -826,13 +826,13 @@ Refer to the remarks for additional usage if the stream is open. - does not support reading, calls to the and methods throw a . - - If the stream is closed, this property returns `false`. - + does not support reading, calls to the and methods throw a . + + If the stream is closed, this property returns `false`. + ]]> File and Stream I/O @@ -888,13 +888,13 @@ Refer to the remarks for additional usage if the stream is open. - does not support seeking, calls to , , , and throw a . - - If the stream is closed, this property returns `false`. - + does not support seeking, calls to , , , and throw a . + + If the stream is closed, this property returns `false`. + ]]> File and Stream I/O @@ -950,13 +950,13 @@ Refer to the remarks for additional usage if the stream supports writing; otherwise, . - does not support writing, a call to , , or throws a . - - If the stream is closed, this property returns `false`. - + does not support writing, a call to , , or throws a . + + If the stream is closed, this property returns `false`. + ]]> File and Stream I/O @@ -1017,20 +1017,20 @@ Refer to the remarks for additional usage Gets or sets the number of bytes allocated for this stream. The length of the usable portion of the buffer for the stream. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.MemoryStream/CPP/memstream.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.IO/MemoryStream/Overview/memstream.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet5"::: + ]]> A capacity is set that is negative or less than the current length of the stream. @@ -1075,7 +1075,7 @@ Refer to the remarks for additional usage . The buffer is still available on a once the stream has been closed. @@ -1084,7 +1084,7 @@ Flushing the stream will not flush its underlying encoder unless you explicitly Attempting to manipulate a stream after it has been closed might throw an . -## Examples +## Examples This code example is part of a larger example provided for the class. ```vb @@ -1267,20 +1267,20 @@ The stream is unwritable. to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the class and optionally releases the managed resources. - method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. - - When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. - + method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. + + When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources. @@ -1456,13 +1456,13 @@ The pending operation does not support writing. Overrides the method so that no action is performed. - method. - - Because any data written to a object is written into RAM, this method is redundant. - + method. + + Because any data written to a object is written into RAM, this method is redundant. + ]]> File and Stream I/O @@ -1525,15 +1525,15 @@ The pending operation does not support writing. Asynchronously clears all buffers for this stream, and monitors cancellation requests. A task that represents the asynchronous flush operation. - object is written into RAM, this method is redundant. - - If the operation is canceled before it completes, the returned task contains the value for the property. - - You can create a cancellation token by creating an instance of the class and passing the property as the `cancellationToken` parameter. - + object is written into RAM, this method is redundant. + + If the operation is canceled before it completes, the returned task contains the value for the property. + + You can create a cancellation token by creating an instance of the class and passing the property as the `cancellationToken` parameter. + 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 . ]]> @@ -1594,18 +1594,18 @@ The pending operation does not support writing. Returns the array of unsigned bytes from which this stream was created. The byte array from which this stream was created, or the underlying array if a byte array was not provided to the constructor during construction of the current instance. - object, the length of the buffer returned from is 256, not 4, with 252 bytes unused. To obtain only the data in the buffer, use the method; however, creates a copy of the data in memory. - - The buffer can also be `null`. - - To create a `MemoryStream` instance with a publicly visible buffer, use , , or . If the current stream is resizable, two calls to this method do not return the same array if the underlying byte array is resized between calls. For additional information, see . - + object, the length of the buffer returned from is 256, not 4, with 252 bytes unused. To obtain only the data in the buffer, use the method; however, creates a copy of the data in memory. + + The buffer can also be `null`. + + To create a `MemoryStream` instance with a publicly visible buffer, use , , or . If the current stream is resizable, two calls to this method do not return the same array if the underlying byte array is resized between calls. For additional information, see . + > [!NOTE] -> This method works when the memory stream is closed. - +> This method works when the memory stream is closed. + ]]> The instance was not created with a publicly visible buffer. @@ -1667,15 +1667,15 @@ The pending operation does not support writing. Gets the length of the stream in bytes. The length of the stream in bytes. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.MemoryStream/CPP/memstream.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.IO/MemoryStream/Overview/memstream.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet5"::: + ]]> The stream is closed. @@ -1771,15 +1771,15 @@ The pending operation does not support writing. Gets or sets the current position within the stream. The current position within the stream. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.MemoryStream/CPP/memstream.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.IO/MemoryStream/Overview/memstream.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet5"::: + ]]> The position is set to a negative value or a value greater than Int32.MaxValue. @@ -1908,31 +1908,31 @@ The pending operation does not support writing. Reads a block of bytes from the current stream and writes the data to a buffer. The total number of bytes written into the buffer. This can be less than the number of bytes requested if that number of bytes are not currently available, or zero if the end of the stream is reached before any bytes are read. - . - - The `offset` parameter gives the offset of the first byte in `buffer` to which data from the current stream is written. The `count` parameter gives the maximum number of bytes to read from the current stream. The returned value is the actual number of bytes read, or zero if the end of the stream is reached. - - If the read operation is successful, the current position within the stream advances by the number of bytes read. If an exception occurs, the current position within the stream remains unchanged. - - The `Read` method will return zero only if the end of the stream is reached. In all other cases, `Read` always reads at least one byte from the stream before returning. By definition, if no data is available from the stream upon a call to `Read`, the `Read` method returns zero (the end of the stream is reached automatically). An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. - - Use for reading primitive data types. - + . + + The `offset` parameter gives the offset of the first byte in `buffer` to which data from the current stream is written. The `count` parameter gives the maximum number of bytes to read from the current stream. The returned value is the actual number of bytes read, or zero if the end of the stream is reached. + + If the read operation is successful, the current position within the stream advances by the number of bytes read. If an exception occurs, the current position within the stream remains unchanged. + + The `Read` method will return zero only if the end of the stream is reached. In all other cases, `Read` always reads at least one byte from the stream before returning. By definition, if no data is available from the stream upon a call to `Read`, the `Read` method returns zero (the end of the stream is reached automatically). An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. + + Use for reading primitive data types. + > [!CAUTION] -> If the byte array specified in the `buffer` parameter is the underlying buffer returned by the method, the array contents are overwritten, and no exception is thrown. - - - -## Examples - This code example is part of a larger example provided for the class. - +> If the byte array specified in the `buffer` parameter is the underlying buffer returned by the method, the array contents are overwritten, and no exception is thrown. + + + +## Examples + This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.MemoryStream/CPP/memstream.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.IO/MemoryStream/Overview/memstream.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet7"::: + ]]> @@ -2066,13 +2066,13 @@ The pending operation does not support writing. Asynchronously reads a sequence of bytes from the current stream, advances the position within the stream by the number of bytes read, and monitors cancellation requests. A task that represents the asynchronous read operation. The value of the parameter contains the total number of bytes read into the buffer. The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) if the end of the stream has been reached. - value for the property. - - You can create a cancellation token by creating an instance of the class and passing the property as the `cancellationToken` parameter. - + value for the property. + + You can create a cancellation token by creating an instance of the class and passing the property as the `cancellationToken` parameter. + 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 . ]]> @@ -2136,22 +2136,22 @@ The pending operation does not support writing. Reads a byte from the current stream. The byte cast to a , or -1 if the end of the stream has been reached. - . - - If the read operation is successful, the current position within the stream is advanced by one byte. If an exception occurs, the current position within the stream is unchanged. - - - -## Examples - This code example is part of a larger example provided for the class. - + . + + If the read operation is successful, the current position within the stream is advanced by one byte. If an exception occurs, the current position within the stream is unchanged. + + + +## Examples + This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.MemoryStream/CPP/memstream.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.IO/MemoryStream/Overview/memstream.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet8"::: + ]]> The current stream instance is closed. @@ -2213,33 +2213,33 @@ The pending operation does not support writing. Sets the position within the current stream to the specified value. The new position within the stream, calculated by combining the initial reference point and the offset. - . - - Seeking to any location beyond the length of the stream is supported. - - Do not use the method to determine the new position in the stream if the was initialized with a non-zero offset. If you do, will return an inaccurate value. Instead, use the property to get the new position of the stream. - - - -## Examples - This code example is part of a larger example provided for the class. - + . + + Seeking to any location beyond the length of the stream is supported. + + Do not use the method to determine the new position in the stream if the was initialized with a non-zero offset. If you do, will return an inaccurate value. Instead, use the property to get the new position of the stream. + + + +## Examples + This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.MemoryStream/CPP/memstream.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.IO/MemoryStream/Overview/memstream.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet6"::: + ]]> Seeking is attempted before the beginning of the stream. is greater than Int32.MaxValue. - There is an invalid . - - -or- - + There is an invalid . + + -or- + caused an arithmetic overflow. The current stream instance is closed. File and Stream I/O @@ -2297,22 +2297,22 @@ The pending operation does not support writing. The value at which to set the length. Sets the length of the current stream to the specified value. - . - - If the specified value is less than the current length of the stream, the stream is truncated. If after the truncation the current position within the stream is past the end of the stream, the method returns -1, the method reads zero bytes into the provided byte array, and and methods append specified bytes at the end of the stream, increasing its length. If the specified value is larger than the current capacity and the stream is resizable, the capacity is increased, and the current position within the stream is unchanged. If the length is increased, the contents of the stream between the old and the new length are initialized to zeros. - + . + + If the specified value is less than the current length of the stream, the stream is truncated. If after the truncation the current position within the stream is past the end of the stream, the method returns -1, the method reads zero bytes into the provided byte array, and and methods append specified bytes at the end of the stream, increasing its length. If the specified value is larger than the current capacity and the stream is resizable, the capacity is increased, and the current position within the stream is unchanged. If the length is increased, the contents of the stream between the old and the new length are initialized to zeros. + > [!NOTE] -> A instance must support writing for this method to work. Use the property to determine whether the current instance supports writing. For additional information, see . - +> A instance must support writing for this method to work. Use the property to determine whether the current instance supports writing. For additional information, see . + ]]> - The current stream is not resizable and is larger than the current capacity. - - -or- - + The current stream is not resizable and is larger than the current capacity. + + -or- + The current stream does not support writing. is negative or is greater than the maximum length of the , where the maximum length is (Int32.MaxValue - origin), and origin is the index into the underlying buffer at which the stream starts. @@ -2375,16 +2375,16 @@ The pending operation does not support writing. Writes the stream contents to a byte array, regardless of the property. A new byte array. - from the array. To get the entire buffer, use the method. - - This method returns a copy of the contents of the as a byte array. If the current instance was constructed on a provided byte array, a copy of the section of the array to which this instance has access is returned. See the constructor for details. - + from the array. To get the entire buffer, use the method. + + This method returns a copy of the contents of the as a byte array. If the current instance was constructed on a provided byte array, a copy of the section of the array to which this instance has access is returned. See the constructor for details. + > [!NOTE] -> This method works when the is closed. - +> This method works when the is closed. + ]]> File and Stream I/O @@ -2463,7 +2463,7 @@ The underlying buffer will not be exposed if the current `MemoryStream` instance - with the parameter `publiclyVisible` set to `false`. > [!NOTE] -> This method works when the memory stream is closed. +> This method works when the memory stream is closed. ]]> @@ -2585,32 +2585,32 @@ The underlying buffer will not be exposed if the current `MemoryStream` instance The maximum number of bytes to write. Writes a block of bytes to the current stream using data read from a buffer. - . - - The `offset` parameter gives the offset of the first byte in `buffer` to write from, and the `count` parameter gives the number of bytes to write. If the write operation is successful, the current position within the stream is advanced by the number of bytes written. If an exception occurs, the current position within the stream is unchanged. - - Except for a `MemoryStream` constructed with a byte[] parameter, write operations at the end of a `MemoryStream` expand the `MemoryStream`. - - - -## Examples - This code example is part of a larger example provided for the class. - + . + + The `offset` parameter gives the offset of the first byte in `buffer` to write from, and the `count` parameter gives the number of bytes to write. If the write operation is successful, the current position within the stream is advanced by the number of bytes written. If an exception occurs, the current position within the stream is unchanged. + + Except for a `MemoryStream` constructed with a byte[] parameter, write operations at the end of a `MemoryStream` expand the `MemoryStream`. + + + +## Examples + This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.MemoryStream/CPP/memstream.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.IO/MemoryStream/Overview/memstream.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet3"::: + ]]> is . - The stream does not support writing. For additional information see . - - -or- - + The stream does not support writing. For additional information see . + + -or- + The current position is closer than bytes to the end of the stream, and the capacity cannot be modified. subtracted from the buffer length is less than . @@ -2742,13 +2742,13 @@ The underlying buffer will not be exposed if the current `MemoryStream` instance Asynchronously writes a sequence of bytes to the current stream, advances the current position within this stream by the number of bytes written, and monitors cancellation requests. A task that represents the asynchronous write operation. - value for the property. - - You can create a cancellation token by creating an instance of the class and passing the property as the `cancellationToken` parameter. - + value for the property. + + You can create a cancellation token by creating an instance of the class and passing the property as the `cancellationToken` parameter. + 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 . ]]> @@ -2814,28 +2814,28 @@ The underlying buffer will not be exposed if the current `MemoryStream` instance The byte to write. Writes a byte to the current stream at the current position. - . - - Except for a `MemoryStream` constructed with a byte[] parameter, write operations at the end of a `MemoryStream` expand the `MemoryStream`. - - - -## Examples - This code example is part of a larger example provided for the class. - + . + + Except for a `MemoryStream` constructed with a byte[] parameter, write operations at the end of a `MemoryStream` expand the `MemoryStream`. + + + +## Examples + This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.MemoryStream/CPP/memstream.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.IO/MemoryStream/Overview/memstream.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.MemoryStream/VB/memstream.vb" id="Snippet4"::: + ]]> - The stream does not support writing. For additional information see . - - -or- - + The stream does not support writing. For additional information see . + + -or- + The current position is at the end of the stream, and the capacity cannot be modified. The current stream is closed. File and Stream I/O @@ -2893,11 +2893,11 @@ The underlying buffer will not be exposed if the current `MemoryStream` instance The stream to write this memory stream to. Writes the entire contents of this memory stream to another stream. - on the underlying buffer of this stream. - + on the underlying buffer of this stream. + ]]> diff --git a/xml/System.IO/Stream.xml b/xml/System.IO/Stream.xml index 8a9c8c9762d..6759890ec01 100644 --- a/xml/System.IO/Stream.xml +++ b/xml/System.IO/Stream.xml @@ -139,7 +139,7 @@ When you implement a derived class of , you must provide implementations for the and methods. The asynchronous methods , , and use the synchronous methods and in their implementations. Therefore, your implementations of and will work correctly with the asynchronous methods. The default implementations of and create a new single-element byte array, and then call your implementations of and . When you derive from , we recommend that you override these methods to access your internal buffer, if you have one, for substantially better performance. You must also provide implementations of , , , , , , , and . - Do not override the method, instead, put all the cleanup logic in the method. For more information, see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + Do not override the method, instead, put all the cleanup logic in the method. For more information, see Implementing a Dispose Method. @@ -699,7 +699,7 @@ ]]> - In derived classes, do not override the method, instead, put all of the cleanup logic in the method. For more information, see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + In derived classes, do not override the method, instead, put all of the cleanup logic in the method. For more information, see Implementing a Dispose Method. File and Stream I/O How to: Read Text from a File @@ -1364,9 +1364,9 @@ In derived classes, do not override the method, instead, put all of the Stream cleanup logic in the method. - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + For more information about and , see Cleaning Up Unmanaged Resources. diff --git a/xml/System.IO/StreamReader.xml b/xml/System.IO/StreamReader.xml index 3e4ccd47f35..78d06a10451 100644 --- a/xml/System.IO/StreamReader.xml +++ b/xml/System.IO/StreamReader.xml @@ -1541,9 +1541,9 @@ Following a call to , any operations on th ]]> - Dispose can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to Dispose[cref,...]. For more information about how to implement see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + Dispose can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to Dispose[cref,...]. For more information about how to implement see Implementing a Dispose Method. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + For more information about and , see Cleaning Up Unmanaged Resources. File and Stream I/O How to: Read Text from a File diff --git a/xml/System.IO/TextReader.xml b/xml/System.IO/TextReader.xml index 2ab8933f0d3..b77e58ee307 100644 --- a/xml/System.IO/TextReader.xml +++ b/xml/System.IO/TextReader.xml @@ -378,9 +378,9 @@ - can be called multiple times by other objects. When overriding this method, be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement this method, see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding this method, be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement this method, see Implementing a Dispose Method. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + For more information about and , see Cleaning Up Unmanaged Resources. File and Stream I/O How to: Read Text from a File diff --git a/xml/System.IO/TextWriter.xml b/xml/System.IO/TextWriter.xml index 8945092f6f8..02242904223 100644 --- a/xml/System.IO/TextWriter.xml +++ b/xml/System.IO/TextWriter.xml @@ -586,9 +586,9 @@ - can be called multiple times by other objects. When overriding this method, be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement this method, see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding this method, be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement this method, see Implementing a Dispose Method. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + For more information about and , see Cleaning Up Unmanaged Resources. File and Stream I/O How to: Read Text from a File diff --git a/xml/System.IO/UnmanagedMemoryAccessor.xml b/xml/System.IO/UnmanagedMemoryAccessor.xml index 3952583d88c..6ad18cc26ac 100644 --- a/xml/System.IO/UnmanagedMemoryAccessor.xml +++ b/xml/System.IO/UnmanagedMemoryAccessor.xml @@ -494,9 +494,9 @@ - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + For more information about and , see Cleaning Up Unmanaged Resources. diff --git a/xml/System.IO/UnmanagedMemoryStream.xml b/xml/System.IO/UnmanagedMemoryStream.xml index 8f97ed87a6b..f9033d6dc57 100644 --- a/xml/System.IO/UnmanagedMemoryStream.xml +++ b/xml/System.IO/UnmanagedMemoryStream.xml @@ -68,18 +68,18 @@ Provides access to unmanaged blocks of memory from managed code. - class. A block of unmanaged memory is allocated and de-allocated using the class. - - :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/Overview/sample.cs" id="Snippet1"::: - + +## Examples + The following code example demonstrates how to read from and write to unmanaged memory using the class. A block of unmanaged memory is allocated and de-allocated using the class. + + :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/Overview/sample.cs" id="Snippet1"::: + ]]> @@ -199,26 +199,26 @@ The length of the memory to use. Initializes a new instance of the class using the specified location and memory length. - class, and by default sets the property to `false` and the property to `true`. The property is set to the value of the `length` parameter and cannot be changed. - - - -## Examples - The following code example demonstrates how to read from and write to unmanaged memory using the class. A block of unmanaged memory is allocated and de-allocated using the class. - - :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: - + class, and by default sets the property to `false` and the property to `true`. The property is set to the value of the `length` parameter and cannot be changed. + + + +## Examples + The following code example demonstrates how to read from and write to unmanaged memory using the class. A block of unmanaged memory is allocated and de-allocated using the class. + + :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: + ]]> The user does not have the required permission. The value is . - The value is less than zero. - + The value is less than zero. + -or- - + The is large enough to cause an overflow. @@ -342,34 +342,34 @@ One of the values. Initializes a new instance of the class using the specified location, memory length, total amount of memory, and file access values. - , and properties. Note that specifying does not guarantee that the stream will be writable. The access parameters allow the implementer to create an object whose implementation can match the actual stream that is exposed. - - - -## Examples - The following code example demonstrates how to read from and write to unmanaged memory using the class. A block of unmanaged memory is allocated and de-allocated using the class. - - :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/Overview/sample.cs" id="Snippet1"::: - + , and properties. Note that specifying does not guarantee that the stream will be writable. The access parameters allow the implementer to create an object whose implementation can match the actual stream that is exposed. + + + +## Examples + The following code example demonstrates how to read from and write to unmanaged memory using the class. A block of unmanaged memory is allocated and de-allocated using the class. + + :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/Overview/sample.cs" id="Snippet1"::: + ]]> The user does not have the required permission. The value is . - The value is less than zero. - + The value is less than zero. + -or- - - The value is less than zero. - + + The value is less than zero. + -or- - + The value is greater than the value. @@ -487,18 +487,18 @@ if the object was created by a constructor with an parameter that did not include reading the stream and if the stream is closed; otherwise, . - class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method which checks the property before attempting to display the contents to the console. - - :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: - + class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method which checks the property before attempting to display the contents to the console. + + :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: + ]]> @@ -555,11 +555,11 @@ if the stream is closed; otherwise, . - @@ -616,18 +616,18 @@ if the object was created by a constructor with an parameter value that supports writing or was created by a constructor that had no parameters, or if the stream is closed; otherwise, . - class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method which checks the property before attempting to write the data to the stream. - - :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: - + class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method which checks the property before attempting to write the data to the stream. + + :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: + ]]> @@ -677,11 +677,11 @@ Gets the stream length (size) or the total amount of memory assigned to a stream (capacity). The size or capacity of the stream. - The stream is closed. @@ -742,20 +742,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. - - When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. - + method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. + + When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources. @@ -804,11 +804,11 @@ Overrides the method so that no action is performed. - base class. Since any data is written to RAM, this method is redundant. - + base class. Since any data is written to RAM, this method is redundant. + ]]> The stream is closed. @@ -872,11 +872,11 @@ Overrides the method so that the operation is cancelled if specified, but no other action is performed. A task that represents the asynchronous flush operation. - calls the method, which means that no action performed. - + calls the method, which means that no action performed. + 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 . ]]> @@ -958,22 +958,22 @@ constructor. It supports methods that need to initialize the pointer before setting stream variables and, therefore, cannot call the parameterized constructor. Such methods should use the parameterless constructor, , initialize the pointer, and then invoke the method. +This method is equivalent to the constructor. It supports methods that need to initialize the pointer before setting stream variables and, therefore, cannot call the parameterized constructor. Such methods should use the parameterless constructor, , initialize the pointer, and then invoke the method. ]]> The user does not have the required permission. The value is . - The value is less than zero. - + The value is less than zero. + -or- - - The value is less than zero. - + + The value is less than zero. + -or- - + The value is large enough to cause an overflow. @@ -1093,18 +1093,18 @@ This method is equivalent to the Gets the length of the data in a stream. The length of the data in the stream. - class. A block of unmanaged memory is allocated and de-allocated using the class. - - :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: - + class. A block of unmanaged memory is allocated and de-allocated using the class. + + :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: + ]]> The stream is closed. @@ -1165,13 +1165,13 @@ This method is equivalent to the Gets or sets the current position in a stream. The current position in the stream. - and methods. will return 0 and will throw a . This support is primarily for design and code compatibility with basic stream operations. - + and methods. will return 0 and will throw a . This support is primarily for design and code compatibility with basic stream operations. + ]]> The stream is closed. @@ -1236,11 +1236,11 @@ This method is equivalent to the Gets or sets a byte pointer to a stream based on the current position in the stream. A byte pointer. - property to zero, and then call this property. - + property to zero, and then call this property. + ]]> The current position is larger than the capacity of the stream. @@ -1364,33 +1364,33 @@ This method is equivalent to the Reads the specified number of bytes into the specified array. The total number of bytes read into the buffer. This can be less than the number of bytes requested if that many bytes are not currently available, or zero (0) if the end of the stream has been reached. - method returns zero only after reaching the end of the stream. Otherwise, always reads at least one byte from the stream before returning. If no data is available from the stream upon a call to , the method will block until at least one byte of data can be returned. An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. - - - -## Examples - The following code example demonstrates how to read from and write to unmanaged memory using the class. A block of unmanaged memory is allocated and de-allocated using the class. - - :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/Overview/sample.cs" id="Snippet1"::: - + method returns zero only after reaching the end of the stream. Otherwise, always reads at least one byte from the stream before returning. If no data is available from the stream upon a call to , the method will block until at least one byte of data can be returned. An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. + + + +## Examples + The following code example demonstrates how to read from and write to unmanaged memory using the class. A block of unmanaged memory is allocated and de-allocated using the class. + + :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/Overview/sample.cs" id="Snippet1"::: + ]]> The stream is closed. - The underlying memory does not support reading. - + The underlying memory does not support reading. + -or- - + The property is set to . The parameter is set to . - The parameter is less than zero. - + The parameter is less than zero. + -or- - + The parameter is less than zero. The length of the buffer array minus the parameter is less than the parameter. @@ -1505,11 +1505,11 @@ This method is equivalent to the Asynchronously reads the specified number of bytes into the specified array. A task that represents the asynchronous read operation. The value of the parameter contains the total number of bytes read into the buffer. The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) if the end of the stream has been reached. - of the property of the returned task. - + of the property of the returned task. + 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 . ]]> @@ -1569,25 +1569,25 @@ This method is equivalent to the Reads a byte from a stream and advances the position within the stream by one byte, or returns -1 if at the end of the stream. The unsigned byte cast to an object, or -1 if at the end of the stream. - class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method which checks the property before attempting to read and display the contents to the console. - - :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: - + class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method which checks the property before attempting to read and display the contents to the console. + + :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: + ]]> The stream is closed. - The underlying memory does not support reading. - + The underlying memory does not support reading. + -or- - + The current position is at the end of the stream. @@ -1642,11 +1642,11 @@ This method is equivalent to the Sets the current position of the current stream to the given value. The new position in the stream. - . - + . + ]]> An attempt was made to seek before the beginning of the stream. @@ -1710,26 +1710,26 @@ This method is equivalent to the The length of the stream. Sets the length of a stream to a specified value. - to work. - + to work. + ]]> An I/O error has occurred. The stream is closed. - The underlying memory does not support writing. - + The underlying memory does not support writing. + -or- - + An attempt is made to write to the stream and the property is . - The specified exceeds the capacity of the stream. - + The specified exceeds the capacity of the stream. + -or- - + The specified is negative. @@ -1845,33 +1845,33 @@ This method is equivalent to the The number of bytes to write to the current stream. Writes a block of bytes to the current stream using data from a buffer. - class. A block of unmanaged memory is allocated and de-allocated using the class. - - :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/Overview/sample.cs" id="Snippet1"::: - + class. A block of unmanaged memory is allocated and de-allocated using the class. + + :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/Overview/sample.cs" id="Snippet1"::: + ]]> The stream is closed. - The underlying memory does not support writing. - + The underlying memory does not support writing. + -or- - - An attempt is made to write to the stream and the property is . - + + An attempt is made to write to the stream and the property is . + -or- - - The value is greater than the capacity of the stream. - + + The value is greater than the capacity of the stream. + -or- - + The position is at the end of the stream capacity. An I/O error occurs. One of the specified parameters is less than zero. @@ -1997,11 +1997,11 @@ If an exception occurs during the write operation, it will be set as the Asynchronously writes a sequence of bytes to the current stream, advances the current position within this stream by the number of bytes written, and monitors cancellation requests. A task that represents the asynchronous write operation. - of the property of the returned task. - + of the property of the returned task. + 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 . ]]> @@ -2063,24 +2063,24 @@ If an exception occurs during the write operation, it will be set as the A byte value written to the stream. Writes a byte to the current position in the file stream. - class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method which checks the property before attempting to write the data to the stream. - - :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: - + class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method which checks the property before attempting to write the data to the stream. + + :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: + ]]> The stream is closed. - The underlying memory does not support writing. - + The underlying memory does not support writing. + -or- - - An attempt is made to write to the stream and the property is . - + + An attempt is made to write to the stream and the property is . + -or- - + The current position is at the end of the capacity of the stream. The supplied causes the stream exceed its maximum capacity. diff --git a/xml/System.IdentityModel.Services.Configuration/FederationConfiguration.xml b/xml/System.IdentityModel.Services.Configuration/FederationConfiguration.xml index 72a574392fa..c6eb496a810 100644 --- a/xml/System.IdentityModel.Services.Configuration/FederationConfiguration.xml +++ b/xml/System.IdentityModel.Services.Configuration/FederationConfiguration.xml @@ -16,11 +16,11 @@ Exposes properties that contain federation settings that control the behavior of the WS-Federation Authentication Module () and the Session Authentication Module () in web applications. - object that is accessed through the property. The first time the property is accessed a new instance is initialized from settings in the configuration file and the event is raised. You can use the properties and methods exposed by the class to modify or replace the object initialized from configuration in an event handler. This object is available through the property inside the event handler. - + object that is accessed through the property. The first time the property is accessed a new instance is initialized from settings in the configuration file and the event is raised. You can use the properties and methods exposed by the class to modify or replace the object initialized from configuration in an event handler. This object is available through the property inside the event handler. + ]]> @@ -33,13 +33,13 @@ Initializes a new instance of the class. - [!IMPORTANT] -> Before the new instance is used by any of the configured HTTP modules, call the method to ensure that the instance is properly initialized. - +> Before the new instance is used by any of the configured HTTP modules, call the method to ensure that the instance is properly initialized. + ]]> @@ -59,14 +59,14 @@ Initializes a new instance of the class by loading settings from the section of the configuration file. - ` configuration section. This constructor calls the constructor with the `loadConfig` parameter `true`. - + ` configuration section. This constructor calls the constructor with the `loadConfig` parameter `true`. + > [!WARNING] -> Before the new instance is used by any of the configured HTTP modules, call the method to ensure that the instance is properly initialized. - +> Before the new instance is used by any of the configured HTTP modules, call the method to ensure that the instance is properly initialized. + ]]> @@ -92,26 +92,26 @@ to initialize with settings loaded from the configuration file; to initialize to default values. Initializes a new instance of the class by optionally loading settings from the section of the configuration file. - [!WARNING] -> Before the new instance is used by any of the configured HTTP modules, call the method to ensure that the instance is properly initialized. - - The `system.identityModel` section must be specified in a `
` element under the `` element in the configuration file or an exception is thrown. - -``` - -
- -``` - - If `loadConfig` is `true` and only a single `` element is specified, settings are loaded using that element. If multiple `` elements are specified, the method attempts to load settings from the element that is unnamed of that has the . If such an element does not exist, the method returns without loading settings. This results in an exception when the method is called. - +> Before the new instance is used by any of the configured HTTP modules, call the method to ensure that the instance is properly initialized. + + The `system.identityModel` section must be specified in a `
` element under the `` element in the configuration file or an exception is thrown. + +``` + +
+ +``` + + If `loadConfig` is `true` and only a single `` element is specified, settings are loaded using that element. If multiple `` elements are specified, the method attempts to load settings from the element that is unnamed of that has the . If such an element does not exist, the method returns without loading settings. This results in an exception when the method is called. + > [!WARNING] -> Microsoft recommends that if you specify multiple `` elements in the `system.identityModel.services` configuration section that at least one of them is unnamed or has its name set to an empty string. - +> Microsoft recommends that if you specify multiple `` elements in the `system.identityModel.services` configuration section that at least one of them is unnamed or has its name set to an empty string. + ]]> The configuration section is not defined in the configuration file. @@ -134,36 +134,36 @@ The name of the element from which to load the configuration. - Initializes a new instance of the class from the [<federationConfiguration>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/federationconfiguration) element with the specified name. + Initializes a new instance of the class from the <federationConfiguration> element with the specified name. - [!WARNING] -> Before the new instance is used by any of the configured HTTP modules, call the method to ensure that the instance is properly initialized. - - If this constructor is called then a `` configuration section with a `` element that has the specified name must exist in the configuration file. - - Both the `system.identityModel` section and the `system.identityModel.services` must be specified in a `
` elements under the `` element in the configuration file or an exception is thrown. - -``` - -
-
- -``` - +> Before the new instance is used by any of the configured HTTP modules, call the method to ensure that the instance is properly initialized. + + If this constructor is called then a `` configuration section with a `` element that has the specified name must exist in the configuration file. + + Both the `system.identityModel` section and the `system.identityModel.services` must be specified in a `
` elements under the `` element in the configuration file or an exception is thrown. + +``` + +
+
+ +``` + ]]> - There is no section defined in the configuration file. - - -or- - - There is no section defined in the configuration file. - - -or- - + There is no section defined in the configuration file. + + -or- + + There is no section defined in the configuration file. + + -or- + There is no element with the specified name in the section. @@ -186,13 +186,13 @@ Gets or sets the cookie handler to be used by the Session Authentication Module (). The cookie handler to be used by the Session Authentication Module (SAM). - An attempt to set the property to occurs. @@ -235,7 +235,7 @@ System.String - Defines the name of the default [<federationConfiguration>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/federationconfiguration) element from which settings should be loaded. This is an empty string as the default element is unnamed. + Defines the name of the default <federationConfiguration> element from which settings should be loaded. This is an empty string as the default element is unnamed. To be added. @@ -258,11 +258,11 @@ Gets or sets the object associated with this instance. The identity configuration object associated with this instance. - An attempt to set the property to occurs. @@ -287,15 +287,15 @@ Initializes the current instance. - property before calling the method. This method sets the property is set `true`. - - The default implementation creates a default cookie handler if there is not one already configured through the property and calls the method on the identity configuration object that is configured through the property. You can override this method to modify this behavior or to provide additional initialization in derived classes. - - This method should be invoked before the class is used by the HTTP Modules to process incoming requests. - + property before calling the method. This method sets the property is set `true`. + + The default implementation creates a default cookie handler if there is not one already configured through the property and calls the method on the identity configuration object that is configured through the property. You can override this method to modify this behavior or to provide additional initialization in derived classes. + + This method should be invoked before the class is used by the HTTP Modules to process incoming requests. + ]]> The current instance has already been initialized (The property is .) @@ -321,13 +321,13 @@ if the configuration object has been configured; otherwise . - object has already been initialized. The method should be called once and only once. - - The `set` operation is `protected`. - + object has already been initialized. The method should be called once and only once. + + The `set` operation is `protected`. + ]]> @@ -354,15 +354,15 @@ The element to load settings from. Can be to load default values. Loads the properties for the current instance from the configuration file. This method is called by constructors that initialize the newly created from configuration settings. - method is called by the constructors to set the properties of the newly created object from the specified `` element. - - If `element` is `null`, the instance is loaded with default values. - - If there is no configuration file, or, if the named section does not exist, then no exception is thrown. Instead, the instance is loaded with default values. - + method is called by the constructors to set the properties of the newly created object from the specified `` element. + + If `element` is `null`, the instance is loaded with default values. + + If there is no configuration file, or, if the named section does not exist, then no exception is thrown. Instead, the instance is loaded with default values. + ]]> @@ -386,11 +386,11 @@ Gets the name associated with this instance. The name associated with this federation configuration instance. - @@ -414,11 +414,11 @@ Gets or sets the X.509 certificate used to sign WS-Federation protocol messages. The X.509 certificate used to sign WS-Federation protocol messages. - @@ -442,11 +442,11 @@ Gets or sets the configuration settings for the WS-Federation Authentication Module (). The configuration settings for the WS-Federation Authentication Module. - An attempt to set the property to occurs. diff --git a/xml/System.IdentityModel.Services/HttpModuleBase.xml b/xml/System.IdentityModel.Services/HttpModuleBase.xml index 7875d993745..8e48e144179 100644 --- a/xml/System.IdentityModel.Services/HttpModuleBase.xml +++ b/xml/System.IdentityModel.Services/HttpModuleBase.xml @@ -18,7 +18,7 @@ - The base class from which HTTP modules that are configurable with the [<system.identityModel.services>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/system-identitymodel-services) element () derive. + The base class from which HTTP modules that are configurable with the <system.identityModel.services> element () derive. To be added. @@ -61,11 +61,11 @@ Releases the resources (except memory) used by the current instance of the class. - @@ -117,13 +117,13 @@ The application object which contains this module. Initializes the HTTP module. - method by initializing the property to the value of the property, invoking the method, and then invoking the method. - - Derived classes override the and methods. - + method by initializing the property to the value of the property, invoking the method, and then invoking the method. + + Derived classes override the and methods. + ]]> @@ -150,11 +150,11 @@ The application object which contains this module. When overridden in a derived class, initializes the current module and prepares it to handle events from its ASP.NET application object. - method to load any additional configuration state as well as to register event handling methods with specific events raised by the object. When this method is called from the method, the property has already been initialized. You can get the configuration object that is in effect for this module from this property. The property should be used for all token processing in this module. - + method to load any additional configuration state as well as to register event handling methods with specific events raised by the object. When this method is called from the method, the property has already been initialized. You can get the configuration object that is in effect for this module from this property. The property should be used for all token processing in this module. + ]]> @@ -178,11 +178,11 @@ When overridden in a derived class, initializes module properties based on values in the object that is in effect for it. - method, the property has already been initialized. You can get the configuration object that is in effect for this module from this property. - + method, the property has already been initialized. You can get the configuration object that is in effect for this module from this property. + ]]> diff --git a/xml/System.Messaging/MessageEnumerator.xml b/xml/System.Messaging/MessageEnumerator.xml index 202deff330e..5e75d654ae9 100644 --- a/xml/System.Messaging/MessageEnumerator.xml +++ b/xml/System.Messaging/MessageEnumerator.xml @@ -25,33 +25,33 @@ Provides a forward-only cursor to enumerate through messages in a message queue. - for dynamic interaction with messages in a queue. Methods available through the class can return either a pointing to a dynamic list of messages in the queue, or an array that contains a copy at a given instant - a snapshot - of the queue at the time the specified method was called. - - Unlike a static snapshot, an enumerator allows you to modify the collection. Using a , you can remove messages from the queue, and the change is immediately reflected in the queue. - - An enumerator does not remove the messages from the queue when it queries the queue. It returns information about the message at the current cursor position, but it leaves the message in the queue. - - A is a cursor, initialized to the head of a dynamic list. The list order is the same as the order of the messages in the queue, according to message priority. You can move the cursor to the first message in the queue by calling . After the enumerator has been initialized, you can use to step forward through the remaining messages. You can specify whether to wait for a message to become available by passing a timeout into the method. - - Because the enumerator is dynamic, a message that is appended beyond the cursor's current position (for example, due to low priority), can be accessed by the enumerator. A message that is inserted before the cursor's current position cannot be accessed. It is not possible to step backward with a . A cursor allows forward-only movement. The method enables you to place the cursor back at the beginning of the queue. - - Instances of for a given queue work independently. You can create two instances that apply to the same queue. The changes that one makes to the messages in the queue will be reflected immediately in a second enumerator if the second enumerator is positioned before the first. However, if two enumerators have the same position and one of them removes the message at that position, an exception is thrown if the other enumerator attempts to get the value of the property on the now-deleted message. - + for dynamic interaction with messages in a queue. Methods available through the class can return either a pointing to a dynamic list of messages in the queue, or an array that contains a copy at a given instant - a snapshot - of the queue at the time the specified method was called. + + Unlike a static snapshot, an enumerator allows you to modify the collection. Using a , you can remove messages from the queue, and the change is immediately reflected in the queue. + + An enumerator does not remove the messages from the queue when it queries the queue. It returns information about the message at the current cursor position, but it leaves the message in the queue. + + A is a cursor, initialized to the head of a dynamic list. The list order is the same as the order of the messages in the queue, according to message priority. You can move the cursor to the first message in the queue by calling . After the enumerator has been initialized, you can use to step forward through the remaining messages. You can specify whether to wait for a message to become available by passing a timeout into the method. + + Because the enumerator is dynamic, a message that is appended beyond the cursor's current position (for example, due to low priority), can be accessed by the enumerator. A message that is inserted before the cursor's current position cannot be accessed. It is not possible to step backward with a . A cursor allows forward-only movement. The method enables you to place the cursor back at the beginning of the queue. + + Instances of for a given queue work independently. You can create two instances that apply to the same queue. The changes that one makes to the messages in the queue will be reflected immediately in a second enumerator if the second enumerator is positioned before the first. However, if two enumerators have the same position and one of them removes the message at that position, an exception is thrown if the other enumerator attempts to get the value of the property on the now-deleted message. + > [!NOTE] -> If you create an instance of with set to `true`, no other application can modify the messages in your enumerator while you have the connection to the queue. - - - -## Examples - The following example gets a dynamic list of messages in a queue and counts all messages with the property set to . - +> If you create an instance of with set to `true`, no other application can modify the messages in your enumerator while you have the connection to the queue. + + + +## Examples + The following example gets a dynamic list of messages in a queue and counts all messages with the property set to . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.GetMessageEnumerator/CPP/mqgetmessageenumerator.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageEnumerator/Overview/mqgetmessageenumerator.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetMessageEnumerator/VB/mqgetmessageenumerator.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetMessageEnumerator/VB/mqgetmessageenumerator.vb" id="Snippet1"::: + ]]> @@ -79,11 +79,11 @@ Frees the resources associated with the enumerator. - to release the resources associated with the handle. - + to release the resources associated with the handle. + ]]> @@ -110,17 +110,17 @@ Gets the current that this enumerator points to. The current message. - is not valid and will throw an exception if it is accessed. You must call to position the cursor at the first message in the queue. - + is not valid and will throw an exception if it is accessed. You must call to position the cursor at the first message in the queue. + ]]> - You called before the first call to . The cursor is located before the first element of the message enumeration. - - -or- - + You called before the first call to . The cursor is located before the first element of the message enumeration. + + -or- + You called after a call to had returned (indicating the cursor is located after the last element of the message enumeration.) The message the enumerator is currently pointing to no longer exists. It might have been deleted. @@ -149,11 +149,11 @@ Gets the native Message Queuing cursor handle used to browse messages in the queue. The native cursor handle. - to release this resource. - + to release this resource. + ]]> The handle does not exist. @@ -193,11 +193,11 @@ Releases all resources used by the . - allows the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - + allows the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + ]]> Cleaning Up Unmanaged Resources @@ -228,20 +228,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method and the method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + method and the method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. Implementing a Dispose method Cleaning Up Unmanaged Resources @@ -269,7 +269,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. For more information, see [Finalize Methods and Destructors](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/0s71x931(v=vs.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)). @@ -314,15 +314,15 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro if the enumerator was successfully advanced to the next message; if the enumerator has reached the end of the queue. - for a message to arrive. - - If a message is not currently available because the queue is empty or because you have moved beyond the last element in the collection, returns `false` to the calling method. - - Upon creation, an enumerator is conceptually positioned before the first message of the queue, and the first call to brings the first message of the queue into view. - + for a message to arrive. + + If a message is not currently available because the queue is empty or because you have moved beyond the last element in the collection, returns `false` to the calling method. + + Upon creation, an enumerator is conceptually positioned before the first message of the queue, and the first call to brings the first message of the queue into view. + ]]> An exception specific to Message Queuing was thrown. @@ -357,22 +357,22 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro if the enumerator successfully advanced to the next message; if the enumerator has reached the end of the queue and a message does not become available within the time specified by the parameter. - waits the specified timeout. - - If the cursor is already at the end of the queue, only returns `true` if the new message arrives within the specified time interval, has lower priority than all messages currently in the queue and is placed at the end of the queue. An overload with no parameter returns immediately if no further messages are in the queue. - - Upon creation, an enumerator is conceptually positioned before the first message of the enumeration, and the first call to brings the first message of the enumeration into view. - + waits the specified timeout. + + If the cursor is already at the end of the queue, only returns `true` if the new message arrives within the specified time interval, has lower priority than all messages currently in the queue and is placed at the end of the queue. An overload with no parameter returns immediately if no further messages are in the queue. + + Upon creation, an enumerator is conceptually positioned before the first message of the enumeration, and the first call to brings the first message of the enumeration into view. + ]]> The value specified for the timeout parameter is invalid. It might represent a negative number. - An exception specific to Message Queuing was thrown. - - -or- - + An exception specific to Message Queuing was thrown. + + -or- + The timeout has expired. @@ -387,11 +387,11 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro Removes the current message from the queue and returns the message to the calling application. Removing the message deletes it from the queue. - instance is retrieved by using the . Do not use to retrieve an instance of as this method has been deprecated. - + instance is retrieved by using the . Do not use to retrieve an instance of as this method has been deprecated. + ]]> @@ -418,17 +418,17 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro Removes the current message from a transactional or non-transactional queue and returns the message to the calling application. There is no timeout specified for a message to arrive in the queue. A that references the first message available in the queue. - removes and returns the message at the cursor's current location. - - If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. - - When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . - - If you call this overload on a transactional queue, Message Queuing creates a single internal transaction. - + removes and returns the message at the cursor's current location. + + If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. + + When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . + + If you call this overload on a transactional queue, Message Queuing creates a single internal transaction. + ]]> @@ -460,17 +460,17 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro Removes the current message from a transactional queue and returns the message to the calling application. There is no timeout specified for a message to arrive in the queue. A that references the first message available in the queue. - removes and returns the message at the cursor's current location, using the internal transaction context defined by the `transaction` parameter. - - If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. - - When working with transactional queues, a rollback of a transaction causes any messages removed by a call to to be returned to the queue. The removal is not irreversible until the transaction is committed. - - When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . - + removes and returns the message at the cursor's current location, using the internal transaction context defined by the `transaction` parameter. + + If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. + + When working with transactional queues, a rollback of a transaction causes any messages removed by a call to to be returned to the queue. The removal is not irreversible until the transaction is committed. + + When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . + ]]> The parameter is . @@ -504,19 +504,19 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro Removes the current message from a queue and returns the message to the calling application. There is no timeout specified for a message to arrive in the queue. A that references the first message available in the queue. - removes and returns the message at the cursor's current location, using a transaction context defined by the `transactionType` parameter. - - Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. - - If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. - - When working with transactional queues, a rollback of a transaction causes any messages removed by a call to to be returned to the queue. The removal is not irreversible until the transaction is committed. - - When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . - + removes and returns the message at the cursor's current location, using a transaction context defined by the `transactionType` parameter. + + Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. + + If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. + + When working with transactional queues, a rollback of a transaction causes any messages removed by a call to to be returned to the queue. The removal is not irreversible until the transaction is committed. + + When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . + ]]> The parameter is not one of the members. @@ -550,17 +550,17 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro Removes the current message from the queue and returns the message to the calling application. If there is a message to remove, the method returns it immediately. Otherwise, the method waits the specified timeout for a new message to arrive. A that references the first message available in the queue. - removes and returns the message at the cursor's current location. If the cursor is at the end of the queue, this overload of the method waits until a message is available or the interval specified by the `timeout` parameter has expired. - - If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. - - When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . - - If you call this overload on a transactional queue, Message Queuing creates a single internal transaction. - + removes and returns the message at the cursor's current location. If the cursor is at the end of the queue, this overload of the method waits until a message is available or the interval specified by the `timeout` parameter has expired. + + If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. + + When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . + + If you call this overload on a transactional queue, Message Queuing creates a single internal transaction. + ]]> The value specified for the parameter is invalid. @@ -596,17 +596,17 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro Removes the current message from a transactional queue and returns the message to the calling application. If there is a message to remove, the method returns it immediately. Otherwise, the method waits the specified timeout for a new message to arrive. A that references the first message available in the queue. - removes and returns the message at the cursor's current location. If the cursor is at the end of the queue, this overload of the method waits until a message is available or the interval specified by the `timeout` parameter has expired. - - When working with transactional queues, a rollback of a transaction causes any messages removed by a call to to be returned to the queue. The removal is not irreversible until the transaction is committed. - - If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. - - When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . - + removes and returns the message at the cursor's current location. If the cursor is at the end of the queue, this overload of the method waits until a message is available or the interval specified by the `timeout` parameter has expired. + + When working with transactional queues, a rollback of a transaction causes any messages removed by a call to to be returned to the queue. The removal is not irreversible until the transaction is committed. + + If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. + + When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . + ]]> The value specified for the parameter is invalid. @@ -644,19 +644,19 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro Removes the current message from a queue and returns the message to the calling application. If there is a message to remove, the method returns it immediately. Otherwise, the method waits the specified timeout for a new message to arrive. A that references the first message available in the queue. - removes and returns the message at the cursor's current location, using a transaction context defined by the `transactionType` parameter. If the cursor is at the end of the queue, this overload of the method waits until a message is available or the interval specified by the `timeout` parameter has expired. - - Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. - - If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. - - When working with transactional queues, a rollback of a transaction causes any messages removed by a call to to be returned to the queue. The removal is not irreversible until the transaction is committed. - - When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . - + removes and returns the message at the cursor's current location, using a transaction context defined by the `transactionType` parameter. If the cursor is at the end of the queue, this overload of the method waits until a message is available or the interval specified by the `timeout` parameter has expired. + + Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. + + If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. + + When working with transactional queues, a rollback of a transaction causes any messages removed by a call to to be returned to the queue. The removal is not irreversible until the transaction is committed. + + When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . + ]]> The value specified for the parameter is invalid. @@ -691,13 +691,13 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro Resets the current enumerator so it points to the head of the queue. - , the cursor points to the first message. You do not need to call after calling to move the cursor forward to the first message in the queue. - + , the cursor points to the first message. You do not need to call after calling to move the cursor forward to the first message in the queue. + ]]> diff --git a/xml/System.Messaging/MessageQueueEnumerator.xml b/xml/System.Messaging/MessageQueueEnumerator.xml index 39528f479ad..8d5004ed6fe 100644 --- a/xml/System.Messaging/MessageQueueEnumerator.xml +++ b/xml/System.Messaging/MessageQueueEnumerator.xml @@ -25,24 +25,24 @@ Provides a forward-only cursor to enumerate through messages in a message queue. - for dynamic interaction with queues on the network. Methods available through the class can return either a containing a dynamic list of queues, or an array that contains a snapshot of the queue collection at the time the specified method was called. - - There is no defined ordering of queues in a network. They are not ordered, for example, by computer, label, public or private status, or other user-accessible criteria. A is a cursor, initialized to the head of a dynamic list. You can move the cursor to the first queue of the enumeration by calling . After the enumerator has been initialized, you can use to step forward through the remaining queues. - - It is not possible to step backward with a . A cursor only allows forward movement through the queue enumeration. However, you can call to reset the enumeration and put the cursor at the beginning of the list again. Because the enumerator is dynamic, a queue that is appended beyond the cursor's current position can be accessed by the enumerator. A queue that is inserted before the cursor's current position cannot be accessed without first calling Reset. - - - -## Examples - The following code example iterates through all the message queues in the network, and examines the path for each queue. Finally, it displays the number of public queues on the network. - + for dynamic interaction with queues on the network. Methods available through the class can return either a containing a dynamic list of queues, or an array that contains a snapshot of the queue collection at the time the specified method was called. + + There is no defined ordering of queues in a network. They are not ordered, for example, by computer, label, public or private status, or other user-accessible criteria. A is a cursor, initialized to the head of a dynamic list. You can move the cursor to the first queue of the enumeration by calling . After the enumerator has been initialized, you can use to step forward through the remaining queues. + + It is not possible to step backward with a . A cursor only allows forward movement through the queue enumeration. However, you can call to reset the enumeration and put the cursor at the beginning of the list again. Because the enumerator is dynamic, a queue that is appended beyond the cursor's current position can be accessed by the enumerator. A queue that is inserted before the cursor's current position cannot be accessed without first calling Reset. + + + +## Examples + The following code example iterates through all the message queues in the network, and examines the path for each queue. Finally, it displays the number of public queues on the network. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.GetMessageQueueEnumerator_noparms/CPP/mqgetmessagequeueenumerator.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetMessageQueueEnumerator/mqgetmessagequeueenumerator.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetMessageQueueEnumerator_noparms/VB/mqgetmessagequeueenumerator.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetMessageQueueEnumerator_noparms/VB/mqgetmessagequeueenumerator.vb" id="Snippet1"::: + ]]> @@ -70,11 +70,11 @@ Frees the resources associated with the enumerator. - , to the queue enumerator during the lifetime of the cursor. When you finish working with the enumerator, call to release the resources associated with the handle. - + , to the queue enumerator during the lifetime of the cursor. When you finish working with the enumerator, call to release the resources associated with the handle. + ]]> @@ -101,19 +101,19 @@ Gets the current of the enumeration. The queue at which the cursor is currently positioned. - is not valid and will throw an exception if it is accessed. You must call to position the cursor at the first queue in the enumeration. - - Multiple calls to with no intervening calls to will return the same object. - + is not valid and will throw an exception if it is accessed. You must call to position the cursor at the first queue in the enumeration. + + Multiple calls to with no intervening calls to will return the same object. + ]]> - You called before the first call to . The cursor is located before the first queue in the enumeration. - - -or- - + You called before the first call to . The cursor is located before the first queue in the enumeration. + + -or- + You called after a call to had returned false (indicating the cursor is located after the last queue in the enumeration). @@ -152,11 +152,11 @@ Releases all resources used by the . - allows the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - + allows the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + ]]> Cleaning Up Unmanaged Resources @@ -187,20 +187,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method and the method, if it has been overridden. `Dispose` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + method and the method, if it has been overridden. `Dispose` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. Implementing a Dispose method Cleaning Up Unmanaged Resources @@ -228,7 +228,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. For more information, see [Finalize Methods and Destructors](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/0s71x931(v=vs.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)). @@ -258,11 +258,11 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro Gets the native Message Queuing handle used to locate queues in a network. The native handle to the current queue. - instance, call to free this handle to the resource. - + instance, call to free this handle to the resource. + ]]> The handle does not exist. @@ -296,15 +296,15 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro if the enumerator was successfully advanced to the next queue; if the enumerator has reached the end of the enumeration. - returns `false` immediately if there are no queues associated with the enumeration. - - will return `true` until it has reached the end of the collection. It will then return `false` for each successive call. However once has returned `false`, accessing the property will throw an exception. - - Upon creation, an enumerator is conceptually positioned before the first of the enumeration, and the first call to brings the first queue of the enumeration into view. - + returns `false` immediately if there are no queues associated with the enumeration. + + will return `true` until it has reached the end of the collection. It will then return `false` for each successive call. However once has returned `false`, accessing the property will throw an exception. + + Upon creation, an enumerator is conceptually positioned before the first of the enumeration, and the first call to brings the first queue of the enumeration into view. + ]]> The calling code does not have browse permissions. @@ -337,13 +337,13 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro Resets the cursor, so it points to the beginning of the enumeration. - positions the cursor at the first queue in the list. You do not need to call after calling to move the cursor forward to the first queue in the enumeration. - + positions the cursor at the first queue in the list. You do not need to call after calling to move the cursor forward to the first queue in the enumeration. + ]]> diff --git a/xml/System.Messaging/MessageQueueTransaction.xml b/xml/System.Messaging/MessageQueueTransaction.xml index 12ab156b5e0..d85680c2408 100644 --- a/xml/System.Messaging/MessageQueueTransaction.xml +++ b/xml/System.Messaging/MessageQueueTransaction.xml @@ -22,24 +22,24 @@ Provides a Message Queuing internal transaction. - class to create a transaction and pass it to an overload of the method or the method that takes a `transaction` parameter. Messages sent as part of a transaction must be sent to transactional queues. Messages received from transactional queues must be received using a specified transaction. - - In addition to the method, you can receive messages with a specified identifier or specified correlation identifier. See the and methods for more information about selectively receiving messages from transactional queues. - - Messages sent to transactional queues are removed if the transaction is committed. Similarly, messages received from transactional queues are returned to the queue if the transaction is rolled back. - - If you instantiate a and pass it to an applicable overload of the method or method to send a message to a non-transactional queue or receive a message from a non-transactional queue, the method throws an exception that indicates "Wrong Transaction Usage." - - is threading apartment aware, so if your apartment state is `STA`, you cannot use the transaction in multiple threads. Visual Basic sets the state of the main thread to `STA`, so you must apply the in the `Main` subroutine. Otherwise, sending a transactional message using another thread throws a exception. You apply the by using the following fragment. - -```vb - - public sub Main() -``` - + class to create a transaction and pass it to an overload of the method or the method that takes a `transaction` parameter. Messages sent as part of a transaction must be sent to transactional queues. Messages received from transactional queues must be received using a specified transaction. + + In addition to the method, you can receive messages with a specified identifier or specified correlation identifier. See the and methods for more information about selectively receiving messages from transactional queues. + + Messages sent to transactional queues are removed if the transaction is committed. Similarly, messages received from transactional queues are returned to the queue if the transaction is rolled back. + + If you instantiate a and pass it to an applicable overload of the method or method to send a message to a non-transactional queue or receive a message from a non-transactional queue, the method throws an exception that indicates "Wrong Transaction Usage." + + is threading apartment aware, so if your apartment state is `STA`, you cannot use the transaction in multiple threads. Visual Basic sets the state of the main thread to `STA`, so you must apply the in the `Main` subroutine. Otherwise, sending a transactional message using another thread throws a exception. You apply the by using the following fragment. + +```vb + + public sub Main() +``` + ]]> This type is thread safe. @@ -64,11 +64,11 @@ Initializes a new instance of the class. - property to `Initialized`. - + property to `Initialized`. + ]]> @@ -94,15 +94,15 @@ Rolls back the pending internal transaction. - marks the unsuccessful completion of a process begun at a call to . - - Typically, one makes a call to within a `Try...Catch` exception-handling block, putting a call to in the `Try` clause, and a call to in the `Catch` clause. - - rolls back the entire transaction. This includes all messages sent or received after the call to . - + marks the unsuccessful completion of a process begun at a call to . + + Typically, one makes a call to within a `Try...Catch` exception-handling block, putting a call to in the `Try` clause, and a call to in the `Catch` clause. + + rolls back the entire transaction. This includes all messages sent or received after the call to . + ]]> The internal transaction you are attempting to roll back has not started. @@ -133,13 +133,13 @@ Begins a new Message Queuing internal transaction. - marks the start of processing that will be committed or rolled back, depending on the success of the transaction. If an exception occurs during processing, the entire transaction is rolled back. This includes all messages sent or received after the call to . - - Typically, one makes a call to within a `Try...Catch` exception-handling block, putting a call to in the `Try` clause, and a call to in the `Catch` clause. - + marks the start of processing that will be committed or rolled back, depending on the success of the transaction. If an exception occurs during processing, the entire transaction is rolled back. This includes all messages sent or received after the call to . + + Typically, one makes a call to within a `Try...Catch` exception-handling block, putting a call to in the `Try` clause, and a call to in the `Catch` clause. + ]]> The transaction has already been started. @@ -170,13 +170,13 @@ Commits a pending internal transaction. - marks the successful completion of processing begun at a call to . If an exception occurs between the call the and the call to , the entire transaction is rolled back. This includes all messages sent or received after the call to . - - Typically, one makes a call to within a `Try...Catch` exception-handling block, putting a call to in the `Try` clause, and a call to in the `Catch` clause. - + marks the successful completion of processing begun at a call to . If an exception occurs between the call the and the call to , the entire transaction is rolled back. This includes all messages sent or received after the call to . + + Typically, one makes a call to within a `Try...Catch` exception-handling block, putting a call to in the `Try` clause, and a call to in the `Catch` clause. + ]]> The transaction you are trying to commit has not started. @@ -219,13 +219,13 @@ Releases all resources used by the . - 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). - - Any pending internal transactions are rolled back by . - + 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). + + Any pending internal transactions are rolled back by . + ]]> @@ -255,20 +255,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method and the method, if it has been overridden. `Dispose` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + method and the method, if it has been overridden. `Dispose` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -293,13 +293,13 @@ Releases the resources held by the current instance. - . Application code should not call this method; an object's 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)). - + . Application code should not call this method; an object's 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)). + ]]> @@ -325,11 +325,11 @@ Gets the status of the transaction. One of the values that indicates whether the transaction has been committed, aborted, initialized, or is pending. - class has been created, the is set by the constructor to `Initialized`. After a call to but before a call to or , the is `Pending`. - + class has been created, the is set by the constructor to `Initialized`. After a call to but before a call to or , the is `Pending`. + ]]> diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index 58830f23fc0..bd09926e03a 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -217,7 +217,7 @@ The specified `handler` will be disposed of by calling [HttpClient.Dispose](xref The responsible for processing the HTTP response messages. - if the inner handler should be disposed of by [HttpClient.Dispose](xref:System.Net.Http.HttpMessageInvoker.Dispose); if you intend to reuse the inner handler. + if the inner handler should be disposed of by HttpClient.Dispose; if you intend to reuse the inner handler. Initializes a new instance of the class with the provided handler, and specifies whether that handler should be disposed when this instance is disposed. To be added. The is . diff --git a/xml/System.Net.Mail/AlternateView.xml b/xml/System.Net.Mail/AlternateView.xml index 3bf374ff3fc..0d0be08db2c 100644 --- a/xml/System.Net.Mail/AlternateView.xml +++ b/xml/System.Net.Mail/AlternateView.xml @@ -51,13 +51,13 @@ Represents the format to view an email message. - class to specify copies of an email message in different formats. For example, if you send a message in HTML, you might also want provide a plain text version in case some of the recipients use email readers that cannot display HTML content. - - This class has two properties and that are used to resolve URLs within the content of the email. is a collection of objects. When rendered, URLs within the email's content are first matched against the URLs in the of each object in the collection, and resolved. is used by the mail reader to resolve relative URLs within the body, and also to resolve relative URLs, in the collection. - + class to specify copies of an email message in different formats. For example, if you send a message in HTML, you might also want provide a plain text version in case some of the recipients use email readers that cannot display HTML content. + + This class has two properties and that are used to resolve URLs within the content of the email. is a collection of objects. When rendered, URLs within the email's content are first matched against the URLs in the of each object in the collection, and resolved. is used by the mail reader to resolve relative URLs within the body, and also to resolve relative URLs, in the collection. + ]]> @@ -71,11 +71,11 @@ Initializes a new instance of . - class call also be initialized by calling one of the methods. - + class call also be initialized by calling one of the methods. + ]]> @@ -123,11 +123,11 @@ A stream that contains the content for this view. Initializes a new instance of with the specified . - class call also be initialized by calling one of the methods. - + class call also be initialized by calling one of the methods. + ]]> @@ -177,11 +177,11 @@ The name of the file that contains the content for this alternate view. Initializes a new instance of with the specified file name. - class call also be initialized by calling one of the methods. - + class call also be initialized by calling one of the methods. + ]]> @@ -244,11 +244,11 @@ The type of the content. Initializes a new instance of with the specified and . - class call also be initialized by calling one of the methods. - + class call also be initialized by calling one of the methods. + ]]> @@ -310,11 +310,11 @@ The MIME media type of the content. Initializes a new instance of with the specified and media type. - class call also be initialized by calling one of the methods. - + class call also be initialized by calling one of the methods. + ]]> @@ -376,11 +376,11 @@ The type of the content. Initializes a new instance of with the specified file name and content type. - class call also be initialized by calling one of the methods. - + class call also be initialized by calling one of the methods. + ]]> @@ -445,11 +445,11 @@ The MIME media type of the content. Initializes a new instance of with the specified file name and media type. - class call also be initialized by calling one of the methods. - + class call also be initialized by calling one of the methods. + ]]> @@ -566,11 +566,11 @@ Creates a of an email message using the content specified in a . An object that represents an alternate view of an email message. - @@ -737,20 +737,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. diff --git a/xml/System.Net.Mail/AttachmentBase.xml b/xml/System.Net.Mail/AttachmentBase.xml index bdddf90e652..599353c94a8 100644 --- a/xml/System.Net.Mail/AttachmentBase.xml +++ b/xml/System.Net.Mail/AttachmentBase.xml @@ -535,13 +535,13 @@ Releases the resources used by the . - 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. - + 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. + ]]> @@ -587,20 +587,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. diff --git a/xml/System.Net.Mail/MailMessage.xml b/xml/System.Net.Mail/MailMessage.xml index 588daa7fd0a..bed70405ce9 100644 --- a/xml/System.Net.Mail/MailMessage.xml +++ b/xml/System.Net.Mail/MailMessage.xml @@ -55,80 +55,80 @@ Represents an email message that can be sent using the class. - class are used to construct email messages that are transmitted to an SMTP server for delivery using the class. - - The sender, recipient, subject, and body of an email message may be specified as parameters when a is used to initialize a object. These parameters may also be set or accessed using properties on the object. - - The primary mail message headers and elements for the message may be set using the following properties of the class. - -|Mail header or part|Property| -|-------------------------|--------------| -|Attachments|| -|Blind carbon copies (BCC)|| -|Carbon copies (CC)|| -|Content-Type|| -|Encoding for custom headers|| -|Message body|| -|Priority|| -|Recipient|| -|Reply-To|| -|Sender|| -|Subject|| - - The class also allows an application to access the headers collection for the message using the property. While this collection is read-only (a new collection can not be set), custom headers can be added to or deleted from this collection. Any custom headers added will be included when the instance is sent. Before a message is sent, only headers specifically added to this collection in the property are included in the collection. After a the instance is sent, the property will also include headers that are set using the associated properties of the class or parameters passed when a is used to initialize a object. - - If some mail headers are malformed, they could cause the email message to become corrupted. So any mail header in the headers collection that can be set using a property on the class should only be set using the class property or as a parameter passed when a initializes a object. The following list of mail headers should not be added using the property and any values set for these headers using the property will be discarded or overwritten when the message is sent: - -- Bcc - -- Cc - -- Content-ID - -- Content-Location - -- Content-Transfer-Encoding - -- Content-Type - -- Date - -- From - -- Importance - -- MIME-Version - -- Priority - -- Reply-To - -- Sender - -- To - -- X-Priority - - If the application does not specify an X-Sender header using the property, the class will create one when the message is sent. - - Use the property to specify copies of an email message in different formats. For example, if you send a message in HTML, you might also want to provide a plain text version in case some of the recipients use email readers that cannot display HTML content. For an example that demonstrates creating a message with alternate views, see . - - Use the property to add attachments to an email message. For an example that demonstrates creating a message with an attachment, see . Calling Dispose on the MailMessage also calls Dispose on each referenced Attachment. - - After assembling your email message, you can send it by using the or methods. - - - -## Examples - The following code example demonstrates creating and sending an email message that includes an attachment. - + class are used to construct email messages that are transmitted to an SMTP server for delivery using the class. + + The sender, recipient, subject, and body of an email message may be specified as parameters when a is used to initialize a object. These parameters may also be set or accessed using properties on the object. + + The primary mail message headers and elements for the message may be set using the following properties of the class. + +|Mail header or part|Property| +|-------------------------|--------------| +|Attachments|| +|Blind carbon copies (BCC)|| +|Carbon copies (CC)|| +|Content-Type|| +|Encoding for custom headers|| +|Message body|| +|Priority|| +|Recipient|| +|Reply-To|| +|Sender|| +|Subject|| + + The class also allows an application to access the headers collection for the message using the property. While this collection is read-only (a new collection can not be set), custom headers can be added to or deleted from this collection. Any custom headers added will be included when the instance is sent. Before a message is sent, only headers specifically added to this collection in the property are included in the collection. After a the instance is sent, the property will also include headers that are set using the associated properties of the class or parameters passed when a is used to initialize a object. + + If some mail headers are malformed, they could cause the email message to become corrupted. So any mail header in the headers collection that can be set using a property on the class should only be set using the class property or as a parameter passed when a initializes a object. The following list of mail headers should not be added using the property and any values set for these headers using the property will be discarded or overwritten when the message is sent: + +- Bcc + +- Cc + +- Content-ID + +- Content-Location + +- Content-Transfer-Encoding + +- Content-Type + +- Date + +- From + +- Importance + +- MIME-Version + +- Priority + +- Reply-To + +- Sender + +- To + +- X-Priority + + If the application does not specify an X-Sender header using the property, the class will create one when the message is sent. + + Use the property to specify copies of an email message in different formats. For example, if you send a message in HTML, you might also want to provide a plain text version in case some of the recipients use email readers that cannot display HTML content. For an example that demonstrates creating a message with alternate views, see . + + Use the property to add attachments to an email message. For an example that demonstrates creating a message with an attachment, see . Calling Dispose on the MailMessage also calls Dispose on each referenced Attachment. + + After assembling your email message, you can send it by using the or methods. + + + +## Examples + The following code example demonstrates creating and sending an email message that includes an attachment. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLMailSync/CPP/NclMailSync.cpp" id="Snippet6"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet6"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet6"::: + ]]> @@ -176,11 +176,11 @@ Initializes an empty instance of the class. - @@ -224,27 +224,27 @@ A that contains the address of the recipient of the email message. Initializes a new instance of the class by using the specified class objects. - property is initialized using `from` and the property is initialized using `to`. - - - -## Examples - The following code example demonstrates calling this constructor. - + property is initialized using `from` and the property is initialized using `to`. + + + +## Examples + The following code example demonstrates calling this constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLMailSync/CPP/NclMailSync.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet4"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet4"::: + ]]> - is . - - -or- - + is . + + -or- + is . or is malformed. @@ -289,33 +289,33 @@ A that contains the addresses of the recipients of the email message. Multiple email addresses must be separated with a comma character (","). Initializes a new instance of the class by using the specified class objects. - property is initialized using `from` and the property is initialized using `to`. - - - -## Examples - The following code example demonstrates calling this constructor. - + property is initialized using `from` and the property is initialized using `to`. + + + +## Examples + The following code example demonstrates calling this constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLMailSync/CPP/NclMailSync.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet2"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet2"::: + ]]> - is . - - -or- - + is . + + -or- + is . - is (""). - - -or- - + is (""). + + -or- + is (""). or is malformed. @@ -379,42 +379,42 @@ A that contains the message body. Initializes a new instance of the class. - object are initialized as follows: - -|Parameter|Property| -|---------------|--------------| -|`from`|| -|`to`|| -|`subject`|| -|`body`|| - - By default, the subject and content are assumed to use the default encoding based on local computer settings. Use the and properties to specify different encodings. - - - -## Examples - The following code example demonstrates calling this constructor. - + object are initialized as follows: + +|Parameter|Property| +|---------------|--------------| +|`from`|| +|`to`|| +|`subject`|| +|`body`|| + + By default, the subject and content are assumed to use the default encoding based on local computer settings. Use the and properties to specify different encodings. + + + +## Examples + The following code example demonstrates calling this constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLMailSync/CPP/NclMailSync.cpp" id="Snippet3"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet3"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet3"::: + ]]> - is . - - -or- - + is . + + -or- + is . - is (""). - - -or- - + is (""). + + -or- + is (""). or is malformed. @@ -457,22 +457,22 @@ Gets the attachment collection used to store alternate forms of the message body. A writable . - property to specify copies of an email message in different formats. For example, if you send a message in HTML, you might also want to provide a plain text version in case some of the recipients use email readers that cannot display HTML content. - - To add an alternate view to a object, create an for the view, and then add it to the collection returned by . Use the property to specify the text version and use the collection to specify views with other MIME types. Use the class members to specify the MIME type for the alternate view. - - - -## Examples - The following code example demonstrates creating and sending an email message with a plain text and an HTML alternate view. - + property to specify copies of an email message in different formats. For example, if you send a message in HTML, you might also want to provide a plain text version in case some of the recipients use email readers that cannot display HTML content. + + To add an alternate view to a object, create an for the view, and then add it to the collection returned by . Use the property to specify the text version and use the collection to specify views with other MIME types. Use the class members to specify the MIME type for the alternate view. + + + +## Examples + The following code example demonstrates creating and sending an email message with a plain text and an HTML alternate view. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLMailSync/CPP/NclMailSync.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet5"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet5"::: + ]]> @@ -514,22 +514,22 @@ Gets the attachment collection used to store data attached to this email message. A writable . - property to add an attachment, such as a file or the contents of a , to this . - - Create an that contains or references the data to be attached, and then add the to the collection returned by . - - - -## Examples - The following code example demonstrates creating and sending an email message with an attachment. - + property to add an attachment, such as a file or the contents of a , to this . + + Create an that contains or references the data to be attached, and then add the to the collection returned by . + + + +## Examples + The following code example demonstrates creating and sending an email message with an attachment. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLMailSync/CPP/NclMailSync.cpp" id="Snippet6"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet6"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet6"::: + ]]> @@ -571,22 +571,22 @@ Gets the address collection that contains the blind carbon copy (BCC) recipients for this email message. A writable object. - for the recipient's address, and then add that object to the collection returned by the property. - - When recipients view an email message, the addresses are usually not displayed. - - - -## Examples - The following code example demonstrates adding an address to the address collection. - + for the recipient's address, and then add that object to the collection returned by the property. + + When recipients view an email message, the addresses are usually not displayed. + + + +## Examples + The following code example demonstrates adding an address to the address collection. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLMailSync/CPP/NclMailSync.cpp" id="Snippet9"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet9"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet9"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet9"::: + ]]> @@ -628,22 +628,22 @@ Gets or sets the message body. A value that contains the body text. - of the content is "text/plain". Specify the encoding used for the body with the property. - - If the body content is available in alternative formats that provide richer presentation options for the recipients, you can specify alternate views for the body content by using the property. For example, an application might choose to send both the plain text body and an HTML version of the message body. Email readers that can display HTML can present the HTML version of the body to the recipient, while readers that cannot display HTML will display the plain text version of the message instead. - - - -## Examples - The following code example demonstrates setting the property. - + of the content is "text/plain". Specify the encoding used for the body with the property. + + If the body content is available in alternative formats that provide richer presentation options for the recipients, you can specify alternate views for the body content by using the property. For example, an application might choose to send both the plain text body and an HTML version of the message body. Email readers that can display HTML can present the HTML version of the body to the recipient, while readers that cannot display HTML will display the plain text version of the message instead. + + + +## Examples + The following code example demonstrates setting the property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLMailSync/CPP/NclMailSync.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet2"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet2"::: + ]]> @@ -708,22 +708,22 @@ Gets or sets the encoding used to encode the message body. An applied to the contents of the . - property sets the character set field in the Content-Type header. The default character set is `"us-ascii"`. - - If you set the property to , , or , the Framework selects a of for this . - - - -## Examples - The following code example demonstrates creating a mail message that uses UTF8 encoding. - + property sets the character set field in the Content-Type header. The default character set is `"us-ascii"`. + + If you set the property to , , or , the Framework selects a of for this . + + + +## Examples + The following code example demonstrates creating a mail message that uses UTF8 encoding. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclMailASync/cpp/mailasync.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/MailAddress/.ctor/mailasync.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclMailASync/vb/mailasync.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclMailASync/vb/mailasync.vb" id="Snippet3"::: + ]]> @@ -807,20 +807,20 @@ Gets the address collection that contains the carbon copy (CC) recipients for this email message. A writable object. - for the recipient's address and then add that object to the collection returned by the property. - - - -## Examples - The following code example demonstrates adding an address to the address collection. - + for the recipient's address and then add that object to the collection returned by the property. + + + +## Examples + The following code example demonstrates adding an address to the address collection. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLMailSync/CPP/NclMailSync.cpp" id="Snippet10"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet10"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet10"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet10"::: + ]]> @@ -926,19 +926,19 @@ Releases all resources used by the . - method 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). - + method 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 . - - - -## Examples - The following code example demonstrates disposing a . - +> Always call before you release your last reference to the . + + + +## Examples + The following code example demonstrates disposing a . + ]]> @@ -984,20 +984,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -1053,20 +1053,20 @@ Gets or sets the from address for this email message. A that contains the from address information. - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLMailSync/CPP/NclMailSync.cpp" id="Snippet10"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet10"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet10"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet10"::: + ]]> @@ -1108,72 +1108,72 @@ Gets the email headers that are transmitted with this email message. A that contains the email headers. - property allows an application to access the headers collection for the message. While this collection is read-only (a new collection can not be set), custom headers can be added to or deleted from this collection. Any custom headers added will be included when the instance is sent. Before a message is sent, only headers specifically added to this collection in the property are included in the collection. After the instance is sent, the property will also include headers that are set using the associated properties of the class or parameters passed when a is used to initialize a object. - - If some mail headers are malformed, they could cause the email message to become corrupted. So any mail header in the headers collection that can be set using a property on the class should only be set using the class property or as a parameter passed when a initializes a object. The following list of mail headers should not be added using the property and any values set for these headers using the property will be discarded or overwritten when the message is sent: - -- Bcc - -- Cc - -- Content-ID - -- Content-Location - -- Content-Transfer-Encoding - -- Content-Type - -- Date - -- From - -- Importance - -- MIME-Version - -- Priority - -- Reply-To - -- Sender - -- To - -- X-Priority - - If the application does not specify an X-Sender header using the property, the class will create one when the message is sent. - - The sender, recipient, subject, and body of an email message may be specified as parameters when a is used to initialize a object. These parameters may also be set or accessed using properties on the object. - - The primary mail message headers and elements for the message may be set using the following properties of the class. - -|Mail header or part|Property| -|-------------------------|--------------| -|Attachments|| -|Blind carbon copies (BCC)|| -|Carbon copies (CC)|| -|Content-Type|| -|Encoding for custom headers|| -|Message body|| -|Priority|| -|Recipient|| -|Reply-To|| -|Sender|| -|Subject|| - - - -## Examples - The following code example demonstrates displaying the headers for a mail message. - + property allows an application to access the headers collection for the message. While this collection is read-only (a new collection can not be set), custom headers can be added to or deleted from this collection. Any custom headers added will be included when the instance is sent. Before a message is sent, only headers specifically added to this collection in the property are included in the collection. After the instance is sent, the property will also include headers that are set using the associated properties of the class or parameters passed when a is used to initialize a object. + + If some mail headers are malformed, they could cause the email message to become corrupted. So any mail header in the headers collection that can be set using a property on the class should only be set using the class property or as a parameter passed when a initializes a object. The following list of mail headers should not be added using the property and any values set for these headers using the property will be discarded or overwritten when the message is sent: + +- Bcc + +- Cc + +- Content-ID + +- Content-Location + +- Content-Transfer-Encoding + +- Content-Type + +- Date + +- From + +- Importance + +- MIME-Version + +- Priority + +- Reply-To + +- Sender + +- To + +- X-Priority + + If the application does not specify an X-Sender header using the property, the class will create one when the message is sent. + + The sender, recipient, subject, and body of an email message may be specified as parameters when a is used to initialize a object. These parameters may also be set or accessed using properties on the object. + + The primary mail message headers and elements for the message may be set using the following properties of the class. + +|Mail header or part|Property| +|-------------------------|--------------| +|Attachments|| +|Blind carbon copies (BCC)|| +|Carbon copies (CC)|| +|Content-Type|| +|Encoding for custom headers|| +|Message body|| +|Priority|| +|Recipient|| +|Reply-To|| +|Sender|| +|Subject|| + + + +## Examples + The following code example demonstrates displaying the headers for a mail message. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLMailSync/CPP/NclMailSync.cpp" id="Snippet24"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet24"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet24"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet24"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet24"::: + ]]> @@ -1229,13 +1229,13 @@ Gets or sets the encoding used for the user-defined custom headers for this email message. The encoding used for user-defined custom headers for this email message. - property defaults to . - - SMTP messages consist of headers and body parts. The IETF RFCs for SMTP restrict the header and body part names to be ASCII. However, the IETF RFCs allow header and body part values to contain Unicode characters. In any particular value, if non-ASCII characters exist, then the value is encoded using a combination of character encoding (UTF8 or Shift-JIS, for example) followed by byte encoding ( or for example). The result is usually that only ASCII characters are in the network transmission stream. - + property defaults to . + + SMTP messages consist of headers and body parts. The IETF RFCs for SMTP restrict the header and body part names to be ASCII. However, the IETF RFCs allow header and body part values to contain Unicode characters. In any particular value, if non-ASCII characters exist, then the value is encoded using a combination of character encoding (UTF8 or Shift-JIS, for example) followed by byte encoding ( or for example). The result is usually that only ASCII characters are in the network transmission stream. + ]]> @@ -1397,11 +1397,11 @@ Gets or sets the ReplyTo address for the mail message. A MailAddress that indicates the value of the field. - property to indicate an address other than the address to use to reply to this message. - + property to indicate an address other than the address to use to reply to this message. + ]]> @@ -1442,13 +1442,13 @@ Gets the list of addresses to reply to for the mail message. The list of the addresses to reply to for the mail message. - property to indicate the list of addresses other than the address to use to reply to this message. - - The property replaces the property that only allows a single address to reply to. - + property to indicate the list of addresses other than the address to use to reply to this message. + + The property replaces the property that only allows a single address to reply to. + ]]> @@ -1505,11 +1505,11 @@ Gets or sets the sender's address for this email message. A that contains the sender's address information. - @@ -1551,20 +1551,20 @@ Gets or sets the subject line for this email message. A that contains the subject content. - property. - - - -## Examples - The following code example demonstrates setting the property. - + property. + + + +## Examples + The following code example demonstrates setting the property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLMailSync/CPP/NclMailSync.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet2"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet2"::: + ]]> @@ -1621,20 +1621,20 @@ Gets or sets the encoding used for the subject content for this email message. An that was used to encode the property. - of , use . - - - -## Examples - The following code example demonstrates setting the property. - + of , use . + + + +## Examples + The following code example demonstrates setting the property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclMailASync/cpp/mailasync.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/MailAddress/.ctor/mailasync.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclMailASync/vb/mailasync.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclMailASync/vb/mailasync.vb" id="Snippet3"::: + ]]> @@ -1680,20 +1680,20 @@ Gets the address collection that contains the recipients of this email message. A writable object. - property is used to designate the addresses on the To line of an email message. To add a recipient to an email message, create a for the recipient's address, and then add that object to the collection returned by this property. - - - -## Examples - The following code example demonstrates setting the property. - + property is used to designate the addresses on the To line of an email message. To add a recipient to an email message, create a for the recipient's address, and then add that object to the collection returned by this property. + + + +## Examples + The following code example demonstrates setting the property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLMailSync/CPP/NclMailSync.cpp" id="Snippet7"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet7"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLMailSync/vb/mail.vb" id="Snippet7"::: + ]]> diff --git a/xml/System.Net.Mail/SmtpStatusCode.xml b/xml/System.Net.Mail/SmtpStatusCode.xml index 7ce4e5ec99d..0210ac9c43e 100644 --- a/xml/System.Net.Mail/SmtpStatusCode.xml +++ b/xml/System.Net.Mail/SmtpStatusCode.xml @@ -40,21 +40,21 @@ Specifies the outcome of sending email by using the class. - enumeration specify reply status values sent by a Simple Mail Transfer Protocol (SMTP) server. The and classes contain properties that return values. - - SMTP is defined in RFC 2821 available at [https://www.ietf.org](https://www.ietf.org/). - - - -## Examples - The following code example displays an error message to the console when an is thrown. - + enumeration specify reply status values sent by a Simple Mail Transfer Protocol (SMTP) server. The and classes contain properties that return values. + + SMTP is defined in RFC 2821 available at [https://www.ietf.org](https://www.ietf.org/). + + + +## Examples + The following code example displays an error message to the console when an is thrown. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLMailSync/CPP/NclMailSync.cpp" id="Snippet23"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet23"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet23"::: + ]]> @@ -474,7 +474,7 @@ 451 - The SMTP service cannot complete the request. This error can occur if the client's IP address cannot be resolved (that is, a reverse lookup failed). You can also receive this error if the client domain has been identified as an open relay or source for unsolicited email (spam). For details, see RFC 2505, which is available at [https://www.ietf.org](https://www.ietf.org/). + The SMTP service cannot complete the request. This error can occur if the client's IP address cannot be resolved (that is, a reverse lookup failed). You can also receive this error if the client domain has been identified as an open relay or source for unsolicited email (spam). For details, see RFC 2505, which is available at https://www.ietf.org. diff --git a/xml/System.Net.Security/AuthenticatedStream.xml b/xml/System.Net.Security/AuthenticatedStream.xml index 59ef5ba3834..9da629f0be9 100644 --- a/xml/System.Net.Security/AuthenticatedStream.xml +++ b/xml/System.Net.Security/AuthenticatedStream.xml @@ -52,23 +52,23 @@ Provides methods for passing credentials across a stream and requesting or performing authentication for client-server applications. - . - - The security protocol implemented by a class that derives from together with the security protocols supported on the client and server will determine the security features that are available to an application. The and classes inherit from and implement the Negotiate and Secure Sockets Layer security protocols, respectively. - - - -## Examples -The following example demonstrates displaying the properties of an authenticated stream. - + . + + The security protocol implemented by a class that derives from together with the security protocols supported on the client and server will determine the security features that are available to an application. The and classes inherit from and implement the Negotiate and Secure Sockets Layer security protocols, respectively. + + + +## Examples +The following example demonstrates displaying the properties of an authenticated stream. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclNegoasyncClient/CPP/NclNegoasyncClient.cpp" id="Snippet6"::: -:::code language="csharp" source="~/snippets/csharp/System.Net.Security/AuthenticatedStream/Overview/client.cs" id="Snippet6"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclNegoasyncClient/VB/client.vb" id="Snippet6"::: +:::code language="csharp" source="~/snippets/csharp/System.Net.Security/AuthenticatedStream/Overview/client.cs" id="Snippet6"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclNegoasyncClient/VB/client.vb" id="Snippet6"::: ]]> @@ -117,20 +117,20 @@ The following example demonstrates displaying the properties of an authenticated A that indicates whether closing this object also closes . Initializes a new instance of the class. - has no effect on the `innerStream` stream. - - This constructor is provided for implementers of authenticated streams, and can be called only by classes that are derived from . - + has no effect on the `innerStream` stream. + + This constructor is provided for implementers of authenticated streams, and can be called only by classes that are derived from . + ]]> - is . - - -or- - + is . + + -or- + is equal to . @@ -176,20 +176,20 @@ The following example demonstrates displaying the properties of an authenticated to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -223,15 +223,15 @@ The following example demonstrates displaying the properties of an authenticated Asynchronously releases the unmanaged and managed resources used by the . A task that represents the asynchronous dispose operation. - is `false`; otherwise, the inner stream is just flushed. - + Calling `DisposeAsync` allows the resources used by the to be reallocated for other purposes. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - + ]]> @@ -280,11 +280,11 @@ The following example demonstrates displaying the properties of an authenticated Gets the stream used by this for sending and receiving data. A object. - can use this property to access the stream passed to the . - + can use this property to access the stream passed to the . + ]]> @@ -328,19 +328,19 @@ The following example demonstrates displaying the properties of an authenticated if successful authentication occurred; otherwise, . - . - - - -## Examples -The following example demonstrates displaying the value of this property. - + . + + + +## Examples +The following example demonstrates displaying the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclNegoasyncClient/CPP/NclNegoasyncClient.cpp" id="Snippet6"::: -:::code language="csharp" source="~/snippets/csharp/System.Net.Security/AuthenticatedStream/Overview/client.cs" id="Snippet6"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclNegoasyncClient/VB/client.vb" id="Snippet6"::: +:::code language="csharp" source="~/snippets/csharp/System.Net.Security/AuthenticatedStream/Overview/client.cs" id="Snippet6"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclNegoasyncClient/VB/client.vb" id="Snippet6"::: ]]> @@ -385,19 +385,19 @@ The following example demonstrates displaying the value of this property. if data is encrypted before being transmitted over the network and decrypted when it reaches the remote endpoint; otherwise, . - @@ -442,19 +442,19 @@ The following example demonstrates displaying the value of this property. if the client and server have been authenticated; otherwise, . - , check the class documentation. - - - -## Examples -The following example demonstrates displaying the value of this property. - + , check the class documentation. + + + +## Examples +The following example demonstrates displaying the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclNegoasyncClient/CPP/NclNegoasyncClient.cpp" id="Snippet6"::: -:::code language="csharp" source="~/snippets/csharp/System.Net.Security/AuthenticatedStream/Overview/client.cs" id="Snippet6"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclNegoasyncClient/VB/client.vb" id="Snippet6"::: +:::code language="csharp" source="~/snippets/csharp/System.Net.Security/AuthenticatedStream/Overview/client.cs" id="Snippet6"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclNegoasyncClient/VB/client.vb" id="Snippet6"::: ]]> @@ -499,19 +499,19 @@ The following example demonstrates displaying the value of this property. if the local endpoint was authenticated as the server side of a client-server authenticated connection; if the local endpoint was authenticated as the client. - @@ -556,20 +556,20 @@ The following example demonstrates displaying the value of this property. if the data is signed before being transmitted; otherwise, . - @@ -619,11 +619,11 @@ The following example demonstrates displaying the value of this property. if the inner stream has been left open; otherwise, . - diff --git a/xml/System.Net.Security/NegotiateStream.xml b/xml/System.Net.Security/NegotiateStream.xml index 3797f09ed81..309617c0bc0 100644 --- a/xml/System.Net.Security/NegotiateStream.xml +++ b/xml/System.Net.Security/NegotiateStream.xml @@ -56,41 +56,41 @@ Provides a stream that uses the Negotiate security protocol to authenticate the client, and optionally the server, in client-server communication. - class for authentication and to help secure information transmitted between a client and a server. Using , you can do the following. - -- Send the client's credentials to the server for Impersonation or Delegation. - -- Request server authentication. - -- Encrypt and/or sign data before transmitting it. - - Authentication must be performed before transmitting information. Clients request authentication using the synchronous methods, which block until the authentication completes, or the asynchronous methods, which do not block while waiting for the authentication to complete. Servers request authentication using the synchronous or asynchronous methods. The client, and optionally the server, is authenticated using the Negotiate security protocol. The Kerberos protocol is used for authentication if both client and server support it; otherwise NTLM is used. The class performs the authentication using the Security Support Provider Interface (SSPI). - - When authentication succeeds, you must check the and properties to determine what security services will be used by the to help secure your data during transmission. Check the property to determine whether mutual authentication occurred. You can get information about the remote client or server using the property. - - If the authentication fails, you will receive an or a . In this case, you can retry the authentication with a different credential. - - You send data using the synchronous or asynchronous or methods. You receive data using the synchronous or asynchronous or methods. If security services such as encryption or signing are enabled, these are automatically applied to your data by the . - - The transmits data using a stream that you supply when creating the . When you supply this underlying stream, you have the option to specify whether closing the also closes the underlying stream. - - - -## Examples -The following example demonstrates the client side of a client-server connection that uses the . The client authenticates and sends a message to the server asynchronously. - + class for authentication and to help secure information transmitted between a client and a server. Using , you can do the following. + +- Send the client's credentials to the server for Impersonation or Delegation. + +- Request server authentication. + +- Encrypt and/or sign data before transmitting it. + + Authentication must be performed before transmitting information. Clients request authentication using the synchronous methods, which block until the authentication completes, or the asynchronous methods, which do not block while waiting for the authentication to complete. Servers request authentication using the synchronous or asynchronous methods. The client, and optionally the server, is authenticated using the Negotiate security protocol. The Kerberos protocol is used for authentication if both client and server support it; otherwise NTLM is used. The class performs the authentication using the Security Support Provider Interface (SSPI). + + When authentication succeeds, you must check the and properties to determine what security services will be used by the to help secure your data during transmission. Check the property to determine whether mutual authentication occurred. You can get information about the remote client or server using the property. + + If the authentication fails, you will receive an or a . In this case, you can retry the authentication with a different credential. + + You send data using the synchronous or asynchronous or methods. You receive data using the synchronous or asynchronous or methods. If security services such as encryption or signing are enabled, these are automatically applied to your data by the . + + The transmits data using a stream that you supply when creating the . When you supply this underlying stream, you have the option to specify whether closing the also closes the underlying stream. + + + +## Examples +The following example demonstrates the client side of a client-server connection that uses the . The client authenticates and sends a message to the server asynchronously. + [!code-cpp[NclNegoAsyncClient#0](~/snippets/cpp/VS_Snippets_Remoting/NclNegoasyncClient/CPP/NclNegoasyncClient.cpp#0)] -[!code-csharp[NclNegoAsyncClient#0](~/snippets/csharp/System.Net.Security/AuthenticatedStream/Overview/client.cs#0)] -[!code-vb[NclNegoAsyncClient#0](~/snippets/visualbasic/VS_Snippets_Remoting/NclNegoasyncClient/VB/client.vb#0)] +[!code-csharp[NclNegoAsyncClient#0](~/snippets/csharp/System.Net.Security/AuthenticatedStream/Overview/client.cs#0)] +[!code-vb[NclNegoAsyncClient#0](~/snippets/visualbasic/VS_Snippets_Remoting/NclNegoasyncClient/VB/client.vb#0)] + +The following code example demonstrates the server side of a client-server connection that uses the to authenticate the client and read a message sent by the client. -The following code example demonstrates the server side of a client-server connection that uses the to authenticate the client and read a message sent by the client. - [!code-cpp[NclNegoAsyncServer#0](~/snippets/cpp/VS_Snippets_Remoting/NclNegoAsyncServer/CPP/NclNegoAsyncServer.cpp#0)] -[!code-csharp[NclNegoAsyncServer#0](~/snippets/csharp/System.Net.Security/NegotiateStream/Overview/server.cs#0)] - +[!code-csharp[NclNegoAsyncServer#0](~/snippets/csharp/System.Net.Security/NegotiateStream/Overview/server.cs#0)] + ]]> Changes to NTLM authentication for HTTPWebRequest in Version 3.5 SP1 @@ -104,11 +104,11 @@ The following code example demonstrates the server side of a client-server conne Initializes a new instance of the class. - from closing the stream that you supply, use the constructor. - + from closing the stream that you supply, use the constructor. + ]]> @@ -157,14 +157,14 @@ The following code example demonstrates the server side of a client-server conne A object used by the for sending and receiving data. Initializes a new instance of the class using the specified . - @@ -210,27 +210,27 @@ The following code example demonstrates the server side of a client-server conne to indicate that closing this has no effect on ; to indicate that closing this also closes . Initializes a new instance of the class using the specified and stream closure behavior. - has no effect on the `innerStream` stream; you must explicitly close `innerStream` when you no longer need it. - - - -## Examples -The following example demonstrates calling this constructor. This code example is part of a larger example provided for the class. - + has no effect on the `innerStream` stream; you must explicitly close `innerStream` when you no longer need it. + + + +## Examples +The following example demonstrates calling this constructor. This code example is part of a larger example provided for the class. + [!code-cpp[NclNegoAsyncClient#1](~/snippets/cpp/VS_Snippets_Remoting/NclNegoasyncClient/CPP/NclNegoasyncClient.cpp#1)] -[!code-csharp[NclNegoAsyncClient#1](~/snippets/csharp/System.Net.Security/AuthenticatedStream/Overview/client.cs#1)] -[!code-vb[NclNegoAsyncClient#1](~/snippets/visualbasic/VS_Snippets_Remoting/NclNegoasyncClient/VB/client.vb#1)] +[!code-csharp[NclNegoAsyncClient#1](~/snippets/csharp/System.Net.Security/AuthenticatedStream/Overview/client.cs#1)] +[!code-vb[NclNegoAsyncClient#1](~/snippets/visualbasic/VS_Snippets_Remoting/NclNegoasyncClient/VB/client.vb#1)] ]]> - is . - + is . + -or- - + is equal to . @@ -281,24 +281,24 @@ The following example demonstrates calling this constructor. This code example i Called by clients to authenticate the client, and optionally the server, in a client-server connection. - . No Service Principal Name (SPN) is specified for the server. The impersonation level is , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. - - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + . No Service Principal Name (SPN) is specified for the server. The impersonation level is , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. + + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + ]]> The authentication failed. You can use this object to retry the authentication. The authentication failed. You can use this object to retry the authentication. This object has been closed. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the server. You cannot use the stream to retry authentication as the client. @@ -350,22 +350,22 @@ The following example demonstrates calling this constructor. This code example i The Service Principal Name (SPN) that uniquely identifies the server to authenticate. Called by clients to authenticate the client, and optionally the server, in a client-server connection. The authentication process uses the specified client credential. - , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. - - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - + , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. + + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + ]]> The authentication failed. You can use this object to retry the authentication. The authentication failed. You can use this object to retry the authentication. This object has been closed. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the server. You cannot use the stream to retry authentication as the client. is . @@ -429,29 +429,29 @@ The following example demonstrates calling this constructor. This code example i The Service Principal Name (SPN) that uniquely identifies the server to authenticate. Called by clients to authenticate the client, and optionally the server, in a client-server connection. The authentication process uses the specified client credential and the channel binding. - , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. - - The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . - - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - + , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. + + The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . + + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + ]]> - is . - + is . + -or- - + is . The authentication failed. You can use this object to retry the authentication. The authentication failed. You can use this object to retry the authentication. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the server. You cannot use the stream to retry authentication as the client. This object has been closed. @@ -510,13 +510,13 @@ The following example demonstrates calling this constructor. This code example i One of the values, indicating how the server can use the client's credentials to access resources. Called by clients to authenticate the client, and optionally the server, in a client-server connection. The authentication process uses the specified credentials and authentication options. - value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + ]]> @@ -526,10 +526,10 @@ The following example demonstrates calling this constructor. This code example i The authentication failed. You can use this object to retry the authentication. The authentication failed. You can use this object to retry the authentication. This object has been closed. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the server. You cannot use the stream to retry authentication as the client. @@ -589,31 +589,31 @@ The following example demonstrates calling this constructor. This code example i One of the values, indicating how the server can use the client's credentials to access resources. Called by clients to authenticate the client, and optionally the server, in a client-server connection. The authentication process uses the specified credential, authentication options, and channel binding. - value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . - - The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . + + The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + ]]> - is . - + is . + -or- - + is . is not a valid value. The authentication failed. You can use this object to retry the authentication. The authentication failed. You can use this object to retry the authentication. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the server. You cannot use the stream to retry authentication as the client. This object has been closed. @@ -668,15 +668,15 @@ The following example demonstrates calling this constructor. This code example i Called by clients to authenticate the client, and optionally the server, in a client-server connection as an asynchronous operation. The task object representing the asynchronous operation. - . No Service Principal Name (SPN) is specified for the server. The impersonation level is , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. - - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + . No Service Principal Name (SPN) is specified for the server. The impersonation level is , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. + + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + 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 . ]]> @@ -684,10 +684,10 @@ The following example demonstrates calling this constructor. This code example i The authentication failed. You can use this object to retry the authentication. The authentication failed. You can use this object to retry the authentication. This object has been closed. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the server. You cannot use the stream to retry authentication as the client. @@ -734,13 +734,13 @@ The following example demonstrates calling this constructor. This code example i Called by clients to authenticate the client, and optionally the server, in a client-server connection as an asynchronous operation. The authentication process uses the specified client credential. The task object representing the asynchronous operation. - , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. - - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - + , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. + + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + 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 . ]]> @@ -748,10 +748,10 @@ The following example demonstrates calling this constructor. This code example i The authentication failed. You can use this object to retry the authentication. The authentication failed. You can use this object to retry the authentication. This object has been closed. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the server. You cannot use the stream to retry authentication as the client. is . @@ -810,31 +810,31 @@ The following example demonstrates calling this constructor. This code example i Called by clients to authenticate the client, and optionally the server, in a client-server connection as an asynchronous operation. The authentication process uses the specified client credential and the channel binding. The task object representing the asynchronous operation. - , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. - - The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . - - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - + , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. + + The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . + + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + 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 . ]]> - is . - + is . + -or- - + is . The authentication failed. You can use this object to retry the authentication. The authentication failed. You can use this object to retry the authentication. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the server. You cannot use the stream to retry authentication as the client. This object has been closed. @@ -888,13 +888,13 @@ The following example demonstrates calling this constructor. This code example i Called by clients to authenticate the client, and optionally the server, in a client-server connection as an asynchronous operation. The authentication process uses the specified credentials and authentication options. The task object representing the asynchronous operation. - value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + 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 . ]]> @@ -906,10 +906,10 @@ The following example demonstrates calling this constructor. This code example i The authentication failed. You can use this object to retry the authentication. The authentication failed. You can use this object to retry the authentication. This object has been closed. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the server. You cannot use the stream to retry authentication as the client. @@ -970,33 +970,33 @@ The following example demonstrates calling this constructor. This code example i Called by clients to authenticate the client, and optionally the server, in a client-server connection as an asynchronous operation. The authentication process uses the specified credential, authentication options, and channel binding. The task object representing the asynchronous operation. - value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . - - The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . + + The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + 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 . ]]> - is . - + is . + -or- - + is . is not a valid value. The authentication failed. You can use this object to retry the authentication. The authentication failed. You can use this object to retry the authentication. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the server. You cannot use the stream to retry authentication as the client. This object has been closed. @@ -1012,11 +1012,11 @@ The following example demonstrates calling this constructor. This code example i Handles the server side of an authentication for a client-server connection. - method. - + method. + ]]> @@ -1058,17 +1058,17 @@ The following example demonstrates calling this constructor. This code example i Called by servers to authenticate the client, and optionally the server, in a client-server connection. - . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . - - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . + + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + ]]> The authentication failed. You can use this object to retry the authentication. @@ -1124,19 +1124,19 @@ The following example demonstrates calling this constructor. This code example i The that is used for extended protection. Called by servers to authenticate the client, and optionally the server, in a client-server connection. The authentication process uses the specified extended protection policy. - . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . - - If the `policy` parameter is `null`, then an extended protection policy is used that has set to . - - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . + + If the `policy` parameter is `null`, then an extended protection policy is used that has set to . + + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + ]]> The and on the extended protection policy passed in the parameter are both . @@ -1199,15 +1199,15 @@ The following example demonstrates calling this constructor. This code example i One of the values, indicating how the server can use the client's credentials to access resources. Called by servers to authenticate the client, and optionally the server, in a client-server connection. The authentication process uses the specified server credentials and authentication options. - and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + ]]> @@ -1217,10 +1217,10 @@ The following example demonstrates calling this constructor. This code example i The authentication failed. You can use this object to try to r-authenticate. The authentication failed. You can use this object to retry the authentication. This object has been closed. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the client. You cannot use the stream to retry authentication as the server. Windows 95 and Windows 98 are not supported. @@ -1279,17 +1279,17 @@ The following example demonstrates calling this constructor. This code example i One of the values, indicating how the server can use the client's credentials to access resources. Called by servers to authenticate the client, and optionally the server, in a client-server connection. The authentication process uses the specified server credentials, authentication options, and extended protection policy. - set to . - - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + set to . + + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + ]]> The and on the extended protection policy passed in the parameter are both . @@ -1299,10 +1299,10 @@ The following example demonstrates calling this constructor. This code example i must be , , or , The authentication failed. You can use this object to try to r-authenticate. The authentication failed. You can use this object to retry the authentication. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the client. You cannot use the stream to retry authentication as the server. This object has been closed. The parameter was set to on a platform that does not support extended protection. @@ -1359,15 +1359,15 @@ The following example demonstrates calling this constructor. This code example i Called by servers to authenticate the client, and optionally the server, in a client-server connection as an asynchronous operation. The task object representing the asynchronous operation. - . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . - - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . + + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + 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 . ]]> @@ -1427,17 +1427,17 @@ The following example demonstrates calling this constructor. This code example i Called by servers to authenticate the client, and optionally the server, in a client-server connection as an asynchronous operation. The authentication process uses the specified extended protection policy. The task object representing the asynchronous operation. - . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . - - If the `policy` parameter is `null`, then an extended protection policy is used that has set to . - - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . + + If the `policy` parameter is `null`, then an extended protection policy is used that has set to . + + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + 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 . ]]> @@ -1497,13 +1497,13 @@ The following example demonstrates calling this constructor. This code example i Called by servers to authenticate the client, and optionally the server, in a client-server connection as an asynchronous operation. The authentication process uses the specified server credentials and authentication options. The task object representing the asynchronous operation. - and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + 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 . ]]> @@ -1515,10 +1515,10 @@ The following example demonstrates calling this constructor. This code example i The authentication failed. You can use this object to try to r-authenticate. The authentication failed. You can use this object to retry the authentication. This object has been closed. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the client. You cannot use the stream to retry authentication as the server. Windows 95 and Windows 98 are not supported. @@ -1578,15 +1578,15 @@ The following example demonstrates calling this constructor. This code example i Called by servers to authenticate the client, and optionally the server, in a client-server connection as an asynchronous operation. The authentication process uses the specified server credentials, authentication options, and extended protection policy. The task object representing the asynchronous operation. - set to . - - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + set to . + + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + 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 . ]]> @@ -1598,10 +1598,10 @@ The following example demonstrates calling this constructor. This code example i must be , , or , The authentication failed. You can use this object to try to r-authenticate. The authentication failed. You can use this object to retry the authentication. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the client. You cannot use the stream to retry authentication as the server. This object has been closed. The parameter was set to on a platform that does not support extended protection. @@ -1619,11 +1619,11 @@ The following example demonstrates calling this constructor. This code example i Begins an asynchronous operation to authenticate the client side of a client-server connection. - methods. - + methods. + ]]> @@ -1678,35 +1678,35 @@ The following example demonstrates calling this constructor. This code example i Called by clients to begin an asynchronous operation to authenticate the client, and optionally the server, in a client-server connection. This method does not block. An object indicating the status of the asynchronous operation. - . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . The class will construct the SPN used for mutual authentication. - - This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. - - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - - - -## Examples -The following example demonstrates calling this method to begin an asynchronous authentication for the client. - + . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . The class will construct the SPN used for mutual authentication. + + This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. + + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + + + +## Examples +The following example demonstrates calling this method to begin an asynchronous authentication for the client. + [!code-cpp[NclNegoAsyncClient#2](~/snippets/cpp/VS_Snippets_Remoting/NclNegoasyncClient/CPP/NclNegoasyncClient.cpp#2)] -[!code-csharp[NclNegoAsyncClient#2](~/snippets/csharp/System.Net.Security/AuthenticatedStream/Overview/client.cs#2)] -[!code-vb[NclNegoAsyncClient#2](~/snippets/visualbasic/VS_Snippets_Remoting/NclNegoasyncClient/VB/client.vb#2)] +[!code-csharp[NclNegoAsyncClient#2](~/snippets/csharp/System.Net.Security/AuthenticatedStream/Overview/client.cs#2)] +[!code-vb[NclNegoAsyncClient#2](~/snippets/visualbasic/VS_Snippets_Remoting/NclNegoasyncClient/VB/client.vb#2)] ]]> The authentication failed. You can use this object to retry the authentication. The authentication failed. You can use this object to retry the authentication. This object has been closed. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the server. You cannot use the stream to retry authentication as the client. @@ -1778,30 +1778,30 @@ The following example demonstrates calling this method to begin an asynchronous Called by clients to begin an asynchronous operation to authenticate the client, and optionally the server, in a client-server connection. The authentication process uses the specified credentials. This method does not block. An object indicating the status of the asynchronous operation. - method overloads. - - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + method overloads. + + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + ]]> - is . - + is . + -or- - + is . The authentication failed. You can use this object to retry the authentication. The authentication failed. You can use this object to retry the authentication. This object has been closed. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the server. You cannot use the stream to retry authentication as the client. @@ -1882,29 +1882,29 @@ The following example demonstrates calling this method to begin an asynchronous Called by clients to begin an asynchronous operation to authenticate the client, and optionally the server, in a client-server connection. The authentication process uses the specified credentials and channel binding. This method does not block. An object indicating the status of the asynchronous operation. - method overloads. - - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + method overloads. + + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + ]]> - is . - + is . + -or- - + is . The authentication failed. You can use this object to retry the authentication. The authentication failed. You can use this object to retry the authentication. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the server. You cannot use the stream to retry authentication as the client. This object has been closed. @@ -1983,32 +1983,32 @@ The following example demonstrates calling this method to begin an asynchronous Called by clients to begin an asynchronous operation to authenticate the client, and optionally the server, in a client-server connection. The authentication process uses the specified credentials and authentication options. This method does not block. An object indicating the status of the asynchronous operation. - value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . - - This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. - - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . + + This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. + + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + ]]> - is . - + is . + -or- - + is . The authentication failed. You can use this object to retry the authentication. The authentication failed. You can use this object to retry the authentication. This object has been closed. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the server. You cannot use the stream to retry authentication as the client. @@ -2087,31 +2087,31 @@ The following example demonstrates calling this method to begin an asynchronous Called by clients to begin an asynchronous operation to authenticate the client, and optionally the server, in a client-server connection. The authentication process uses the specified credentials, authentication options, and channel binding. This method does not block. An object indicating the status of the asynchronous operation. - value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . - - This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. - - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . + + This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. + + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + ]]> - is . - + is . + -or- - + is . The authentication failed. You can use this object to retry the authentication. The authentication failed. You can use this object to retry the authentication. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the server. You cannot use the stream to retry authentication as the client. This object has been closed. @@ -2127,11 +2127,11 @@ The following example demonstrates calling this method to begin an asynchronous Begins an asynchronous operation to handle the server side of authenticating a client-server connection. - method. - + method. + ]]> @@ -2186,17 +2186,17 @@ The following example demonstrates calling this method to begin an asynchronous Called by servers to begin an asynchronous operation to authenticate the client, and optionally the server, in a client-server connection. This method does not block. An object indicating the status of the asynchronous operation. - . No Service Principal Name (SPN) is specified for the server. The impersonation level is , the security level is . - - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - To block until the operation completes, use one of the method overloads. - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + . No Service Principal Name (SPN) is specified for the server. The impersonation level is , the security level is . + + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + To block until the operation completes, use one of the method overloads. + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + ]]> The authentication failed. You can use this object to retry the authentication. @@ -2257,25 +2257,25 @@ The following example demonstrates calling this method to begin an asynchronous Called by servers to begin an asynchronous operation to authenticate the client, and optionally the server, in a client-server connection. The authentication process uses the specified extended protection policy. This method does not block. An object indicating the status of the asynchronous operation. - . No Service Principal Name (SPN) is specified for the server. The impersonation level is , the security level is . - - If the `policy` parameter is `null`, then an extended protection policy is used that has set to . - - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - To block until the operation completes, use one of the method overloads. - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - - ]]> - - The and on the extended protection policy passed in the parameter are both . - The authentication failed. You can use this object to retry the authentication. - The authentication failed. You can use this object to retry the authentication. - This object has been closed. + . No Service Principal Name (SPN) is specified for the server. The impersonation level is , the security level is . + + If the `policy` parameter is `null`, then an extended protection policy is used that has set to . + + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + To block until the operation completes, use one of the method overloads. + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + + ]]> + + The and on the extended protection policy passed in the parameter are both . + The authentication failed. You can use this object to retry the authentication. + The authentication failed. You can use this object to retry the authentication. + This object has been closed. The parameter was set to on a platform that does not support extended protection. Integrated Windows Authentication with Extended Protection @@ -2352,17 +2352,17 @@ The following example demonstrates calling this method to begin an asynchronous Called by servers to begin an asynchronous operation to authenticate the client, and optionally the server, in a client-server connection. The authentication process uses the specified server credentials and authentication options. This method does not block. An object indicating the status of the asynchronous operation. - value. Successful authentication does not guarantee that, the requested has been granted. You must check the and properties to determine what security services are used by the . - - This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. - - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + value. Successful authentication does not guarantee that, the requested has been granted. You must check the and properties to determine what security services are used by the . + + This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. + + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + ]]> @@ -2372,10 +2372,10 @@ The following example demonstrates calling this method to begin an asynchronous The authentication failed. You can use this object to retry the authentication. The authentication failed. You can use this object to retry the authentication. This object has been closed. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the client. You cannot use the stream to retry authentication as the server. Windows 95 and Windows 98 are not supported. @@ -2445,19 +2445,19 @@ The following example demonstrates calling this method to begin an asynchronous Called by servers to begin an asynchronous operation to authenticate the client, and optionally the server, in a client-server connection. The authentication process uses the specified server credentials, authentication options, and extended protection policy. This method does not block. An object indicating the status of the asynchronous operation. - value. Successful authentication does not guarantee that, the requested has been granted. You must check the and properties to determine what security services are used by the . - - If the `policy` parameter is `null`, then an extended protection policy is used that has set to . - - This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. - - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - + value. Successful authentication does not guarantee that, the requested has been granted. You must check the and properties to determine what security services are used by the . + + If the `policy` parameter is `null`, then an extended protection policy is used that has set to . + + This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. + + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + ]]> The and on the extended protection policy passed in the parameter are both . @@ -2467,10 +2467,10 @@ The following example demonstrates calling this method to begin an asynchronous must be , , or , The authentication failed. You can use this object to retry the authentication. The authentication failed. You can use this object to retry the authentication. - Authentication has already occurred. - + Authentication has already occurred. + -or- - + This stream was used previously to attempt authentication as the client. You cannot use the stream to retry authentication as the server. This object has been closed. The parameter was set to on a platform that does not support extended protection. @@ -2543,45 +2543,45 @@ The following example demonstrates calling this method to begin an asynchronous Begins an asynchronous read operation that reads data from the stream and stores it in the specified array. An object indicating the status of the asynchronous operation. - method. - - The asynchronous read operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) - - The class does not support multiple simultaneous read operations. If you attempt to start a read operation while another read operation is already executing on the same stream, a exception will be thrown. - - You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. - - - -## Examples - The following code example demonstrates starting an asynchronous read operation. This code example is part of a larger example provided for the class. - + method. + + The asynchronous read operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + + The class does not support multiple simultaneous read operations. If you attempt to start a read operation while another read operation is already executing on the same stream, a exception will be thrown. + + You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. + + + +## Examples + The following code example demonstrates starting an asynchronous read operation. This code example is part of a larger example provided for the class. + [!code-cpp[NclNegoAsyncServer#1](~/snippets/cpp/VS_Snippets_Remoting/NclNegoAsyncServer/CPP/NclNegoAsyncServer.cpp#1)] - [!code-csharp[NclNegoAsyncServer#1](~/snippets/csharp/System.Net.Security/NegotiateStream/Overview/server.cs#1)] - + [!code-csharp[NclNegoAsyncServer#1](~/snippets/csharp/System.Net.Security/NegotiateStream/Overview/server.cs#1)] + ]]> is . - is less than 0. - + is less than 0. + -or- - - is greater than the length of . - + + is greater than the length of . + -or- - + plus is greater than the length of . - The read operation failed. - + The read operation failed. + -or- - + Encryption is in use, but the data could not be decrypted. There is already a read operation in progress. This object has been closed. @@ -2652,52 +2652,52 @@ The following example demonstrates calling this method to begin an asynchronous Begins an asynchronous write operation that writes s from the specified buffer to the stream. An object indicating the status of the asynchronous operation. - method. - - The asynchronous read operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) - - The class does not support multiple simultaneous write operations. If you attempt to start a write operation while another write operation is already executing on the same stream, a exception will be thrown. - - You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. - - - -## Examples -The following example demonstrates beginning an asynchronous write operation. - + method. + + The asynchronous read operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + + The class does not support multiple simultaneous write operations. If you attempt to start a write operation while another write operation is already executing on the same stream, a exception will be thrown. + + You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. + + + +## Examples +The following example demonstrates beginning an asynchronous write operation. + [!code-cpp[NclNegoAsyncClient#3](~/snippets/cpp/VS_Snippets_Remoting/NclNegoasyncClient/CPP/NclNegoasyncClient.cpp#3)] -[!code-csharp[NclNegoAsyncClient#3](~/snippets/csharp/System.Net.Security/AuthenticatedStream/Overview/client.cs#3)] -[!code-vb[NclNegoAsyncClient#3](~/snippets/visualbasic/VS_Snippets_Remoting/NclNegoasyncClient/VB/client.vb#3)] +[!code-csharp[NclNegoAsyncClient#3](~/snippets/csharp/System.Net.Security/AuthenticatedStream/Overview/client.cs#3)] +[!code-vb[NclNegoAsyncClient#3](~/snippets/visualbasic/VS_Snippets_Remoting/NclNegoasyncClient/VB/client.vb#3)] + +The following method is called when the operation completes. -The following method is called when the operation completes. - [!code-cpp[NclNegoAsyncClient#4](~/snippets/cpp/VS_Snippets_Remoting/NclNegoasyncClient/CPP/NclNegoasyncClient.cpp#4)] -[!code-csharp[NclNegoAsyncClient#4](~/snippets/csharp/System.Net.Security/AuthenticatedStream/Overview/client.cs#4)] -[!code-vb[NclNegoAsyncClient#4](~/snippets/visualbasic/VS_Snippets_Remoting/NclNegoasyncClient/VB/client.vb#4)] +[!code-csharp[NclNegoAsyncClient#4](~/snippets/csharp/System.Net.Security/AuthenticatedStream/Overview/client.cs#4)] +[!code-vb[NclNegoAsyncClient#4](~/snippets/visualbasic/VS_Snippets_Remoting/NclNegoasyncClient/VB/client.vb#4)] ]]> is . - . - + . + -or- - - is greater than the length of . - + + is greater than the length of . + -or- - + plus count is greater than the length of . - The write operation failed. - + The write operation failed. + -or- - + Encryption is in use, but the data could not be encrypted. There is already a write operation in progress. This object has been closed. @@ -2743,19 +2743,19 @@ The following method is called when the operation completes. if authentication has occurred and the underlying stream is readable; otherwise, . - property on the underlying stream. The underlying stream is specified when you create an instance of the class. - - - -## Examples - The following code example demonstrates displaying the value of this property. - + property on the underlying stream. The underlying stream is specified when you create an instance of the class. + + + +## Examples + The following code example demonstrates displaying the value of this property. + [!code-cpp[NclNegoSyncClient#2](~/snippets/cpp/VS_Snippets_Remoting/NclNegoSyncClient/CPP/NclNegoSyncClient.cpp#2)] - [!code-csharp[NclNegoSyncClient#2](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#2)] - + [!code-csharp[NclNegoSyncClient#2](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#2)] + ]]> @@ -2798,19 +2798,19 @@ The following method is called when the operation completes. Gets a value that indicates whether the underlying stream is seekable. This property always returns . - object or its underlying stream. The underlying stream is specified when you create an instance of the class. - - - -## Examples - The following code example demonstrates displaying the value of this property. - + object or its underlying stream. The underlying stream is specified when you create an instance of the class. + + + +## Examples + The following code example demonstrates displaying the value of this property. + [!code-cpp[NclNegoSyncClient#2](~/snippets/cpp/VS_Snippets_Remoting/NclNegoSyncClient/CPP/NclNegoSyncClient.cpp#2)] - [!code-csharp[NclNegoSyncClient#2](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#2)] - + [!code-csharp[NclNegoSyncClient#2](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#2)] + ]]> @@ -2855,19 +2855,19 @@ The following method is called when the operation completes. if the underlying stream supports time-outs; otherwise, . - property on the underlying stream. The underlying stream is specified when you create an instance of the class. - - - -## Examples - The following code example demonstrates displaying the value of this property. - + property on the underlying stream. The underlying stream is specified when you create an instance of the class. + + + +## Examples + The following code example demonstrates displaying the value of this property. + [!code-cpp[NclNegoSyncClient#2](~/snippets/cpp/VS_Snippets_Remoting/NclNegoSyncClient/CPP/NclNegoSyncClient.cpp#2)] - [!code-csharp[NclNegoSyncClient#2](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#2)] - + [!code-csharp[NclNegoSyncClient#2](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#2)] + ]]> @@ -2911,19 +2911,19 @@ The following method is called when the operation completes. if authentication has occurred and the underlying stream is writable; otherwise, . - property on the underlying stream. The underlying stream is specified when you create an instance of the class. - - - -## Examples - The following code example demonstrates displaying the value of this property. - + property on the underlying stream. The underlying stream is specified when you create an instance of the class. + + + +## Examples + The following code example demonstrates displaying the value of this property. + [!code-cpp[NclNegoSyncClient#2](~/snippets/cpp/VS_Snippets_Remoting/NclNegoSyncClient/CPP/NclNegoSyncClient.cpp#2)] - [!code-csharp[NclNegoSyncClient#2](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#2)] - + [!code-csharp[NclNegoSyncClient#2](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#2)] + ]]> @@ -2969,20 +2969,20 @@ The following method is called when the operation completes. to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -3016,15 +3016,15 @@ The following method is called when the operation completes. Asynchronously releases the unmanaged and managed resources used by the . A task that represents the asynchronous dispose operation. - is `false`; otherwise, the inner stream is just flushed. - + Calling `DisposeAsync` allows the resources used by the to be reallocated for other purposes. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - + ]]> @@ -3069,15 +3069,15 @@ The following method is called when the operation completes. An instance returned by a call to . Ends a pending asynchronous client authentication operation that was started with a call to . - and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - - To perform this operation synchronously, use one of the method. - + and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + + To perform this operation synchronously, use one of the method. + ]]> @@ -3129,17 +3129,17 @@ The following method is called when the operation completes. An instance returned by a call to . Ends a pending asynchronous client authentication operation that was started with a call to . - and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - - To perform this operation synchronously, use the method. - + and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. + + To perform this operation synchronously, use the method. + ]]> @@ -3192,23 +3192,23 @@ The following method is called when the operation completes. Ends an asynchronous read operation that was started with a call to . A value that specifies the number of bytes read from the underlying stream. - method. - - You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. - - - -## Examples - The following code example demonstrates ending an asynchronous read operation. For an example that demonstrates starting the operation, see . - + method. + + You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. + + + +## Examples + The following code example demonstrates ending an asynchronous read operation. For an example that demonstrates starting the operation, see . + [!code-cpp[NclNegoAsyncServer#3](~/snippets/cpp/VS_Snippets_Remoting/NclNegoAsyncServer/CPP/NclNegoAsyncServer.cpp#3)] - [!code-csharp[NclNegoAsyncServer#3](~/snippets/csharp/System.Net.Security/NegotiateStream/Overview/server.cs#3)] - + [!code-csharp[NclNegoAsyncServer#3](~/snippets/csharp/System.Net.Security/NegotiateStream/Overview/server.cs#3)] + ]]> @@ -3262,23 +3262,23 @@ Authentication has not occurred. An instance returned by a call to . Ends an asynchronous write operation that was started with a call to . - , , , , , or methods. - - To perform this operation synchronously, use the method. - - - -## Examples -The following example demonstrates a method that is called to complete the asynchronous write operation. For an example that demonstrates starting the operation, see . - + , , , , , or methods. + + To perform this operation synchronously, use the method. + + + +## Examples +The following example demonstrates a method that is called to complete the asynchronous write operation. For an example that demonstrates starting the operation, see . + [!code-cpp[NclNegoAsyncClient#4](~/snippets/cpp/VS_Snippets_Remoting/NclNegoasyncClient/CPP/NclNegoasyncClient.cpp#4)] -[!code-csharp[NclNegoAsyncClient#4](~/snippets/csharp/System.Net.Security/AuthenticatedStream/Overview/client.cs#4)] -[!code-vb[NclNegoAsyncClient#4](~/snippets/visualbasic/VS_Snippets_Remoting/NclNegoasyncClient/VB/client.vb#4)] +[!code-csharp[NclNegoAsyncClient#4](~/snippets/csharp/System.Net.Security/AuthenticatedStream/Overview/client.cs#4)] +[!code-vb[NclNegoAsyncClient#4](~/snippets/visualbasic/VS_Snippets_Remoting/NclNegoasyncClient/VB/client.vb#4)] ]]> @@ -3331,19 +3331,19 @@ Authentication has not occurred. Causes any buffered data to be written to the underlying device. - on the underlying stream. - - - -## Examples - The following code example demonstrates flushing the stream. - + on the underlying stream. + + + +## Examples + The following code example demonstrates flushing the stream. + [!code-cpp[NclNegoSyncClient#4](~/snippets/cpp/VS_Snippets_Remoting/NclNegoSyncClient/CPP/NclNegoSyncClient.cpp#4)] - [!code-csharp[NclNegoSyncClient#4](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#4)] - + [!code-csharp[NclNegoSyncClient#4](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#4)] + ]]> @@ -3382,11 +3382,11 @@ Authentication has not occurred. Asynchronously writes any buffered data to the underlying device. A task that represents the asynchronous flush operation. - on the underlying stream. - + on the underlying stream. + 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 . ]]> @@ -3432,19 +3432,19 @@ Authentication has not occurred. Gets a value that indicates how the server can use the client's credentials. One of the values. - or methods. If you authenticate without specifying a , is used. - - - -## Examples - The following code example demonstrates displaying the value of this property. - + or methods. If you authenticate without specifying a , is used. + + + +## Examples + The following code example demonstrates displaying the value of this property. + [!code-cpp[NclNegoSyncClient#1](~/snippets/cpp/VS_Snippets_Remoting/NclNegoSyncClient/CPP/NclNegoSyncClient.cpp#1)] - [!code-csharp[NclNegoSyncClient#1](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#1)] - + [!code-csharp[NclNegoSyncClient#1](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#1)] + ]]> Authentication failed or has not occurred. @@ -3489,19 +3489,19 @@ Authentication has not occurred. if successful authentication occurred; otherwise, . - or methods. Servers authenticate by calling the or methods. - - - -## Examples - The following code example demonstrates displaying the value of this property. - + or methods. Servers authenticate by calling the or methods. + + + +## Examples + The following code example demonstrates displaying the value of this property. + [!code-cpp[NclNegoSyncClient#1](~/snippets/cpp/VS_Snippets_Remoting/NclNegoSyncClient/CPP/NclNegoSyncClient.cpp#1)] - [!code-csharp[NclNegoSyncClient#1](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#1)] - + [!code-csharp[NclNegoSyncClient#1](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#1)] + ]]> @@ -3545,19 +3545,19 @@ Authentication has not occurred. if data is encrypted before being transmitted over the network and decrypted when it reaches the remote endpoint; otherwise, . - @@ -3602,21 +3602,21 @@ Authentication has not occurred. if the server has been authenticated; otherwise, . - @@ -3660,21 +3660,21 @@ Authentication has not occurred. if the local endpoint was successfully authenticated as the server side of the authenticated connection; otherwise, . - or methods. - - - -## Examples - The following code example demonstrates displaying the value of this property. - + or methods. + + + +## Examples + The following code example demonstrates displaying the value of this property. + [!code-cpp[NclNegoSyncClient#1](~/snippets/cpp/VS_Snippets_Remoting/NclNegoSyncClient/CPP/NclNegoSyncClient.cpp#1)] - [!code-csharp[NclNegoSyncClient#1](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#1)] - + [!code-csharp[NclNegoSyncClient#1](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#1)] + ]]> @@ -3718,19 +3718,19 @@ Authentication has not occurred. if the data is signed before being transmitted; otherwise, . - @@ -3773,19 +3773,19 @@ Authentication has not occurred. Gets the length of the underlying stream. A that specifies the length of the underlying stream. - property on the underlying stream. If the underlying stream is not seekable, this property will typically throw an exception. The run-time type of the underlying stream determines the run-time type of the exception that is thrown. - - - -## Examples - The following code example demonstrates displaying the value of this property. - + property on the underlying stream. If the underlying stream is not seekable, this property will typically throw an exception. The run-time type of the underlying stream determines the run-time type of the exception that is thrown. + + + +## Examples + The following code example demonstrates displaying the value of this property. + [!code-cpp[NclNegoSyncClient#2](~/snippets/cpp/VS_Snippets_Remoting/NclNegoSyncClient/CPP/NclNegoSyncClient.cpp#2)] - [!code-csharp[NclNegoSyncClient#2](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#2)] - + [!code-csharp[NclNegoSyncClient#2](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#2)] + ]]> Getting the value of this property is not supported when the underlying stream is a . @@ -3829,17 +3829,17 @@ Authentication has not occurred. Gets or sets the current position in the underlying stream. A that specifies the current position in the underlying stream. - property on the underlying stream. If the underlying stream is not seekable, this property will typically throw an exception. The run-time type of the underlying stream determines the run-time type of the exception that is thrown. - + property on the underlying stream. If the underlying stream is not seekable, this property will typically throw an exception. The run-time type of the underlying stream determines the run-time type of the exception that is thrown. + ]]> - Setting this property is not supported. - + Setting this property is not supported. + -or- - + Getting the value of this property is not supported when the underlying stream is a . @@ -3889,23 +3889,23 @@ Authentication has not occurred. Reads data from this stream and stores it in the specified array. An value that specifies the number of bytes read from the underlying stream. When there is no more data to be read, returns 0. - , , , , , or methods. - - To perform this operation asynchronously, use the method. - - - -## Examples - The following code example demonstrates reading from a . - + , , , , , or methods. + + To perform this operation asynchronously, use the method. + + + +## Examples + The following code example demonstrates reading from a . + [!code-cpp[NclNegoSyncServer#1](~/snippets/cpp/VS_Snippets_Remoting/NclNegoSyncServer/CPP/NclNegoSyncServer.cpp#1)] - [!code-csharp[NclNegoSyncServer#1](~/snippets/csharp/System.Net.Security/NegotiateStream/Read/server.cs#1)] - + [!code-csharp[NclNegoSyncServer#1](~/snippets/csharp/System.Net.Security/NegotiateStream/Read/server.cs#1)] + ]]> The read operation failed. @@ -3950,13 +3950,13 @@ Authentication has not occurred. Reads data asynchronously from the and stores it in a byte memory range as an asynchronous operation. A that represents the asynchronous read operation. The value of its property contains the total number of bytes read into . - , , , , , or methods. - + ]]> The read operation failed. @@ -4000,13 +4000,13 @@ This method reads asynchronously as much data as is available into `buffer` and Reads data asynchronously from this stream and stores it in the specified array. An value that specifies the number of bytes read from the underlying stream. When there is no more data to be read, returns 0. - , , , , , or methods. - + , , , , , or 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 . ]]> @@ -4055,21 +4055,21 @@ This method reads asynchronously as much data as is available into `buffer` and Gets or sets the amount of time a read operation blocks waiting for data. A that specifies the amount of time that will elapse before a read operation fails. - property on the underlying stream. When you set this property, the value on the underlying stream is set to the specified value. - - If the underlying stream is a , is in milliseconds and is set to by default so that read operations do not time out. - - - -## Examples - The following code example demonstrates displaying the value of this property. - + property on the underlying stream. When you set this property, the value on the underlying stream is set to the specified value. + + If the underlying stream is a , is in milliseconds and is set to by default so that read operations do not time out. + + + +## Examples + The following code example demonstrates displaying the value of this property. + [!code-cpp[NclNegoSyncClient#2](~/snippets/cpp/VS_Snippets_Remoting/NclNegoSyncClient/CPP/NclNegoSyncClient.cpp#2)] - [!code-csharp[NclNegoSyncClient#2](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#2)] - + [!code-csharp[NclNegoSyncClient#2](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#2)] + ]]> @@ -4112,19 +4112,19 @@ This method reads asynchronously as much data as is available into `buffer` and Gets information about the identity of the remote party sharing this authenticated stream. An object that describes the identity of the remote endpoint. - containing the Service Principal Name (SPN) of the server and the authentication protocol used. When accessed by the server, this property returns a that describes the client. If the is not available, client information is returned to the server in a . - - - -## Examples - The following code example demonstrates displaying the value of this property. - + containing the Service Principal Name (SPN) of the server and the authentication protocol used. When accessed by the server, this property returns a that describes the client. If the is not available, client information is returned to the server in a . + + + +## Examples + The following code example demonstrates displaying the value of this property. + [!code-cpp[NclNegoAsyncServer#2](~/snippets/cpp/VS_Snippets_Remoting/NclNegoAsyncServer/CPP/NclNegoAsyncServer.cpp#2)] - [!code-csharp[NclNegoAsyncServer#2](~/snippets/csharp/System.Net.Security/NegotiateStream/Overview/server.cs#2)] - + [!code-csharp[NclNegoAsyncServer#2](~/snippets/csharp/System.Net.Security/NegotiateStream/Overview/server.cs#2)] + ]]> Authentication failed or has not occurred. @@ -4174,11 +4174,11 @@ This method reads asynchronously as much data as is available into `buffer` and Throws . Always throws a . - . - + . + ]]> Seeking is not supported on . @@ -4272,43 +4272,43 @@ This method reads asynchronously as much data as is available into `buffer` and A containing the number of bytes to read from . Write the specified number of s to the underlying stream using the specified buffer and offset. - on the underlying stream. - - This method blocks while the write operation completes. To prevent blocking while the operation completes, use the method. - - You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. - - The class does not support multiple simultaneous write operations. If you attempt to start a write operation while another write operation is already executing on the same stream, a exception will be thrown. - - - -## Examples - The following code example demonstrates writing to a . - + on the underlying stream. + + This method blocks while the write operation completes. To prevent blocking while the operation completes, use the method. + + You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. + + The class does not support multiple simultaneous write operations. If you attempt to start a write operation while another write operation is already executing on the same stream, a exception will be thrown. + + + +## Examples + The following code example demonstrates writing to a . + [!code-cpp[NclNegoSyncClient#4](~/snippets/cpp/VS_Snippets_Remoting/NclNegoSyncClient/CPP/NclNegoSyncClient.cpp#4)] - [!code-csharp[NclNegoSyncClient#4](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#4)] - + [!code-csharp[NclNegoSyncClient#4](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#4)] + ]]> is . - . - + . + -or- - - is greater than the length of . - + + is greater than the length of . + -or- - + plus count is greater than the length of . - The write operation failed. - + The write operation failed. + -or- - + Encryption is in use, but the data could not be encrypted. There is already a write operation in progress. This object has been closed. @@ -4352,13 +4352,13 @@ This method reads asynchronously as much data as is available into `buffer` and Write asynchronously the specified number of s to the underlying stream. A that represents the asynchronous read operation. - on the underlying stream. - - You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. - + on the underlying stream. + + You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. + ]]> This object has been closed. @@ -4403,12 +4403,12 @@ This method reads asynchronously as much data as is available into `buffer` and A that represents the asynchronous read operation. on the underlying stream. - - You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. - + + You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or 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 . ]]> @@ -4418,19 +4418,19 @@ This method reads asynchronously as much data as is available into `buffer` and is . - . - + . + -or- - + is greater than the length of . - + -or- - + plus count is greater than the length of . The write operation failed. - + -or- - + Encryption is in use, but the data could not be encrypted. This object has been closed. Authentication has not occurred. @@ -4473,21 +4473,21 @@ This method reads asynchronously as much data as is available into `buffer` and Gets or sets the amount of time a write operation blocks waiting for data. A that specifies the amount of time that will elapse before a write operation fails. - property on the underlying stream. For set operations, the specified value sets the value on the underlying stream. - - If the underlying stream is a , is in milliseconds and is set to by default so that write operations do not time out. - - - -## Examples - The following code example demonstrates displaying the value of this property. - + property on the underlying stream. For set operations, the specified value sets the value on the underlying stream. + + If the underlying stream is a , is in milliseconds and is set to by default so that write operations do not time out. + + + +## Examples + The following code example demonstrates displaying the value of this property. + [!code-cpp[NclNegoSyncClient#2](~/snippets/cpp/VS_Snippets_Remoting/NclNegoSyncClient/CPP/NclNegoSyncClient.cpp#2)] - [!code-csharp[NclNegoSyncClient#2](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#2)] - + [!code-csharp[NclNegoSyncClient#2](~/snippets/csharp/System.Net.Security/NegotiateStream/.ctor/client.cs#2)] + ]]> diff --git a/xml/System.Net.Security/SslStream.xml b/xml/System.Net.Security/SslStream.xml index 76462f286ac..009dba13985 100644 --- a/xml/System.Net.Security/SslStream.xml +++ b/xml/System.Net.Security/SslStream.xml @@ -53,61 +53,61 @@ Provides a stream used for client-server communication that uses the Secure Socket Layer (SSL) security protocol to authenticate the server and optionally the client. - . An SSL connection, such as that provided by , should be used when communicating sensitive information between a client and a server. Using an helps to prevent anyone from reading and tampering with information while it is in transit on the network. - - An instance transmits data using a stream that you supply when creating the . When you supply this underlying stream, you have the option to specify whether closing the also closes the underlying stream. Typically, the class is used with the and classes. The method provides a suitable for use with the class. - - After creating an , the server and optionally, the client must be authenticated. The server must provide an X509 certificate that establishes proof of its identity and can request that the client also do so. Authentication must be performed before transmitting information using an . Clients initiate authentication using the synchronous methods, which block until the authentication completes, or the asynchronous methods, which do not block waiting for the authentication to complete. Servers initiate authentication using the synchronous or asynchronous methods. Both client and server must initiate the authentication. - - The authentication is handled by the Security Support Provider (SSPI) channel provider. The client is given an opportunity to control validation of the server's certificate by specifying a delegate when creating an . The server can also control validation by supplying a delegate. The method referenced by the delegate includes the remote party's certificate and any errors SSPI encountered while validating the certificate. Note that if the server specifies a delegate, the delegate's method is invoked regardless of whether the server requested client authentication. If the server did not request client authentication, the server's delegate method receives a null certificate and an empty array of certificate errors. - - If the server requires client authentication, the client must specify one or more certificates for authentication. If the client has more than one certificate, the client can provide a delegate to select the correct certificate for the server. The client's certificates must be located in the current user's "My" certificate store. Client authentication via certificates is not supported for the (SSL version 2) protocol. - - If the authentication fails, you receive a , and the is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - - When the authentication process, also known as the SSL handshake, succeeds, the identity of the server (and optionally, the client) is established and the can be used by the client and server to exchange messages. Before sending or receiving information, the client and server should check the security services and levels provided by the to determine whether the protocol, algorithms, and strengths selected meet their requirements for integrity and confidentiality. If the current settings are not sufficient, the stream should be closed. You can check the security services provided by the using the and properties. The following table shows the elements that report the cryptographic settings used for authentication, encryption and data signing. - -|Element|Members| -|-------------|-------------| -|The security protocol used to authenticate the server and, optionally, the client.|The property and the associated enumeration.| -|The key exchange algorithm.|The property and the associated enumeration.| -|The message integrity algorithm.|The property and the associated enumeration.| -|The message confidentiality algorithm.|The property and the associated enumeration.| -|The strengths of the selected algorithms.|The , , and properties.| - - After a successful authentication, you can send data using the synchronous or asynchronous methods. You can receive data using the synchronous or asynchronous methods. - - If you specified to the that the underlying stream should be left open, you are responsible for closing that stream when you are done using it. - + . An SSL connection, such as that provided by , should be used when communicating sensitive information between a client and a server. Using an helps to prevent anyone from reading and tampering with information while it is in transit on the network. + + An instance transmits data using a stream that you supply when creating the . When you supply this underlying stream, you have the option to specify whether closing the also closes the underlying stream. Typically, the class is used with the and classes. The method provides a suitable for use with the class. + + After creating an , the server and optionally, the client must be authenticated. The server must provide an X509 certificate that establishes proof of its identity and can request that the client also do so. Authentication must be performed before transmitting information using an . Clients initiate authentication using the synchronous methods, which block until the authentication completes, or the asynchronous methods, which do not block waiting for the authentication to complete. Servers initiate authentication using the synchronous or asynchronous methods. Both client and server must initiate the authentication. + + The authentication is handled by the Security Support Provider (SSPI) channel provider. The client is given an opportunity to control validation of the server's certificate by specifying a delegate when creating an . The server can also control validation by supplying a delegate. The method referenced by the delegate includes the remote party's certificate and any errors SSPI encountered while validating the certificate. Note that if the server specifies a delegate, the delegate's method is invoked regardless of whether the server requested client authentication. If the server did not request client authentication, the server's delegate method receives a null certificate and an empty array of certificate errors. + + If the server requires client authentication, the client must specify one or more certificates for authentication. If the client has more than one certificate, the client can provide a delegate to select the correct certificate for the server. The client's certificates must be located in the current user's "My" certificate store. Client authentication via certificates is not supported for the (SSL version 2) protocol. + + If the authentication fails, you receive a , and the is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + + When the authentication process, also known as the SSL handshake, succeeds, the identity of the server (and optionally, the client) is established and the can be used by the client and server to exchange messages. Before sending or receiving information, the client and server should check the security services and levels provided by the to determine whether the protocol, algorithms, and strengths selected meet their requirements for integrity and confidentiality. If the current settings are not sufficient, the stream should be closed. You can check the security services provided by the using the and properties. The following table shows the elements that report the cryptographic settings used for authentication, encryption and data signing. + +|Element|Members| +|-------------|-------------| +|The security protocol used to authenticate the server and, optionally, the client.|The property and the associated enumeration.| +|The key exchange algorithm.|The property and the associated enumeration.| +|The message integrity algorithm.|The property and the associated enumeration.| +|The message confidentiality algorithm.|The property and the associated enumeration.| +|The strengths of the selected algorithms.|The , , and properties.| + + After a successful authentication, you can send data using the synchronous or asynchronous methods. You can receive data using the synchronous or asynchronous methods. + + If you specified to the that the underlying stream should be left open, you are responsible for closing that stream when you are done using it. + > [!NOTE] -> If the application that creates the object runs with the credentials of a Normal user, the application will not be able to access certificates installed in the local machine store unless permission has been explicitly given to the user to do so. - - assumes that a timeout along with any other when one is thrown from the inner stream will be treated as fatal by its caller. Reusing a instance after a timeout will return garbage. An application should the and throw an exception in these cases. - - The .NET Framework 4.6 includes a new security feature that blocks insecure cipher and hashing algorithms for connections. Applications using TLS/SSL through APIs such as HttpClient, HttpWebRequest, FTPClient, SmtpClient, SslStream, etc. and targeting .NET Framework 4.6 get the more-secure behavior by default. - - Developers may want to opt out of this behavior in order to maintain interoperability with their existing SSL3 services OR TLS w/ RC4 services. [This article](https://support.microsoft.com/kb/3069494) explains how to modify your code so that the new behavior is disabled. - +> If the application that creates the object runs with the credentials of a Normal user, the application will not be able to access certificates installed in the local machine store unless permission has been explicitly given to the user to do so. + + assumes that a timeout along with any other when one is thrown from the inner stream will be treated as fatal by its caller. Reusing a instance after a timeout will return garbage. An application should the and throw an exception in these cases. + + The .NET Framework 4.6 includes a new security feature that blocks insecure cipher and hashing algorithms for connections. Applications using TLS/SSL through APIs such as HttpClient, HttpWebRequest, FTPClient, SmtpClient, SslStream, etc. and targeting .NET Framework 4.6 get the more-secure behavior by default. + + Developers may want to opt out of this behavior in order to maintain interoperability with their existing SSL3 services OR TLS w/ RC4 services. [This article](https://support.microsoft.com/kb/3069494) explains how to modify your code so that the new behavior is disabled. + The .NET Framework 4.7 adds new overloads for the methods that authenticate SslStreams that do not specify a TLS version, but instead use the TLS version defined as the system default in [SCHANNEL](/windows/win32/secauthn/secure-channel). Use these methods in your app as a way to be able to later modify the defaults as TLS version best practice changes over time, without the need to rebuild and redeploy your app. Also see [Transport Layer Security (TLS) best practices with the .NET Framework](/dotnet/framework/network-programming/tls). - - - -## Examples - The following code example demonstrates creating an that uses the class to communicate with clients. - + + + +## Examples + The following code example demonstrates creating an that uses the class to communicate with clients. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslServerSync/CPP/NclSslServerSync.cpp" id="Snippet0"::: -:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet0"::: +:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet0"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslServerSync/VB/serversync.vb" id="Snippet0"::: - - The following code example demonstrates creating a that uses the class to communicate with a server. - + + The following code example demonstrates creating a that uses the class to communicate with a server. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslClientSync/CPP/clientsync.cpp" id="Snippet0"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Security/RemoteCertificateValidationCallback/Overview/clientsync.cs" id="Snippet0"::: + :::code language="csharp" source="~/snippets/csharp/System.Net.Security/RemoteCertificateValidationCallback/Overview/clientsync.cs" id="Snippet0"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslClientSync/VB/clientsync.vb" id="Snippet0"::: ]]> @@ -126,11 +126,11 @@ Initializes a new instance of the class. - from closing the stream that you supply, use the constructor. - + from closing the stream that you supply, use the constructor. + ]]> @@ -179,26 +179,26 @@ A object used by the for sending and receiving data. Initializes a new instance of the class using the specified . - defaults to for the instance that is constructed. - - The use of the Null cipher is required when the encryption policy is set to . - + defaults to for the instance that is constructed. + + The use of the Null cipher is required when the encryption policy is set to . + ]]> - is not readable. - - -or- - + is not readable. + + -or- + is not writable. - is . - - -or- - + is . + + -or- + is equal to . @@ -248,37 +248,37 @@ A Boolean value that indicates the closure behavior of the object used by the for sending and receiving data. This parameter indicates if the inner stream is left open. Initializes a new instance of the class using the specified and stream closure behavior. - has no effect on the `innerStream` stream; you must explicitly close `innerStream` when you no longer need it. - - If a value is not specified in the configuration file for encryptionpolicy, the defaults to for the instance that is constructed. - - The use of the Null cipher is required when the encryption policy is set to . - - - -## Examples - The following code example demonstrates calling this constructor. - + has no effect on the `innerStream` stream; you must explicitly close `innerStream` when you no longer need it. + + If a value is not specified in the configuration file for encryptionpolicy, the defaults to for the instance that is constructed. + + The use of the Null cipher is required when the encryption policy is set to . + + + +## Examples + The following code example demonstrates calling this constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslServerSync/CPP/NclSslServerSync.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslServerSync/VB/serversync.vb" id="Snippet1"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslServerSync/VB/serversync.vb" id="Snippet1"::: + ]]> - is not readable. - - -or- - + is not readable. + + -or- + is not writable. - is . - - -or- - + is . + + -or- + is equal to . @@ -338,47 +338,47 @@ A delegate responsible for validating the certificate supplied by the remote party. Initializes a new instance of the class using the specified , stream closure behavior and certificate validation delegate. - has no effect on the `innerStream` stream; you must explicitly close `innerStream` when you no longer need it. - - The `userCertificateValidationCallback` delegate's `certificateErrors` argument contains any Windows error codes returned by the channel Security Support Provider Interface (SSPI). The return value of the method invoked by the `userCertificateValidationCallback` delegate determines whether authentication succeeds. - - The security protocol and cryptographic algorithms are already selected when the `userCertificateValidationCallback` delegate's method is invoked. You can use the method to determine whether the selected cryptographic algorithms and strengths are sufficient for your application. If not, the method should return `false` to prevent the from being created. - - If a value is not specified in the configuration file for encryptionpolicy, the defaults to for the instance that is constructed. - - The use of the Null cipher is required when the encryption policy is set to . - + has no effect on the `innerStream` stream; you must explicitly close `innerStream` when you no longer need it. + + The `userCertificateValidationCallback` delegate's `certificateErrors` argument contains any Windows error codes returned by the channel Security Support Provider Interface (SSPI). The return value of the method invoked by the `userCertificateValidationCallback` delegate determines whether authentication succeeds. + + The security protocol and cryptographic algorithms are already selected when the `userCertificateValidationCallback` delegate's method is invoked. You can use the method to determine whether the selected cryptographic algorithms and strengths are sufficient for your application. If not, the method should return `false` to prevent the from being created. + + If a value is not specified in the configuration file for encryptionpolicy, the defaults to for the instance that is constructed. + + The use of the Null cipher is required when the encryption policy is set to . + > [!NOTE] > .NET caches SSL sessions as they are created and attempts to reuse a cached session for subsequent requests, if possible. When attempting to reuse an SSL session, the Framework uses the first element of the provided during authentication (if there is one), or tries to reuse an anonymous sessions if the certificate collection is empty. - + > [!NOTE] -> Client certificates are not supported in the SSL version 2 protocol. - - - -## Examples - The following code example creates an and initiates the client portion of the authentication. - +> Client certificates are not supported in the SSL version 2 protocol. + + + +## Examples + The following code example creates an and initiates the client portion of the authentication. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslClientSync/CPP/clientsync.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Security/RemoteCertificateValidationCallback/Overview/clientsync.cs" id="Snippet4"::: + :::code language="csharp" source="~/snippets/csharp/System.Net.Security/RemoteCertificateValidationCallback/Overview/clientsync.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslClientSync/VB/clientsync.vb" id="Snippet4"::: - + ]]> - is not readable. - - -or- - + is not readable. + + -or- + is not writable. - is . - - -or- - + is . + + -or- + is equal to . @@ -444,45 +444,45 @@ A delegate responsible for selecting the certificate used for authentication. Initializes a new instance of the class using the specified , stream closure behavior, certificate validation delegate and certificate selection delegate. - has no effect on the `innerStream` stream; you must explicitly close `innerStream` when you no longer need it. - - The `userCertificateValidationCallback` delegate's `certificateErrors` argument contains any Windows error codes returned by the channel Security Support Provider Interface (SSPI). The return value of the method invoked by the `userCertificateValidationCallback` delegate determines whether authentication succeeds. - - The security protocol and cryptographic algorithms are already selected when the `userCertificateValidationCallback` delegate's method is invoked. You can use the method to determine whether the selected cryptographic algorithms and strengths are sufficient for your application. If not, the method should return `false` to prevent the from being created. - - The `userCertificateSelectionCallback` delegate is useful when your application has multiple certificates and must dynamically choose a certificate. Certificates in the "MY" store are passed to the method invoked by the delegate. - - If a value is not specified in the configuration file for encryptionpolicy, the defaults to for the instance that is constructed. - - The use of the Null cipher is required when the encryption policy is set to . - + has no effect on the `innerStream` stream; you must explicitly close `innerStream` when you no longer need it. + + The `userCertificateValidationCallback` delegate's `certificateErrors` argument contains any Windows error codes returned by the channel Security Support Provider Interface (SSPI). The return value of the method invoked by the `userCertificateValidationCallback` delegate determines whether authentication succeeds. + + The security protocol and cryptographic algorithms are already selected when the `userCertificateValidationCallback` delegate's method is invoked. You can use the method to determine whether the selected cryptographic algorithms and strengths are sufficient for your application. If not, the method should return `false` to prevent the from being created. + + The `userCertificateSelectionCallback` delegate is useful when your application has multiple certificates and must dynamically choose a certificate. Certificates in the "MY" store are passed to the method invoked by the delegate. + + If a value is not specified in the configuration file for encryptionpolicy, the defaults to for the instance that is constructed. + + The use of the Null cipher is required when the encryption policy is set to . + > [!NOTE] > .NET caches SSL sessions as they are created and attempts to reuse a cached session for subsequent requests, if possible. When attempting to reuse an SSL session, the Framework uses the first element of the provided during authentication (if there is one), or tries to reuse an anonymous sessions if the certificate collection is empty. - - -## Examples - The following code example demonstrates calling this constructor. This example is part of a larger example provided for the class. - + + +## Examples + The following code example demonstrates calling this constructor. This example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslClientAsync/CPP/NclSslClientAsync.cpp" id="Snippet6"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Security/LocalCertificateSelectionCallback/Overview/clientasync.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslClientAsync/VB/clientasync.vb" id="Snippet6"::: + :::code language="csharp" source="~/snippets/csharp/System.Net.Security/LocalCertificateSelectionCallback/Overview/clientasync.cs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslClientAsync/VB/clientasync.vb" id="Snippet6"::: ]]> - is not readable. - - -or- - + is not readable. + + -or- + is not writable. - is . - - -or- - + is . + + -or- + is equal to . @@ -545,28 +545,28 @@ The to use. Initializes a new instance of the class using the specified . - . - + . + ]]> - is not readable. - - -or- - - is not writable. - - -or- - + is not readable. + + -or- + + is not writable. + + -or- + is not valid. - is . - - -or- - + is . + + -or- + is equal to . @@ -609,15 +609,15 @@ The property bag for the SSL connection. Called by clients to authenticate the server and optionally the client in a client-server connection. - and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + ]]> @@ -675,28 +675,28 @@ The name of the server that shares this . Called by clients to authenticate the server and optionally the client in a client-server connection. - and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + ]]> is . The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Server authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Server authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. @@ -750,18 +750,18 @@ A value that specifies whether the certificate revocation list is checked during authentication. Called by clients to authenticate the server and optionally the client in a client-server connection. The authentication process uses the specified certificate collection, and the system default SSL protocol. - and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + > [!NOTE] -> Client certificates are not supported in the SSL version 2 protocol. - +> Client certificates are not supported in the SSL version 2 protocol. + ]]> @@ -820,18 +820,18 @@ A value that specifies whether the certificate revocation list is checked during authentication. Called by clients to authenticate the server and optionally the client in a client-server connection. The authentication process uses the specified certificate collection and SSL protocol. - and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + > [!NOTE] -> Client certificates are not supported in the SSL version 2 protocol. - +> Client certificates are not supported in the SSL version 2 protocol. + ]]> @@ -887,15 +887,15 @@ Called by clients to authenticate the server and optionally the client in a client-server connection as an asynchronous operation. The task object representing the asynchronous operation. - and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + 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 . ]]> @@ -903,14 +903,14 @@ is . The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Server authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Server authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. @@ -952,14 +952,14 @@ Called by clients to authenticate the server and optionally the client in a client-server connection as an asynchronous operation. The authentication process uses information specified in the property bag. The task object representing the asynchronous operation. - and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + 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 . ]]> @@ -967,14 +967,14 @@ is . The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Server authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Server authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. The cancellation token was canceled. This exception is stored into the returned task. @@ -1030,31 +1030,31 @@ Called by clients to authenticate the server and optionally the client in a client-server connection as an asynchronous operation. The authentication process uses the specified certificate collection and the system default SSL protocol. The task object representing the asynchronous operation. - and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + > [!NOTE] -> Client certificates are not supported in the SSL version 2 protocol. - +> Client certificates are not supported in the SSL version 2 protocol. + 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 . ]]> The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Server authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Server authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. @@ -1114,31 +1114,31 @@ Called by clients to authenticate the server and optionally the client in a client-server connection as an asynchronous operation. The authentication process uses the specified certificate collection and SSL protocol. The task object representing the asynchronous operation. - and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + > [!NOTE] -> Client certificates are not supported in the SSL version 2 protocol. - +> Client certificates are not supported in the SSL version 2 protocol. + 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 . ]]> The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Server authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Server authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. @@ -1196,14 +1196,14 @@ is . The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Client authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Client authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. The method is not supported on Windows 95, Windows 98, or Windows Millennium. @@ -1255,28 +1255,28 @@ The certificate used to authenticate the server. Called by servers to authenticate the server and optionally the client in a client-server connection using the specified certificate. - method overloads. - - If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + method overloads. + + If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + ]]> is . The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Client authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Client authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. The method is not supported on Windows 95, Windows 98, or Windows Millennium. @@ -1323,28 +1323,28 @@ A value that specifies whether the certificate revocation list is checked during authentication. Called by servers to authenticate the server and optionally the client in a client-server connection using the specified certificates and requirements, and using the system default security protocol. - method overloads. - - If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + + This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. + + If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + ]]> is . The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Client authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Client authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. The method is not supported on Windows 95, Windows 98, or Windows Millennium. @@ -1396,15 +1396,15 @@ A value that specifies whether the certificate revocation list is checked during authentication. Called by servers to authenticate the server and optionally the client in a client-server connection using the specified certificates, requirements and security protocol. - method overloads. - - If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + + This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. + + If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + ]]> @@ -1412,14 +1412,14 @@ is not a valid value. The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Client authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Client authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. The method is not supported on Windows 95, Windows 98, or Windows Millennium. @@ -1476,15 +1476,15 @@ Called by servers to authenticate the server and optionally the client in a client-server connection using the specified certificate as an asynchronous operation. The task object representing the asynchronous operation. - . The certificate revocation list is not checked during authentication. The client is not required to provide a certificate for authentication. - - If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + + This method authenticates using . The certificate revocation list is not checked during authentication. The client is not required to provide a certificate for authentication. + + If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + 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 . ]]> @@ -1492,14 +1492,14 @@ is . The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Client authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Client authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. The method is not supported on Windows 95, Windows 98, or Windows Millennium. @@ -1542,12 +1542,12 @@ Called by servers to authenticate the server and optionally the client in a client-server connection as an asynchronous operation. The authentication process uses information specified in the property bag. The task object representing the asynchronous operation. - , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + 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 . ]]> @@ -1557,14 +1557,14 @@ is . The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Client authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Client authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. The cancellation token was canceled. This exception is stored into the returned task. @@ -1610,25 +1610,25 @@ Called by servers to authenticate the server and optionally the client in a client-server connection as an asynchronous operation. The authentication process uses information returned by . The task object representing the asynchronous operation. - , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + ]]> Either or or is and is not set in the constructor. The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Client authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Client authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. The cancellation token was canceled. This exception is stored into the returned task. @@ -1676,13 +1676,13 @@ Called by servers to authenticate the server and optionally the client in a client-server connection using the specified certificates, requirements and security protocol as an asynchronous operation. The task object representing the asynchronous operation. - , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + + If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + 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 . ]]> @@ -1690,14 +1690,14 @@ is . The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Client authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Client authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. @@ -1749,13 +1749,13 @@ Called by servers to authenticate the server and optionally the client in a client-server connection using the specified certificates, requirements and security protocol as an asynchronous operation. The task object representing the asynchronous operation. - , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + + If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + 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 . ]]> @@ -1763,14 +1763,14 @@ is . The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Client authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Client authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. @@ -1784,11 +1784,11 @@ Begins an operation to authenticate the client side of a client-server connection. - methods. - + methods. + ]]> @@ -1853,34 +1853,34 @@ Called by clients to begin an asynchronous operation to authenticate the server and optionally the client. An object that indicates the status of the asynchronous operation. - method. Typically, the method is invoked by the `asyncCallback` delegate. - - This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. - - For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) - - If you receive a , this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + method. Typically, the method is invoked by the `asyncCallback` delegate. + + This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. + + For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + + If you receive a , this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + ]]> is . The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Server authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Server authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. @@ -1945,37 +1945,37 @@ Called by clients to begin an asynchronous operation to authenticate the server and optionally the client using the specified certificates and the system default security protocol. An object that indicates the status of the asynchronous operation. - method. Typically, the method is invoked by the `asyncCallback` delegate. - - This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. - - For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) - - If you receive a , this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + + The value specified for `targetHost` must match the name on the server's certificate. + + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. + + This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. + + For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + + If you receive a , this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + > [!NOTE] -> Client certificates are not supported in the SSL version 2 protocol. - +> Client certificates are not supported in the SSL version 2 protocol. + ]]> is . The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Server authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Server authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. @@ -2045,24 +2045,24 @@ Called by clients to begin an asynchronous operation to authenticate the server and optionally the client using the specified certificates and security protocol. An object that indicates the status of the asynchronous operation. - method. Typically, the method is invoked by the `asyncCallback` delegate. - - This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. - - For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) - - If you receive a , this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + + The value specified for `targetHost` must match the name on the server's certificate. + + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. + + This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. + + For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + + If you receive a , this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + > [!NOTE] -> Client certificates are not supported in the SSL version 2 protocol. - +> Client certificates are not supported in the SSL version 2 protocol. + ]]> @@ -2070,14 +2070,14 @@ is not a valid value. The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Server authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Server authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. @@ -2091,11 +2091,11 @@ Begins an asynchronous operation to handle the server side of authenticating a client-server connection. - methods. - + methods. + ]]> @@ -2166,32 +2166,32 @@ Called by servers to begin an asynchronous operation to authenticate the client and optionally the server in a client-server connection. An object indicating the status of the asynchronous operation. - method. Typically, the method is invoked by the `asyncCallback` delegate. - - This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. - - For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) - - If you receive a , this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + method. Typically, the method is invoked by the `asyncCallback` delegate. + + This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. + + For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + + If you receive a , this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + ]]> is . The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Client authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Client authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. The method is not supported on Windows 95, Windows 98, or Windows Millennium. @@ -2258,32 +2258,32 @@ Called by servers to begin an asynchronous operation to authenticate the server and optionally the client using the specified certificates and requirements, and the system default security protocol. An object that indicates the status of the asynchronous operation. - method. Typically, the method is invoked by the `asyncCallback` delegate. - - This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. - - For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) - - If you receive a , this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. + + This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. + + For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + + If you receive a , this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + ]]> is . The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Server authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Server authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. The method is not supported on Windows 95, Windows 98, or Windows Millennium. @@ -2355,19 +2355,19 @@ Called by servers to begin an asynchronous operation to authenticate the server and optionally the client using the specified certificates, requirements and security protocol. An object that indicates the status of the asynchronous operation. - method. Typically, the method is invoked by the `asyncCallback` delegate. - - This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. - - For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) - - If you receive a , this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - + + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. + + This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. + + For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + + If you receive a , this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + ]]> @@ -2375,14 +2375,14 @@ is not a valid value. The authentication failed and left this object in an unusable state. - Authentication has already occurred. - - -or- - - Server authentication using this was tried previously. - - -or- - + Authentication has already occurred. + + -or- + + Server authentication using this was tried previously. + + -or- + Authentication is already in progress. This object has been closed. The method is not supported on Windows 95, Windows 98, or Windows Millennium. @@ -2452,38 +2452,38 @@ Begins an asynchronous read operation that reads data from the stream and stores it in the specified array. An object that indicates the status of the asynchronous operation. - method. Typically, the method is invoked by the `asyncCallback` delegate. - - This method does not block while the operation completes. To block until the operation completes, use the method. - - For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) - - The class does not support multiple simultaneous read operations. - - You cannot call this method until you have successfully authenticated. To authenticate call one of the , or , , methods. - - - -## Examples - The following code example demonstrates starting an asynchronous read operation. - + method. Typically, the method is invoked by the `asyncCallback` delegate. + + This method does not block while the operation completes. To block until the operation completes, use the method. + + For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + + The class does not support multiple simultaneous read operations. + + You cannot call this method until you have successfully authenticated. To authenticate call one of the , or , , methods. + + + +## Examples + The following code example demonstrates starting an asynchronous read operation. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslClientAsync/CPP/NclSslClientAsync.cpp" id="Snippet8"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Security/LocalCertificateSelectionCallback/Overview/clientasync.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslClientAsync/VB/clientasync.vb" id="Snippet8"::: + :::code language="csharp" source="~/snippets/csharp/System.Net.Security/LocalCertificateSelectionCallback/Overview/clientasync.cs" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslClientAsync/VB/clientasync.vb" id="Snippet8"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslClientAsync/CPP/NclSslClientAsync.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Security/LocalCertificateSelectionCallback/Overview/clientasync.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslClientAsync/VB/clientasync.vb" id="Snippet4"::: + :::code language="csharp" source="~/snippets/csharp/System.Net.Security/LocalCertificateSelectionCallback/Overview/clientasync.cs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslClientAsync/VB/clientasync.vb" id="Snippet4"::: + + + The following method is called when the read completes. - - The following method is called when the read completes. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslClientAsync/CPP/NclSslClientAsync.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Security/LocalCertificateSelectionCallback/Overview/clientasync.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslClientAsync/VB/clientasync.vb" id="Snippet5"::: + :::code language="csharp" source="~/snippets/csharp/System.Net.Security/LocalCertificateSelectionCallback/Overview/clientasync.cs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslClientAsync/VB/clientasync.vb" id="Snippet5"::: ]]> @@ -2494,15 +2494,15 @@ -or- - is greater than the length of . + is greater than the length of . + +-or- --or- - + count is greater than the length of . - The read operation failed. - - -or- - + The read operation failed. + + -or- + Encryption is in use, but the data could not be decrypted. There is already a read operation in progress. This object has been closed. @@ -2573,27 +2573,27 @@ Begins an asynchronous write operation that writes s from the specified buffer to the stream. An object indicating the status of the asynchronous operation. - is . is less than zero. - + -or- - - is greater than the length of . - + + is greater than the length of . + -or- - + + count is greater than the length of . The write operation failed. There is already a write operation in progress. @@ -2640,20 +2640,20 @@ if authentication has occurred and the underlying stream is readable; otherwise . - on the underlying stream. - - The underlying stream is specified when you create an instance of the class. - - - -## Examples - The following code example demonstrates displaying the value of this property. - + on the underlying stream. + + The underlying stream is specified when you create an instance of the class. + + + +## Examples + The following code example demonstrates displaying the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslServerSync/CPP/NclSslServerSync.cpp" id="Snippet5"::: -:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet5"::: +:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslServerSync/VB/serversync.vb" id="Snippet5"::: ]]> @@ -2698,13 +2698,13 @@ Gets a value that indicates whether the underlying stream is seekable. This property always returns . - object or its underlying stream. - - The underlying stream is specified when you create an instance of the class. - + object or its underlying stream. + + The underlying stream is specified when you create an instance of the class. + ]]> @@ -2750,22 +2750,22 @@ if the underlying stream supports time-outs; otherwise, . - on the underlying stream. - - The underlying stream is specified when you create an instance of the class. - - - -## Examples - The following code example demonstrates displaying the value of this property. - + on the underlying stream. + + The underlying stream is specified when you create an instance of the class. + + + +## Examples + The following code example demonstrates displaying the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslServerSync/CPP/NclSslServerSync.cpp" id="Snippet5"::: -:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet5"::: +:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslServerSync/VB/serversync.vb" id="Snippet5"::: - + ]]> @@ -2809,22 +2809,22 @@ if authentication has occurred and the underlying stream is writable; otherwise . - on the underlying stream. - - The underlying stream is specified when you create an instance of the class. - - - -## Examples - The following code example demonstrates displaying the value of this property. - + on the underlying stream. + + The underlying stream is specified when you create an instance of the class. + + + +## Examples + The following code example demonstrates displaying the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslServerSync/CPP/NclSslServerSync.cpp" id="Snippet5"::: -:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet5"::: +:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslServerSync/VB/serversync.vb" id="Snippet5"::: - + ]]> @@ -2868,20 +2868,20 @@ if the certificate revocation list is checked; otherwise, . - @@ -2924,22 +2924,22 @@ Gets a value that identifies the bulk encryption algorithm used by this . A value that identifies the bulk encryption algorithm used by this . - is required for the property when the enumeration value is used to construct a instance. - - Windows Server 2003 and Windows XP do not support the value. So even if the value is used to construct the instance, the property will be . The value is only returned on Windows Vista and later. - - - -## Examples - The following code example displays the cryptography settings for the specified stream. - + is required for the property when the enumeration value is used to construct a instance. + + Windows Server 2003 and Windows XP do not support the value. So even if the value is used to construct the instance, the property will be . The value is only returned on Windows Vista and later. + + + +## Examples + The following code example displays the cryptography settings for the specified stream. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslServerSync/CPP/NclSslServerSync.cpp" id="Snippet3"::: -:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet3"::: +:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslServerSync/VB/serversync.vb" id="Snippet3"::: - + ]]> The property was accessed before the completion of the authentication process or the authentication process failed. @@ -2983,38 +2983,38 @@ Gets a value that identifies the strength of the cipher algorithm used by this . An value that specifies the strength of the algorithm, in bits. - @@ -3060,20 +3060,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -3107,15 +3107,15 @@ Asynchronously releases the unmanaged and managed resources used by the . A task that represents the asynchronous dispose operation. - is `false`; otherwise, the inner stream is just flushed. - + Calling `DisposeAsync` allows the resources used by the to be reallocated for other purposes. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - + ]]> @@ -3160,15 +3160,15 @@ An instance returned by a call to . Ends a pending asynchronous server authentication operation started with a previous call to . - and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - - To perform this operation synchronously, use one of the methods. - + and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + + To perform this operation synchronously, use one of the methods. + ]]> @@ -3219,15 +3219,15 @@ An instance returned by a call to . Ends a pending asynchronous client authentication operation started with a previous call to . - and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - - If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - - To perform this operation synchronously, use one of the method. - + and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + + If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. + + To perform this operation synchronously, use one of the method. + ]]> @@ -3279,23 +3279,23 @@ Ends an asynchronous read operation started with a previous call to . A value that specifies the number of bytes read from the underlying stream. - method. - - You cannot call this method until you have successfully authenticated. To authenticate call one of the , or , , methods. - - - -## Examples - The following code example demonstrates ending an asynchronous read operation. - + method. + + You cannot call this method until you have successfully authenticated. To authenticate call one of the , or , , methods. + + + +## Examples + The following code example demonstrates ending an asynchronous read operation. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslClientAsync/CPP/NclSslClientAsync.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Security/LocalCertificateSelectionCallback/Overview/clientasync.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslClientAsync/VB/clientasync.vb" id="Snippet5"::: + :::code language="csharp" source="~/snippets/csharp/System.Net.Security/LocalCertificateSelectionCallback/Overview/clientasync.cs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslClientAsync/VB/clientasync.vb" id="Snippet5"::: ]]> @@ -3351,23 +3351,23 @@ Authentication has not occurred. An instance returned by a call to . Ends an asynchronous write operation started with a previous call to . - , or , , methods. - - To perform this operation synchronously, use the method. - - - -## Examples - The following code example demonstrates ending an asynchronous write operation. - + , or , , methods. + + To perform this operation synchronously, use the method. + + + +## Examples + The following code example demonstrates ending an asynchronous write operation. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslServerAsync/CPP/NclSslServerAsync.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/BeginWrite/serverasync.cs" id="Snippet4"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/BeginWrite/serverasync.cs" id="Snippet4"::: + ]]> @@ -3457,18 +3457,18 @@ Authentication has not occurred. Causes any buffered data to be written to the underlying device. - on the underlying stream. - - - -## Examples - The following code example demonstrates calling this method. - + on the underlying stream. + + + +## Examples + The following code example demonstrates calling this method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslClientSync/CPP/clientsync.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Security/RemoteCertificateValidationCallback/Overview/clientsync.cs" id="Snippet5"::: + :::code language="csharp" source="~/snippets/csharp/System.Net.Security/RemoteCertificateValidationCallback/Overview/clientsync.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslClientSync/VB/clientsync.vb" id="Snippet5"::: ]]> @@ -3509,9 +3509,9 @@ Authentication has not occurred. Asynchronously writes any buffered data to the underlying device. A task that represents the asynchronous flush operation. - on the underlying stream. 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 . @@ -3559,20 +3559,20 @@ Authentication has not occurred. Gets the algorithm used for generating message authentication codes (MACs). The algorithm used for generating message authentication codes (MACs). - The property was accessed before the completion of the authentication process or the authentication process failed. @@ -3616,20 +3616,20 @@ Authentication has not occurred. Gets a value that identifies the strength of the hash algorithm used by this instance. An value that specifies the strength of the algorithm, in bits. Valid values are 128 or 160. - @@ -3673,20 +3673,20 @@ Authentication has not occurred. if successful authentication occurred; otherwise, . - or methods. Servers authenticate by calling the or methods. - - - -## Examples - The following code example demonstrates displaying the value of this property. - + or methods. Servers authenticate by calling the or methods. + + + +## Examples + The following code example demonstrates displaying the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslServerSync/CPP/NclSslServerSync.cpp" id="Snippet4"::: -:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet4"::: +:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslServerSync/VB/serversync.vb" id="Snippet4"::: - + ]]> @@ -3730,20 +3730,20 @@ Authentication has not occurred. if data is encrypted before being transmitted over the network and decrypted when it reaches the remote endpoint; otherwise . - @@ -3787,20 +3787,20 @@ Authentication has not occurred. if both server and client have been authenticated; otherwise . - @@ -3846,22 +3846,22 @@ Authentication has not occurred. if the local endpoint was successfully authenticated as the server side of the authenticated connection; otherwise . - or methods. - - - -## Examples - The following code example demonstrates displaying the value of this property. - + or methods. + + + +## Examples + The following code example demonstrates displaying the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslServerSync/CPP/NclSslServerSync.cpp" id="Snippet4"::: -:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet4"::: +:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslServerSync/VB/serversync.vb" id="Snippet4"::: - + ]]> @@ -3905,20 +3905,20 @@ Authentication has not occurred. if the data is signed before being transmitted; otherwise . - @@ -3961,22 +3961,22 @@ Authentication has not occurred. Gets the key exchange algorithm used by this . An value. - until the authentication occurs. - - The key exchange algorithm protects information used to generate shared keys. - - - -## Examples - The following code example displays the cryptography settings for the specified stream. - + until the authentication occurs. + + The key exchange algorithm protects information used to generate shared keys. + + + +## Examples + The following code example displays the cryptography settings for the specified stream. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslServerSync/CPP/NclSslServerSync.cpp" id="Snippet3"::: -:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet3"::: +:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslServerSync/VB/serversync.vb" id="Snippet3"::: - + ]]> @@ -4019,29 +4019,29 @@ Authentication has not occurred. Gets a value that identifies the strength of the key exchange algorithm used by this instance. An value that specifies the strength of the algorithm, in bits. - @@ -4085,11 +4085,11 @@ Authentication has not occurred. Gets the length of the underlying stream. The length of the underlying stream. - on the underlying stream. If the underlying stream is not seekable, this method typically throws an exception. The run-time type of the underlying stream determines the run-time type of the exception that is thrown. - + on the underlying stream. If the underlying stream is not seekable, this method typically throws an exception. The run-time type of the underlying stream determines the run-time type of the exception that is thrown. + ]]> Getting the value of this property is not supported when the underlying stream is a . @@ -4144,15 +4144,15 @@ Authentication has not occurred. Gets the certificate used to authenticate the local endpoint. An X509Certificate object that represents the certificate supplied for authentication or if no certificate was supplied. - Authentication failed or has not occurred. @@ -4268,8 +4268,8 @@ Authentication has not occurred. Gets the cipher suite which was negotiated for this connection. One of the enumeration values that identifies the cipher suite which was negotiated for this connection. - or . @@ -4317,17 +4317,17 @@ This property gets the cipher suite that is going to be used in the communicatio Gets or sets the current position in the underlying stream. The current position in the underlying stream. - on the underlying stream. If the underlying stream is not seekable, this method typically throws an exception. The run-time type of the underlying stream determines the run-time type of the exception that is thrown. - + on the underlying stream. If the underlying stream is not seekable, this method typically throws an exception. The run-time type of the underlying stream determines the run-time type of the exception that is thrown. + ]]> - Setting this property is not supported. - - -or- - + Setting this property is not supported. + + -or- + Getting the value of this property is not supported when the underlying stream is a . @@ -4377,22 +4377,22 @@ This property gets the cipher suite that is going to be used in the communicatio Reads data from this stream and stores it in the specified array. A value that specifies the number of bytes read. When there is no more data to be read, returns 0. - , or , , methods. - - To perform this operation asynchronously, use the method. - - - -## Examples - The following code example demonstrates reading from an . - + , or , , methods. + + To perform this operation asynchronously, use the method. + + + +## Examples + The following code example demonstrates reading from an . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslClientSync/CPP/clientsync.cpp" id="Snippet6"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Security/RemoteCertificateValidationCallback/Overview/clientsync.cs" id="Snippet6"::: + :::code language="csharp" source="~/snippets/csharp/System.Net.Security/RemoteCertificateValidationCallback/Overview/clientsync.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslClientSync/VB/clientsync.vb" id="Snippet6"::: ]]> @@ -4401,12 +4401,12 @@ This property gets the cipher suite that is going to be used in the communicatio is . is less than zero. - + -or- - is greater than the length of . + is greater than the length of . --or- +-or- + count is greater than the length of . The read operation failed. Check the inner exception, if present to determine the cause of the failure. @@ -4455,13 +4455,13 @@ This property gets the cipher suite that is going to be used in the communicatio Asynchronously reads data from this stream and stores it in the specified memory range. A task that represents the asynchronous read operation. The value of its property contains the total number of bytes read into . When there is no more data to be read, returns 0. - @@ -4512,13 +4512,13 @@ This property gets the cipher suite that is going to be used in the communicatio Asynchronously reads data from this stream and stores it in the specified range of a byte array. A task that represents the asynchronous read operation. The value of its property contains the total number of bytes read into . When there is no more data to be read, returns 0. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -4528,14 +4528,14 @@ This property gets the cipher suite that is going to be used in the communicatio is . - is less than 0. - - -or- - + is less than 0. + + -or- + is less than 0. - - -or- - + + -or- + is greater than the length of minus . Authentication has not occurred. The read operation failed. Check the inner exception, if it is present, to determine the cause of the failure. @@ -4574,11 +4574,11 @@ This property gets the cipher suite that is going to be used in the communicatio Reads a byte from the and advances the position within the stream by one byte, or returns -1 if at the end of the stream. The unsigned byte cast to an , or -1 if at the end of the stream. - @@ -4627,22 +4627,22 @@ This property gets the cipher suite that is going to be used in the communicatio Gets or sets the amount of time, expressed in milliseconds, a read operation blocks waiting for data. The amount of time, in milliseconds, that elapses before a synchronous read operation fails. - on the underlying stream. When you set this property, the value on the underlying stream is set to the specified value. - - If the underlying stream is a , is in milliseconds and is set to by default so that read operations do not timeout. - - - -## Examples - The following code example demonstrates setting the value of this property. - + on the underlying stream. When you set this property, the value on the underlying stream is set to the specified value. + + If the underlying stream is a , is in milliseconds and is set to by default so that read operations do not timeout. + + + +## Examples + The following code example demonstrates setting the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslServerSync/CPP/NclSslServerSync.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslServerSync/VB/serversync.vb" id="Snippet1"::: - + ]]> @@ -4696,16 +4696,16 @@ This property gets the cipher suite that is going to be used in the communicatio Gets the certificate used to authenticate the remote endpoint. An X509Certificate object that represents the certificate supplied for authentication or if no certificate was supplied. - object. - -## Examples - The following code example demonstrates displaying the certificate returned by this property. - + +## Examples + The following code example demonstrates displaying the certificate returned by this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslServerSync/CPP/NclSslServerSync.cpp" id="Snippet6"::: -:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet6"::: +:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslServerSync/VB/serversync.vb" id="Snippet6"::: - + ]]> Authentication failed or has not occurred. @@ -4755,11 +4755,11 @@ If the property is accessed, the remote certificate will not be disposed when th Throws a . Always throws a . - class. - + class. + ]]> Seeking is not supported by objects. @@ -4806,11 +4806,11 @@ If the property is accessed, the remote certificate will not be disposed when th An value that specifies the length of the stream. Sets the length of the underlying stream. - on the underlying stream specified when this was created. - + on the underlying stream specified when this was created. + ]]> @@ -4890,21 +4890,21 @@ If the property is accessed, the remote certificate will not be disposed when th Gets a value that indicates the security protocol used to authenticate this connection. The value that represents protocols used for authentication. - or via and or . If no security protocol was explicitly specified, the value is used. - - The actual protocol used for authentication is selected based on the ones supported by the client and server. - - -## Examples - The following example displays the security properties of the specified stream. - + + The actual protocol used for authentication is selected based on the ones supported by the client and server. + + +## Examples + The following example displays the security properties of the specified stream. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslServerSync/CPP/NclSslServerSync.cpp" id="Snippet3"::: -:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet3"::: +:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslServerSync/VB/serversync.vb" id="Snippet3"::: - + ]]> @@ -5030,24 +5030,24 @@ If the property is accessed, the remote certificate will not be disposed when th A array that supplies the bytes written to the stream. Writes the specified data to this stream. - method. - - You cannot call this method until you have successfully authenticated. To authenticate call one of the , or , , methods. - - The class does not support multiple simultaneous write operations. - - - -## Examples - The following code example demonstrates writing to an authenticated . - + method. + + You cannot call this method until you have successfully authenticated. To authenticate call one of the , or , , methods. + + The class does not support multiple simultaneous write operations. + + + +## Examples + The following code example demonstrates writing to an authenticated . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslServerSync/CPP/NclSslServerSync.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslServerSync/VB/serversync.vb" id="Snippet1"::: - + ]]> @@ -5103,15 +5103,15 @@ If the property is accessed, the remote certificate will not be disposed when th A that contains the number of bytes to read from . Write the specified number of s to the underlying stream using the specified buffer and offset. - method. - - You cannot call this method until you have successfully authenticated. To authenticate call one of the , or , , methods. - - The class does not support multiple simultaneous write operations. - + method. + + You cannot call this method until you have successfully authenticated. To authenticate call one of the , or , , methods. + + The class does not support multiple simultaneous write operations. + ]]> @@ -5121,10 +5121,10 @@ If the property is accessed, the remote certificate will not be disposed when th -or- - is greater than the length of . - - -or- - + is greater than the length of . + + -or- + + count is greater than the length of . The write operation failed. There is already a write operation in progress. @@ -5172,10 +5172,10 @@ If the property is accessed, the remote certificate will not be disposed when th Asynchronously writes data to the underlying stream from a read-only byte memory range. A task that represents the asynchronous write operation. - class does not support multiple simultaneous write operations. @@ -5227,10 +5227,10 @@ The class does not support multiple simulta Asynchronously writes data to the underlying stream from the specified range of a byte array. A task that represents the asynchronous write operation. - class does not support multiple simultaneous write operations. @@ -5241,14 +5241,14 @@ The class does not support multiple simulta is . - is less than 0. - - -or- - + is less than 0. + + -or- + is less than 0. - - -or- - + + -or- + is greater than the length of minus . Authentication has not occurred. The write operation failed. @@ -5295,22 +5295,22 @@ The class does not support multiple simulta Gets or sets the amount of time a write operation blocks waiting for data. The amount of time that elapses before a synchronous write operation fails. - on the underlying stream. For set operations, the specified value sets the value on the underlying stream. - - If the underlying stream is a , is in milliseconds and is set to by default so that write operations do not timeout. - - - -## Examples - The following code example demonstrates setting the value of this property. - + on the underlying stream. For set operations, the specified value sets the value on the underlying stream. + + If the underlying stream is a , is in milliseconds and is set to by default so that write operations do not timeout. + + + +## Examples + The following code example demonstrates setting the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclSslServerSync/CPP/NclSslServerSync.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Net.Security/SslStream/Overview/serversync.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NclSslServerSync/VB/serversync.vb" id="Snippet1"::: - + ]]> diff --git a/xml/System.Net.Sockets/NetworkStream.xml b/xml/System.Net.Sockets/NetworkStream.xml index d1667e02df8..63ea51cf6d7 100644 --- a/xml/System.Net.Sockets/NetworkStream.xml +++ b/xml/System.Net.Sockets/NetworkStream.xml @@ -59,19 +59,19 @@ Provides the underlying stream of data for network access. - class provides methods for sending and receiving data over sockets in blocking mode. For more information about blocking versus nonblocking s, see [Using an Asynchronous Client Socket](/dotnet/framework/network-programming/using-an-asynchronous-client-socket). You can use the class for both synchronous and asynchronous data transfer. For more information about synchronous and asynchronous communication, see [Sockets](/dotnet/framework/network-programming/sockets). - - To create a , you must provide a connected . You can also specify what permission the has over the provided . By default, closing the does not close the provided . If you want the to have permission to close the provided , you must specify `true` for the value of the `ownsSocket` parameter. - - Use the and methods for simple single threaded synchronous blocking I/O. If you want to process your I/O asynchronously, consider using the or -based methods and . - - The does not support random access to the network data stream. The value of the property, which indicates whether the stream supports seeking, is always `false`; reading the property, reading the property, or calling the method will throw a . - - Read and write operations can be performed simultaneously on an instance of the class without the need for synchronization. As long as there is one unique thread for the write operations and one unique thread for the read operations, there will be no cross-interference between read and write threads and no synchronization is required. - + class provides methods for sending and receiving data over sockets in blocking mode. For more information about blocking versus nonblocking s, see [Using an Asynchronous Client Socket](/dotnet/framework/network-programming/using-an-asynchronous-client-socket). You can use the class for both synchronous and asynchronous data transfer. For more information about synchronous and asynchronous communication, see [Sockets](/dotnet/framework/network-programming/sockets). + + To create a , you must provide a connected . You can also specify what permission the has over the provided . By default, closing the does not close the provided . If you want the to have permission to close the provided , you must specify `true` for the value of the `ownsSocket` parameter. + + Use the and methods for simple single threaded synchronous blocking I/O. If you want to process your I/O asynchronously, consider using the or -based methods and . + + The does not support random access to the network data stream. The value of the property, which indicates whether the stream supports seeking, is always `false`; reading the property, reading the property, or calling the method will throw a . + + Read and write operations can be performed simultaneously on an instance of the class without the need for synchronization. As long as there is one unique thread for the write operations and one unique thread for the read operations, there will be no cross-interference between read and write threads and no synchronization is required. + ]]> @@ -127,24 +127,24 @@ The that the will use to send and receive data. Creates a new instance of the class for the specified . - is created with read/write access to the specified . - The does not own the underlying , so calling the or method does not close the . - + The does not own the underlying , so calling the or method does not close the . + ]]> The parameter is . - The parameter is not connected. - - -or- - - The property of the parameter is not . - - -or- - + The parameter is not connected. + + -or- + + The property of the parameter is not . + + -or- + The parameter is in a nonblocking state. Using Streams on the Network @@ -191,23 +191,23 @@ Set to to indicate that the will take ownership of the ; otherwise, . Initializes a new instance of the class for the specified with the specified ownership. - is created with read/write access to the specified . If the value of `ownsSocket` parameter is `true`, the takes ownership of the underlying , and calling the or method also closes the underlying . ]]> The parameter is . - The parameter is not connected. - - -or- - - the value of the property of the parameter is not . - - -or- - + The parameter is not connected. + + -or- + + the value of the property of the parameter is not . + + -or- + the parameter is in a nonblocking state. @@ -252,25 +252,25 @@ A bitwise combination of the values that specify the type of access given to the over the provided . Creates a new instance of the class for the specified with the specified access rights. - is created with the specified access to the specified . With this constructor, the does not own the underlying , so calling the or method does not close the underlying . - - The `access` parameter sets the and properties of the . If you specify , then the allows calls to the method. If you specify , then the allows calls to the method. If you specify , both method calls are allowed. + + The `access` parameter sets the and properties of the . If you specify , then the allows calls to the method. If you specify , then the allows calls to the method. If you specify , both method calls are allowed. ]]> The parameter is . - The parameter is not connected. - - -or- - - the property of the parameter is not . - - -or- - + The parameter is not connected. + + -or- + + the property of the parameter is not . + + -or- + the parameter is in a nonblocking state. @@ -322,25 +322,25 @@ Set to to indicate that the will take ownership of the ; otherwise, . Creates a new instance of the class for the specified with the specified access rights and the specified ownership. - is created with read/write access to the specified . If the value of the `ownsSocket` parameter is `true`, the takes ownership of the underlying , and calling the or method also closes the underlying . - - The `access` parameter sets the and properties of the . If you specify , then the allows calls to the method. If you specify , then the allows calls to the method. If you specify , both method calls are allowed. + + The `access` parameter sets the and properties of the . If you specify , then the allows calls to the method. If you specify , then the allows calls to the method. If you specify , both method calls are allowed. ]]> The parameter is . - The parameter is not connected. - - -or- - - The property of the parameter is not . - - -or- - + The parameter is not connected. + + -or- + + The property of the parameter is not . + + -or- + The parameter is in a nonblocking state. @@ -422,47 +422,47 @@ Begins an asynchronous read from the . An that represents the asynchronous call. - [!IMPORTANT] > This is a compatibility API, we don't recommend to use the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (Begin / End) methods for new development. Instead, use the Task-based equivalents. You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. - - The operation reads as much data as is available, up to the number of bytes specified by the `size` parameter. - + The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. + + The operation reads as much data as is available, up to the number of bytes specified by the `size` parameter. + > [!NOTE] -> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code. +> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code. Read and write operations can be performed simultaneously on an instance of the class without the need for synchronization. As long as there is one unique thread for the write operations and one unique thread for the read operations, there will be no cross-interference between read and write threads and no synchronization is required. ]]> The parameter is . - The parameter is less than 0. - - -or- - - The parameter is greater than the length of the paramater. - - -or- - - The is less than 0. - - -or- - + The parameter is less than 0. + + -or- + + The parameter is greater than the length of the paramater. + + -or- + + The is less than 0. + + -or- + The is greater than the length of minus the value of the parameter. - The underlying is closed. - - -or- - - There was a failure while reading from the network. - - -or- - + The underlying is closed. + + -or- + + There was a failure while reading from the network. + + -or- + An error occurred when accessing the socket. The is closed. @@ -540,45 +540,45 @@ Begins an asynchronous write to a stream. An that represents the asynchronous call. - [!IMPORTANT] > This is a compatibility API, we don't recommend to use the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (Begin / End) methods for new development. Instead, use the Task-based equivalents. You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. - + The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. + > [!NOTE] -> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code. - +> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code. + Read and write operations can be performed simultaneously on an instance of the class without the need for synchronization. As long as there is one unique thread for the write operations and one unique thread for the read operations, there will be no cross-interference between read and write threads and no synchronization is required. - + ]]> The parameter is . - The parameter is less than 0. - - -or- - - The parameter is greater than the length of . - - -or- - - The parameter is less than 0. - - -or- - + The parameter is less than 0. + + -or- + + The parameter is greater than the length of . + + -or- + + The parameter is less than 0. + + -or- + The parameter is greater than the length of minus the value of the parameter. - The underlying is closed. - - -or- - - There was a failure while writing to the network. - - -or- - + The underlying is closed. + + -or- + + There was a failure while writing to the network. + + -or- + An error occurred when accessing the socket. The is closed. @@ -630,11 +630,11 @@ if data can be read from the stream; otherwise, . The default value is . - is `true`, allows calls to the method. Provide the appropriate enumerated value in the constructor to set the readability and writability of the . - + > [!NOTE] > The property is set when the is initialized. > Changes in the underlying 's state (eg. closure) do not affect the value of . @@ -726,11 +726,11 @@ in all cases. - . - + . + ]]> @@ -781,14 +781,14 @@ if data can be written to the ; otherwise, . The default value is . - is `true`, allows calls to the method. Provide the appropriate enumerated value in the constructor to set the readability and writability of the . - + > [!NOTE] > The property is set when the is initialized. -> Changes in the underlying 's state (eg. closure) do not affect the value of . +> Changes in the underlying 's state (eg. closure) do not affect the value of . ]]> @@ -823,12 +823,12 @@ . If the owns the underlying , it is closed as well. If a was associated with a , the `Close` method will close the TCP connection, but not dispose of the associated . -## Examples +## Examples The following code example closes the . ```vb @@ -894,13 +894,13 @@ myNetworkStream->Close(); A 32-bit signed integer that specifies the number of milliseconds to wait to send any remaining data before closing. Closes the after waiting the specified time to allow data to be sent. - method frees both unmanaged and managed resources associated with the . If the owns the underlying , it is closed as well. - - If a was associated with a , the method will close the TCP connection, but not dispose of the associated . - + method frees both unmanaged and managed resources associated with the . If the owns the underlying , it is closed as well. + + If a was associated with a , the method will close the TCP connection, but not dispose of the associated . + ]]> The parameter is less than -1. @@ -988,10 +988,10 @@ The Close method frees both unmanaged and managed resources associated with the if data is available on the stream to be read; otherwise, . - property to determine if data is queued to be immediately read. + property to determine if data is queued to be immediately read. If is `true`, a call to returns immediately. If the remote host shuts down or closes the connection, may throw a . @@ -1054,20 +1054,20 @@ The Close method frees both unmanaged and managed resources associated with the to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + This method is called by the public `Dispose()` method and the method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -1113,26 +1113,26 @@ The Close method frees both unmanaged and managed resources associated with the Handles the end of an asynchronous read. The number of bytes read from the . - [!IMPORTANT] > This is a compatibility API, we don't recommend to use the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (Begin / End) methods for new development. Instead, use the Task-based equivalents. - The method completes the read operation started by the method. You need to pass the created by the matching call. will block the calling thread until the operation is completed. - - The operation reads as much data as is available, up to the number of bytes specified by the `size` parameter. - + The method completes the read operation started by the method. You need to pass the created by the matching call. will block the calling thread until the operation is completed. + + The operation reads as much data as is available, up to the number of bytes specified by the `size` parameter. + > [!NOTE] -> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code. +> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code. ]]> The parameter is . - The underlying is closed. - - -or- - + The underlying is closed. + + -or- + An error occurred when accessing the socket. The is closed. @@ -1179,30 +1179,30 @@ The Close method frees both unmanaged and managed resources associated with the The that represents the asynchronous call. Handles the end of an asynchronous write. - [!IMPORTANT] > This is a compatibility API, we don't recommend to use the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (Begin / End) methods for new development. Instead, use the Task-based equivalents. - The method completes the read operation started by the method. You need to pass the created by the matching call. will block the calling thread until the operation is completed. - - The operation reads as much data as is available, up to the number of bytes specified by the `size` parameter. - + The method completes the read operation started by the method. You need to pass the created by the matching call. will block the calling thread until the operation is completed. + + The operation reads as much data as is available, up to the number of bytes specified by the `size` parameter. + > [!NOTE] -> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code. +> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code. ]]> The parameter is . - The underlying is closed. - - -or- - - An error occurred while writing to the network. - - -or- - + The underlying is closed. + + -or- + + An error occurred while writing to the network. + + -or- + An error occurred when accessing the socket. The is closed. @@ -1247,13 +1247,13 @@ The Close method frees both unmanaged and managed resources associated with the Releases all resources used by the . - . Application code should not call this method; an object's 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 about using the Finalize method, 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)). - + . Application code should not call this method; an object's 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 about using the Finalize method, 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)). + ]]> @@ -1297,11 +1297,11 @@ The Close method frees both unmanaged and managed resources associated with the Flushes data from the stream. This method is reserved for future use. - method implements the method; however, because is not buffered, it has no effect on network streams. Calling the method does not throw an exception. - + method implements the method; however, because is not buffered, it has no effect on network streams. Calling the method does not throw an exception. + ]]> @@ -1347,11 +1347,11 @@ The Close method frees both unmanaged and managed resources associated with the Flushes data from the stream as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after data has been flushed from the stream for the instance. - + object will complete after data has been flushed from the stream for the instance. + 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 . ]]> @@ -1482,17 +1482,17 @@ The Close method frees both unmanaged and managed resources associated with the Reads data from the and stores it to a span of bytes in memory. The number of bytes read from the . - [!NOTE] -> Check to see if the is readable by calling the property. If you attempt to read from a that is not readable, you will get an . - +> Check to see if the is readable by calling the property. If you attempt to read from a that is not readable, you will get an . + > [!NOTE] -> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - +> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + ]]> The does not support reading. @@ -1559,40 +1559,40 @@ There is a failure reading from the network. Reads data from the and stores it to a byte array. The number of bytes read from the . - [!NOTE] -> Check to see if the is readable by calling the property. If you attempt to read from a that is not readable, you will get an . - +> Check to see if the is readable by calling the property. If you attempt to read from a that is not readable, you will get an . + > [!NOTE] -> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + + +## Examples + The following code example uses to determine if data is available to be read. If data is available, it reads from the . - -## Examples - The following code example uses to determine if data is available to be read. If data is available, it reads from the . - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/NetworkStream/Overview/source.cs" id="Snippet4"::: - + ]]> is . - is less than 0. - - -or- - - is greater than the length of . - - -or- - - is less than 0. - - -or- - + is less than 0. + + -or- + + is greater than the length of . + + -or- + + is less than 0. + + -or- + is greater than the length of minus . The does not support reading. An error occurred when accessing the socket. @@ -1656,22 +1656,22 @@ There is a failure reading from the network. to indicate that the can be read; otherwise, . The default value is . - class to use the property. If is `true`, allows calls to the method. You can also determine whether a is readable by checking the publicly accessible property. - - The property is set when the is initialized. - - - -## Examples - In the following code example, the `CanCommunicate` property checks the property to determine if the is readable. - + class to use the property. If is `true`, allows calls to the method. You can also determine whether a is readable by checking the publicly accessible property. + + The property is set when the is initialized. + + + +## Examples + In the following code example, the `CanCommunicate` property checks the property to determine if the is readable. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NetworkStream_Protected_Members/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/NetworkStream/Readable/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NetworkStream_Protected_Members/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NetworkStream_Protected_Members/VB/source.vb" id="Snippet1"::: + ]]> @@ -1719,17 +1719,17 @@ There is a failure reading from the network. Reads data from the and stores it in a byte memory range as an asynchronous operation. A that represents the asynchronous read operation. The value of its property contains the total number of bytes read into . - [!NOTE] -> Check to see if the is readable by calling the property. If you attempt to read from a that is not readable, you will get an . - +> Check to see if the is readable by calling the property. If you attempt to read from a that is not readable, you will get an . + > [!NOTE] -> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - +> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + ]]> The does not support reading. @@ -1790,17 +1790,17 @@ There is a failure reading from the network. Reads data from the and stores it to a specified range of a byte array as an asynchronous operation. A task that represents the asynchronous read operation. The value of its property contains the total number of bytes read into . - [!NOTE] -> Check to see if the is readable by calling the property. If you attempt to read from a that is not readable, you will get an . - +> Check to see if the is readable by calling the property. If you attempt to read from a that is not readable, you will get an . + > [!NOTE] -> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - +> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + 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 . ]]> @@ -1845,16 +1845,16 @@ There is a failure reading from the network. Reads a byte from the and advances the position within the stream by one byte, or returns -1 if at the end of the stream. The unsigned byte cast to an , or -1 if at the end of the stream. - [!NOTE] -> Check to see if the is readable by calling the property. If you attempt to read from a that is not readable, you will get an . - +> Check to see if the is readable by calling the property. If you attempt to read from a that is not readable, you will get an . + > [!NOTE] -> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - +> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + ]]> The does not support reading. @@ -1904,20 +1904,20 @@ There is a failure reading from the network. Gets or sets the amount of time that a read operation blocks waiting for data. A that specifies the amount of time, in milliseconds, that will elapse before a read operation fails. The default value, , specifies that the read operation does not time out. - . - + . + > [!NOTE] > This property affects only synchronous reads performed by calling the method. This property does not affect asynchronous reads performed by calling the or method. - - -## Examples - The following code example sets the read time-out for a network stream to 10 milliseconds. - - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/NetworkStream/ReadTimeout/tcpclient.cs" id="Snippet2"::: - + + +## Examples + The following code example sets the read time-out for a network stream to 10 milliseconds. + + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/NetworkStream/ReadTimeout/tcpclient.cs" id="Snippet2"::: + ]]> The value specified is less than or equal to zero and is not . @@ -2063,23 +2063,23 @@ There is a failure reading from the network. Gets the underlying . A that represents the underlying network connection. - can use this property to get the underlying . Use the underlying returned from the property if you require access beyond that which provides. - + can use this property to get the underlying . Use the underlying returned from the property if you require access beyond that which provides. + > [!NOTE] -> This property is accessible only through this class or a derived class. - - - -## Examples - The following code example retrieves the underlying to verify an active connection. - +> This property is accessible only through this class or a derived class. + + + +## Examples + The following code example retrieves the underlying to verify an active connection. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NetworkStream_Protected_Members/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/NetworkStream/Readable/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NetworkStream_Protected_Members/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NetworkStream_Protected_Members/VB/source.vb" id="Snippet1"::: + ]]> @@ -2114,7 +2114,7 @@ There is a failure reading from the network. . 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 about using the Dispose method, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] @@ -2165,7 +2165,7 @@ Call `Dispose` when you are finished using the is thrown. > [!NOTE] @@ -2238,40 +2238,40 @@ There was a failure while writing to the network. The number of bytes to write to the . Writes data to the from a specified range of a byte array. - is thrown. - + is thrown. + > [!NOTE] > Check to see if the is writable by calling the property. If you attempt to write to a that is not writable, you will get an . > [!NOTE] > If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code and refer to the Windows Sockets version 2 API error code documentation for a detailed description of the error. - -## Examples - The following code example checks to see whether the is writable. If it is, then is used to write a small message. - + +## Examples + The following code example checks to see whether the is writable. If it is, then is used to write a small message. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NetworkStream_Synch_SendAndReceive/CPP/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/NetworkStream/Overview/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NetworkStream_Synch_SendAndReceive/VB/source.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NetworkStream_Synch_SendAndReceive/VB/source.vb" id="Snippet3"::: + ]]> The parameter is . - The parameter is less than 0. - - -or- - - The parameter is greater than the length of . - - -or- - - The parameter is less than 0. - - -or- - + The parameter is less than 0. + + -or- + + The parameter is greater than the length of . + + -or- + + The parameter is less than 0. + + -or- + The parameter is greater than the length of minus the value of the parameter. The does not support writing. An error occurred when accessing the socket. @@ -2333,22 +2333,22 @@ There was a failure while writing to the network. if data can be written to the stream; otherwise, . The default value is . - class to use the property. If is `true`, allows calls to the method. You can also determine whether a is writable by checking the publicly accessible property. - - The property is set when the is initialized. - - - -## Examples - In the following code example, the `CanCommunicate` property checks the property to determine if the is writable. - + class to use the property. If is `true`, allows calls to the method. You can also determine whether a is writable by checking the publicly accessible property. + + The property is set when the is initialized. + + + +## Examples + In the following code example, the `CanCommunicate` property checks the property to determine if the is writable. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NetworkStream_Protected_Members/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/NetworkStream/Readable/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NetworkStream_Protected_Members/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NetworkStream_Protected_Members/VB/source.vb" id="Snippet1"::: + ]]> @@ -2396,7 +2396,7 @@ There was a failure while writing to the network. A task that represents the asynchronous write operation. [!NOTE] @@ -2466,7 +2466,7 @@ There was a failure while writing to the network. A task that represents the asynchronous write operation. [!NOTE] @@ -2480,24 +2480,24 @@ This method stores in the task it returns all non-usage exceptions that the meth ]]> The parameter is . - The parameter is less than 0. - - -or- - - The parameter is greater than the length of . - - -or- - - The parameter is less than 0. - - -or- - + The parameter is less than 0. + + -or- + + The parameter is greater than the length of . + + -or- + + The parameter is less than 0. + + -or- + The parameter is greater than the length of minus the value of the parameter. The does not support writing. - There was a failure while writing to the network. - - -or- - + There was a failure while writing to the network. + + -or- + An error occurred when accessing the socket. The is closed. The cancellation token was canceled. This exception is stored into the returned task. @@ -2592,22 +2592,22 @@ There was a failure while writing to the network. Gets or sets the amount of time that a write operation blocks waiting for data. A that specifies the amount of time, in milliseconds, that will elapse before a write operation fails. The default value, , specifies that the write operation does not time out. - . - + . + > [!NOTE] > This property affects only synchronous write operations performed by calling the method. This property does not affect asynchronous writes performed by calling the or method. - - - -## Examples - The following code example sets the write time-out for a network stream to 10 milliseconds. - + + + +## Examples + The following code example sets the write time-out for a network stream to 10 milliseconds. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NclTcpServerSync/cpp/tcplistener.cpp" id="Snippet0"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/NetworkStream/WriteTimeout/tcplistener.cs" id="Snippet0"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/NetworkStream/WriteTimeout/tcplistener.cs" id="Snippet0"::: + ]]> The value specified is less than or equal to zero and is not . diff --git a/xml/System.Net.Sockets/Socket.xml b/xml/System.Net.Sockets/Socket.xml index 9a1d35b7824..05b5a27f52b 100644 --- a/xml/System.Net.Sockets/Socket.xml +++ b/xml/System.Net.Sockets/Socket.xml @@ -4957,9 +4957,9 @@ This method populates the instance with data ga - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [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)). + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. diff --git a/xml/System.Net.Sockets/SocketAsyncEventArgs.xml b/xml/System.Net.Sockets/SocketAsyncEventArgs.xml index 87451fba35c..29e3ea458fb 100644 --- a/xml/System.Net.Sockets/SocketAsyncEventArgs.xml +++ b/xml/System.Net.Sockets/SocketAsyncEventArgs.xml @@ -61,38 +61,38 @@ Represents an asynchronous socket operation. - class is part of a set of enhancements to the class that provide an alternative asynchronous pattern that can be used by specialized high-performance socket applications. This class was specifically designed for network server applications that require high performance. An application can use the enhanced asynchronous pattern exclusively or only in targeted hot areas (for example, when receiving large amounts of data). - - The main feature of these enhancements is the avoidance of the repeated allocation and synchronization of objects during high-volume asynchronous socket I/O. The Begin/End design pattern currently implemented by the class requires a object be allocated for each asynchronous socket operation. - - In the new class enhancements, asynchronous socket operations are described by reusable objects allocated and maintained by the application. High-performance socket applications know best the amount of overlapped socket operations that must be sustained. The application can create as many of the objects that it needs. For example, if a server application needs to have 15 socket accept operations outstanding at all times to support incoming client connection rates, it can allocate 15 reusable objects for that purpose. - - The pattern for performing an asynchronous socket operation with this class consists of the following steps: - -1. Allocate a new context object, or get a free one from an application pool. - -2. Set properties on the context object to the operation about to be performed (the completion callback method, the data buffer, the offset into the buffer, and the maximum amount of data to transfer, for example). - -3. Call the appropriate socket method (xxxAsync) to initiate the asynchronous operation. - -4. If the asynchronous socket method (xxxAsync) returns true, in the callback, query the context properties for completion status. - -5. If the asynchronous socket method (xxxAsync) returns false, the operation completed synchronously. The context properties may be queried for the operation result. - -6. Reuse the context for another operation, put it back in the pool, or discard it. - - The lifetime of the new asynchronous socket operation context object is determined by references by the application code and asynchronous I/O references. It is not necessary for the application to retain a reference to an asynchronous socket operation context object after it is submitted as a parameter to one of the asynchronous socket operation methods. It will remain referenced until the completion callback returns. However it is advantageous for the application to retain the reference to the context so that it can be reused for a future asynchronous socket operation. - - - -## Examples - The following code example implements the connection logic for the socket server that uses the class. After accepting a connection, all data read from the client is sent back to the client. The read and echo back to the client pattern is continued until the client disconnects. The BufferManager class that is used by this example is displayed in the code example for the method. The SocketAsyncEventArgsPool class that is used in this example is displayed in the code example for the constructor. - - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/SocketAsyncEventArgs/Overview/AsyncSocketServer.cs" id="Snippet3"::: - + class is part of a set of enhancements to the class that provide an alternative asynchronous pattern that can be used by specialized high-performance socket applications. This class was specifically designed for network server applications that require high performance. An application can use the enhanced asynchronous pattern exclusively or only in targeted hot areas (for example, when receiving large amounts of data). + + The main feature of these enhancements is the avoidance of the repeated allocation and synchronization of objects during high-volume asynchronous socket I/O. The Begin/End design pattern currently implemented by the class requires a object be allocated for each asynchronous socket operation. + + In the new class enhancements, asynchronous socket operations are described by reusable objects allocated and maintained by the application. High-performance socket applications know best the amount of overlapped socket operations that must be sustained. The application can create as many of the objects that it needs. For example, if a server application needs to have 15 socket accept operations outstanding at all times to support incoming client connection rates, it can allocate 15 reusable objects for that purpose. + + The pattern for performing an asynchronous socket operation with this class consists of the following steps: + +1. Allocate a new context object, or get a free one from an application pool. + +2. Set properties on the context object to the operation about to be performed (the completion callback method, the data buffer, the offset into the buffer, and the maximum amount of data to transfer, for example). + +3. Call the appropriate socket method (xxxAsync) to initiate the asynchronous operation. + +4. If the asynchronous socket method (xxxAsync) returns true, in the callback, query the context properties for completion status. + +5. If the asynchronous socket method (xxxAsync) returns false, the operation completed synchronously. The context properties may be queried for the operation result. + +6. Reuse the context for another operation, put it back in the pool, or discard it. + + The lifetime of the new asynchronous socket operation context object is determined by references by the application code and asynchronous I/O references. It is not necessary for the application to retain a reference to an asynchronous socket operation context object after it is submitted as a parameter to one of the asynchronous socket operation methods. It will remain referenced until the completion callback returns. However it is advantageous for the application to retain the reference to the context so that it can be reused for a future asynchronous socket operation. + + + +## Examples + The following code example implements the connection logic for the socket server that uses the class. After accepting a connection, all data read from the client is sent back to the client. The read and echo back to the client pattern is continued until the client disconnects. The BufferManager class that is used by this example is displayed in the code example for the method. The SocketAsyncEventArgsPool class that is used in this example is displayed in the code example for the constructor. + + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/SocketAsyncEventArgs/Overview/AsyncSocketServer.cs" id="Snippet3"::: + ]]> @@ -149,30 +149,30 @@ Creates an empty instance. - property will be equal to . - -- The property will be equal to , which specifies no flags will be used. - -- The property will be equal to . - - The caller must set the appropriate properties prior to passing the object to the appropriate asynchronous socket (xxxAsync) method. - - - -## Examples - The following code example represents a collection of reusable objects. - - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/SocketAsyncEventArgs/Overview/AsyncSocketServer.cs" id="Snippet2"::: - + property will be equal to . + +- The property will be equal to , which specifies no flags will be used. + +- The property will be equal to . + + The caller must set the appropriate properties prior to passing the object to the appropriate asynchronous socket (xxxAsync) method. + + + +## Examples + The following code example represents a collection of reusable objects. + + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/SocketAsyncEventArgs/Overview/AsyncSocketServer.cs" id="Snippet2"::: + ]]> The platform is not supported. @@ -265,11 +265,11 @@ Gets or sets the socket to use or the socket created for accepting a connection with an asynchronous socket method. The to use or the socket created for accepting a connection with an asynchronous socket method. - that will be used for an asynchronous socket accept operation. Upon completion of the accept operation, it is the socket representing the accepted connection. If not supplied (set to null) before calling the method, a new socket will be created automatically and be accessible in the completion callback with this property. - + that will be used for an asynchronous socket accept operation. Upon completion of the accept operation, it is the socket representing the accepted connection. If not supplied (set to null) before calling the method, a new socket will be created automatically and be accessible in the completion callback with this property. + ]]> @@ -324,13 +324,13 @@ Gets the data buffer to use with an asynchronous socket method. A array that represents the data buffer to use with an asynchronous socket method. - instance. To set the buffer, the method must be used. - - This property is used with the , , , , , , and methods. - + instance. To set the buffer, the method must be used. + + This property is used with the , , , , , , and methods. + ]]> @@ -396,21 +396,21 @@ Gets or sets an array of data buffers to use with an asynchronous socket method. An that represents an array of data buffers to use with an asynchronous socket method. - and methods. - - This property is used to provide multiple buffers of data to be sent or to provide multiple buffers in which to store received data for an asynchronous socket operation that can send or receive data. Multiple buffers using the property are supported by the and methods. - - If the property is set to a non-null value, the property must be null and is ignored by the and methods. - - If the was set to a non-null value and an attempt is made to set the property to a non-null value, an exception is thrown. - - If the property is set to a non-null value, the and methods will throw an . - - The parameter is ignored by the and methods. - + and methods. + + This property is used to provide multiple buffers of data to be sent or to provide multiple buffers in which to store received data for an asynchronous socket operation that can send or receive data. Multiple buffers using the property are supported by the and methods. + + If the property is set to a non-null value, the property must be null and is ignored by the and methods. + + If the was set to a non-null value and an attempt is made to set the property to a non-null value, an exception is thrown. + + If the property is set to a non-null value, the and methods will throw an . + + The parameter is ignored by the and methods. + ]]> There are ambiguous buffers specified on a set operation. This exception occurs if the property has been set to a non-null value and an attempt was made to set the property to a non-null value. @@ -467,13 +467,13 @@ Gets the number of bytes transferred in the socket operation. An that contains the number of bytes transferred in the socket operation. - method. - + method. + ]]> @@ -534,15 +534,15 @@ The event used to complete an asynchronous operation. - event provides a way for client applications to complete an asynchronous socket operation. An event handler should be attached to the event within a instance when an asynchronous socket operation is initiated, otherwise the application will not be able to determine when the operation completes. - - The completion callback delegates referenced by the event contains program logic to finish processing the asynchronous socket operation for the client. - - When the event is signaled, the application uses the object parameter to obtain the status of the completed asynchronous socket operation. - + event provides a way for client applications to complete an asynchronous socket operation. An event handler should be attached to the event within a instance when an asynchronous socket operation is initiated, otherwise the application will not be able to determine when the operation completes. + + The completion callback delegates referenced by the event contains program logic to finish processing the asynchronous socket operation for the client. + + When the event is signaled, the application uses the object parameter to obtain the status of the completed asynchronous socket operation. + ]]> @@ -595,15 +595,15 @@ Gets the exception in the case of a connection failure when a was used. An that indicates the cause of the connection error when a was specified for the property. - was specified for the property, the property will contain the exception that indicates the detailed cause of the socket error. - - When an was specified for the property and a connection failure occurs, the property will be a `null` reference. - - The property is always set in the case of a connection failure. The property contains more information about the failure if it was a failure connecting to a . If an application is only interested in whether the connect operation succeeded or failed, then the application only needs to check the property. - + was specified for the property, the property will contain the exception that indicates the detailed cause of the socket error. + + When an was specified for the property and a connection failure occurs, the property will be a `null` reference. + + The property is always set in the case of a connection failure. The property contains more information about the failure if it was a failure connecting to a . If an application is only interested in whether the connect operation succeeded or failed, then the application only needs to check the property. + ]]> @@ -657,11 +657,11 @@ The created and connected object after successful completion of the method. The connected object. - method, this property contains the newly created and connected object. - + method, this property contains the newly created and connected object. + ]]> @@ -715,13 +715,13 @@ Gets the maximum amount of data, in bytes, to send or receive in an asynchronous operation. An that contains the maximum amount of data, in bytes, to send or receive. - method. - - This property is used with the , , , , , , and methods. - + method. + + This property is used with the , , , , , , and methods. + ]]> @@ -785,11 +785,11 @@ Gets or sets a value that specifies if socket can be reused after a disconnect operation. A that specifies if socket can be reused after a disconnect operation. - method. If true, a socket disconnected by the method can be reused after disconnect completion in subsequent socket accept or connect operations. - + method. If true, a socket disconnected by the method can be reused after disconnect completion in subsequent socket accept or connect operations. + ]]> @@ -840,23 +840,23 @@ Releases the unmanaged resources used by the instance and optionally disposes of the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -903,11 +903,11 @@ Frees resources used by the class. - class finalizer closes the and free resources associated with the . - + class finalizer closes the and free resources associated with the . + ]]> @@ -960,17 +960,17 @@ Gets the type of socket operation most recently performed with this context object. A instance that indicates the type of socket operation most recently performed with this context object. - object. The value of this property will be until the instance is used to begin an asynchronous socket operation. The property will then be set to the type of operation being performed in the methods that take the as a parameter. This property more easily facilitates using a single completion callback delegate for multiple kinds of asynchronous socket operations. - - This property remains valid in a instance until the instance is used for another asynchronous socket (xxxAsync) operation. - - This property is set by all asynchronous socket (xxxAsync) methods. - - Calling an asynchronous socket method (xxxAsync) on the class sets this property value. This property is intended for use with the SocketAsyncCallback completion routine implemented by the application. - + object. The value of this property will be until the instance is used to begin an asynchronous socket operation. The property will then be set to the type of operation being performed in the methods that take the as a parameter. This property more easily facilitates using a single completion callback delegate for multiple kinds of asynchronous socket operations. + + This property remains valid in a instance until the instance is used for another asynchronous socket (xxxAsync) operation. + + This property is set by all asynchronous socket (xxxAsync) methods. + + Calling an asynchronous socket method (xxxAsync) on the class sets this property value. This property is intended for use with the SocketAsyncCallback completion routine implemented by the application. + ]]> @@ -1030,13 +1030,13 @@ Gets the region of memory to use as a buffer with an asynchronous socket method. A region of memory that represents the data buffer to use with an asynchronous socket method. - instance. To set the buffer, the method must be used. -This property is used with the , , , , , , and methods. +This property is used with the , , , , , , and methods. ]]> @@ -1098,15 +1098,15 @@ This property is used with the Gets the offset, in bytes, into the data buffer referenced by the property. An that contains the offset, in bytes, into the data buffer referenced by the property. - property. This value is set by calling the method. - - This property does not apply to the property. - - This property is used with the , , , , , , and methods. - + property. This value is set by calling the method. + + This property does not apply to the property. + + This property is used with the , , , , , , and methods. + ]]> @@ -1170,19 +1170,19 @@ This property is used with the The event that is signaled. Represents a method that is called when an asynchronous operation completes. - object when the current operation is complete. This method is used with all asynchronous socket (xxxAsync) methods. - - An application that creates a class inheriting from can override this method to hook into this completion notification and clean up any resources that it allocated for the operation. The default implementation just raises the event. - - This method is used to hook up an event handler to be used as the completion callback for a subsequent asynchronous socket operation. The caller must implement at least one callback delegate inherited from this method prior to starting an asynchronous socket operation using one of the asynchronous (xxxAsync) methods on the class. - - The caller's method provides a way for client applications to complete an asynchronous socket operation. A callback delegate must be implemented when an asynchronous socket operation is initiated. The completion callback delegate(s) inherited from the method must contain program logic to finish processing the asynchronous socket operation for the client. - - When an asynchronous operation is signaled, the application uses the object parameter to obtain status of the completed asynchronous socket operation. - + object when the current operation is complete. This method is used with all asynchronous socket (xxxAsync) methods. + + An application that creates a class inheriting from can override this method to hook into this completion notification and clean up any resources that it allocated for the operation. The default implementation just raises the event. + + This method is used to hook up an event handler to be used as the completion callback for a subsequent asynchronous socket operation. The caller must implement at least one callback delegate inherited from this method prior to starting an asynchronous socket operation using one of the asynchronous (xxxAsync) methods on the class. + + The caller's method provides a way for client applications to complete an asynchronous socket operation. A callback delegate must be implemented when an asynchronous socket operation is initiated. The completion callback delegate(s) inherited from the method must contain program logic to finish processing the asynchronous socket operation for the client. + + When an asynchronous operation is signaled, the application uses the object parameter to obtain status of the completed asynchronous socket operation. + ]]> @@ -1243,13 +1243,13 @@ This property is used with the Gets the IP address and interface of a received packet. An instance that contains the destination IP address and interface of a received packet. - method. - - This property is used with the method. - + method. + + This property is used with the method. + ]]> @@ -1312,15 +1312,15 @@ This property is used with the Gets or sets the remote IP endpoint for an asynchronous operation. An that represents the remote IP endpoint for an asynchronous operation. - method. This property can specify the remote endpoint to which to send data using method. This property can specify the remote endpoint from which data was received using the or methods. - - This remote endpoint specified by this property can include an IPv4 or IPv6 address. - - This property is used with the , , , or methods. - + method. This property can specify the remote endpoint to which to send data using method. This property can specify the remote endpoint from which data was received using the or methods. + + This remote endpoint specified by this property can include an IPv4 or IPv6 address. + + This property is used with the , , , or methods. + ]]> @@ -1386,11 +1386,11 @@ This property is used with the Gets or sets an array of buffers to be sent for an asynchronous operation used by the method. An array of objects that represent an array of buffers to be sent. - method. - + method. + ]]> @@ -1447,11 +1447,11 @@ This property is used with the Gets or sets a bitwise combination of values for an asynchronous operation used by the method. A that contains a bitwise combination of values that are used with an asynchronous operation. - that are used by the method. - + that are used by the method. + ]]> @@ -1509,11 +1509,11 @@ This property is used with the Gets or sets the size, in bytes, of the data block used in the send operation. An that contains the size, in bytes, of the data block used in the send operation. - property. This capability is useful for message protocols that place limitations on the size of individual send requests. - + property. This capability is useful for message protocols that place limitations on the size of individual send requests. + ]]> @@ -1528,11 +1528,11 @@ This property is used with the Initializes the data buffer to use with an asynchronous socket method. - property to null and the and properties to zero. - + property to null and the and properties to zero. + ]]> @@ -1584,7 +1584,7 @@ This property is used with the The region of memory to use as a buffer with an asynchronous socket method. Sets the region of memory to use as a buffer with an asynchronous socket method. - property to the `buffer` parameter, the property to the `buffer` length, and the property to zero. @@ -1640,15 +1640,15 @@ This method sets the The maximum amount of data, in bytes, to send or receive in the buffer. Sets the data buffer to use with an asynchronous socket method. - property. - - This method sets the property to the `count` parameter and the property to the `offset` parameter. If the property is null, this method ignores the `offset` and `count` parameters and sets the and properties to 0. - - This method does not change the property. - + property. + + This method sets the property to the `count` parameter and the property to the `offset` parameter. If the property is null, this method ignores the `offset` and `count` parameters and sets the and properties to 0. + + This method does not change the property. + ]]> An argument was out of range. This exception occurs if the parameter is less than zero or greater than the length of the array in the property. This exception also occurs if the parameter is less than zero or greater than the length of the array in the property minus the parameter. @@ -1713,20 +1713,20 @@ This method sets the The maximum amount of data, in bytes, to send or receive in the buffer. Sets the data buffer to use with an asynchronous socket method. - property to the `buffer` parameter, the property to the `count` parameter, and the property to the `offset` parameter. - - - -## Examples - The following code example creates a single large buffer which can be divided up and assigned to objects for use with each socket I/O operation. This enables buffers to be easily reused and guards against fragmenting heap memory. - - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/SocketAsyncEventArgs/Overview/AsyncSocketServer.cs" id="Snippet1"::: - + property to the `buffer` parameter, the property to the `count` parameter, and the property to the `offset` parameter. + + + +## Examples + The following code example creates a single large buffer which can be divided up and assigned to objects for use with each socket I/O operation. This enables buffers to be easily reused and guards against fragmenting heap memory. + + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/SocketAsyncEventArgs/Overview/AsyncSocketServer.cs" id="Snippet1"::: + ]]> There are ambiguous buffers specified. This exception occurs if the property is also not null and the property is also not null. @@ -1774,11 +1774,11 @@ This method sets the Gets or sets the protocol to use to download the socket client access policy file. The protocol to use to download the socket client access policy file. - specifies the method to download a client access policy file. - + specifies the method to download a client access policy file. + ]]> @@ -1835,13 +1835,13 @@ This method sets the Gets or sets the result of the asynchronous socket operation. A that represents the result of the asynchronous socket operation. - indicates successful completion of an operation. This property is primarily used in an application's event handler routine. - - This property is used with all of the asynchronous socket (xxxAsync) methods. - + indicates successful completion of an operation. This property is primarily used in an application's event handler routine. + + This property is used with all of the asynchronous socket (xxxAsync) methods. + ]]> @@ -1907,13 +1907,13 @@ This method sets the Gets the results of an asynchronous socket operation or sets the behavior of an asynchronous operation. A that represents the results of an asynchronous socket operation. - to be used for an asynchronous socket operation. - - This property is used with the , , , and methods. - + to be used for an asynchronous socket operation. + + This property is used with the , , , and methods. + ]]> @@ -1976,13 +1976,13 @@ This method sets the Gets or sets a user or application object associated with this asynchronous socket operation. An object that represents the user or application object associated with this asynchronous socket operation. - object. Primarily, this property is a way for an application to pass state to the application's event handler (for example, the asynchronous operation completion method). - - This property is used with all of the asynchronous socket (xxxAsync) methods. - + object. Primarily, this property is a way for an application to pass state to the application's event handler (for example, the asynchronous operation completion method). + + This property is used with all of the asynchronous socket (xxxAsync) methods. + ]]> diff --git a/xml/System.Net.Sockets/TcpClient.xml b/xml/System.Net.Sockets/TcpClient.xml index 082e9dbf4b0..82808f80119 100644 --- a/xml/System.Net.Sockets/TcpClient.xml +++ b/xml/System.Net.Sockets/TcpClient.xml @@ -1855,9 +1855,9 @@ The `Available` property is a way to determine whether data is queued for readin - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [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)). + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. diff --git a/xml/System.Net.Sockets/UdpClient.xml b/xml/System.Net.Sockets/UdpClient.xml index 05454e8ca1f..e1a0e601648 100644 --- a/xml/System.Net.Sockets/UdpClient.xml +++ b/xml/System.Net.Sockets/UdpClient.xml @@ -57,31 +57,31 @@ Provides User Datagram Protocol (UDP) network services. - class provides simple methods for sending and receiving connectionless UDP datagrams in blocking synchronous mode. Because UDP is a connectionless transport protocol, you do not need to establish a remote host connection prior to sending and receiving data. You do, however, have the option of establishing a default remote host in one of the following two ways: - -- Create an instance of the class using the remote host name and port number as parameters. - -- Create an instance of the class and then call the method. - - You can use any of the send methods provided in the to send data to a remote device. Use the method to receive data from remote hosts. - + class provides simple methods for sending and receiving connectionless UDP datagrams in blocking synchronous mode. Because UDP is a connectionless transport protocol, you do not need to establish a remote host connection prior to sending and receiving data. You do, however, have the option of establishing a default remote host in one of the following two ways: + +- Create an instance of the class using the remote host name and port number as parameters. + +- Create an instance of the class and then call the method. + + You can use any of the send methods provided in the to send data to a remote device. Use the method to receive data from remote hosts. + > [!NOTE] -> Do not call using a host name or if you have already specified a default remote host. If you do, will throw an exception. - - methods also allow you to send and receive multicast datagrams. Use the method to subscribe a to a multicast group. Use the method to unsubscribe a from a multicast group. - - - -## Examples - The following example establishes a connection using the host name `www.contoso.com` on port 11000. A small string message is sent to two separate remote host machines. The method blocks execution until a message is received. Using the passed to , the identity of the responding host is revealed. - +> Do not call using a host name or if you have already specified a default remote host. If you do, will throw an exception. + + methods also allow you to send and receive multicast datagrams. Use the method to subscribe a to a multicast group. Use the method to unsubscribe a from a multicast group. + + + +## Examples + The following example establishes a connection using the host name `www.contoso.com` on port 11000. A small string message is sent to two separate remote host machines. The method blocks execution until a message is received. Using the passed to , the identity of the responding host is revealed. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic UdpClientExample/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClientExample/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClientExample/VB/source.vb" id="Snippet1"::: + ]]> @@ -139,25 +139,25 @@ Initializes a new instance of the class. - and allows the underlying service provider to assign the most appropriate local IPv4 address and port number. If this constructor is used, the instance is set with an address family of IPv4 that cannot be changed or overwritten by a connect method call with an IPv6 target. - + and allows the underlying service provider to assign the most appropriate local IPv4 address and port number. If this constructor is used, the instance is set with an address family of IPv4 that cannot be changed or overwritten by a connect method call with an IPv6 target. + > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - This constructor is not suitable for joining a multicast group because it does not perform socket binding. Also, it works only with IPv4 address types. - - - -## Examples - The following example demonstrates how to use the parameterless constructor to create an instance of the class. - +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + + This constructor is not suitable for joining a multicast group because it does not perform socket binding. Also, it works only with IPv4 address types. + + + +## Examples + The following example demonstrates how to use the parameterless constructor to create an instance of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/CPP/source.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/.ctor/source.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet4"::: + ]]> An error occurred when accessing the socket. @@ -208,25 +208,25 @@ The local port number from which you intend to communicate. Initializes a new instance of the class and binds it to the local port number provided. - and binds it to the port number from which you intend to communicate. Use this constructor if you are only interested in setting the local port number. The underlying service provider will assign the local IP address. If you pass 0 to the constructor, the underlying service provider will assign a port number. If this constructor is used, the instance is set with an address family of IPv4 that cannot be changed or overwritten by a connect method call with an IPv6 target. - + and binds it to the port number from which you intend to communicate. Use this constructor if you are only interested in setting the local port number. The underlying service provider will assign the local IP address. If you pass 0 to the constructor, the underlying service provider will assign a port number. If this constructor is used, the instance is set with an address family of IPv4 that cannot be changed or overwritten by a connect method call with an IPv6 target. + > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - This constructor works only with IPv4 address types. - - - -## Examples - The following example demonstrates using a local port number to create an instance of the class. - +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + + This constructor works only with IPv4 address types. + + + +## Examples + The following example demonstrates using a local port number to create an instance of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet1"::: + ]]> The parameter is greater than or less than . @@ -272,25 +272,25 @@ An that represents the local endpoint to which you bind the UDP connection. Initializes a new instance of the class and binds it to the specified local endpoint. - and binds it to the specified by the `localEP` parameter. Before you call this constructor, you must create an using the IP address and port number from which you intend to send and receive data. You do not need to specify a local IP address and port number for sending and receiving data. If you do not, the underlying service provider will assign the most appropriate local IP address and port number. - - If this constructor is used, the instance is set with the address family specified by the `localEP` parameter that cannot be changed or overwritten by a connect method call with a different address family. - + and binds it to the specified by the `localEP` parameter. Before you call this constructor, you must create an using the IP address and port number from which you intend to send and receive data. You do not need to specify a local IP address and port number for sending and receiving data. If you do not, the underlying service provider will assign the most appropriate local IP address and port number. + + If this constructor is used, the instance is set with the address family specified by the `localEP` parameter that cannot be changed or overwritten by a connect method call with a different address family. + > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - - -## Examples - The following example demonstrates how to create an instance of the class using a local endpoint. - +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + + + +## Examples + The following example demonstrates how to create an instance of the class using a local endpoint. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/.ctor/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet2"::: + ]]> @@ -338,18 +338,18 @@ One of the values that specifies the addressing scheme of the socket. Initializes a new instance of the class. - value. To use an IPv6 address, pass the value. Passing any other value will cause the method to throw an . - - If this constructor is used, the instance is set with the address family specified by the `family` parameter that cannot be changed or overwritten by a connect method call with a different address family. - + value. To use an IPv6 address, pass the value. Passing any other value will cause the method to throw an . + + If this constructor is used, the instance is set with the address family specified by the `family` parameter that cannot be changed or overwritten by a connect method call with a different address family. + > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - The is not suitable for joining a multicast group because it does not perform socket binding. - +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + + The is not suitable for joining a multicast group because it does not perform socket binding. + ]]> @@ -398,27 +398,27 @@ One of the values that specifies the addressing scheme of the socket. Initializes a new instance of the class and binds it to the local port number provided. - and binds it to the port number from which you intend to communicate. - - The `family` parameter determines whether the listener uses an IP version 4 address (IPv4) or an IP version 6 (IPv6) address. To use an IPv4 address, pass the value. To use an IPv6 address, pass the value. Passing any other value will cause the method to throw an . - - If this constructor is used, the instance is set with the address family specified by the `family` parameter that cannot be changed or overwritten by a connect method call with a different address family. - + and binds it to the port number from which you intend to communicate. + + The `family` parameter determines whether the listener uses an IP version 4 address (IPv4) or an IP version 6 (IPv6) address. To use an IPv4 address, pass the value. To use an IPv6 address, pass the value. Passing any other value will cause the method to throw an . + + If this constructor is used, the instance is set with the address family specified by the `family` parameter that cannot be changed or overwritten by a connect method call with a different address family. + > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - - -## Examples - The following code example shows how to create a UDP client to use in a multicast group. - +> If you receive a , use to obtain the specific error code. Once you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + + + +## Examples + The following code example shows how to create a UDP client to use in a multicast group. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient.JoinMulticastGroup/CPP/joinmulticastgroup.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/IPv6MulticastOption/Overview/joinmulticastgroup.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.Sockets.UdpClient.JoinMulticastGroup/VB/joinmulticastgroup.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.Sockets.UdpClient.JoinMulticastGroup/VB/joinmulticastgroup.vb" id="Snippet3"::: + ]]> @@ -468,23 +468,23 @@ The remote port number to which you intend to connect. Initializes a new instance of the class and establishes a default remote host. - and establishes a remote host using the `hostname` and `port` parameters. Establishing a default remote host is optional. If you use this constructor, you do not have to specify a remote host in each call to the method. Specifying a default remote host limits you to that host only. You can change the default remote host at any time by calling the method. If you want to specify a remote host in your call to the method, do not use this constructor. - + and establishes a remote host using the `hostname` and `port` parameters. Establishing a default remote host is optional. If you use this constructor, you do not have to specify a remote host in each call to the method. Specifying a default remote host limits you to that host only. You can change the default remote host at any time by calling the method. If you want to specify a remote host in your call to the method, do not use this constructor. + > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - - -## Examples - The following example demonstrates how to create an instance of the class using a host name and port number. - +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + + + +## Examples + The following example demonstrates how to create an instance of the class using a host name and port number. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/CPP/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/.ctor/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet3"::: + ]]> @@ -546,11 +546,11 @@ if a connection is active; otherwise, . - can use this property to determine if a default remote host has been established. You can establish a default remote host by using the appropriate constructor or by calling the method. If you do establish a default remote host, you cannot specify a remote host in your call to . - + can use this property to determine if a default remote host has been established. You can establish a default remote host by using the appropriate constructor or by calling the method. If you do establish a default remote host, you cannot specify a remote host in your call to . + ]]> @@ -603,17 +603,17 @@ A Boolean value that specifies whether to enable or disable NAT traversal. Enables or disables Network Address Translation (NAT) traversal on a instance. - method is used to enable or disable NAT traversal for a instance. NAT traversal may be provided using Teredo, 6to4, or an ISATAP tunnel. - - When the `allowed` parameter is false, the option on the associated socket is set to . This explicitly disables NAT traversal for a instance. - - When the `allowed` parameter is true, the option on the associated socket is set to . This may allow NAT traversal for a depending on firewall rules in place on the system. - - A Teredo address is an IPv6 address with the prefix of 2001::/32. Teredo addresses can be returned through normal DNS name resolution or enumerated as an IPv6 address assigned to a local interface. - + method is used to enable or disable NAT traversal for a instance. NAT traversal may be provided using Teredo, 6to4, or an ISATAP tunnel. + + When the `allowed` parameter is false, the option on the associated socket is set to . This explicitly disables NAT traversal for a instance. + + When the `allowed` parameter is true, the option on the associated socket is set to . This may allow NAT traversal for a depending on firewall rules in place on the system. + + A Teredo address is an IPv6 address with the prefix of 2001::/32. Teredo addresses can be returned through normal DNS name resolution or enumerated as an IPv6 address assigned to a local interface. + ]]> @@ -661,24 +661,24 @@ Gets the amount of data received from the network that is available to read. The number of bytes of data received from the network. - property is used to determine the amount of data queued in the network buffer for reading. If data is available, call to get the data. If no data is available, the property returns 0. - - If the remote host shuts down or closes the connection, the property throws a . - + property is used to determine the amount of data queued in the network buffer for reading. If data is available, call to get the data. If no data is available, the property returns 0. + + If the remote host shuts down or closes the connection, the property throws a . + > [!NOTE] -> If you receive a , use to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - - -## Examples - The following code example shows the use of the property. - +> If you receive a , use to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + + + +## Examples + The following code example shows the use of the property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient/CPP/newudpclient.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet1"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet1"::: + ]]> An error occurred while attempting to access the socket. @@ -735,23 +735,23 @@ Receives a datagram from a remote host asynchronously. An object that references the asynchronous receive. - operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. - - This method does not block until the operation is complete. To block until the operation is complete, use the method. - - For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). - - - -## Examples - The following code example uses to asynchronously receive a server response. - + operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. + + This method does not block until the operation is complete. To block until the operation is complete, use the method. + + For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). + + + +## Examples + The following code example uses to asynchronously receive a server response. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient1/cpp/asyncudp.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet1"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet1"::: + ]]> @@ -834,26 +834,26 @@ Sends a datagram to a remote host asynchronously. The destination was specified previously by a call to . An object that references the asynchronous send. - operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. - - This method does not block until the operation completes. To block until the operation is complete, use one of the method overloads. - - For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). - - - -## Examples - The following code example uses to asynchronously send a server request. - + operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. + + This method does not block until the operation completes. To block until the operation is complete, use one of the method overloads. + + For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). + + + +## Examples + The following code example uses to asynchronously send a server request. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient1/cpp/asyncudp.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet2"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet2"::: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient1/cpp/asyncudp.cpp" id="Snippet3"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet3"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet3"::: + ]]> @@ -921,26 +921,26 @@ Sends a datagram to a destination asynchronously. The destination is specified by a . An object that references the asynchronous send. - operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. - - This method does not block until the operation is complete. To block until the operation is complete, use one of the method overloads. - - For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). - - - -## Examples - The following code example uses to asynchronously send a server request. - + operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. + + This method does not block until the operation is complete. To block until the operation is complete, use one of the method overloads. + + For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). + + + +## Examples + The following code example uses to asynchronously send a server request. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient1/cpp/asyncudp.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet2"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet2"::: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient1/cpp/asyncudp.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet4"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet4"::: + ]]> @@ -1010,26 +1010,26 @@ Sends a datagram to a destination asynchronously. The destination is specified by the host name and port number. An object that references the asynchronous send. - operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. - - This method does not block until the operation is complete. To block until the operation is complete, use one of the method overloads. - - For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). - - - -## Examples - The following code example uses to asynchronously send a server request. - + operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. + + This method does not block until the operation is complete. To block until the operation is complete, use one of the method overloads. + + For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). + + + +## Examples + The following code example uses to asynchronously send a server request. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient1/cpp/asyncudp.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet2"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet2"::: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient1/cpp/asyncudp.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet5"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet5"::: + ]]> @@ -1086,20 +1086,20 @@ Gets or sets the underlying network . The underlying Network . - creates a used to send and receive data over a network. Classes deriving from can use this property to get or set this . Use the underlying returned from if you require access beyond that which provides. You can also use to set the underlying to an existing . This is useful if you want to take advantage of the simplicity of using a pre-existing . - - - -## Examples - The following example demonstrates the use of the property. In this example, broadcasting is enabled for the underlying . - + creates a used to send and receive data over a network. Classes deriving from can use this property to get or set this . Use the underlying returned from if you require access beyond that which provides. You can also use to set the underlying to an existing . This is useful if you want to take advantage of the simplicity of using a pre-existing . + + + +## Examples + The following example demonstrates the use of the property. In this example, broadcasting is enabled for the underlying . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic UdpClient.ProtectedMethodsAndPropertiesExample/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Client/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.ProtectedMethodsAndPropertiesExample/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.ProtectedMethodsAndPropertiesExample/VB/source.vb" id="Snippet1"::: + ]]> @@ -1149,23 +1149,23 @@ Closes the UDP connection. - disables the underlying and releases all managed and unmanaged resources associated with the . - + disables the underlying and releases all managed and unmanaged resources associated with the . + > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - - -## Examples - The following example demonstrates closing a by calling the method. - +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + + + +## Examples + The following example demonstrates closing a by calling the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/CPP/source.cpp" id="Snippet15"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/.ctor/source.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet15"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet15"::: + ]]> An error occurred when accessing the socket. @@ -1223,29 +1223,29 @@ An that specifies the network endpoint to which you intend to send data. Establishes a default remote host using the specified network endpoint. - method establishes a default remote host using the value specified in the `endPoint` parameter. Once established, you do not have to specify a remote host in each call to the method. - - Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the method or create another without a default remote host. If you have established a default remote host and you also provide a remote host in your call to the method, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - If you call the method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from , use the Client method to obtain the underlying , and set the socket option to . - - You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify in your call to the method. If your application requires greater control over broadcast addresses, you can also revert to using the class. - + method establishes a default remote host using the value specified in the `endPoint` parameter. Once established, you do not have to specify a remote host in each call to the method. + + Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the method or create another without a default remote host. If you have established a default remote host and you also provide a remote host in your call to the method, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + + If you call the method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from , use the Client method to obtain the underlying , and set the socket option to . + + You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify in your call to the method. If your application requires greater control over broadcast addresses, you can also revert to using the class. + > [!NOTE] -> Since the UDP protocol is connectionless, the method does not block. Do not call the method if you intend to receive multicasted datagrams. - - - -## Examples - The following example uses an to establish a default remote host. - +> Since the UDP protocol is connectionless, the method does not block. Do not call the method if you intend to receive multicasted datagrams. + + + +## Examples + The following example uses an to establish a default remote host. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/.ctor/source.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet7"::: + ]]> An error occurred when accessing the socket. @@ -1300,29 +1300,29 @@ The port number to which you intend send data. Establishes a default remote host using the specified IP address and port number. - method establishes a default remote host using the values specified in the `addr` and `port` parameters. Once established, you do not have to specify a remote host in each call to the method. - - Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the method or create another without a default remote host. If you have established a default remote host and you also provide a remote host in your call to the method, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - If you call the method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from , use the client method to obtain the underlying , and set the socket option to . - - You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify in your call to the method. If your application requires greater control over broadcast addresses, you can also revert to using the class. - + method establishes a default remote host using the values specified in the `addr` and `port` parameters. Once established, you do not have to specify a remote host in each call to the method. + + Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the method or create another without a default remote host. If you have established a default remote host and you also provide a remote host in your call to the method, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + + If you call the method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from , use the client method to obtain the underlying , and set the socket option to . + + You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify in your call to the method. If your application requires greater control over broadcast addresses, you can also revert to using the class. + > [!NOTE] -> Since the UDP protocol is connectionless, the method does not block. Do not call the method if you intend to receive multicasted datagrams. - - - -## Examples - The following example uses an IP address and port number to connect with a remote host. - +> Since the UDP protocol is connectionless, the method does not block. Do not call the method if you intend to receive multicasted datagrams. + + + +## Examples + The following example uses an IP address and port number to connect with a remote host. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/CPP/source.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/.ctor/source.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet6"::: + ]]> @@ -1380,31 +1380,31 @@ The port number on the remote host to which you intend to send data. Establishes a default remote host using the specified host name and port number. - method establishes a default remote host using the values specified in the `port` and `hostname` parameters. Once established, you do not have to specify a remote host in each call to the method. - - Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the method or create another without a default remote host. - - If you have established a default remote host and you also provide a remote host in your call to the method, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - If you call the method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from , use the client method to obtain the underlying , and set the socket option to . - - You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify in your call to the method. If your application requires greater control over broadcast addresses, you can also revert to using the class. - + method establishes a default remote host using the values specified in the `port` and `hostname` parameters. Once established, you do not have to specify a remote host in each call to the method. + + Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the method or create another without a default remote host. + + If you have established a default remote host and you also provide a remote host in your call to the method, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + + If you call the method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from , use the client method to obtain the underlying , and set the socket option to . + + You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify in your call to the method. If your application requires greater control over broadcast addresses, you can also revert to using the class. + > [!NOTE] -> Since the UDP protocol is connectionless, the method does not block. Do not call the method if you intend to receive multicasted datagrams. - - - -## Examples - The following example uses the host name and port number to connect to a remote host. - +> Since the UDP protocol is connectionless, the method does not block. Do not call the method if you intend to receive multicasted datagrams. + + + +## Examples + The following example uses the host name and port number to connect to a remote host. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/CPP/source.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/.ctor/source.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet5"::: + ]]> The is closed. @@ -1500,20 +1500,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -1556,19 +1556,19 @@ if the doesn't allow datagram fragmentation; otherwise, . The default is . - option is set, the datagram is discarded, and an Internet Control Message Protocol (ICMP) error message is sent back to the sender of the datagram. - - - -## Examples - The following code example shows the use of the property. - + option is set, the datagram is discarded, and an Internet Control Message Protocol (ICMP) error message is sent back to the sender of the datagram. + + + +## Examples + The following code example shows the use of the property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient/CPP/newudpclient.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet2"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet2"::: + ]]> This property can be set only for sockets that use the flag or the flag. @@ -1626,23 +1626,23 @@ The of the multicast group to leave. Leaves a multicast group. - method withdraws the from the multicast group identified by the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router, removing the router from the multicast group. After a withdraws from the group, it will no longer be able to receive datagrams sent to that group. - + method withdraws the from the multicast group identified by the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router, removing the router from the multicast group. After a withdraws from the group, it will no longer be able to receive datagrams sent to that group. + > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - - -## Examples - The following example demonstrates how to drop a multicast group by providing a multicast address. - +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + + + +## Examples + The following example demonstrates how to drop a multicast group by providing a multicast address. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient.JoinMulticastGroup/CPP/joinmulticastgroup.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/IPv6MulticastOption/Overview/joinmulticastgroup.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.Sockets.UdpClient.JoinMulticastGroup/VB/joinmulticastgroup.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.Sockets.UdpClient.JoinMulticastGroup/VB/joinmulticastgroup.vb" id="Snippet2"::: + ]]> The underlying has been closed. @@ -1697,23 +1697,23 @@ The local address of the multicast group to leave. Leaves a multicast group. - method withdraws the from the multicast group identified by the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router, removing the router from the multicast group. After a withdraws from the group, it will no longer be able to receive datagrams sent to that group. - + method withdraws the from the multicast group identified by the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router, removing the router from the multicast group. After a withdraws from the group, it will no longer be able to receive datagrams sent to that group. + > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - - -## Examples - The following code example demonstrates how to drop a multicast group by providing a multicast address. - +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + + + +## Examples + The following code example demonstrates how to drop a multicast group by providing a multicast address. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient.JoinMulticastGroup/CPP/joinmulticastgroup.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/IPv6MulticastOption/Overview/joinmulticastgroup.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.Sockets.UdpClient.JoinMulticastGroup/VB/joinmulticastgroup.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.Sockets.UdpClient.JoinMulticastGroup/VB/joinmulticastgroup.vb" id="Snippet2"::: + ]]> The underlying has been closed. @@ -1763,19 +1763,19 @@ if the allows sending broadcast packets; otherwise, . The default is . - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient/CPP/newudpclient.cpp" id="Snippet3"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet3"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet3"::: + ]]> @@ -1831,21 +1831,21 @@ Ends a pending asynchronous receive. If successful, an array of bytes that contains datagram data. - method. - - - -## Examples - The following code example uses to complete an asynchronous receive of a server response. - + method. + + + +## Examples + The following code example uses to complete an asynchronous receive of a server response. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient1/cpp/asyncudp.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet1"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet1"::: + ]]> @@ -1899,21 +1899,21 @@ Ends a pending asynchronous send. If successful, the number of bytes sent to the . - method. - - - -## Examples - The following code example uses to complete an asynchronous send of a server request. - + method. + + + +## Examples + The following code example uses to complete an asynchronous send of a server request. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient1/cpp/asyncudp.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet2"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet2"::: + ]]> @@ -1965,21 +1965,21 @@ if the allows only one client to use a specific port; otherwise, . The default is for Windows Server 2003 and Windows XP Service Pack 2 and later, and for all other versions. - property to prevent multiple clients from using a specific port. - - This property must be set before the underlying socket is bound to a client port. If you call , , , or , the client port is bound as a side effect of the constructor, and you cannot subsequently set the property - - - -## Examples - The following code example creates a , and gets and sets the property. - + property to prevent multiple clients from using a specific port. + + This property must be set before the underlying socket is bound to a client port. If you call , , , or , the client port is bound as a side effect of the constructor, and you cannot subsequently set the property + + + +## Examples + The following code example creates a , and gets and sets the property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient/CPP/newudpclient.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet4"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet4"::: + ]]> An error occurred when attempting to access the underlying socket. @@ -2038,33 +2038,33 @@ The multicast of the group you want to join. Adds a to a multicast group. - method subscribes the to a multicast group using the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router requesting membership to the multicast group. The multicast address range is 224.0.0.0 to 239.255.255.255. If you specify an address outside this range or if the router to which the request is made is not multicast enabled, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. Once the is listed with the router as a member of the multicast group, it will be able to receive multicasted datagrams sent to the specified . - + method subscribes the to a multicast group using the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router requesting membership to the multicast group. The multicast address range is 224.0.0.0 to 239.255.255.255. If you specify an address outside this range or if the router to which the request is made is not multicast enabled, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. Once the is listed with the router as a member of the multicast group, it will be able to receive multicasted datagrams sent to the specified . + > [!NOTE] -> You must create the using the multicast port number; otherwise, you will not be able to receive multicasted datagrams. Do not call the method prior to calling the method, or the method will not work. You do not need to belong to a multicast group to send datagrams to a multicast IP address. - - Before joining a multicast group, make sure the socket is bound to the port or endpoint. You do that by calling one of the constructors that accept a port or an endpoint as a parameter. - - To stop receiving multicasted datagrams, call the method and provide the of the group from which you would like to withdraw. - +> You must create the using the multicast port number; otherwise, you will not be able to receive multicasted datagrams. Do not call the method prior to calling the method, or the method will not work. You do not need to belong to a multicast group to send datagrams to a multicast IP address. + + Before joining a multicast group, make sure the socket is bound to the port or endpoint. You do that by calling one of the constructors that accept a port or an endpoint as a parameter. + + To stop receiving multicasted datagrams, call the method and provide the of the group from which you would like to withdraw. + > [!NOTE] -> In the IPv6 case, there are several multicast address ranges you can choose from. Please, refer to the IETF RFC 2375. - +> In the IPv6 case, there are several multicast address ranges you can choose from. Please, refer to the IETF RFC 2375. + > [!NOTE] -> You cannot call on a constructed without a specific local port (that is, using the or constructor). - - - -## Examples - The following code example demonstrates how to join a multicast group by providing a multicast address. - +> You cannot call on a constructed without a specific local port (that is, using the or constructor). + + + +## Examples + The following code example demonstrates how to join a multicast group by providing a multicast address. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient.JoinMulticastGroup/CPP/joinmulticastgroup.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/IPv6MulticastOption/Overview/joinmulticastgroup.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.Sockets.UdpClient.JoinMulticastGroup/VB/joinmulticastgroup.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.Sockets.UdpClient.JoinMulticastGroup/VB/joinmulticastgroup.vb" id="Snippet1"::: + ]]> The underlying has been closed. @@ -2117,26 +2117,26 @@ The multicast of the group you want to join. Adds a to a multicast group. - [!NOTE] -> There are several multicast address ranges to choose from. Refer to the IETF RFC 2375. - +> There are several multicast address ranges to choose from. Refer to the IETF RFC 2375. + > [!NOTE] -> You cannot call on a constructed without a specific local port (that is, using the or constructor). - - - -## Examples +> You cannot call on a constructed without a specific local port (that is, using the or constructor). + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient.JoinMulticastGroup/CPP/joinmulticastgroup.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/IPv6MulticastOption/Overview/joinmulticastgroup.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.Sockets.UdpClient.JoinMulticastGroup/VB/joinmulticastgroup.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.Sockets.UdpClient.JoinMulticastGroup/VB/joinmulticastgroup.vb" id="Snippet5"::: + ]]> The underlying has been closed. @@ -2187,30 +2187,30 @@ The Time to Live (TTL), measured in router hops. Adds a to a multicast group with the specified Time to Live (TTL). - method subscribes the to a multicast group using the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router requesting membership to the multicast group. The multicast address range is 224.0.0.0 to 239.255.255.255. If you specify an address outside this range or if the router to which the request is made is not multicast enabled, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. The `timeToLive` parameter specifies how many router hops will be allowed for a multicasted datagram before being discarded. Once the is listed with the router as a member of the multicast group, it will be able to receive multicasted datagrams sent to the specified . - + method subscribes the to a multicast group using the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router requesting membership to the multicast group. The multicast address range is 224.0.0.0 to 239.255.255.255. If you specify an address outside this range or if the router to which the request is made is not multicast enabled, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. The `timeToLive` parameter specifies how many router hops will be allowed for a multicasted datagram before being discarded. Once the is listed with the router as a member of the multicast group, it will be able to receive multicasted datagrams sent to the specified . + > [!NOTE] -> You must create the using the multicast port number otherwise you will not be able to receive multicasted datagrams. Do not call the method prior to calling the method or the receive method will not work. You do not need to belong to a multicast group to send datagrams to a multicast IP address. - - Before joining a multicast group make sure the socket is bound to the port or endpoint. You do that by calling one of the constructors that accept as parameter a port or an endpoint. - - To stop receiving multicasted datagrams, call the method and provide the of the group from which you would like to withdraw. - +> You must create the using the multicast port number otherwise you will not be able to receive multicasted datagrams. Do not call the method prior to calling the method or the receive method will not work. You do not need to belong to a multicast group to send datagrams to a multicast IP address. + + Before joining a multicast group make sure the socket is bound to the port or endpoint. You do that by calling one of the constructors that accept as parameter a port or an endpoint. + + To stop receiving multicasted datagrams, call the method and provide the of the group from which you would like to withdraw. + > [!NOTE] -> You cannot call on a constructed without a specific local port (that is, using the or constructor). - - - -## Examples - The following example demonstrates how to join a multicast group by providing two parameters, a multicast address, and a number that represents the TTL. - +> You cannot call on a constructed without a specific local port (that is, using the or constructor). + + + +## Examples + The following example demonstrates how to join a multicast group by providing two parameters, a multicast address, and a number that represents the TTL. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/CPP/source.cpp" id="Snippet13"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/.ctor/source.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet13"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet13"::: + ]]> The TTL provided is not between 0 and 255 @@ -2265,25 +2265,25 @@ The local . Adds a to a multicast group. - [!NOTE] -> There are several multicast address ranges to choose from. You can find them in the IETF RFC 2375. - +> There are several multicast address ranges to choose from. You can find them in the IETF RFC 2375. + > [!NOTE] -> You cannot call on a constructed without a specific local port (that is, using the or constructor). - - - -## Examples - The following code example shows the use of the method. - +> You cannot call on a constructed without a specific local port (that is, using the or constructor). + + + +## Examples + The following code example shows the use of the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient/CPP/newudpclient.cpp" id="Snippet6"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet6"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet6"::: + ]]> The underlying has been closed. @@ -2329,19 +2329,19 @@ if the receives outgoing multicast packets; otherwise, . - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient/CPP/newudpclient.cpp" id="Snippet7"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet7"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet7"::: + ]]> @@ -2400,27 +2400,27 @@ Returns a UDP datagram that was sent by a remote host. An array of type that contains datagram data. - method will block until a datagram arrives from a remote host. When data is available, the method will read the first enqueued datagram and return the data portion as a byte array. This method populates the `remoteEP` parameter with the and port number of the sender. - - If you specify a default remote host in the method, the method will accept datagrams from that host only. All other datagrams will be discarded. - - If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - + method will block until a datagram arrives from a remote host. When data is available, the method will read the first enqueued datagram and return the data portion as a byte array. This method populates the `remoteEP` parameter with the and port number of the sender. + + If you specify a default remote host in the method, the method will accept datagrams from that host only. All other datagrams will be discarded. + + If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + > [!NOTE] -> If you intend to receive multicasted datagrams, do not call the method prior to calling the method. The you use to receive datagrams must be created using the multicast port number. - - - -## Examples - The following example demonstrates the method. The method blocks execution until it receives a message. Using the passed to , the identity of the responding host is revealed. - +> If you intend to receive multicasted datagrams, do not call the method prior to calling the method. The you use to receive datagrams must be created using the multicast port number. + + + +## Examples + The following example demonstrates the method. The method blocks execution until it receives a message. Using the passed to , the identity of the responding host is revealed. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/CPP/source.cpp" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/.ctor/source.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet11"::: + ]]> The underlying has been closed. @@ -2469,18 +2469,18 @@ Returns a UDP datagram asynchronously that was sent by a remote host. The task object representing the asynchronous operation. - > object will complete after the UDP packet has been received. - - If you specify a default remote host in the method, this method will accept datagrams from that host only. All other datagrams will be discarded. - - If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - + > object will complete after the UDP packet has been received. + + If you specify a default remote host in the method, this method will accept datagrams from that host only. All other datagrams will be discarded. + + If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + > [!WARNING] -> If you intend to receive multicasted datagrams, do not call the method prior to calling this method. The you use to receive datagrams must be created using the multicast port number. - +> If you intend to receive multicasted datagrams, do not call the method prior to calling this method. The you use to receive datagrams must be created using the multicast port number. + ]]> The underlying has been closed. @@ -2621,22 +2621,22 @@ Sends a UDP datagram to a remote host. The number of bytes sent. - method and returns the number of bytes sent. If you do not call before calling this overload, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - If you want to send datagrams to a different remote host, you must call the method and specify the desired remote host. Use either of the other method overloads to send datagrams to a broadcast address. - - - -## Examples - The following example demonstrates the method. You must establish a default remote host prior to using this overload. - + method and returns the number of bytes sent. If you do not call before calling this overload, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + + If you want to send datagrams to a different remote host, you must call the method and specify the desired remote host. Use either of the other method overloads to send datagrams to a broadcast address. + + + +## Examples + The following example demonstrates the method. You must establish a default remote host prior to using this overload. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/CPP/source.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/.ctor/source.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet10"::: + ]]> @@ -2752,25 +2752,25 @@ Sends a UDP datagram to the host at the specified remote endpoint. The number of bytes sent. - method sends datagrams to the specified endpoint and returns the number of bytes successfully sent. Before calling this overload, you must first create an using the IP address and port number of the remote host to which your datagrams will be delivered. You can send datagrams to the default broadcast address, 255.255.255.255, by specifying for the property of the . After you have created this , pass it to the method as the `endPoint` parameter. - - If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. - + method sends datagrams to the specified endpoint and returns the number of bytes successfully sent. Before calling this overload, you must first create an using the IP address and port number of the remote host to which your datagrams will be delivered. You can send datagrams to the default broadcast address, 255.255.255.255, by specifying for the property of the . After you have created this , pass it to the method as the `endPoint` parameter. + + If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. + > [!NOTE] -> Do not provide an `endPoint` parameter to this method if you have already established a remote host with the method. If you do, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - - -## Examples - The following example demonstrates the method. This example uses an to specify the target host. - +> Do not provide an `endPoint` parameter to this method if you have already established a remote host with the method. If you do, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + + + +## Examples + The following example demonstrates the method. This example uses an to specify the target host. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/CPP/source.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/.ctor/source.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet8"::: + ]]> @@ -2893,25 +2893,25 @@ Sends a UDP datagram to a specified port on a specified remote host. The number of bytes sent. - method sends datagrams to the values specified by the `hostname` and `port` parameters and returns the number of bytes successfully sent. You can send datagrams to the default broadcast address by specifying "255.255.255.255" for the `hostname` parameter value. - - If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. - + method sends datagrams to the values specified by the `hostname` and `port` parameters and returns the number of bytes successfully sent. You can send datagrams to the default broadcast address by specifying "255.255.255.255" for the `hostname` parameter value. + + If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. + > [!NOTE] -> Do not provide a host name or port number to this method if you have already established a remote host with the method. If you do, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - - -## Examples - The following example demonstrates the method. This example uses a host name and a port number to identify the target host. - +> Do not provide a host name or port number to this method if you have already established a remote host with the method. If you do, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + + + +## Examples + The following example demonstrates the method. This example uses a host name and a port number to identify the target host. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/CPP/source.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/.ctor/source.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic UdpClient.PublicMethodsAndPropertiesExample/VB/source.vb" id="Snippet9"::: + ]]> @@ -2976,13 +2976,13 @@ Sends a UDP datagram asynchronously to a remote host. Returns . - method. If you do not call before calling this overload, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - If you want to send datagrams to a different remote host, you must call the method and specify the desired remote host. Use either of the other method overloads to send datagrams to a broadcast address. - + method. If you do not call before calling this overload, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + + If you want to send datagrams to a different remote host, you must call the method and specify the desired remote host. Use either of the other method overloads to send datagrams to a broadcast address. + 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 . ]]> @@ -3088,16 +3088,16 @@ Sends a UDP datagram asynchronously to a remote host. Returns . - using the IP address and port number of the remote host to which your datagrams will be delivered. You can send datagrams to the default broadcast address, 255.255.255.255, by specifying for the property of the . After you have created this , pass it to this method as the `endPoint` parameter. - - If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. - + using the IP address and port number of the remote host to which your datagrams will be delivered. You can send datagrams to the default broadcast address, 255.255.255.255, by specifying for the property of the . After you have created this , pass it to this method as the `endPoint` parameter. + + If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. + > [!WARNING] -> Do not provide an `endPoint` parameter to this method if you have already established a remote host with the method. If you do, this method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - +> Do not provide an `endPoint` parameter to this method if you have already established a remote host with the method. If you do, this method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + 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 . ]]> @@ -3218,16 +3218,16 @@ Sends a UDP datagram asynchronously to a remote host. Returns . - method to obtain the underlying , and set the socket option to . You can also revert to using the class. - + method to obtain the underlying , and set the socket option to . You can also revert to using the class. + > [!WARNING] -> Do not provide a host name or port number to this method if you have already established a remote host with the method. If you do, this method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - +> Do not provide a host name or port number to this method if you have already established a remote host with the method. If you do, this method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + 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 . ]]> @@ -3330,10 +3330,10 @@ . The IDisposable.Dispose method leaves the in an unusable state. After calling IDisposable.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] +> [!NOTE] > Always call IDisposable.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. ]]> @@ -3379,19 +3379,19 @@ Call IDisposable.Dispose when you are finished using the Gets or sets a value that specifies the Time to Live (TTL) value of Internet Protocol (IP) packets sent by the . The TTL value. - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.Sockets.UdpClient/CPP/newudpclient.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet5"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet5"::: + ]]> diff --git a/xml/System.Net/HttpListener.xml b/xml/System.Net/HttpListener.xml index 5607a715df6..ca8314ad27c 100644 --- a/xml/System.Net/HttpListener.xml +++ b/xml/System.Net/HttpListener.xml @@ -115,7 +115,7 @@ This class cannot be used on the current operating system. Windows Server 2003 or Windows XP SP2 is required to use instances of this class. - Note: This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + Note: This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. @@ -174,7 +174,7 @@ ]]> - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. @@ -410,7 +410,7 @@ This object has not been started or is currently stopped. This object is closed. - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. @@ -468,7 +468,7 @@ The following code example demonstrates calling the `Close` method: ]]> - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. @@ -618,7 +618,7 @@ The following code example demonstrates calling the `Close` method: The method was already called for the specified object. This object is closed. - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. @@ -836,7 +836,7 @@ The following code example demonstrates calling the `Close` method: The does not have any Uniform Resource Identifier (URI) prefixes to respond to. This object is closed. - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. @@ -1249,7 +1249,7 @@ The following code example demonstrates calling the `Close` method: A Win32 function call failed. Check the exception's property to determine the cause of the exception. This object is closed. - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. @@ -1310,7 +1310,7 @@ The following code example demonstrates using the This object has been closed. - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. diff --git a/xml/System.Net/HttpListenerContext.xml b/xml/System.Net/HttpListenerContext.xml index 817ec1e51f7..baffd619768 100644 --- a/xml/System.Net/HttpListenerContext.xml +++ b/xml/System.Net/HttpListenerContext.xml @@ -51,23 +51,23 @@ Provides access to the request and response objects used by the class. This class cannot be inherited. - object. This class also has methods that allow an object to accept a WebSocket connection. - - The method returns instances of the class. To get the object that represents the client request, use the property. To get the object that represents the response that will be sent to the client by the , use the property. To get user information about the client sending the request, such as its login name and whether it has been authenticated, you can query the properties in the object returned by the property. - - Closing an object sends the response to the client and frees any resources used by the . Aborting an object discards the response to the client if it has not already been sent, and frees any resources used by the . After closing or aborting an object, you cannot reference its methods or properties. If you do so, you will receive an exception. - - - -## Examples - The following code example displays the user information for a client request. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet8"::: - + object. This class also has methods that allow an object to accept a WebSocket connection. + + The method returns instances of the class. To get the object that represents the client request, use the property. To get the object that represents the response that will be sent to the client by the , use the property. To get user information about the client sending the request, such as its login name and whether it has been authenticated, you can query the properties in the object returned by the property. + + Closing an object sends the response to the client and frees any resources used by the . Aborting an object discards the response to the client if it has not already been sent, and frees any resources used by the . After closing or aborting an object, you cannot reference its methods or properties. If you do so, you will receive an exception. + + + +## Examples + The following code example displays the user information for a client request. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet8"::: + ]]> @@ -133,20 +133,20 @@ Accept a WebSocket connection as an asynchronous operation. The task object representing the asynchronous operation. The property on the task object returns an object. - object will complete after the WebSocket connection has been accepted. - - The size of the receive buffer is 16,385 bytes. The WebSocket keep-alive interval is set to the default value of 30,000 (30 seconds). - + object will complete after the WebSocket connection has been accepted. + + The size of the receive buffer is 16,385 bytes. The WebSocket keep-alive interval is set to the default value of 30,000 (30 seconds). + ]]> - is an empty string - - -or- - + is an empty string + + -or- + contains illegal characters. An error occurred when sending the response to complete the WebSocket handshake. @@ -202,20 +202,20 @@ Accept a WebSocket connection specifying the supported WebSocket sub-protocol and WebSocket keep-alive interval as an asynchronous operation. The task object representing the asynchronous operation. The property on the task object returns an object. - object will complete after the WebSocket connection has been accepted. - - The size of the receive buffer is 16,385 bytes. - + object will complete after the WebSocket connection has been accepted. + + The size of the receive buffer is 16,385 bytes. + ]]> - is an empty string - - -or- - + is an empty string + + -or- + contains illegal characters. is too small. @@ -275,28 +275,28 @@ Accept a WebSocket connection specifying the supported WebSocket sub-protocol, receive buffer size, and WebSocket keep-alive interval as an asynchronous operation. The task object representing the asynchronous operation. The property on the task object returns an object. - > object will complete after the WebSocket connection has been accepted. - + > object will complete after the WebSocket connection has been accepted. + ]]> - is an empty string - - -or- - + is an empty string + + -or- + contains illegal characters. - is too small. - - -or- - - is less than 16 bytes - - -or- - + is too small. + + -or- + + is less than 16 bytes + + -or- + is greater than 64K bytes. An error occurred when sending the response to complete the WebSocket handshake. @@ -366,28 +366,28 @@ Accept a WebSocket connection specifying the supported WebSocket sub-protocol, receive buffer size, WebSocket keep-alive interval, and the internal buffer as an asynchronous operation. The task object representing the asynchronous operation. The property on the task object returns an object. - object will complete after the WebSocket connection has been accepted. - + object will complete after the WebSocket connection has been accepted. + ]]> - is an empty string - - -or- - + is an empty string + + -or- + contains illegal characters. - is too small. - - -or- - - is less than 16 bytes - - -or- - + is too small. + + -or- + + is less than 16 bytes + + -or- + is greater than 64K bytes. An error occurred when sending the response to complete the WebSocket handshake. @@ -436,19 +436,19 @@ Gets the that represents a client's request for a resource. An object that represents the client request. - , it will send the response to the client, close the that contains the response, and close the object returned by this property. - - - -## Examples - The following code example demonstrates calling this method. The `listener` variable holds an object. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet3"::: - + , it will send the response to the client, close the that contains the response, and close the object returned by this property. + + + +## Examples + The following code example demonstrates calling this method. The `listener` variable holds an object. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet3"::: + ]]> @@ -490,23 +490,23 @@ Gets the object that will be sent to the client in response to the client's request. An object used to send a response back to the client. - object returned by this property. After configuring the response, you send it to the client by closing the response, or by closing this object. - - - -## Examples - The following code example demonstrates getting the response to a client's request and adding the response body. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet3"::: - + object returned by this property. After configuring the response, you send it to the client by closing the response, or by closing this object. + + + +## Examples + The following code example demonstrates getting the response to a client's request and adding the response body. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet3"::: + ]]> - Note: This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + Note: This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. @@ -558,21 +558,21 @@ Gets an object used to obtain identity, authentication information, and security roles for the client whose request is represented by this object. An object that describes the client, or if the that supplied this does not require authentication. - indicates that it requires authentication using the property or by specifying an delegate using the property. - - To determine the client's login name and authentication information, check the property in the object returned by this property. - - - -## Examples - The following code example demonstrates accessing identity and authentication information about the client, and returning it to the client in the response. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet8"::: - + indicates that it requires authentication using the property or by specifying an delegate using the property. + + To determine the client's login name and authentication information, check the property in the object returned by this property. + + + +## Examples + The following code example demonstrates accessing identity and authentication information about the client, and returning it to the client in the response. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet8"::: + ]]> diff --git a/xml/System.Net/HttpListenerPrefixCollection.xml b/xml/System.Net/HttpListenerPrefixCollection.xml index 5db96fcb583..7baf1937eaa 100644 --- a/xml/System.Net/HttpListenerPrefixCollection.xml +++ b/xml/System.Net/HttpListenerPrefixCollection.xml @@ -64,19 +64,19 @@ Represents the collection used to store Uniform Resource Identifier (URI) prefixes for objects. - property returns instances of this collection. - - - -## Examples - The following code example creates an and adds user-specified prefixes to its . - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet2"::: - + property returns instances of this collection. + + + +## Examples + The following code example creates an and adds user-specified prefixes to its . + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet2"::: + ]]> @@ -124,34 +124,34 @@ A that identifies the URI information that is compared in incoming requests. The prefix must be terminated with a forward slash ("/"). Adds a Uniform Resource Identifier (URI) prefix to the collection. - object. When checking `uriPrefix` to ensure it is valid, case is ignored. - - A URI prefix string is composed of a scheme (http or https), a host, an optional port, and an optional path, for example, "`http://www.contoso.com:8080/customerData/`". The prefix must be terminated with a forward slash ("/"). The with the prefix that most closely matches a requested URI responds to the request. Multiple objects cannot add the same prefix. An exception is thrown if an adds a prefix that is already in use. - - When a port is specified, the host element can be replaced with "`*`" to indicate that the accepts requests sent to the port if the requested URI does not match any other prefix. For example, to receive all requests sent to port 8080 when the requested URI is not handled by any other , the prefix is "`http://*:8080/`". Similarly, to specify that the accepts all requests sent to a port, replace the host element with the "`+`" character, "`https://+:8080/`". The "`*`" and "`+`" characters can be present in prefixes that include paths. - - Starting with .NET 4.5.3 and Windows 10, wildcard subdomains are supported in URI prefixes that are managed by an object. To specify a wildcard subdomain, use the "\*" character as part of the hostname in a URI prefix: for example, `http://*.foo.com/`, and pass this as the argument to the HttpListenerPrefixCollection.Add method. This will work on .NET 4.5.3 and Windows 10; in earlier versions, this would generate an - - - -## Examples - The following code example creates an and adds user-specified prefixes to its . - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet2"::: - + object. When checking `uriPrefix` to ensure it is valid, case is ignored. + + A URI prefix string is composed of a scheme (http or https), a host, an optional port, and an optional path, for example, "`http://www.contoso.com:8080/customerData/`". The prefix must be terminated with a forward slash ("/"). The with the prefix that most closely matches a requested URI responds to the request. Multiple objects cannot add the same prefix. An exception is thrown if an adds a prefix that is already in use. + + When a port is specified, the host element can be replaced with "`*`" to indicate that the accepts requests sent to the port if the requested URI does not match any other prefix. For example, to receive all requests sent to port 8080 when the requested URI is not handled by any other , the prefix is "`http://*:8080/`". Similarly, to specify that the accepts all requests sent to a port, replace the host element with the "`+`" character, "`https://+:8080/`". The "`*`" and "`+`" characters can be present in prefixes that include paths. + + Starting with .NET 4.5.3 and Windows 10, wildcard subdomains are supported in URI prefixes that are managed by an object. To specify a wildcard subdomain, use the "\*" character as part of the hostname in a URI prefix: for example, `http://*.foo.com/`, and pass this as the argument to the HttpListenerPrefixCollection.Add method. This will work on .NET 4.5.3 and Windows 10; in earlier versions, this would generate an + + + +## Examples + The following code example creates an and adds user-specified prefixes to its . + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet2"::: + ]]> is . - does not use the http:// or https:// scheme. These are the only schemes supported for objects. - - -or- - + does not use the http:// or https:// scheme. These are the only schemes supported for objects. + + -or- + is not a correctly formatted URI prefix. Make sure the string is terminated with a "/". The associated with this collection is closed. A Windows function call failed. Check the exception's property to determine the cause of the exception. This exception is thrown if another has already added the prefix . @@ -198,25 +198,25 @@ Removes all the Uniform Resource Identifier (URI) prefixes from the collection. - without adding new prefixes; if you try to do so, an exception is thrown. - - - -## Examples - The following code example removes all prefixes in an . - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet6"::: - + without adding new prefixes; if you try to do so, an exception is thrown. + + + +## Examples + The following code example removes all prefixes in an . + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet6"::: + ]]> A Windows function call failed. Check the exception's property to determine the cause of the exception. The associated with this collection is closed. - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. @@ -266,19 +266,19 @@ if this collection contains the prefix specified by ; otherwise, . - . - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet4"::: - + . + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet4"::: + ]]> @@ -295,11 +295,11 @@ Copies the contents of an to the specified array. - @@ -346,19 +346,19 @@ The zero-based index in at which copying begins. Copies the contents of an to the specified array. - . - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet7"::: - + . + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet7"::: + ]]> @@ -415,19 +415,19 @@ The zero-based index in at which copying begins. Copies the contents of an to the specified string array. - . - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet7"::: - + . + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet7"::: + ]]> @@ -477,14 +477,14 @@ Gets the number of prefixes contained in the collection. An that contains the number of prefixes in this collection. - @@ -531,23 +531,23 @@ Returns an object that can be used to iterate through the collection. An object that implements the interface and provides access to the strings in this collection. - method before you can access the first element. To access the element at the current position, call the property. - - Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . - - For a detailed description of enumerators, see the documentation for the class and the method. - - - -## Examples - The following code example demonstrates enumerating through a collection. Note that the Visual Basic and C# examples use language specific statements to enumerate through the collection instead of retrieving the enumerator. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet1"::: - + method before you can access the first element. To access the element at the current position, call the property. + + Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . + + For a detailed description of enumerators, see the documentation for the class and the method. + + + +## Examples + The following code example demonstrates enumerating through a collection. Note that the Visual Basic and C# examples use language specific statements to enumerate through the collection instead of retrieving the enumerator. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet1"::: + ]]> @@ -632,11 +632,11 @@ Gets a value that indicates whether access to the collection is synchronized (thread-safe). This property always returns . - @@ -687,11 +687,11 @@ if the was found in the and removed; otherwise . - @@ -699,7 +699,7 @@ A Windows function call failed. To determine the cause of the exception, check the exception's error code. The associated with this collection is closed. - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. @@ -751,15 +751,15 @@ Returns an object that can be used to iterate through the collection. An object that implements the interface and provides access to the strings in this collection. - method before you can access the first element. To access the element at the current position, call the property. - - Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . - - For a detailed description of enumerators, see the documentation for the class and the method. - + method before you can access the first element. To access the element at the current position, call the property. + + Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . + + For a detailed description of enumerators, see the documentation for the class and the method. + ]]> diff --git a/xml/System.Net/HttpListenerRequest.xml b/xml/System.Net/HttpListenerRequest.xml index 6fedb3fc2a1..455e079dbaa 100644 --- a/xml/System.Net/HttpListenerRequest.xml +++ b/xml/System.Net/HttpListenerRequest.xml @@ -51,23 +51,23 @@ Describes an incoming HTTP request to an object. This class cannot be inherited. - object, the provides a object that contains information about the sender, the request, and the response that is sent to the client. The property returns the object that describes the request. - - The object contains information about the request, such as the request string, string, and request body data (see the property). - - To reply to the request, you must get the associated response using the property. - - - -## Examples - The following code example demonstrates how to receive and respond to a . - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet2"::: - + object, the provides a object that contains information about the sender, the request, and the response that is sent to the client. The property returns the object that describes the request. + + The object contains information about the request, such as the request string, string, and request body data (see the property). + + To reply to the request, you must get the associated response using the property. + + + +## Examples + The following code example demonstrates how to receive and respond to a . + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet2"::: + ]]> @@ -119,21 +119,21 @@ Gets the MIME types accepted by the client. A array that contains the type names specified in the request's header or if the client request did not include an header. - enumeration. - - - -## Examples - The following code example demonstrates using this property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet15"::: - + enumeration. + + + +## Examples + The following code example demonstrates using this property. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet15"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet15"::: + ]]> @@ -230,25 +230,25 @@ Gets an error code that identifies a problem with the provided by the client. An value that contains a Windows error code. - - The client certificate has not been initialized yet by a call to the or methods - - -or - - + The client certificate has not been initialized yet by a call to the or methods + + -or - + The operation is still in progress. @@ -292,19 +292,19 @@ Gets the content encoding that can be used with data sent with the request. An object suitable for use with the data in the property. - object can be used to convert byte sequences into character sets (code pages) and characters into byte sequences. This property uses the charset value from the `Content-Type` header to determine the encoding. If that information is not available, this property returns . - - - -## Examples - The following code example demonstrates using the property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet16"::: - + object can be used to convert byte sequences into character sets (code pages) and characters into byte sequences. This property uses the charset value from the `Content-Type` header to determine the encoding. If that information is not available, this property returns . + + + +## Examples + The following code example demonstrates using the property. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet16"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet16"::: + ]]> @@ -349,21 +349,21 @@ Gets the length of the body data included in the request. The value from the request's header. This value is -1 if the content length is not known. - enumeration. - - - -## Examples - The following code example uses the property while processing body data. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet16"::: - + enumeration. + + + +## Examples + The following code example uses the property while processing body data. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet16"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet16"::: + ]]> @@ -423,23 +423,23 @@ Gets the MIME type of the body data included in the request. A that contains the text of the request's header. - enumeration and RFC 2616, available at [https://www.rfc-editor.org](https://www.rfc-editor.org/). - - The is null when there is no `Content-Type` header in the request. - - - -## Examples - The following code example demonstrates how to use this property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet16"::: - + enumeration and RFC 2616, available at [https://www.rfc-editor.org](https://www.rfc-editor.org/). + + The is null when there is no `Content-Type` header in the request. + + + +## Examples + The following code example demonstrates how to use this property. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet16"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet16"::: + ]]> @@ -484,19 +484,19 @@ Gets the cookies sent with the request. A that contains cookies that accompany the request. This property returns an empty collection if the request does not contain cookies. - @@ -598,11 +598,11 @@ Retrieves the client's X.509 v.3 certificate. A object that contains the client's X.509 v.3 certificate. - A call to this method to retrieve the client's X.509 v.3 certificate is in progress and therefore another call to this method cannot be made. @@ -647,13 +647,13 @@ Retrieves the client's X.509 v.3 certificate as an asynchronous operation. The task object representing the asynchronous operation. The property on the task object returns a object that contains the client's X.509 v.3 certificate. - object will complete when the certificate has been retrieved. - - If a call to this method to retrieve the client's X.509 v.3 certificate is in progress, then another call to this method cannot be made. - + object will complete when the certificate has been retrieved. + + If a call to this method to retrieve the client's X.509 v.3 certificate is in progress, then another call to this method cannot be made. + 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 . ]]> @@ -699,19 +699,19 @@ if the request has associated body data; otherwise, . - @@ -756,21 +756,21 @@ Gets the collection of header name/value pairs sent in the request. A that contains the HTTP headers included in the request. - enumeration. - - - -## Examples - The following code example displays all the information in a given object. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet21"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet21"::: - + enumeration. + + + +## Examples + The following code example displays all the information in a given object. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet21"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet21"::: + ]]> @@ -815,19 +815,19 @@ Gets the HTTP method specified by the client. A that contains the method used in the request. - @@ -872,26 +872,26 @@ Gets a stream that contains the body data sent by the client. A readable object that contains the bytes sent by the client in the body of the request. This property returns if no data is sent with the request. - [!NOTE] -> Closing the request does not close the stream returned by this property. When you no longer need the stream, you should close it by calling the method. - - - -## Examples - The following code example demonstrates using this property to read the data sent with a request. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet16"::: - +> Closing the request does not close the stream returned by this property. When you no longer need the stream, you should close it by calling the method. + + + +## Examples + The following code example demonstrates using this property to read the data sent with a request. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet16"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet16"::: + ]]> - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. @@ -936,21 +936,21 @@ if the client was authenticated; otherwise, . - or property. - - Your application does not receive an for requests from clients that are not successfully authenticated. - - - -## Examples - The following code example displays the value of the property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet17"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet17"::: - + or property. + + Your application does not receive an for requests from clients that are not successfully authenticated. + + + +## Examples + The following code example displays the value of the property. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet17"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet17"::: + ]]> @@ -1002,19 +1002,19 @@ if the request originated on the same computer as the object that provided the request; otherwise, . - property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet17"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet17"::: - + property. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet17"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet17"::: + ]]> @@ -1060,19 +1060,19 @@ if the TCP connection is using SSL; otherwise, . - instead of . If the connection cannot be established using SSL, the client receives a that provides information about the error. - - - -## Examples - The following code example demonstrates using the property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet17"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet17"::: - + instead of . If the connection cannot be established using SSL, the client receives a that provides information about the error. + + + +## Examples + The following code example demonstrates using the property. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet17"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet17"::: + ]]> @@ -1114,8 +1114,8 @@ Gets a value that indicates whether the TCP connection was a WebSocket request. - Returns . - + Returns . + if the TCP connection is a WebSocket request; otherwise, . To be added. @@ -1158,19 +1158,19 @@ if the connection should be kept open; otherwise, . - @@ -1221,19 +1221,19 @@ Gets the server IP address and port number to which the request is directed. An that represents the IP address that the request is sent to. - @@ -1284,19 +1284,19 @@ Gets the HTTP version used by the requesting client. A that identifies the client's version of HTTP. - @@ -1341,20 +1341,20 @@ Gets the query string included in the request. A object that contains the query data included in the request . - property value from the object returned by . - + property value from the object returned by . + > [!NOTE] > Queries without an equals sign (for example, `http://www.contoso.com/query.htm?Name`) are added to the `null` key in the . - -## Examples - The following code example demonstrates using the property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet15"::: - + +## Examples + The following code example demonstrates using the property. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet15"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet15"::: + ]]> @@ -1414,21 +1414,21 @@ Gets the URL information (without the host and port) requested by the client. A that contains the raw URL for this request. - property. - - - -## Examples - The following code example demonstrates using the property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet11"::: - + property. + + + +## Examples + The following code example demonstrates using the property. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet11"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet11"::: + ]]> @@ -1479,14 +1479,14 @@ Gets the client IP address and port number from which the request originated. An that represents the IP address and port number from which the request originated. - @@ -1585,11 +1585,11 @@ Gets the Service Provider Name (SPN) that the client sent on the request. A that contains the SPN the client sent on the request. - property to perform custom Service Provide Name (SPN) validation. - + property to perform custom Service Provide Name (SPN) validation. + ]]> @@ -1639,15 +1639,15 @@ Gets the for the client request. A object for the client request. - property can be used to retrieve the channel binding token (CBT) for an which was sent using HTTPS. - - An application could use the property to perform custom authentication using calls to the native Win32 [AcceptSecurityContext](https://go.microsoft.com/fwlink/?LinkId=147021) function. - - If an application attempts to retrieve the channel binding token (CBT) from this property using the method and the is not , then the will throw . The overrides the method with an internal implementation. - + property can be used to retrieve the channel binding token (CBT) for an which was sent using HTTPS. + + An application could use the property to perform custom authentication using calls to the native Win32 [AcceptSecurityContext](https://go.microsoft.com/fwlink/?LinkId=147021) function. + + If an application attempts to retrieve the channel binding token (CBT) from this property using the method and the is not , then the will throw . The overrides the method with an internal implementation. + ]]> @@ -1712,82 +1712,82 @@ Gets the object requested by the client. A object that identifies the resource requested by the client. - property allows you to obtain all the information available from a object. If you need to know only the raw text of the URI request, consider using the property instead. - - The property is null if the from the client could not be parsed. - - The property indicates if uses the raw unescaped URI instead of the converted URI where any percent-encoded values are converted and other normalization steps are taken. - - When a instance receives a request through the `http.sys` service, it creates an instance of the URI string provided by `http.sys`, and exposes it as the property. - - The `http.sys` service exposes two request URI strings: - -- Raw URI - -- Converted URI - - The raw URI is the provided in the request line of a HTTP request: - - `GET /path/` - - `Host: www.contoso.com` - - The raw URI provided by `http.sys` for the request mentioned above, is "/path/". This represents the string following the HTTP verb as it was sent over the network. - - The `http.sys` service creates a converted URI from the information provided in the request using the URI provided in the HTTP request line and the Host header to determine the origin server the request should be forwarded to. This is done by comparing the information from the request with a set of registered URI prefixes. In order to be able to compare those values, some normalization to the request needs to be done. For the sample above the converted URI would be as follows: - - `http://www.contoso.com/path/` - - The `http.sys` service combines the property value and the string in the request line to create a converted URI. In addition, `http.sys` and the class also do the following: - -- Un-escapes all percent encoded values. - -- Converts percent-encoded non-ASCII characters into a UTF-16 character representation. Note that UTF-8 and ANSI/DBCS characters are supported as well as Unicode characters (Unicode encoding using the %uXXXX format). - -- Executes other normalization steps, like path compression. - - Since the request doesn't contain any information about the encoding used for percent-encoded values, it may not be possible to determine the correct encoding just by parsing the percent-encoded values. - - Therefore `http.sys` provides two registry keys for modifying the process: - -|Registry Key|Default Value|Description| -|------------------|-------------------|-----------------| -|EnableNonUTF8|1|If zero, `http.sys` accepts only UTF-8-encoded URLs.

If non-zero, `http.sys` also accepts ANSI-encoded or DBCS-encoded URLs in requests.| -|FavorUTF8|1|If non-zero, `http.sys` always tries to decode a URL as UTF-8 first; if that conversion fails and EnableNonUTF8 is non-zero, Http.sys then tries to decode it as ANSI or DBCS.

If zero (and EnableNonUTF8 is non-zero), `http.sys` tries to decode it as ANSI or DBCS; if that is not successful, it tries a UTF-8 conversion.| - - When receives a request, it uses the converted URI from `http.sys` as input to the property. - - There is a need for supporting characters besides characters and numbers in URIs. An example is the following URI, which is used to retrieve customer information for customer number "1/3812": - - `http://www.contoso.com/Customer('1%2F3812')/` - - Note the percent-encoded slash in the Uri (%2F). This is necessary, since in this case the slash character represents data and not a path delimiter. - - Passing the string to Uri constructor will lead to the following URI: - - `http://www.contoso.com/Customer('1/3812')/` - - Splitting the path into its segments would result in the following elements: - - `Customer('1` - - `3812')` - - This is not the intent of the sender of the request. - - If the property is set to false, then when the receives a request, it uses the raw URI instead of the converted URI from `http.sys` as input to the property. - - - -## Examples - The following code example demonstrates using the property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet15"::: - + property allows you to obtain all the information available from a object. If you need to know only the raw text of the URI request, consider using the property instead. + + The property is null if the from the client could not be parsed. + + The property indicates if uses the raw unescaped URI instead of the converted URI where any percent-encoded values are converted and other normalization steps are taken. + + When a instance receives a request through the `http.sys` service, it creates an instance of the URI string provided by `http.sys`, and exposes it as the property. + + The `http.sys` service exposes two request URI strings: + +- Raw URI + +- Converted URI + + The raw URI is the provided in the request line of a HTTP request: + + `GET /path/` + + `Host: www.contoso.com` + + The raw URI provided by `http.sys` for the request mentioned above, is "/path/". This represents the string following the HTTP verb as it was sent over the network. + + The `http.sys` service creates a converted URI from the information provided in the request using the URI provided in the HTTP request line and the Host header to determine the origin server the request should be forwarded to. This is done by comparing the information from the request with a set of registered URI prefixes. In order to be able to compare those values, some normalization to the request needs to be done. For the sample above the converted URI would be as follows: + + `http://www.contoso.com/path/` + + The `http.sys` service combines the property value and the string in the request line to create a converted URI. In addition, `http.sys` and the class also do the following: + +- Un-escapes all percent encoded values. + +- Converts percent-encoded non-ASCII characters into a UTF-16 character representation. Note that UTF-8 and ANSI/DBCS characters are supported as well as Unicode characters (Unicode encoding using the %uXXXX format). + +- Executes other normalization steps, like path compression. + + Since the request doesn't contain any information about the encoding used for percent-encoded values, it may not be possible to determine the correct encoding just by parsing the percent-encoded values. + + Therefore `http.sys` provides two registry keys for modifying the process: + +|Registry Key|Default Value|Description| +|------------------|-------------------|-----------------| +|EnableNonUTF8|1|If zero, `http.sys` accepts only UTF-8-encoded URLs.

If non-zero, `http.sys` also accepts ANSI-encoded or DBCS-encoded URLs in requests.| +|FavorUTF8|1|If non-zero, `http.sys` always tries to decode a URL as UTF-8 first; if that conversion fails and EnableNonUTF8 is non-zero, Http.sys then tries to decode it as ANSI or DBCS.

If zero (and EnableNonUTF8 is non-zero), `http.sys` tries to decode it as ANSI or DBCS; if that is not successful, it tries a UTF-8 conversion.| + + When receives a request, it uses the converted URI from `http.sys` as input to the property. + + There is a need for supporting characters besides characters and numbers in URIs. An example is the following URI, which is used to retrieve customer information for customer number "1/3812": + + `http://www.contoso.com/Customer('1%2F3812')/` + + Note the percent-encoded slash in the Uri (%2F). This is necessary, since in this case the slash character represents data and not a path delimiter. + + Passing the string to Uri constructor will lead to the following URI: + + `http://www.contoso.com/Customer('1/3812')/` + + Splitting the path into its segments would result in the following elements: + + `Customer('1` + + `3812')` + + This is not the intent of the sender of the request. + + If the property is set to false, then when the receives a request, it uses the raw URI instead of the converted URI from `http.sys` as input to the property. + + + +## Examples + The following code example demonstrates using the property. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet15"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet15"::: + ]]> @@ -1846,25 +1846,25 @@ Gets the Uniform Resource Identifier (URI) of the resource that referred the client to the server. A object that contains the text of the request's header, or if the header was not included in the request. - header. Therefore, while the property can be useful for identifying basic trends in Web traffic; you should not use it as part of an authorization scheme to control access to data. - - For a complete list of request headers, see the enumeration. - - The is null when there is no `Referrer` header in the request or when the `Referrer` header is present in the request but does not parse to a valid . - - - -## Examples - The following code example demonstrates using this property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet15"::: - + header. Therefore, while the property can be useful for identifying basic trends in Web traffic; you should not use it as part of an authorization scheme to control access to data. + + For a complete list of request headers, see the enumeration. + + The is null when there is no `Referrer` header in the request or when the `Referrer` header is present in the request but does not parse to a valid . + + + +## Examples + The following code example demonstrates using this property. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet15"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet15"::: + ]]> @@ -1924,23 +1924,23 @@ Gets the user agent presented by the client. A object that contains the text of the request's header. - enumeration. - - The is null when there is no `User-Agent` header in the request. - - - -## Examples - The following code example demonstrates using this property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet15"::: - + enumeration. + + The is null when there is no `User-Agent` header in the request. + + + +## Examples + The following code example demonstrates using this property. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet15"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet15"::: + ]]> @@ -1991,19 +1991,19 @@ Gets the server IP address and port number to which the request is directed. A that contains the host address information. - property value. - - - -## Examples - The following code example displays the value of this property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet15"::: - + property value. + + + +## Examples + The following code example displays the value of this property. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet15"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet15"::: + ]]> @@ -2054,23 +2054,23 @@ Gets the DNS name and, if provided, the port number specified by the client. A value that contains the text of the request's header. - enumeration. - - - -## Examples - The following code example demonstrates using this property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet15"::: - + enumeration. + + + +## Examples + The following code example demonstrates using this property. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet15"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet15"::: + ]]> @@ -2122,21 +2122,21 @@ Gets the natural languages that are preferred for the response. A array that contains the languages specified in the request's header or if the client request did not include an header. - enumeration. - - - -## Examples - The following code example displays the languages from the request's `Accept-Language` header. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet15"::: - + enumeration. + + + +## Examples + The following code example displays the languages from the request's `Accept-Language` header. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet15"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet15"::: + ]]> diff --git a/xml/System.Net/HttpWebRequest.xml b/xml/System.Net/HttpWebRequest.xml index 0af7c6ea897..daa865218cb 100644 --- a/xml/System.Net/HttpWebRequest.xml +++ b/xml/System.Net/HttpWebRequest.xml @@ -1617,7 +1617,7 @@ Both constructors are obsolete and should not b The request cache validator indicated that the response for this request can be served from the cache; however, requests that write data must not use the cache. This exception can occur if you are using a custom cache validator that is incorrectly implemented. was previously called. - In a .NET Compact Framework application, a request stream with zero content length was not obtained and closed correctly. For more information about handling zero content length requests, see [Network Programming in the .NET Compact Framework](https://learn.microsoft.com/previous-versions/visualstudio/visual-studio-2008/1afx2b0f(v=vs.90)). + In a .NET Compact Framework application, a request stream with zero content length was not obtained and closed correctly. For more information about handling zero content length requests, see Network Programming in the .NET Compact Framework. DefaultProxy Element (Network Settings) @@ -3200,7 +3200,7 @@ The GetHashCode method returns a hash code of the web request. This value can be -or- An error occurred while processing the request. - In a .NET Compact Framework application, a request stream with zero content length was not obtained and closed correctly. For more information about handling zero content length requests, see [Network Programming in the .NET Compact Framework](https://learn.microsoft.com/previous-versions/visualstudio/visual-studio-2008/1afx2b0f(v=vs.90)). + In a .NET Compact Framework application, a request stream with zero content length was not obtained and closed correctly. For more information about handling zero content length requests, see Network Programming in the .NET Compact Framework. DefaultProxy Element (Network Settings) diff --git a/xml/System.Net/HttpWebResponse.xml b/xml/System.Net/HttpWebResponse.xml index e54bc96e0fc..d1b780c4dd6 100644 --- a/xml/System.Net/HttpWebResponse.xml +++ b/xml/System.Net/HttpWebResponse.xml @@ -712,9 +712,9 @@ The contents of the response from the Internet resource are returned as a - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [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)). + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. diff --git a/xml/System.Net/WebRequest.xml b/xml/System.Net/WebRequest.xml index 767f4b3bce0..de74efe689f 100644 --- a/xml/System.Net/WebRequest.xml +++ b/xml/System.Net/WebRequest.xml @@ -366,7 +366,7 @@ Gets or sets values indicating the level of authentication and impersonation used for this request. A bitwise combination of the values. The default value is . - In mutual authentication, both the client and server present credentials to establish their identity. The and values are relevant for Kerberos authentication. Kerberos authentication can be supported directly, or can be used if the Negotiate security protocol is used to select the actual security protocol. For more information about authentication protocols, see [Internet Authentication](/dotnet/framework/network-programming/internet-authentication). + In mutual authentication, both the client and server present credentials to establish their identity. The and values are relevant for Kerberos authentication. Kerberos authentication can be supported directly, or can be used if the Negotiate security protocol is used to select the actual security protocol. For more information about authentication protocols, see Internet Authentication. To determine whether mutual authentication occurred, check the property. diff --git a/xml/System.Printing.IndexedProperties/PrintProperty.xml b/xml/System.Printing.IndexedProperties/PrintProperty.xml index 9b8cc57e12b..2913a43b75f 100644 --- a/xml/System.Printing.IndexedProperties/PrintProperty.xml +++ b/xml/System.Printing.IndexedProperties/PrintProperty.xml @@ -36,14 +36,14 @@ Represents a property (and the value of the property) of a printing system hardware or software component. - @@ -73,11 +73,11 @@ The name of the property that this object represents. Initializes a new instance of the class. - property of a object must be spelled "QueuePort", not "PrintPort", "Port", or "Queueport". - + property of a object must be spelled "QueuePort", not "PrintPort", "Port", or "Queueport". + ]]> @@ -168,20 +168,20 @@ to release both managed resources and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources that are being used by the and optionally releases the managed resources. - method, if it has been overridden. `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. - + method, if it has been overridden. `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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -360,14 +360,14 @@ When overridden in a derived class, gets the name of the property that the object represents. A that represents the name of the property. - @@ -430,14 +430,14 @@ When overridden in a derived class, gets or sets the value of the property that the object represents. To be added. - diff --git a/xml/System.Printing.IndexedProperties/PrintPropertyDictionary.xml b/xml/System.Printing.IndexedProperties/PrintPropertyDictionary.xml index e52027eb4c4..bf19cc1acf2 100644 --- a/xml/System.Printing.IndexedProperties/PrintPropertyDictionary.xml +++ b/xml/System.Printing.IndexedProperties/PrintPropertyDictionary.xml @@ -43,24 +43,24 @@ Represents a collection of properties and values that are associated with an object in the namespace. - dictionary. The property of each in the collection is an instance of a class that is derived from . - - - -## Examples - The following example shows how to use this class to install a second printer that differs in its properties from an existing printer only in location, port, and shared status. - + dictionary. The property of each in the collection is an instance of a class that is derived from . + + + +## Examples + The following example shows how to use this class 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"::: - - The following example shows how to use this class to discover at run time the properties, and the types of those properties, of a print system object, without using reflection. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/ClonePrinter/visualbasic/program.vb" id="Snippetcloneprinter"::: + + The following example shows how to use this class to discover at run time the properties, and the types of those properties, of a print system object, 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"::: + ]]> @@ -166,21 +166,21 @@ An object (of a class that is derived from ) that represents a property of a printing system hardware or software component. Adds the specified object (of a class that is derived from ) into the dictionary. - 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 . - - - -## Examples - The following example shows how to use this method to install a second printer that differs in its properties from an existing printer only in location, port, and shared status. - + 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 . + + + +## Examples + The following example shows how to use this method 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"::: + ]]> @@ -227,14 +227,14 @@ Releases all the resources that are being used by the . - 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). - + 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. + ]]> @@ -276,20 +276,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources that are being used by the and optionally releases the managed resources. - 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. - + 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. + ]]> - can be called multiple times by other objects. When you override , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When you override , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -363,11 +363,11 @@ Gets the object (of a class that is derived from ) that represents the specified property. An object of a class that is derived from the . - property of a object must be spelled "QueuePort", not "PrintPort", "Port", or "Queueport". - + property of a object must be spelled "QueuePort", not "PrintPort", "Port", or "Queueport". + ]]> @@ -435,19 +435,19 @@ An object of a type that is derived from . Sets the value of the specified attribute to an object of a class that is derived from . - diff --git a/xml/System.Printing.Interop/PrintTicketConverter.xml b/xml/System.Printing.Interop/PrintTicketConverter.xml index 1b165f1d56e..66deda8740f 100644 --- a/xml/System.Printing.Interop/PrintTicketConverter.xml +++ b/xml/System.Printing.Interop/PrintTicketConverter.xml @@ -32,11 +32,11 @@ Converts managed objects to unmanaged Graphics Device Interface (GDI) DEVMODE structures, and vice versa. - . To validate it, use . - + . To validate it, use . + ]]> @@ -68,11 +68,11 @@ The Print Schema version to use in the and DEVMODE conversion. Initializes a new instance of the class for the specified printer. - @@ -127,15 +127,15 @@ Converts the specified DEVMODE structure to a managed code . The new managed . - is the entire print job. - - This method does not validate the . To validate it, use . - + is the entire print job. + + This method does not validate the . To validate it, use . + ]]> This is already disposed. @@ -175,13 +175,13 @@ Converts the specified DEVMODE structure to a managed code that has the specified scope. The new . - . To validate it, use . - - For more information on the DEVMODE structure, see [DEVMODE](/windows/win32/api/wingdi/ns-wingdi-devmodea). - + . To validate it, use . + + For more information on the DEVMODE structure, see [DEVMODE](/windows/win32/api/wingdi/ns-wingdi-devmodea). + ]]> This is already disposed. @@ -237,15 +237,15 @@ Converts the specified managed to an unmanaged DEVMODE structure that is based on the DEVMODE structure identified by the . A array that contains the new DEVMODE structure. - parameter must be the entire print job. - - 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). - + parameter must be the entire print job. + + 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). + ]]> This is already disposed. @@ -288,23 +288,23 @@ Converts the specified managed code with the specified scope, into an unmanaged DEVMODE structure that is based on the DEVMODE structure identified by the . A buffer that represents the new DEVMODE structure. - . To validate it, use . - - For more information on the DEVMODE structure, see [DEVMODE](/windows/win32/api/wingdi/ns-wingdi-devmodea). - + . To validate it, use . + + For more information on the DEVMODE structure, see [DEVMODE](/windows/win32/api/wingdi/ns-wingdi-devmodea). + ]]> This is already disposed. The value of is null ( in Visual Basic). The content of is not well-formed. The conversion failed. - The is not a valid value. - - -or- - + The is not a valid value. + + -or- + The is not a valid value. @@ -369,8 +369,8 @@ System.Int32 - Gets the maximum [Print Schema](/windows/win32/printdocs/printschema) version that can support. - The maximum [Print Schema](/windows/win32/printdocs/printschema) version that can support. + Gets the maximum Print Schema version that can support. + The maximum Print Schema version that can support. To be added. Print Schema @@ -408,16 +408,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. + ]]> diff --git a/xml/System.Printing/PrintCapabilities.xml b/xml/System.Printing/PrintCapabilities.xml index 6b1b8251b9b..50e6d9c47fb 100644 --- a/xml/System.Printing/PrintCapabilities.xml +++ b/xml/System.Printing/PrintCapabilities.xml @@ -22,31 +22,31 @@ Defines the capabilities of a printer. - object is an easy-to-work-with representation of a certain type of XML document called a *PrintCapabilities document*. The latter is a snapshot of all of a printer's capabilities and their current settings. For example, if the printer supports color printing, then the document would have a `` element that sets out how color output will be handled. The element is, in turn, represented by the property of the object. If the printer does not support color, then there is no `` element in the document and the value of the property is `null`. The PrintCapabilities document must conform to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397). - - The class enables your application to obtain a printer's capabilities without having to engage in any direct reading of XML objects. - - All of the most popular features of file and photo printers, for both home and business, are encapsulated by the class. But the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) defines many more, less common, features and it can be extended to handle features of specialty printing devices. So, although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. - - **Note** When the object is created with the constructor that takes a PrintCapabilities document (as a ) parameter, that entire document is stored in a non-public field in the object, including the XML elements within it that express less common features that are not represented by any of the public properties of the class. In fact, if the driver that produced the PrintCapabilities document is using a private extension of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397), that privately defined markup is also stored as part of the non-public PrintCapabilities document. - + object is an easy-to-work-with representation of a certain type of XML document called a *PrintCapabilities document*. The latter is a snapshot of all of a printer's capabilities and their current settings. For example, if the printer supports color printing, then the document would have a `` element that sets out how color output will be handled. The element is, in turn, represented by the property of the object. If the printer does not support color, then there is no `` element in the document and the value of the property is `null`. The PrintCapabilities document must conform to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397). + + The class enables your application to obtain a printer's capabilities without having to engage in any direct reading of XML objects. + + All of the most popular features of file and photo printers, for both home and business, are encapsulated by the class. But the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) defines many more, less common, features and it can be extended to handle features of specialty printing devices. So, although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. + + **Note** When the object is created with the constructor that takes a PrintCapabilities document (as a ) parameter, that entire document is stored in a non-public field in the object, including the XML elements within it that express less common features that are not represented by any of the public properties of the class. In fact, if the driver that produced the PrintCapabilities document is using a private extension of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397), that privately defined markup is also stored as part of the non-public PrintCapabilities document. + > [!CAUTION] -> Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. - - If you want to print from a Windows Forms application, see the namespace. - - - -## Examples - The following example shows how to determine the capabilities of a specific printer and how to configure a print job to take advantage of them. - +> Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. + + If you want to print from a Windows Forms application, see the namespace. + + + +## Examples + The following example shows how to determine the capabilities of a specific printer and how to configure a print job to take advantage of them. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Wpf/XpsCreate/CPP/XpsCreate.cpp" id="Snippetprintercapabilities"::: :::code language="csharp" source="~/snippets/csharp/System.Printing/Collation/Overview/XpsCreate.cs" id="Snippetprintercapabilities"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/XpsCreate/visualbasic/xpscreate.vb" id="Snippetprintercapabilities"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/XpsCreate/visualbasic/xpscreate.vb" id="Snippetprintercapabilities"::: + ]]> @@ -74,15 +74,15 @@ An XML that describes printer capabilities and conforms to the Print Schema. - Initializes a new instance of the class by using an XML stream (that contains a PrintCapabilities document) that specifies printer capabilities and complies with the XML [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397). + Initializes a new instance of the class by using an XML stream (that contains a PrintCapabilities document) that specifies printer capabilities and complies with the XML Print Schema. - class. In fact, if the driver that produced the PrintCapabilities document is using a private extension of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397), that privately defined markup is also stored as part of the non-public PrintCapabilities document. - - The private parts of the document, if any, are not validated by the constructor, but all **Print Schema**-defined parts are validated, including the parts that are not represented by any of the public properties of the class. Accordingly, the could be thrown even if all of the XML markup that corresponds to the public properties is valid. - + class. In fact, if the driver that produced the PrintCapabilities document is using a private extension of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397), that privately defined markup is also stored as part of the non-public PrintCapabilities document. + + The private parts of the document, if any, are not validated by the constructor, but all **Print Schema**-defined parts are validated, including the parts that are not represented by any of the public properties of the class. Accordingly, the could be thrown even if all of the XML markup that corresponds to the public properties is valid. + ]]> @@ -116,26 +116,26 @@ Gets a collection of values that identify the collation capabilities of a printer. A of values. - @@ -165,13 +165,13 @@ Gets a collection of values that identify whether and how a printer can substitute device-based fonts for computer-based fonts. A of values. - and values in the collection. - - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageDeviceFontSubstitution` keyword. - + and values in the collection. + + This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageDeviceFontSubstitution` keyword. + ]]> @@ -201,22 +201,22 @@ Gets a collection of values that identify whether and how a printer can perform two-sided printing. A of values. - @@ -246,13 +246,13 @@ Gets a collection of values that indicate what input bin (paper tray) is used. A of values. - @@ -282,11 +282,11 @@ Gets a value indicating the maximum number of copies that the device can print in a single print job. A nullable value that specifies the maximum number of copies that a printer can print. Returns if the device driver does not report a maximum. - @@ -316,13 +316,13 @@ Gets a value indicating the height of the imageable area on a page, where height means the vertical dimension relative to the page's orientation. A nullable value indicating the height, in pixels, which are 1/96 inch increments, of the area on a page that the printer is capable of printing. - @@ -352,13 +352,13 @@ Gets a value indicating the width of the imageable area on a page, where width means the horizontal dimension relative to the page's orientation. A nullable value indicating the width, in pixels, which are 1/96 inch increments, of the area on a page that the printer is capable of printing. - @@ -388,13 +388,13 @@ Gets a collection of values that specify the ways in which a printer can print content with color and shades of gray. A of values. - @@ -424,15 +424,15 @@ Gets a collection of values that indicate the types of output quality the printer supports. A of values. - enumeration has values for , , and quality, among others. - - If the printer does not support output quality selection, the collection is empty. - - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageOutputQuality` keyword. - + enumeration has values for , , and quality, among others. + + If the printer does not support output quality selection, the collection is empty. + + This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageOutputQuality` keyword. + ]]> @@ -462,15 +462,15 @@ Gets a collection of values that indicate whether the printer can print up to the edge of the media. A of values. - @@ -500,11 +500,11 @@ Gets an object that represents the area of a page that the printer can use. A object that specifies the distance, in pixels (units of 1/96 inch), of the upper-left corner of the imageable area. The vertical distance is measured from the top edge of the paper and the horizontal distance is measured from the left edge. The return value also specifies the width and height of the imageable area. If the printer driver does not report an imageable area, then this property is null. - @@ -534,31 +534,31 @@ Gets a collection of objects that identify the paper and media sizes that a printer supports. A of objects. - 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. - - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageMediaSize` keyword. - - - -## Examples - The following code example shows how to search for a particular value in the . - -```csharp -foreach (PageMediaSize mediaSize in pc.PageMediaSizeCapability) - { - if (mediaSize.PageMediaSizeName == PageMediaSizeName.ISOA4) - { - Console.WriteLine("A4 size is supported"); - break; - } - } -``` - + 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. + + This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageMediaSize` keyword. + + + +## Examples + The following code example shows how to search for a particular value in the . + +```csharp +foreach (PageMediaSize mediaSize in pc.PageMediaSizeCapability) + { + if (mediaSize.PageMediaSizeName == PageMediaSizeName.ISOA4) + { + Console.WriteLine("A4 size is supported"); + break; + } + } +``` + ]]> @@ -588,13 +588,13 @@ foreach (PageMediaSize mediaSize in pc.PageMediaSizeCapability) Gets a collection of values that identify what types of paper and other media a printer supports. A of values specifying the print media, such as card stock, label, plain, or photographic. - @@ -624,13 +624,13 @@ foreach (PageMediaSize mediaSize in pc.PageMediaSizeCapability) Gets a collection of values that indicate whether a printer is capable of printing multiple-page documents from front-to-back, back-to-front, or both ways. A of values. - @@ -660,13 +660,13 @@ foreach (PageMediaSize mediaSize in pc.PageMediaSizeCapability) Gets a collection of values that identify what types of page orientation a printer supports. A of values. - @@ -696,33 +696,33 @@ foreach (PageMediaSize mediaSize in pc.PageMediaSizeCapability) Gets a collection of objects that identify what levels of page resolution the printer supports. A of objects. Each value represents a page resolution as a qualitative value, a dots-per-inch value, or both. - 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. - - If the printer does not support page resolution choices, the collection is empty. - - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageResolution` keyword. - - - -## Examples - The following code example shows how to search for a particular value in the . - -```csharp -foreach (PageResolution pageRes in pc.PageResolutionCapability) - { - if (pageRes.QualitativeResolution == PageQualitativeResolution.High) - { - Console.WriteLine("High quality is supported"); - break; - } - } -``` - + 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. + + If the printer does not support page resolution choices, the collection is empty. + + This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageResolution` keyword. + + + +## Examples + The following code example shows how to search for a particular value in the . + +```csharp +foreach (PageResolution pageRes in pc.PageResolutionCapability) + { + if (pageRes.QualitativeResolution == PageQualitativeResolution.High) + { + Console.WriteLine("High quality is supported"); + break; + } + } +``` + ]]> @@ -752,31 +752,31 @@ foreach (PageResolution pageRes in pc.PageResolutionCapability) Gets the maximum and minimum percentages by which a printer can enlarge or reduce the print image on a page. A object with and properties holding values that represent percentages. - property generally represents the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageScaling` keyword. But there are some complexities as follows. - -- If the PrintCapabilities document does not have a `PageScaling` element, or it has one, but neither its **CustomSquare** nor **Custom** options are defined; then the property is null. - -- In all other cases, the property's behavior is as follows. - - The property of the property's object is the smallest of the following values. - - - The **MinValue** property of the `PageScalingScaleWidth` datatype that provides the value of the **Custom** option's **ScaleWidth** `ScoredProperty`. - - - The **MinValue** property of the `PageScalingScaleHeight` datatype that provides the value of the **Custom** option's **ScaleHeight** `ScoredProperty`. - - - The **MinValue** property of the `PageScalingScale` datatype that provides the value of the **CustomSquare** option's **Scale** `ScoredProperty`. - - The property of the property's object is the largest of the following values. - - - The **MaxValue** property of the `PageScalingScaleWidth` datatype that provides the value of the **Custom** option's **ScaleWidth** `ScoredProperty`. - - - The **MaxValue** property of the `PageScalingScaleHeight` datatype that provides the value of the **Custom** option's **ScaleHeight** `ScoredProperty`. - - - The **MaxValue** property of the `PageScalingScale` datatype that provides the value of the **CustomSquare** option's **Scale** `ScoredProperty`. - + property generally represents the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageScaling` keyword. But there are some complexities as follows. + +- If the PrintCapabilities document does not have a `PageScaling` element, or it has one, but neither its **CustomSquare** nor **Custom** options are defined; then the property is null. + +- In all other cases, the property's behavior is as follows. + + The property of the property's object is the smallest of the following values. + + - The **MinValue** property of the `PageScalingScaleWidth` datatype that provides the value of the **Custom** option's **ScaleWidth** `ScoredProperty`. + + - The **MinValue** property of the `PageScalingScaleHeight` datatype that provides the value of the **Custom** option's **ScaleHeight** `ScoredProperty`. + + - The **MinValue** property of the `PageScalingScale` datatype that provides the value of the **CustomSquare** option's **Scale** `ScoredProperty`. + + The property of the property's object is the largest of the following values. + + - The **MaxValue** property of the `PageScalingScaleWidth` datatype that provides the value of the **Custom** option's **ScaleWidth** `ScoredProperty`. + + - The **MaxValue** property of the `PageScalingScaleHeight` datatype that provides the value of the **Custom** option's **ScaleHeight** `ScoredProperty`. + + - The **MaxValue** property of the `PageScalingScale` datatype that provides the value of the **CustomSquare** option's **Scale** `ScoredProperty`. + ]]> @@ -806,15 +806,15 @@ foreach (PageResolution pageRes in pc.PageResolutionCapability) Gets a collection of integers, each identifying the number of pages that a user can choose to print on a single side of a sheet of paper. A of values representing the options that a printer supports for printing more than one page per side. - @@ -844,15 +844,15 @@ foreach (PageResolution pageRes in pc.PageResolutionCapability) Gets a collection of values that identify what patterns a printer supports for presenting multiple pages on a single side of a sheet of paper. A of values. - @@ -882,13 +882,13 @@ foreach (PageResolution pageRes in pc.PageResolutionCapability) Gets a collection of values that identify the quality options the printer supports for printing photographs. A of values. - @@ -918,22 +918,22 @@ foreach (PageResolution pageRes in pc.PageResolutionCapability) Gets a collection of values that identify the types of automatic stapling that a printer supports. A of values. - @@ -963,13 +963,13 @@ foreach (PageResolution pageRes in pc.PageResolutionCapability) Gets a collection of values that identify the methods that a printer supports for handling TrueType fonts. A of values. - diff --git a/xml/System.Printing/PrintJobInfoCollection.xml b/xml/System.Printing/PrintJobInfoCollection.xml index 283129ec8f2..a5c8fe8e95f 100644 --- a/xml/System.Printing/PrintJobInfoCollection.xml +++ b/xml/System.Printing/PrintJobInfoCollection.xml @@ -32,15 +32,15 @@ Represents one or more objects. - [!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. + ]]> @@ -72,11 +72,11 @@ A list of a subset of the properties of a object. Initializes a new instance of the class that contains the objects for every job that is in the specified and that initializes those objects only in the properties that are listed in the specified property filter. - objects in the collection are initialized only in those properties that are listed in the `propertyFilter`. - + objects in the collection are initialized only in those properties that are listed in the `propertyFilter`. + ]]> @@ -154,20 +154,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources that are being used by the and optionally releases the managed resources. - method, if it has been overridden. `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. - + method, if it has been overridden. `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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -200,11 +200,11 @@ Gets an object that implements the generic interface that is closed with . An object that implements the generic interface and that can iterate through the objects that the contains. - only when you need to customize iteration, such as by skipping every other member. - + only when you need to customize iteration, such as by skipping every other member. + ]]> @@ -236,13 +236,13 @@ Gets an object that implements the non-generic interface. An object that implements the non-generic interface and that can iterate through the objects that the contains. - instead of . The is public only to fulfill the requirements of the interface, which is implemented by this collection. - + instead of . The is public only to fulfill the requirements of the interface, which is implemented by this collection. + ]]> diff --git a/xml/System.Printing/PrintQueue.xml b/xml/System.Printing/PrintQueue.xml index 5139c6faa1a..a1102ec71ef 100644 --- a/xml/System.Printing/PrintQueue.xml +++ b/xml/System.Printing/PrintQueue.xml @@ -763,7 +763,7 @@ Gets the version of the Print Schema. - The version of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) in use. + The version of the Print Schema in use. 4.0.0.0 - Gets a object that specifies the printer's capabilities as an XML stream that complies with the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397). + Gets a object that specifies the printer's capabilities as an XML stream that complies with the Print Schema. - Gets a object that specifies the printer's capabilities as an XML stream that complies with the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397). + Gets a object that specifies the printer's capabilities as an XML stream that complies with the Print Schema. A specifying the printer's capabilities by using the XML schema "PrintCapabilities," a part of the Print Schema system. To be added. The print capabilities could not be retrieved. @@ -1623,7 +1623,7 @@ A print ticket that provides the basis on which the print capabilities are reported. - Gets a object that specifies the printer's capabilities in an XML format that complies with the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397). + Gets a object that specifies the printer's capabilities in an XML format that complies with the Print Schema. A specifying the printer's capabilities by using the XML schema "PrintCapabilities," a part of the Print Schema system. System.Int32 - Gets the most recent possible version number of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) that the queue can use. - The most recent version number of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) that the queue can use. + Gets the most recent possible version number of the Print Schema that the queue can use. + The most recent version number of the Print Schema that the queue can use. Represents a collection of objects. - [!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 collection to test a printer's capabilities and configure a print job to take advantage of them. - +> 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 collection to test a printer's capabilities and configure a print job to take advantage of them. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Wpf/XpsCreate/CPP/XpsCreate.cpp" id="Snippetprintercapabilities"::: :::code language="csharp" source="~/snippets/csharp/System.Printing/Collation/Overview/XpsCreate.cs" id="Snippetprintercapabilities"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/XpsCreate/visualbasic/xpscreate.vb" id="Snippetprintercapabilities"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/XpsCreate/visualbasic/xpscreate.vb" id="Snippetprintercapabilities"::: + ]]> @@ -114,11 +114,11 @@ The properties of the collection members that are initialized. Initializes a new instance of the class for the specified . - @@ -152,11 +152,11 @@ An array that specifies the types of print queues that are included in the collection. Initializes a new instance of the class for the specified , containing only the print server's queues of the specified . - @@ -234,20 +234,20 @@ to release both the managed resources and the unmanaged resources; to release only the unmanaged resources. Releases the unmanaged resources that are being used by the , and optionally releases the managed resources that are being used. - method, if it has been overridden. `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. - + method, if it has been overridden. `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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -280,20 +280,20 @@ Returns an object that implements the generic interface that has been closed with . An object that implements the generic and that can iterate through the objects that the contains. - only when you need to customize iteration, such as by skipping every other member. - - - -## Examples - The following example shows how to use this method to test a printer's capabilities and configure a print job to take advantage of them. - + only when you need to customize iteration, such as by skipping every other member. + + + +## Examples + The following example shows how to use this method to test a printer's capabilities and configure a print job to take advantage of them. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Wpf/XpsCreate/CPP/XpsCreate.cpp" id="Snippetprintercapabilities"::: :::code language="csharp" source="~/snippets/csharp/System.Printing/Collation/Overview/XpsCreate.cs" id="Snippetprintercapabilities"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/XpsCreate/visualbasic/xpscreate.vb" id="Snippetprintercapabilities"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/XpsCreate/visualbasic/xpscreate.vb" id="Snippetprintercapabilities"::: + ]]> @@ -325,13 +325,13 @@ Gets an object that implements the non-generic interface. An object that implements the non-generic and that can iterate through the objects that the contains. - instead of . The is public only to fulfill the requirements of the interface, which is implemented by this collection. - + instead of . The is public only to fulfill the requirements of the interface, which is implemented by this collection. + ]]> diff --git a/xml/System.Printing/PrintQueueStream.xml b/xml/System.Printing/PrintQueueStream.xml index e2ed6023349..9b82d932c2d 100644 --- a/xml/System.Printing/PrintQueueStream.xml +++ b/xml/System.Printing/PrintQueueStream.xml @@ -22,16 +22,16 @@ A stream that represents a spooled print job in a print queue. - array, you can also use two of the overloads of the method and the property to write to the spool file. - + 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. - - 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. + ]]> @@ -356,20 +356,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources that are used by the and optionally releases the managed resources. - 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. - + 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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that were previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding , be careful not to reference objects that were previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -401,11 +401,11 @@ A reference to the pending asynchronous I/O request. Ends an asynchronous write operation. - 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 . + ]]> @@ -441,13 +441,13 @@ Enables a to attempt to free resources and perform other cleanup operations before the is reclaimed by garbage collection. - . 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)). - + . 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)). + ]]> @@ -670,13 +670,13 @@ Reads a sequence of bytes from the stream and advances the read/write position in the stream by the number of bytes that were read. An that holds the total number of bytes that are read into the buffer. - @@ -748,13 +748,13 @@ The needed length, in bytes, of the current stream. Sets the length of the stream. - to work. - - Use the property to determine whether the current instance supports writing, and use the property to determine whether seeking is supported. - + 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/PrintSystemObject.xml b/xml/System.Printing/PrintSystemObject.xml index 132affbfea7..225608b29de 100644 --- a/xml/System.Printing/PrintSystemObject.xml +++ b/xml/System.Printing/PrintSystemObject.xml @@ -27,16 +27,16 @@ Defines basic properties and methods that are common to the objects of the printing system. Classes that derive from this class represent such objects as print queues, print servers, and print jobs. - collection of different object types, calling the method on each of them in turn. - + 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. - - 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. + ]]> @@ -156,19 +156,19 @@ When overridden in a derived class, writes any changes that your program has made to the object's properties to the actual software or hardware component that the object represents. - class, will write changes that are made to the object's properties to the actual computer that the object represents. - - - -## Examples - The following example shows how to use this method (called on a object, which overrides the method from ) as part of the process of merging print tickets. - + class, will write changes that are made to the object's properties to the actual computer that the object represents. + + + +## Examples + The following example shows how to use this method (called on a object, which overrides the method from ) as part of the process of merging print tickets. + :::code language="csharp" source="~/snippets/csharp/System.Printing/PrintQueue/Commit/printticket.cs" id="Snippetusingmergeandvalidate"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PrintTicketManagment/visualbasic/printticket.vb" id="Snippetusingmergeandvalidate"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PrintTicketManagment/visualbasic/printticket.vb" id="Snippetusingmergeandvalidate"::: + ]]> @@ -215,14 +215,14 @@ Releases all resources used by the . - 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). - + 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. + ]]> @@ -270,20 +270,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `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. - + method, if it has been overridden. `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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -318,11 +318,11 @@ Releases the resources that are being used by 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. - + 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. + ]]> @@ -497,11 +497,11 @@ Gets the parent of the object. Another . - @@ -541,14 +541,14 @@ Gets a collection of attribute and value pairs. A that contains attribute and value pairs. - @@ -578,11 +578,11 @@ When overridden in a derived class, updates the properties of an object of the derived class so that its values match the values of the actual software or hardware component that the object represents. - 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 . - + 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 961e6723b09..4d34d4f31ff 100644 --- a/xml/System.Printing/PrintSystemObjectPropertiesChangedEventArgs.xml +++ b/xml/System.Printing/PrintSystemObjectPropertiesChangedEventArgs.xml @@ -26,15 +26,15 @@ Provides data for a PropertiesChanged event, which you must create. - [!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. + ]]> @@ -107,14 +107,14 @@ Releases all resources used by the object. - 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). - + 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 `Finalize` 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 `Finalize` method of the object. + ]]> @@ -156,20 +156,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources that are used by the object and optionally releases the managed resources. - 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. - + 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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that were previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding , be careful not to reference objects that were previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. diff --git a/xml/System.Printing/PrintSystemObjectPropertyChangedEventArgs.xml b/xml/System.Printing/PrintSystemObjectPropertyChangedEventArgs.xml index 19356022b7a..8c65b04b211 100644 --- a/xml/System.Printing/PrintSystemObjectPropertyChangedEventArgs.xml +++ b/xml/System.Printing/PrintSystemObjectPropertyChangedEventArgs.xml @@ -26,15 +26,15 @@ Provides data for a PropertyChanged event, which you must create. - [!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. + ]]> @@ -107,14 +107,14 @@ Releases all resources used by the . - 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). - + 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. + ]]> @@ -156,20 +156,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources that are used by the and optionally releases the managed resources. - 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. - + 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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that were previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding , be careful not to reference objects that were previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. diff --git a/xml/System.Printing/PrintSystemObjects.xml b/xml/System.Printing/PrintSystemObjects.xml index f8070906524..8fa6a832902 100644 --- a/xml/System.Printing/PrintSystemObjects.xml +++ b/xml/System.Printing/PrintSystemObjects.xml @@ -26,16 +26,16 @@ Represents a collection of print system objects. - , you may want to derive a collection of objects of that class from . - + , you may want to derive a collection of objects of that class from . + > [!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. + ]]> @@ -110,14 +110,14 @@ Releases all resources used by the . - 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). - + 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. + ]]> @@ -159,20 +159,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources that are used by the and optionally releases the managed resources. - 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. - + 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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. diff --git a/xml/System.Printing/PrintTicket.xml b/xml/System.Printing/PrintTicket.xml index 46ec3579b5a..e4aebdf1147 100644 --- a/xml/System.Printing/PrintTicket.xml +++ b/xml/System.Printing/PrintTicket.xml @@ -26,31 +26,31 @@ Defines the settings of a print job. - object is an easy-to-work-with representation of a certain type of XML document called a *PrintTicket document*. The latter is a set of instructions telling a printer how to set its various features (such as duplexing, collating, and stapling). For example, to instruct the printer to turn on its stapler and staple print jobs in the upper left corner, the document would have a `` element that specifies **StapleTopLeft**. The element is, in turn, represented by the property of the object. The PrintTicket document must conform to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397). - - The class enables your application to configure the printer's features without having to engage in any direct writing of XML objects. - - All of the most popular features of home and business file and photo printers are represented by properties of the class. But the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) defines many more, less common, features and it can be extended to handle features of specialty printing devices. So, although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. For more information see [How to: Extend the Print Schema and Create New Print System Classes](https://learn.microsoft.com/previous-versions/aa970573(v=vs.100)). - - **Note** When the object is created with the constructor that takes a PrintTicket document (as a ) parameter, that entire document is stored in a non-public field in the object, including the XML elements within it that express less common features that are not represented by any of the public properties of the class. In fact, if the driver that produced the PrintTicket document is using a private extension of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397), that privately defined markup is also stored as part of the non-public PrintTicket document. - + object is an easy-to-work-with representation of a certain type of XML document called a *PrintTicket document*. The latter is a set of instructions telling a printer how to set its various features (such as duplexing, collating, and stapling). For example, to instruct the printer to turn on its stapler and staple print jobs in the upper left corner, the document would have a `` element that specifies **StapleTopLeft**. The element is, in turn, represented by the property of the object. The PrintTicket document must conform to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397). + + The class enables your application to configure the printer's features without having to engage in any direct writing of XML objects. + + All of the most popular features of home and business file and photo printers are represented by properties of the class. But the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) defines many more, less common, features and it can be extended to handle features of specialty printing devices. So, although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. For more information see [How to: Extend the Print Schema and Create New Print System Classes](https://learn.microsoft.com/previous-versions/aa970573(v=vs.100)). + + **Note** When the object is created with the constructor that takes a PrintTicket document (as a ) parameter, that entire document is stored in a non-public field in the object, including the XML elements within it that express less common features that are not represented by any of the public properties of the class. In fact, if the driver that produced the PrintTicket document is using a private extension of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397), that privately defined markup is also stored as part of the non-public PrintTicket document. + > [!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 determine the capabilities of a specific printer and how to configure a print job to take advantage of them. - +> Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. + + If you want to print from a Windows Forms application, see the namespace. + + + +## Examples + The following example shows how to determine the capabilities of a specific printer and how to configure a print job to take advantage of them. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Wpf/XpsCreate/CPP/XpsCreate.cpp" id="Snippetprintercapabilities"::: :::code language="csharp" source="~/snippets/csharp/System.Printing/Collation/Overview/XpsCreate.cs" id="Snippetprintercapabilities"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/XpsCreate/visualbasic/xpscreate.vb" id="Snippetprintercapabilities"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/XpsCreate/visualbasic/xpscreate.vb" id="Snippetprintercapabilities"::: + ]]> @@ -85,14 +85,14 @@ Initializes a new instance of the class. - @@ -120,21 +120,21 @@ An XML stream that describes a print job and conforms to the Print Schema. - Initializes a new instance of the class by using an XML stream (that contains a PrintTicket document) that complies with the XML [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397). + Initializes a new instance of the class by using an XML stream (that contains a PrintTicket document) that complies with the XML Print Schema. - class. In fact, if the driver that produced the PrintTicket document is using a private extension of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397), that privately defined markup is also stored as part of the non-public PrintTicket document. - - The private parts of the document, if any, are not validated by the constructor, but all **Print Schema**-defined parts are validated, including the parts that are not represented by any of the public properties of the class. Accordingly, the could be thrown even if all of the XML markup that corresponds to the public properties is valid. - - 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. - + class. In fact, if the driver that produced the PrintTicket document is using a private extension of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397), that privately defined markup is also stored as part of the non-public PrintTicket document. + + The private parts of the document, if any, are not validated by the constructor, but all **Print Schema**-defined parts are validated, including the parts that are not represented by any of the public properties of the class. Accordingly, the could be thrown even if all of the XML markup that corresponds to the public properties is valid. + + 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. + ]]> @@ -197,24 +197,24 @@ Gets or sets a value indicating whether the printer collates its output. A value indicating whether the printer collates its output. - (see and ) will not contain any markup for this feature. - - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `DocumentCollate` keyword, not the `JobCollateAllDocuments` keyword. - - You can test for the options that the printer supports by using the property. - - - -## Examples - The following example shows how to use this property when testing a printer's capabilities and configuring a print job to take advantage of them. - + (see and ) will not contain any markup for this feature. + + This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `DocumentCollate` keyword, not the `JobCollateAllDocuments` keyword. + + You can test for the options that the printer supports by using the property. + + + +## Examples + The following example shows how to use this property when testing a printer's capabilities and configuring a print job to take advantage of them. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Wpf/XpsCreate/CPP/XpsCreate.cpp" id="Snippetprintercapabilities"::: :::code language="csharp" source="~/snippets/csharp/System.Printing/Collation/Overview/XpsCreate.cs" id="Snippetprintercapabilities"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/XpsCreate/visualbasic/xpscreate.vb" id="Snippetprintercapabilities"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/XpsCreate/visualbasic/xpscreate.vb" id="Snippetprintercapabilities"::: + ]]> Calling code has attempted to set the property to a value that is not in the enumeration. @@ -245,15 +245,15 @@ Gets or sets the number of copies for the print job. A nullable value that specifies how many copies to print. - (see and ) will not contain any markup for this feature. - - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `JobCopiesAllDocuments` keyword, not the `DocumentCopiesAllPages` keyword, or the `PageCopies` keyword. - - You can test for the printer's maximum by using the property. - + (see and ) will not contain any markup for this feature. + + This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `JobCopiesAllDocuments` keyword, not the `DocumentCopiesAllPages` keyword, or the `PageCopies` keyword. + + You can test for the printer's maximum by using the property. + ]]> Calling code has attempted to set the property to a value less than 1. @@ -284,15 +284,15 @@ Gets or sets a value indicating whether the printer substitutes device-based fonts for computer-based fonts on the print job. A value indicating whether the device substitutes device-based fonts for computer-based fonts for the current print job. - (see and ) will not contain any markup for this feature. - - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageDeviceFontSubstitution` keyword. - - You can test for the options that the printer supports by using the property. - + (see and ) will not contain any markup for this feature. + + This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageDeviceFontSubstitution` keyword. + + You can test for the options that the printer supports by using the property. + ]]> Calling code has attempted to set the property to a value that is not in the enumeration. @@ -323,23 +323,23 @@ Gets or sets a value indicating what kind of two-sided printing, if any, the printer uses for the print job. A value indicating what sort of two-sided printing, if any, the printer uses for the print job. - (see and ) will not contain any markup for this feature. - - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `JobDuplexAllDocumentsContiguously` keyword, not the `DocumentDuplex` keyword. - - You can test for the options that the printer supports by using the property. - - - -## Examples - The following example shows how to use this property while merging two print tickets. - + (see and ) will not contain any markup for this feature. + + This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `JobDuplexAllDocumentsContiguously` keyword, not the `DocumentDuplex` keyword. + + You can test for the options that the printer supports by using the property. + + + +## Examples + The following example shows how to use this property while merging two print tickets. + :::code language="csharp" source="~/snippets/csharp/System.Printing/PrintQueue/Commit/printticket.cs" id="Snippetusingmergeandvalidate"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PrintTicketManagment/visualbasic/printticket.vb" id="Snippetusingmergeandvalidate"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PrintTicketManagment/visualbasic/printticket.vb" id="Snippetusingmergeandvalidate"::: + ]]> Calling code has attempted to set the property to a value that is not in the enumeration. @@ -368,16 +368,16 @@ - Returns a object that represents the property values of a as an XML stream that conforms to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397). + Returns a object that represents the property values of a as an XML stream that conforms to the Print Schema. A object that describes the print ticket with XML that conforms to the Print Schema. - are `null`, they will simply not be included in the XML markup. - - If the object was constructed with a PrintTicket document that contains markup elements not represented by any of the class's public properties, those elements will be included in the PrintTicket document returned by this method. - + are `null`, they will simply not be included in the XML markup. + + If the object was constructed with a PrintTicket document that contains markup elements not represented by any of the class's public properties, those elements will be included in the PrintTicket document returned by this method. + ]]> Print Schema @@ -408,23 +408,23 @@ Gets or sets a value indicating what input bin (paper tray) to use. An value indicating what input tray is used and whether it is chosen manually or automatically. - (see and ) will not contain any markup for this feature. That is, there will be no markup for the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s features `JobInputBin`, `DocumentInputBin`, or `PageInputBin`. - - When this property is not `null`, it will have the following relationships to the features defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397). - -- If the XML form of the contains `JobInputBin`, then this property has the same value as `JobInputBin` (regardless of whether or not there is also `DocumentInputBin` or `PageInputBin`. markup in the XML version of the ). - -- If there is no `JobInputBin` markup, but there is `DocumentInputBin`, then this property has the same value as `DocumentInputBin` (regardless of whether or not there is also `PageInputBin` markup) present. - -- If there is neither `JobInputBin` nor `DocumentInputBin` markup, but there is `PageInputBin` markup, then this property has the same value as `PageInputBin`. - - When this property is set to any value, then matching `JobInputBin` markup will be added to the XML print ticket and any `DocumentInputBin` and `PageInputBin` markup that is already there will be removed. - - You can test for the options that the printer supports by using the property. - + (see and ) will not contain any markup for this feature. That is, there will be no markup for the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s features `JobInputBin`, `DocumentInputBin`, or `PageInputBin`. + + When this property is not `null`, it will have the following relationships to the features defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397). + +- If the XML form of the contains `JobInputBin`, then this property has the same value as `JobInputBin` (regardless of whether or not there is also `DocumentInputBin` or `PageInputBin`. markup in the XML version of the ). + +- If there is no `JobInputBin` markup, but there is `DocumentInputBin`, then this property has the same value as `DocumentInputBin` (regardless of whether or not there is also `PageInputBin` markup) present. + +- If there is neither `JobInputBin` nor `DocumentInputBin` markup, but there is `PageInputBin` markup, then this property has the same value as `PageInputBin`. + + When this property is set to any value, then matching `JobInputBin` markup will be added to the XML print ticket and any `DocumentInputBin` and `PageInputBin` markup that is already there will be removed. + + You can test for the options that the printer supports by using the property. + ]]> Calling code has attempted to set the property to a value that is not in the enumeration. @@ -455,23 +455,23 @@ Gets or sets a value indicating how the printer handles content that has color or shades of gray. An value indicating how the printer handles content that has color or shades of gray. - (see and ) will not contain any markup for this feature. - - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageOutputColor` keyword. - - You can test for the options that the printer supports by using the property. - - - -## Examples - The following example shows how to use this property to configure a print job. - + (see and ) will not contain any markup for this feature. + + This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageOutputColor` keyword. + + You can test for the options that the printer supports by using the property. + + + +## Examples + The following example shows how to use this property to configure a print job. + :::code language="csharp" source="~/snippets/csharp/System.Printing/LocalPrintServer/Overview/XpsPrintHelper.cs" id="Snippetoutputcolorandpageorientation"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/XpsPrint/visualbasic/xpsprinthelper.vb" id="Snippetoutputcolorandpageorientation"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/XpsPrint/visualbasic/xpsprinthelper.vb" id="Snippetoutputcolorandpageorientation"::: + ]]> Calling code has attempted to set the property to a value that is not in the enumeration. @@ -502,15 +502,15 @@ Gets or sets a value indicating the quality of output for the print job. An value that specifies the needed level of quality. - (see and ) will not contain any markup for this feature. - - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageOutputQuality` keyword. - - You can test for the options that the printer supports by using the property. - + (see and ) will not contain any markup for this feature. + + This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageOutputQuality` keyword. + + You can test for the options that the printer supports by using the property. + ]]> Calling code has attempted to set the property to a value that is not in the enumeration. @@ -541,15 +541,15 @@ Gets or sets a value indicating whether the device prints content to the edge of the media or leaves an unprinted margin around the edge. A value that specifies whether the printer uses borderless printing. - (see and ) will not contain any markup for this feature. - - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageBorderless` keyword. - - You can test for the options that the printer supports by using the property. - + (see and ) will not contain any markup for this feature. + + This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageBorderless` keyword. + + You can test for the options that the printer supports by using the property. + ]]> Calling code has attempted to set the property to a value that is not in the enumeration. @@ -580,31 +580,31 @@ Gets or sets the page size for the paper (or other media) that a printer uses for a print job. A object that represents the page size by using a name, dimensions, or both. - property. - - - -## Examples - The following example shows how to use this property to scale a visual element to fit within the margins of the paper on which it is to print. - + property. + + + +## Examples + The following example shows how to use this property 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/VS_Snippets_Wpf/XpsPrint/visualbasic/xpsprinthelper.vb" id="Snippetpagemediasize"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/XpsPrint/visualbasic/xpsprinthelper.vb" id="Snippetpagemediasize"::: + ]]> - Calling code has attempted to set the property with a object that has at least one property. - + Calling code has attempted to set the property with a object that has at least one property. + -or- - - Calling code has attempted to set the property with a object whose property is set to a value that is not in the enumeration. - + + Calling code has attempted to set the property with a object whose property is set to a value that is not in the enumeration. + -or- - + Calling code has attempted to set the property with a object whose or property is set to a value less than 1. @@ -633,15 +633,15 @@ Gets or sets a value indicating what sort of paper or media the printer uses for the print job. A value specifying the print media, such as card stock, label, plain, or photographic. - (see and ) will not contain any markup for this feature. - - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageMediaType` keyword. - - You can test for the options that the printer supports by using the property. - + (see and ) will not contain any markup for this feature. + + This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageMediaType` keyword. + + You can test for the options that the printer supports by using the property. + ]]> Calling code has attempted to set the property to a value that is not in the enumeration. @@ -672,15 +672,15 @@ Gets or sets a value indicating whether the printer prints multiple pages back-to-front or front-to-back. A value specifying last-page-first printing or first-page-first printing. - (see and ) will not contain any markup for this feature. - - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `JobPageOrder` keyword. - - You can test for the options that the printer supports by using the property. - + (see and ) will not contain any markup for this feature. + + This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `JobPageOrder` keyword. + + You can test for the options that the printer supports by using the property. + ]]> Calling code has attempted to set the property to a value that is not in the enumeration. @@ -711,23 +711,23 @@ Gets or sets a value indicating how the page content is oriented for printing. A value specifying how page content is oriented, for example, or . - (see and ) will not contain any markup for this feature. - - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageOrientation` keyword. - - You can test for the options that the printer supports by using the property. - - - -## Examples - The following example shows how to use this property to configure a print job. - + (see and ) will not contain any markup for this feature. + + This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageOrientation` keyword. + + You can test for the options that the printer supports by using the property. + + + +## Examples + The following example shows how to use this property to configure a print job. + :::code language="csharp" source="~/snippets/csharp/System.Printing/LocalPrintServer/Overview/XpsPrintHelper.cs" id="Snippetoutputcolorandpageorientation"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/XpsPrint/visualbasic/xpsprinthelper.vb" id="Snippetoutputcolorandpageorientation"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/XpsPrint/visualbasic/xpsprinthelper.vb" id="Snippetoutputcolorandpageorientation"::: + ]]> Calling code has attempted to set the property to a value that is not in the enumeration. @@ -758,25 +758,25 @@ Gets or sets the level of page resolution that the printer uses for a print job. A value that represents the resolution as a qualitative value, a dots-per-inch value, or both. - class has properties in which you can specify the dots-per-inch for the X and Y dimensions and a property where you can give a qualitative expression to the resolution. - - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageResolution` keyword. - - You can test for the options that the printer supports by using the property. - + class has properties in which you can specify the dots-per-inch for the X and Y dimensions and a property where you can give a qualitative expression to the resolution. + + This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageResolution` keyword. + + You can test for the options that the printer supports by using the property. + ]]> - Calling code has attempted to set the property with a object that has at least one property. - + Calling code has attempted to set the property with a object that has at least one property. + -or- - - Calling code has attempted to set the property with a object whose property is set to a value that is not in the enumeration. - + + Calling code has attempted to set the property with a object whose property is set to a value that is not in the enumeration. + -or- - + Calling code has attempted to set the property with a object whose or property is set to a value less than 1. @@ -806,29 +806,29 @@ Gets or sets the percentage by which the printer enlarges or reduces the print image on a page. An value that represents a percentage. - . - - A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. - - This property generally represents the **Scale** `ScoredProperty` of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageScaling` keyword. But there are some complexities as follows. - - When reading the property, the property behaves as follows. - -- If the PrintTicket XML document has the `PageScaling` feature set to the **CustomSquare** option, and the **CustomSquare** option's **Scale** value is positive value, then that is the value that is returned. - -- If the PrintTicket XML document has the `PageScaling` feature set to the **Custom** option, and the **Custom** option's **ScaleWidth** value is positive value, then that is the value that is returned. - -- In all other cases, `null` is returned. - - When setting the property, the property behaves as follows. - -- If it's set to `null`, then the `PageScaling` markup is removed from the PrintTicket XML document. - -- Otherwise, the `PageScaling` feature in the PrintTicket XML document is set to **CustomSquare** and the **CustomSquare** option's **Scale** value is set to the passed value. (See **Exceptions** for what happens if the property is set to a value less than 1.) - + . + + A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. + + This property generally represents the **Scale** `ScoredProperty` of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageScaling` keyword. But there are some complexities as follows. + + When reading the property, the property behaves as follows. + +- If the PrintTicket XML document has the `PageScaling` feature set to the **CustomSquare** option, and the **CustomSquare** option's **Scale** value is positive value, then that is the value that is returned. + +- If the PrintTicket XML document has the `PageScaling` feature set to the **Custom** option, and the **Custom** option's **ScaleWidth** value is positive value, then that is the value that is returned. + +- In all other cases, `null` is returned. + + When setting the property, the property behaves as follows. + +- If it's set to `null`, then the `PageScaling` markup is removed from the PrintTicket XML document. + +- Otherwise, the `PageScaling` feature in the PrintTicket XML document is set to **CustomSquare** and the **CustomSquare** option's **Scale** value is set to the passed value. (See **Exceptions** for what happens if the property is set to a value less than 1.) + ]]> Calling code has attempted to set the property to a value that is less than 1. @@ -859,17 +859,17 @@ Gets or sets the number of pages that print on each printed side of a sheet of paper. A nullable value that represents the number of pages that print on each printed side of a sheet of paper. - 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. - - This property corresponds to the **PagesPerSheet**`ScoredProperty` of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `JobNUpAllDocumentsContiguously` keyword, not the `DocumentNUp` keyword. - - You can test for the options that the printer supports by using the property. - + 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. + + This property corresponds to the **PagesPerSheet**`ScoredProperty` of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `JobNUpAllDocumentsContiguously` keyword, not the `DocumentNUp` keyword. + + You can test for the options that the printer supports by using the property. + ]]> Calling code has attempted to set the property to a value that is less than 1. @@ -900,17 +900,17 @@ Gets or sets a value indicating how a printer arranges multiple pages that print on each side of a sheet of paper. A value indicating how a printer presents multiple pages per sheet. - (see and ) will not contain any markup for this feature. - - This property corresponds to the **PresentationDirection** subfeature of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `JobNUpAllDocumentsContiguously` keyword, not the `DocumentNUp` keyword. - - You can test for the options that the printer supports by using the property. - + (see and ) will not contain any markup for this feature. + + This property corresponds to the **PresentationDirection** subfeature of the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `JobNUpAllDocumentsContiguously` keyword, not the `DocumentNUp` keyword. + + You can test for the options that the printer supports by using the property. + ]]> Calling code has attempted to set the property to a value that is not in the enumeration. @@ -941,17 +941,17 @@ Gets or sets a value indicating in qualitative terms the level of quality the printer uses to print a photograph. A value indicating the level of photo quality. - (see and ) will not contain any markup for this feature. - - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PagePhotoPrintingIntent` keyword. - - You can test for the options that the printer supports by using the property. - + (see and ) will not contain any markup for this feature. + + This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PagePhotoPrintingIntent` keyword. + + You can test for the options that the printer supports by using the property. + ]]> Calling code has attempted to set the property to a value that is not in the enumeration. @@ -1013,17 +1013,17 @@ The that holds the saved . - Saves the settings to a object by using an XML format that conforms to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397). + Saves the settings to a object by using an XML format that conforms to the Print Schema. - are `null`, they will simply not be included in the XML markup. - - If the object was constructed with a PrintTicket document that contains markup elements not represented by any of the class's public properties, those elements will be included in the PrintTicket document saved by this method. - + are `null`, they will simply not be included in the XML markup. + + If the object was constructed with a PrintTicket document that contains markup elements not represented by any of the class's public properties, those elements will be included in the PrintTicket document saved by this method. + ]]> Print Schema @@ -1054,26 +1054,26 @@ Gets or sets a value indicating whether, and where, a printer staples multiple pages. A value specifying how a printer staples the output. - (see and ) will not contain any markup for this feature. - - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `JobStapleAllDocuments` keyword, not the `DocumentStaple` keyword. - - You can test for the options that the printer supports by using the property. - - - -## Examples - The following example shows how to use this property when testing a printer's capabilities and configuring a print job to take advantage of them. - + (see and ) will not contain any markup for this feature. + + This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `JobStapleAllDocuments` keyword, not the `DocumentStaple` keyword. + + You can test for the options that the printer supports by using the property. + + + +## Examples + The following example shows how to use this property when testing a printer's capabilities and configuring a print job to take advantage of them. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Wpf/XpsCreate/CPP/XpsCreate.cpp" id="Snippetprintercapabilities"::: :::code language="csharp" source="~/snippets/csharp/System.Printing/Collation/Overview/XpsCreate.cs" id="Snippetprintercapabilities"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/XpsCreate/visualbasic/xpscreate.vb" id="Snippetprintercapabilities"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/XpsCreate/visualbasic/xpscreate.vb" id="Snippetprintercapabilities"::: + ]]> Calling code has attempted to set the property to a value that is not in the enumeration. @@ -1104,15 +1104,15 @@ Gets or sets a value indicating how the printer handles text that uses TrueType fonts. A value specifying how a printer handles TrueType fonts. - (see and ) will not contain any markup for this feature. - - This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageTrueTypeFontMode` keyword. - - You can test for the options that the printer supports by using the property. - + (see and ) will not contain any markup for this feature. + + This property corresponds to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageTrueTypeFontMode` keyword. + + You can test for the options that the printer supports by using the property. + ]]> Calling code has attempted to set the property to a value that is not in the enumeration. diff --git a/xml/System.Reflection/MemberInfo.xml b/xml/System.Reflection/MemberInfo.xml index 8c2e6597a55..b668bb26979 100644 --- a/xml/System.Reflection/MemberInfo.xml +++ b/xml/System.Reflection/MemberInfo.xml @@ -438,7 +438,7 @@ ]]> - This member belongs to a type that is loaded into the reflection-only context. See [How to: Load Assemblies into the Reflection-Only Context](/dotnet/framework/reflection-and-codedom/how-to-load-assemblies-into-the-reflection-only-context). + This member belongs to a type that is loaded into the reflection-only context. See How to: Load Assemblies into the Reflection-Only Context. A custom attribute type could not be loaded. @@ -516,7 +516,7 @@ A custom attribute type cannot be loaded. If is . - This member belongs to a type that is loaded into the reflection-only context. See [How to: Load Assemblies into the Reflection-Only Context](/dotnet/framework/reflection-and-codedom/how-to-load-assemblies-into-the-reflection-only-context). + This member belongs to a type that is loaded into the reflection-only context. See How to: Load Assemblies into the Reflection-Only Context. diff --git a/xml/System.Reflection/MethodImportAttributes.xml b/xml/System.Reflection/MethodImportAttributes.xml index 8a482d69e14..9c8449b770e 100644 --- a/xml/System.Reflection/MethodImportAttributes.xml +++ b/xml/System.Reflection/MethodImportAttributes.xml @@ -32,23 +32,23 @@ Specifies flags for the unmanaged method import attributes. - structure. +## Remarks + +Method import attributes are used with the structure. To check whether a value of this enumeration has the specific flag, combine that value with the corresponding mask constant using the bitwise AND operation (`&` in C#) and compare its result with the constant of the flag you need to check. For example, to check for CDecl calling convention, use a code like this: ```csharp -if((attributes & MethodImportAttributes.CallingConventionMask) == MethodImportAttributes.CallingConventionCDecl) +if((attributes & MethodImportAttributes.CallingConventionMask) == MethodImportAttributes.CallingConventionCDecl) { // The calling convention is CDecl } ``` For more information about the unmanaged method import and the meaning of these attributes, see . - + ]]> @@ -311,7 +311,7 @@ For more information about the unmanaged method import and the meaning of these 256 - Specifies that [the default platform calling convention](/dotnet/standard/native-interop/calling-conventions#platform-default-calling-convention) is used. + Specifies that the default platform calling convention is used. @@ -369,7 +369,7 @@ For more information about the unmanaged method import and the meaning of these 6 - Specifies that the character set is chosen automatically. See [Charsets and marshaling](/dotnet/standard/native-interop/charset) for details. + Specifies that the character set is chosen automatically. See Charsets and marshaling for details. diff --git a/xml/System.Resources/NeutralResourcesLanguageAttribute.xml b/xml/System.Resources/NeutralResourcesLanguageAttribute.xml index 6200ccb3c4c..5a722acc3c7 100644 --- a/xml/System.Resources/NeutralResourcesLanguageAttribute.xml +++ b/xml/System.Resources/NeutralResourcesLanguageAttribute.xml @@ -293,7 +293,7 @@ For a detailed list of culture names available on Windows systems, see the **Lan System.Resources.UltimateResourceFallbackLocation - Gets the location for the class to use to retrieve neutral resources by using the [resource fallback process](/dotnet/framework/resources/packaging-and-deploying-resources-in-desktop-apps). + Gets the location for the class to use to retrieve neutral resources by using the resource fallback process. One of the enumeration values that indicates the location (main assembly or satellite) from which to retrieve neutral resources. To be added. diff --git a/xml/System.Resources/ResXResourceReader.xml b/xml/System.Resources/ResXResourceReader.xml index 62d80b3fba6..a41fd29dd03 100644 --- a/xml/System.Resources/ResXResourceReader.xml +++ b/xml/System.Resources/ResXResourceReader.xml @@ -46,49 +46,49 @@ Enumerates XML resource (.resx) files and streams, and reads the sequential resource name and value pairs. - class provides a default implementation of the interface that reads resource information in an XML format. To read resource information from a binary resource format, use the class. - - You use the class to enumerate resources in .resx files by traversing the dictionary enumerator () that is returned by the method. You call the methods provided by to advance to the next resource and to read the name and value of each resource in the .resx file. - + The class provides a default implementation of the interface that reads resource information in an XML format. To read resource information from a binary resource format, use the class. + + You use the class to enumerate resources in .resx files by traversing the dictionary enumerator () that is returned by the method. You call the methods provided by to advance to the next resource and to read the name and value of each resource in the .resx file. + > [!NOTE] -> The class provides two enumerators. The method returns an object; we recommend that you use this method to enumerate resources. The method is an explicit interface implementation that returns an object; we do not recommend its use. - - The following example uses the method to obtain an object that is used to enumerate the resources in a .resx file. The example includes a `CreateResourceFile` routine that creates the necessary resource file. - +> The class provides two enumerators. The method returns an object; we recommend that you use this method to enumerate resources. The method is an explicit interface implementation that returns an object; we do not recommend its use. + + The following example uses the method to obtain an object that is used to enumerate the resources in a .resx file. The example includes a `CreateResourceFile` routine that creates the necessary resource file. + :::code language="csharp" source="~/snippets/csharp/System.Resources/ResXResourceReader/Overview/resxresourcereader1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resxresourcereader.class/vb/resxresourcereader1.vb" id="Snippet1"::: - - If the property is `true`, the value of the property is a object rather than the resource value. This makes a resource item's comment available from the property. The following example sets the property to `true` and enumerates the resources in a .resx file, - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resxresourcereader.class/vb/resxresourcereader1.vb" id="Snippet1"::: + + If the property is `true`, the value of the property is a object rather than the resource value. This makes a resource item's comment available from the property. The following example sets the property to `true` and enumerates the resources in a .resx file, + :::code language="csharp" source="~/snippets/csharp/System.Resources/ResXResourceReader/Overview/resxresourcereader2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resxresourcereader.class/vb/resxresourcereader2.vb" id="Snippet2"::: - - If is `true`, the items in the enumeration can be either: - -- Named resources along with their data. In this case, the property is `null`. - -- Named resources along with the name of the file that contains the resource data. In this case, the property returns a object that provides information about the resource, including its filename. If relative file names are used, you should always set the property to provide a reference point for the relative file path. - - If you want to retrieve named resources from a .resx file rather than enumerating its resources, you can instantiate a object and call its `GetString` and `GetObject` methods. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resxresourcereader.class/vb/resxresourcereader2.vb" id="Snippet2"::: + + If is `true`, the items in the enumeration can be either: + +- Named resources along with their data. In this case, the property is `null`. + +- Named resources along with the name of the file that contains the resource data. In this case, the property returns a object that provides information about the resource, including its filename. If relative file names are used, you should always set the property to provide a reference point for the relative file path. + + If you want to retrieve named resources from a .resx file rather than enumerating its resources, you can instantiate a object and call its `GetString` and `GetObject` methods. + > [!NOTE] -> The class contains a link demand and an inheritance demand at the class level that applies to all members. A exception is thrown when either the immediate caller or the derived class does not have full-trust permission. - - - -## Examples - The following example demonstrates how to use a to iterate through the resources in a .resx file. First, the `rsxr` is created for the file `items.resx`. Next, the method is used to create an to iterate through the resources and display the contents to the console. - +> The class contains a link demand and an inheritance demand at the class level that applies to all members. A exception is thrown when either the immediate caller or the derived class does not have full-trust permission. + + + +## Examples + The following example demonstrates how to use a to iterate through the resources in a .resx file. First, the `rsxr` is created for the file `items.resx`. Next, the method is used to create an to iterate through the resources and display the contents to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Resources.ResXResourceReader Example/CPP/resxresourcereader.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Resources/ResXResourceReader/Overview/resxresourcereader.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Resources.ResXResourceReader Example/VB/resxresourcereader.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Resources.ResXResourceReader Example/VB/resxresourcereader.vb" id="Snippet1"::: + ]]> @@ -137,13 +137,13 @@ An input stream that contains resources. Initializes a new instance of the class for the specified stream. - [!NOTE] -> The and methods do not close the stream you specify in this constructor. - +> The and methods do not close the stream you specify in this constructor. + ]]> @@ -214,15 +214,15 @@ The path of the resource file to read. Initializes a new instance of the class for the specified resource file. - class for the specified file, iterates through the resources of the file, and displays the contents to the console. - + class for the specified file, iterates through the resources of the file, and displays the contents to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Resources.ResXResourceReader Example/CPP/resxresourcereader.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Resources/ResXResourceReader/Overview/resxresourcereader.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Resources.ResXResourceReader Example/VB/resxresourcereader.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Resources.ResXResourceReader Example/VB/resxresourcereader.vb" id="Snippet1"::: + ]]> @@ -492,21 +492,21 @@ Gets or sets the base path for the relative file path specified in a object. A path that, if prepended to the relative file path specified in a object, yields an absolute path to a resource file. - property is used to resolve relative file path references that are assigned to the property of objects. By default, its value is , and relative file path references are resolved in relationship to the current directory returned by the property. You should set this property before you begin enumerating resources. - - - -## Examples - The following example creates an XML resource file that contains images of dog breeds, and also creates a string resource that specifies the application that created the resource. objects are used to store the path to the images rather than storing the binary images themselves in the resource file. The example sets the property so that the relative file paths in the images' file names are interpreted as subdirectories of a directory named C:\data\\. - + property is used to resolve relative file path references that are assigned to the property of objects. By default, its value is , and relative file path references are resolved in relationship to the current directory returned by the property. You should set this property before you begin enumerating resources. + + + +## Examples + The following example creates an XML resource file that contains images of dog breeds, and also creates a string resource that specifies the application that created the resource. objects are used to store the path to the images rather than storing the binary images themselves in the resource file. The example sets the property so that the relative file paths in the images' file names are interpreted as subdirectories of a directory named C:\data\\. + :::code language="csharp" source="~/snippets/csharp/System.Resources/ResXResourceReader/BasePath/basepathex1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resxresourcereader.basepath/vb/basepathex1.vb" id="Snippet1"::: - - Note that you must add a reference to System.Drawing.dll to compile the project successfully. The example also requires that the necessary images exist in a directory named C:\data\images\\. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resxresourcereader.basepath/vb/basepathex1.vb" id="Snippet1"::: + + Note that you must add a reference to System.Drawing.dll to compile the project successfully. The example also requires that the necessary images exist in a directory named C:\data\images\\. + ]]> In a set operation, a value cannot be specified because the XML resource file has already been accessed and is in use. @@ -542,20 +542,20 @@ Releases all resources used by the . - enables the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - - - -## Examples - The following example displays the resources of a file to the console, and then uses the method to shut down the reader and to make its resources available for other processes. - + enables the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + + + +## Examples + The following example displays the resources of a file to the console, and then uses the method to shut down the reader and to make its resources available for other processes. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Resources.ResXResourceReader Example/CPP/resxresourcereader.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Resources/ResXResourceReader/Overview/resxresourcereader.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Resources.ResXResourceReader Example/VB/resxresourcereader.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Resources.ResXResourceReader Example/VB/resxresourcereader.vb" id="Snippet1"::: + ]]> @@ -590,18 +590,18 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method or the method. invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + method or the method. invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement and about the disposable pattern, see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose), , and . + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement and about the disposable pattern, see Implementing a Dispose Method, , and . @@ -785,19 +785,19 @@ Returns an enumerator for the current object. An enumerator for the current object. - method retrieves the name/value pairs in the XML resource (.resx) stream or string associated with the current object. However, if the property is set to `true` before you call , the resource items are retrieved as objects. In this case, all resource nodes are returned regardless of type. - - - -## Examples - The following example uses the method to obtain an object that is used to enumerate the resources in a .resx file. The example includes a `CreateResourceFile` routine that creates the necessary resource file. - + method retrieves the name/value pairs in the XML resource (.resx) stream or string associated with the current object. However, if the property is set to `true` before you call , the resource items are retrieved as objects. In this case, all resource nodes are returned regardless of type. + + + +## Examples + The following example uses the method to obtain an object that is used to enumerate the resources in a .resx file. The example includes a `CreateResourceFile` routine that creates the necessary resource file. + :::code language="csharp" source="~/snippets/csharp/System.Resources/ResXResourceReader/Overview/resxresourcereader1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resxresourcereader.class/vb/resxresourcereader1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resxresourcereader.class/vb/resxresourcereader1.vb" id="Snippet1"::: + ]]> @@ -828,20 +828,20 @@ Provides a dictionary enumerator that can retrieve the design-time properties from the current XML resource file or stream. An enumerator for the metadata in a resource. - method provides an object that can retrieve the metadata from the resource file or stream associated with the current object. However, if the property is set to `true` before you call , no resource nodes are retrieved. - - - -## Examples - The following example uses the method to iterate through the metadata resources in an XML resource file. This code example is part of a larger example provided for the property. - + method provides an object that can retrieve the metadata from the resource file or stream associated with the current object. However, if the property is set to `true` before you call , no resource nodes are retrieved. + + + +## Examples + The following example uses the method to iterate through the metadata resources in an XML resource file. This code example is part of a larger example provided for the property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Resources.ResXResourceReader Example/CPP/useresxdatanodes.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Resources/ResXResourceReader/Overview/useresxdatanodes.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Resources.ResXResourceReader Example/VB/useresxdatanodes.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Resources.ResXResourceReader Example/VB/useresxdatanodes.vb" id="Snippet4"::: + ]]> @@ -882,11 +882,11 @@ Returns an enumerator for the current object. For a description of this member, see the method. An enumerator that can iterate through the name/value pairs in the XML resource (.resx) stream or string associated with the current object. - instance is cast to an interface. To enumerate the resources in a .resx file, we recommend that you call the method, and then call the `MoveNext` method on the returned object. - + instance is cast to an interface. To enumerate the resources in a .resx file, we recommend that you call the method, and then call the `MoveNext` method on the returned object. + ]]> @@ -920,11 +920,11 @@ Releases the unmanaged resources used by the and optionally releases the managed resources. For a description of this member, see the method. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -962,50 +962,50 @@ if resource data nodes are retrieved; if resource data nodes are ignored. - property before you begin enumerating resources. By default, its value is `false`. - - - -## Examples - The following example enumerates and displays resource items in an XML file. Initially, is set to `false` to show both data and metadata items as they occur in the resource file. The second enumeration has the set to `true` so that resource data elements are returned as objects. - + property before you begin enumerating resources. By default, its value is `false`. + + + +## Examples + The following example enumerates and displays resource items in an XML file. Initially, is set to `false` to show both data and metadata items as they occur in the resource file. The second enumeration has the set to `true` so that resource data elements are returned as objects. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Resources.ResXResourceReader Example/CPP/useresxdatanodes.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Resources/ResXResourceReader/Overview/useresxdatanodes.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Resources.ResXResourceReader Example/VB/useresxdatanodes.vb" id="Snippet2"::: - - The resource XML file used by the example contains one data node and one metadata node. To use the XML file with the previous example, copy the following text and save it to a file named Resource1.resx. - -``` - - - - text/microsoft-resx - - - 2.0 - - - System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, - Culture=neutral, PublicKeyToken=b77a5c561934e089 - - - - System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, - Culture=neutral, PublicKeyToken=b77a5c561934e089 - - - - Sample DATA value - - - Sample METADATA value - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Resources.ResXResourceReader Example/VB/useresxdatanodes.vb" id="Snippet2"::: + + The resource XML file used by the example contains one data node and one metadata node. To use the XML file with the previous example, copy the following text and save it to a file named Resource1.resx. + +``` + + + + text/microsoft-resx + + + 2.0 + + + System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, + Culture=neutral, PublicKeyToken=b77a5c561934e089 + + + + System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, + Culture=neutral, PublicKeyToken=b77a5c561934e089 + + + + Sample DATA value + + + Sample METADATA value + + +``` + ]]> In a set operation, the enumerator for the resource file or stream is already open. diff --git a/xml/System.Resources/ResXResourceWriter.xml b/xml/System.Resources/ResXResourceWriter.xml index 21712a336d7..f34ae7c45c7 100644 --- a/xml/System.Resources/ResXResourceWriter.xml +++ b/xml/System.Resources/ResXResourceWriter.xml @@ -43,30 +43,30 @@ Writes resources in an XML resource (.resx) file or an output stream. - writes resources in XML format. To write a binary resource file, use . - - Resources are specified as name/value pairs using the method. Resource names are case-sensitive when used for lookups; but to more easily support authoring tools and help eliminate bugs, does not allow a.resx file to have names that vary only by case. - - To create a.resx file, create a with a unique file name, call at least once, call to write the resources file to disk, and then call to close the file. Calling will implicitly the file if required. - - The resources are not necessarily written in the same order they were added. - - For more information on the format of a.resx file, see [Working with .resx Files Programmatically](/dotnet/framework/resources/working-with-resx-files-programmatically). - + writes resources in XML format. To write a binary resource file, use . + + Resources are specified as name/value pairs using the method. Resource names are case-sensitive when used for lookups; but to more easily support authoring tools and help eliminate bugs, does not allow a.resx file to have names that vary only by case. + + To create a.resx file, create a with a unique file name, call at least once, call to write the resources file to disk, and then call to close the file. Calling will implicitly the file if required. + + The resources are not necessarily written in the same order they were added. + + For more information on the format of a.resx file, see [Working with .resx Files Programmatically](/dotnet/framework/resources/working-with-resx-files-programmatically). + > [!NOTE] -> This class contains a link demand and an inheritance demand at the class level that applies to all members. A is thrown when either the immediate caller or the derived class does not have full-trust permission. - - - -## Examples - The following example creates a .resx file named `CarResources.resx` that stores six strings, an icon, and two application-defined objects (two `Automobile` objects). Note that the `Automobile` class, which is defined and instantiated in the example, is tagged with the attribute. - +> This class contains a link demand and an inheritance demand at the class level that applies to all members. A is thrown when either the immediate caller or the derived class does not have full-trust permission. + + + +## Examples + The following example creates a .resx file named `CarResources.resx` that stores six strings, an icon, and two application-defined objects (two `Automobile` objects). Note that the `Automobile` class, which is defined and instantiated in the example, is tagged with the attribute. + :::code language="csharp" source="~/snippets/csharp/System.Resources/ResXResourceWriter/Overview/create1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.resx/vb/create1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.resx/vb/create1.vb" id="Snippet1"::: + ]]> Working with .resx Files Programmatically @@ -107,13 +107,13 @@ The output stream. Initializes a new instance of the class that writes the resources to the specified stream object. - [!NOTE] -> The method closes the stream you specify as a parameter. To write the resource to the stream without closing the stream, you must use the method. - +> The method closes the stream you specify as a parameter. To write the resource to the stream without closing the stream, you must use the method. + ]]> @@ -172,11 +172,11 @@ The output file name. Initializes a new instance of the class that writes the resources to the specified file. - exception. - + exception. + ]]> The directory specified in does not exist. @@ -216,11 +216,11 @@ The delegate that is used to target earlier versions of the .NET Framework. Initializes a new instance of the class that writes the resources to a specified stream object and sets a converter delegate. This delegate enables resource assemblies to be written that target versions of the .NET Framework before .NET Framework 4 by using qualified assembly names. - @@ -259,11 +259,11 @@ The delegate that is used to target earlier versions of the .NET Framework. Initializes a new instance of the class that writes the resources to a specified object and sets a delegate that enables resource assemblies to be written that target versions of the .NET Framework before .NET Framework 4 by using qualified assembly names. - @@ -302,11 +302,11 @@ The delegate that is used to target earlier versions of the .NET Framework. Initializes a new instance of the class that writes the resources to a specified file and sets a delegate that enables resource assemblies to be written that target versions of the .NET Framework before .NET Framework 4 by using qualified assembly names. - The directory specified in does not exist. @@ -350,11 +350,11 @@ The name of the assembly represented by . Adds the specified alias to a list of aliases. - is called. - + is called. + ]]> @@ -590,13 +590,13 @@ The value of the resource to add as an 8-bit unsigned integer array. Adds a named resource specified as a byte array to the list of resources to write. - is called. - - The resource is serialized and stored in a binary format. - + is called. + + The resource is serialized and stored in a binary format. + ]]> @@ -643,21 +643,21 @@ The value of the resource. Adds a named resource specified as an object to the list of resources to write. - is called. The resource that was added must be serializable. - - If the resource being added is a string, it is written as a string; otherwise, the resource is serialized and stored in a binary format. - - - -## Examples - The following example creates a .resx file named `CarResources.resx` that stores six strings, an icon, and two application-defined objects (two `Automobile` objects). To store the icon and the `Automobile` objects, it calls the method. Note that the `Automobile` class, which is defined and instantiated in the example, is tagged with the attribute. - + is called. The resource that was added must be serializable. + + If the resource being added is a string, it is written as a string; otherwise, the resource is serialized and stored in a binary format. + + + +## Examples + The following example creates a .resx file named `CarResources.resx` that stores six strings, an icon, and two application-defined objects (two `Automobile` objects). To store the icon and the `Automobile` objects, it calls the method. Note that the `Automobile` class, which is defined and instantiated in the example, is tagged with the attribute. + :::code language="csharp" source="~/snippets/csharp/System.Resources/ResXResourceWriter/Overview/create1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.resx/vb/create1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.resx/vb/create1.vb" id="Snippet1"::: + ]]> @@ -710,21 +710,21 @@ The value of the resource. Adds a string resource to the resources. - is called. - - - -## Examples - The following example creates a .resx file named `CarResources.resx` that stores six strings, an icon, and two application-defined objects (two `Automobile` objects). To store the strings, it calls the method. - + is called. + + + +## Examples + The following example creates a .resx file named `CarResources.resx` that stores six strings, an icon, and two application-defined objects (two `Automobile` objects). To store the strings, it calls the method. + :::code language="csharp" source="~/snippets/csharp/System.Resources/ResXResourceWriter/Overview/create1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.resx/vb/create1.vb" id="Snippet1"::: - - Note that the `Automobile` class, which is defined and instantiated in the example, is tagged with the attribute. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.resx/vb/create1.vb" id="Snippet1"::: + + Note that the `Automobile` class, which is defined and instantiated in the example, is tagged with the attribute. + ]]> @@ -868,11 +868,11 @@ Releases all resources used by the . - . - + . + ]]> @@ -942,13 +942,13 @@ Releases all resources used by the . - method calls the method, if necessary, before releasing managed and unmanaged system resources. - - Calling allows the system resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - + method calls the method, if necessary, before releasing managed and unmanaged system resources. + + Calling allows the system resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + ]]> @@ -983,21 +983,21 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method calls the method, if necessary, before releasing managed and unmanaged system resources. - - This method is called by the public method and the method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + method calls the method, if necessary, before releasing managed and unmanaged system resources. + + This method is called by the public method and the method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + For more information about and , see and . @@ -1059,13 +1059,13 @@ Writes all resources added by the method to the output file or stream. - method writes the resources to the output file or stream. If you want to write the resources as well as close the output file or stream, call the method. - - The method can be called only once. After calling the method, all methods other than will throw an exception. - + method writes the resources to the output file or stream. If you want to write the resources as well as close the output file or stream, call the method. + + The method can be called only once. After calling the method, all methods other than will throw an exception. + ]]> The resource has already been saved. @@ -1123,11 +1123,11 @@ Specifies the schema to use in writing the XML file. This field is read-only. - diff --git a/xml/System.Runtime.CompilerServices/AsyncStateMachineAttribute.xml b/xml/System.Runtime.CompilerServices/AsyncStateMachineAttribute.xml index 28b6bede0de..e158249d3b2 100644 --- a/xml/System.Runtime.CompilerServices/AsyncStateMachineAttribute.xml +++ b/xml/System.Runtime.CompilerServices/AsyncStateMachineAttribute.xml @@ -55,31 +55,31 @@ - Indicates whether a method is marked with either the Async or [async](/dotnet/csharp/language-reference/keywords/async) modifier. + Indicates whether a method is marked with either the Async or async modifier. - object for the method name by using . - -- Obtains a object for the attribute by using [GetType Operator](/dotnet/visual-basic/language-reference/operators/gettype-operator) or [typeof](/dotnet/csharp/language-reference/keywords/typeof). - -- Obtains an attribute object for the method and attribute type by using `MethodInfo.GetCustomAttribute`. If `GetCustomAttribute` returns `Nothing` (Visual Basic) or `null` (C#), the method doesn't contain the attribute. - + object for the method name by using . + +- Obtains a object for the attribute by using [GetType Operator](/dotnet/visual-basic/language-reference/operators/gettype-operator) or [typeof](/dotnet/csharp/language-reference/keywords/typeof). + +- Obtains an attribute object for the method and attribute type by using `MethodInfo.GetCustomAttribute`. If `GetCustomAttribute` returns `Nothing` (Visual Basic) or `null` (C#), the method doesn't contain the attribute. + :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/AsyncStateMachineAttribute/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/runtime.compilerservices.asyncstatemachineattribute/vb/module1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/runtime.compilerservices.asyncstatemachineattribute/vb/module1.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Runtime.InteropServices.WindowsRuntime/WindowsRuntimeMarshal.xml b/xml/System.Runtime.InteropServices.WindowsRuntime/WindowsRuntimeMarshal.xml index d9e69a7d0e5..62b520faefd 100644 --- a/xml/System.Runtime.InteropServices.WindowsRuntime/WindowsRuntimeMarshal.xml +++ b/xml/System.Runtime.InteropServices.WindowsRuntime/WindowsRuntimeMarshal.xml @@ -73,10 +73,10 @@ Adds the specified event handler to a Windows Runtime event. To be added. - is . - - -or- - + is . + + -or- + is . @@ -113,8 +113,8 @@ - The address of the [HSTRING](https://go.microsoft.com/fwlink/p/?LinkId=246451) to free. - Frees the specified Windows Runtime[HSTRING](https://go.microsoft.com/fwlink/p/?LinkId=246451). + The address of the HSTRING to free. + Frees the specified Windows RuntimeHSTRING. To be added. The Windows Runtime is not supported on the current version of the operating system. @@ -157,18 +157,18 @@ Returns an object that implements the activation factory interface for the specified Windows Runtime type. An object that implements the activation factory interface. - - does not represent a Windows Runtime type (that is, belonging to the Windows Runtime itself or defined in a Windows Runtime component). - - -or- - + does not represent a Windows Runtime type (that is, belonging to the Windows Runtime itself or defined in a Windows Runtime component). + + -or- + The object specified for was not provided by the common language runtime type system. is . @@ -208,8 +208,8 @@ - An unmanaged pointer to the [HSTRING](https://go.microsoft.com/fwlink/p/?LinkId=246451) to copy. - Returns a managed string that contains a copy of the specified Windows Runtime[HSTRING](https://go.microsoft.com/fwlink/p/?LinkId=246451). + An unmanaged pointer to the HSTRING to copy. + Returns a managed string that contains a copy of the specified Windows RuntimeHSTRING. A managed string that contains a copy of the HSTRING if is not ; otherwise, . To be added. The Windows Runtime is not supported on the current version of the operating system. @@ -335,14 +335,14 @@ The managed string to copy. - Allocates a Windows Runtime[HSTRING](https://go.microsoft.com/fwlink/p/?LinkId=246451) and copies the specified managed string to it. + Allocates a Windows RuntimeHSTRING and copies the specified managed string to it. An unmanaged pointer to the new HSTRING, or if is . - method to release the [HSTRING](https://go.microsoft.com/fwlink/p/?LinkId=246451) when you are done using it. - + method to release the [HSTRING](https://go.microsoft.com/fwlink/p/?LinkId=246451) when you are done using it. + ]]> The Windows Runtime is not supported on the current version of the operating system. diff --git a/xml/System.Runtime.InteropServices/CharSet.xml b/xml/System.Runtime.InteropServices/CharSet.xml index 4e5644ac48f..4e48ffc5fd4 100644 --- a/xml/System.Runtime.InteropServices/CharSet.xml +++ b/xml/System.Runtime.InteropServices/CharSet.xml @@ -58,20 +58,20 @@ Dictates which character set marshaled strings should use. - and . For a detailed description of the string marshaling and name matching behavior associated with this enumeration, see [Specifying a Character Set](/dotnet/framework/interop/specifying-a-character-set). - - - -## Examples - The following code example shows how to specify a enumeration value when applying the to a managed definition. - + and . For a detailed description of the string marshaling and name matching behavior associated with this enumeration, see [Specifying a Character Set](/dotnet/framework/interop/specifying-a-character-set). + + + +## Examples + The following code example shows how to specify a enumeration value when applying the to a managed definition. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.runtime.interopservices.charset/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/CharSet/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.charset/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.charset/vb/source.vb" id="Snippet1"::: + ]]> @@ -118,7 +118,7 @@ 2 - Marshal strings as multiple-byte character strings: the system default [Windows (ANSI) code page](/windows/win32/intl/code-pages) on Windows, and UTF-8 on Unix. + Marshal strings as multiple-byte character strings: the system default Windows (ANSI) code page on Windows, and UTF-8 on Unix. @@ -157,7 +157,7 @@ 4 - Automatically marshal strings appropriately for the target operating system. See [Charsets and marshaling](/dotnet/standard/native-interop/charset) for details. Although the common language runtime default is , languages may override this default. For example, by default C# and Visual Basic mark all methods and types as . + Automatically marshal strings appropriately for the target operating system. See Charsets and marshaling for details. Although the common language runtime default is , languages may override this default. For example, by default C# and Visual Basic mark all methods and types as . diff --git a/xml/System.Runtime.InteropServices/ComAwareEventInfo.xml b/xml/System.Runtime.InteropServices/ComAwareEventInfo.xml index ec7f14ca68f..e82df12b257 100644 --- a/xml/System.Runtime.InteropServices/ComAwareEventInfo.xml +++ b/xml/System.Runtime.InteropServices/ComAwareEventInfo.xml @@ -431,7 +431,7 @@ ]]> - This member belongs to a type that is loaded into the reflection-only context. See [How to: Load Assemblies into the Reflection-Only Context](/dotnet/framework/reflection-and-codedom/how-to-load-assemblies-into-the-reflection-only-context). + This member belongs to a type that is loaded into the reflection-only context. See How to: Load Assemblies into the Reflection-Only Context. A custom attribute type cannot be loaded. @@ -481,7 +481,7 @@ To be added. is . - This member belongs to a type that is loaded into the reflection-only context. See [How to: Load Assemblies into the Reflection-Only Context](/dotnet/framework/reflection-and-codedom/how-to-load-assemblies-into-the-reflection-only-context) + This member belongs to a type that is loaded into the reflection-only context. See How to: Load Assemblies into the Reflection-Only Context A custom attribute type cannot be loaded. diff --git a/xml/System.Runtime.InteropServices/ComInterfaceType.xml b/xml/System.Runtime.InteropServices/ComInterfaceType.xml index e1d2feb08ac..c235aca824a 100644 --- a/xml/System.Runtime.InteropServices/ComInterfaceType.xml +++ b/xml/System.Runtime.InteropServices/ComInterfaceType.xml @@ -59,11 +59,11 @@ Identifies how to expose an interface to COM. - attribute. - + attribute. + ]]> @@ -119,7 +119,7 @@ 0 - Indicates that the interface is exposed to COM as a [dual interface](https://msdn.microsoft.com/library/1d39d64c-e23a-4249-a167-4369d5bd2b65), which enables both early and late binding. is the default value. + Indicates that the interface is exposed to COM as a dual interface, which enables both early and late binding. is the default value. diff --git a/xml/System.Runtime.InteropServices/CustomQueryInterfaceMode.xml b/xml/System.Runtime.InteropServices/CustomQueryInterfaceMode.xml index 8d21c15cec5..6f367972a77 100644 --- a/xml/System.Runtime.InteropServices/CustomQueryInterfaceMode.xml +++ b/xml/System.Runtime.InteropServices/CustomQueryInterfaceMode.xml @@ -59,7 +59,7 @@ - Indicates whether the method's [IUnknown::QueryInterface](https://go.microsoft.com/fwlink/?LinkID=144867) calls can use the interface. + Indicates whether the method's IUnknown::QueryInterface calls can use the interface. To be added. @@ -102,7 +102,7 @@ 1 - [IUnknown::QueryInterface](https://go.microsoft.com/fwlink/?LinkID=144867) method calls can use the interface. When you use this value, the method overload functions like the overload. + IUnknown::QueryInterface method calls can use the interface. When you use this value, the method overload functions like the overload. @@ -144,7 +144,7 @@ 0 - [IUnknown::QueryInterface](https://go.microsoft.com/fwlink/?LinkID=144867) method calls should ignore the interface. + IUnknown::QueryInterface method calls should ignore the interface. diff --git a/xml/System.Runtime.InteropServices/CustomQueryInterfaceResult.xml b/xml/System.Runtime.InteropServices/CustomQueryInterfaceResult.xml index ee09f847855..dd8d863dfdf 100644 --- a/xml/System.Runtime.InteropServices/CustomQueryInterfaceResult.xml +++ b/xml/System.Runtime.InteropServices/CustomQueryInterfaceResult.xml @@ -106,7 +106,7 @@ 2 - The interface for a specific interface ID is not available. In this case, the returned interface is . E_NOINTERFACE is returned to the caller of [IUnknown::QueryInterface](https://go.microsoft.com/fwlink/?LinkId=144867). + The interface for a specific interface ID is not available. In this case, the returned interface is . E_NOINTERFACE is returned to the caller of IUnknown::QueryInterface. @@ -148,7 +148,7 @@ 0 - The interface pointer that is returned from the method can be used as the result of [IUnknown::QueryInterface](https://go.microsoft.com/fwlink/?LinkId=144867). + The interface pointer that is returned from the method can be used as the result of IUnknown::QueryInterface. @@ -190,7 +190,7 @@ 1 - The custom was not used. Instead, the default implementation of [IUnknown::QueryInterface](https://go.microsoft.com/fwlink/?LinkId=144867) should be used. + The custom was not used. Instead, the default implementation of IUnknown::QueryInterface should be used. diff --git a/xml/System.Runtime.InteropServices/Marshal.xml b/xml/System.Runtime.InteropServices/Marshal.xml index 03afd30fd50..0bdb28fcf2c 100644 --- a/xml/System.Runtime.InteropServices/Marshal.xml +++ b/xml/System.Runtime.InteropServices/Marshal.xml @@ -2009,7 +2009,7 @@ The type of the managed object to aggregate. - The outer [IUnknown](/windows/win32/api/unknwn/nn-unknwn-iunknown) pointer. + The outer IUnknown pointer. The managed object to aggregate. @@ -2515,7 +2515,7 @@ The address of the BSTR to be freed. - Frees a using the COM [SysFreeString](https://go.microsoft.com/fwlink/?LinkID=148633) function. + Frees a using the COM SysFreeString function. The object that provides the interface. - Returns a pointer to an [IUnknown](/windows/win32/api/unknwn/nn-unknwn-iunknown) interface that represents the specified interface on an object of the specified type. Custom query interface access is enabled by default. + Returns a pointer to an IUnknown interface that represents the specified interface on an object of the specified type. Custom query interface access is enabled by default. The interface pointer that represents the interface. A type that represents an interface or a class. Gets the first slot in the virtual function table (v-table or VTBL) that contains user-defined methods. - The first VTBL slot that contains user-defined methods. The first slot is 3 if the interface is based on IUnknown, and 7 if the interface is based on [IDispatch](/windows/win32/api/oaidl/nn-oaidl-idispatch). + The first VTBL slot that contains user-defined methods. The first slot is 3 if the interface is based on IUnknown, and 7 if the interface is based on IDispatch. - [IUnknown::QueryInterface](https://go.microsoft.com/fwlink/?LinkId=144867) failure. + IUnknown::QueryInterface failure. .NET Core and .NET 5+ only: In all cases. @@ -359,7 +359,7 @@ The following table shows the supported combinations for `clsid` and `riid`. ]]> - [IUnknown::QueryInterface](https://go.microsoft.com/fwlink/?LinkId=144867) failure. + IUnknown::QueryInterface failure. .NET Core and .NET 5+ only: In all cases. diff --git a/xml/System.Runtime.InteropServices/TypeLibImporterFlags.xml b/xml/System.Runtime.InteropServices/TypeLibImporterFlags.xml index 2929dcc0d50..f97d9ae40e5 100644 --- a/xml/System.Runtime.InteropServices/TypeLibImporterFlags.xml +++ b/xml/System.Runtime.InteropServices/TypeLibImporterFlags.xml @@ -32,11 +32,11 @@ Indicates how an assembly should be produced. - method. - + method. + ]]> @@ -312,7 +312,7 @@ 8 - Transforms parameters of methods on dispatch-only interfaces ([dispinterface](https://msdn.microsoft.com/library/e8c18ae5-3d9e-4dff-aa20-b5acc723eacf)) into return values. + Transforms parameters of methods on dispatch-only interfaces (dispinterface) into return values. diff --git a/xml/System.Runtime.InteropServices/UnmanagedCallersOnlyAttribute.xml b/xml/System.Runtime.InteropServices/UnmanagedCallersOnlyAttribute.xml index c3f4a59dcf3..a3a6465abf3 100644 --- a/xml/System.Runtime.InteropServices/UnmanagedCallersOnlyAttribute.xml +++ b/xml/System.Runtime.InteropServices/UnmanagedCallersOnlyAttribute.xml @@ -95,7 +95,7 @@ to a native function. System.Type[] - Optional. If omitted, the runtime will use [the default platform calling convention](/dotnet/standard/native-interop/calling-conventions#platform-default-calling-convention). + Optional. If omitted, the runtime will use the default platform calling convention. Identifies how to marshal parameters or fields to unmanaged code. - enumeration with the attribute to specify how types are marshaled during interoperation with unmanaged code. You can use this enumeration to marshal code using simple value types (I1, I2, I4, I8, R4, R8, U2, U4, and U8), unmanaged types that are unavailable in the .NET Framework, and various miscellaneous types. - - For more information, see [Interoperating with Unmanaged Code](/dotnet/framework/interop/). - - - -## Examples - The following code fragment demonstrates how to declare, in managed source code, an unmanaged interface implemented by a COM component. The attribute prevents the `IMyStorage` interface from being exported back for use by COM. (COM clients should use the existing COM component directly.) In this example, specifies several members, which represent the types used by the original COM interface. - + enumeration with the attribute to specify how types are marshaled during interoperation with unmanaged code. You can use this enumeration to marshal code using simple value types (I1, I2, I4, I8, R4, R8, U2, U4, and U8), unmanaged types that are unavailable in the .NET Framework, and various miscellaneous types. + + For more information, see [Interoperating with Unmanaged Code](/dotnet/framework/interop/). + + + +## Examples + The following code fragment demonstrates how to declare, in managed source code, an unmanaged interface implemented by a COM component. The attribute prevents the `IMyStorage` interface from being exported back for use by COM. (COM clients should use the existing COM component directly.) In this example, specifies several members, which represent the types used by the original COM interface. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ImprovedInteropSnippets/CPP/codefile2.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/ComImportAttribute/Overview/codefile2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ImprovedInteropSnippets/VB/codefile2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ImprovedInteropSnippets/VB/codefile2.vb" id="Snippet2"::: + ]]> @@ -634,7 +634,7 @@ 47 - A Windows Runtime string. You can use this member on the data type. [Built-in support for WinRT was removed in .NET 5](https://learn.microsoft.com/dotnet/core/compatibility/interop/5.0/built-in-support-for-winrt-removed). See [Formerly built-in supported types](https://learn.microsoft.com/dotnet/standard/native-interop/best-practices#formerly-built-in-supported-types) for workaround. + A Windows Runtime string. You can use this member on the data type. Built-in support for WinRT was removed in .NET 5. See Formerly built-in supported types for workaround. @@ -930,7 +930,7 @@ 46 - A Windows Runtime interface pointer. You can use this member on the data type. [Built-in support for WinRT was removed in .NET 5](https://learn.microsoft.com/dotnet/core/compatibility/interop/5.0/built-in-support-for-winrt-removed). + A Windows Runtime interface pointer. You can use this member on the data type. Built-in support for WinRT was removed in .NET 5. diff --git a/xml/System.Runtime.Remoting.Channels/SoapServerFormatterSink.xml b/xml/System.Runtime.Remoting.Channels/SoapServerFormatterSink.xml index ac14c1570d7..b8fed1a161e 100644 --- a/xml/System.Runtime.Remoting.Channels/SoapServerFormatterSink.xml +++ b/xml/System.Runtime.Remoting.Channels/SoapServerFormatterSink.xml @@ -243,7 +243,7 @@ Gets a of properties for the current channel sink. - A of properties for the current channel sink. For more information, see [Channel and Formatter Configuration Properties](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/kw7c6kwc(v=vs.100)). + A of properties for the current channel sink. For more information, see Channel and Formatter Configuration Properties. To be added. Channel and Formatter Configuration Properties diff --git a/xml/System.Runtime.Remoting.Services/EnterpriseServicesHelper.xml b/xml/System.Runtime.Remoting.Services/EnterpriseServicesHelper.xml index fd66a4bd939..7fed8219cfd 100644 --- a/xml/System.Runtime.Remoting.Services/EnterpriseServicesHelper.xml +++ b/xml/System.Runtime.Remoting.Services/EnterpriseServicesHelper.xml @@ -29,13 +29,13 @@ Provides APIs that are needed for communication and operation with unmanaged classes outside of the . This class cannot be inherited. - [!NOTE] -> This class makes a link demand. A SecurityException is thrown if the immediate caller does not have infrastructure permission. See [Link Demands](/dotnet/framework/misc/link-demands) for more information. - +> This class makes a link demand. A SecurityException is thrown if the immediate caller does not have infrastructure permission. See [Link Demands](/dotnet/framework/misc/link-demands) for more information. + ]]> @@ -126,13 +126,13 @@ A proxy that represents the new instance of a class that is referenced by a CCW. Switches a COM Callable Wrapper (CCW) from one instance of a class to another instance of the same class. - [!CAUTION] -> This method can cause unwanted behavior. Before calling it, the user must ensure that this is a thread-safe operation, and that a call is not being made through the CCW to one of the instances of the class. - +> This method can cause unwanted behavior. Before calling it, the user must ensure that this is a thread-safe operation, and that a call is not being made through the CCW to one of the instances of the class. + ]]> The immediate caller does not have UnmanagedCode permission. @@ -166,14 +166,14 @@ A pointer to the COM interface to wrap. - Wraps the specified COM interface with a [Runtime Callable Wrapper](/dotnet/framework/interop/runtime-callable-wrapper) (RCW). + Wraps the specified COM interface with a Runtime Callable Wrapper (RCW). The RCW where the specified is wrapped. - method is similar to the method, but does not attempt to maintain the identity of the unmanaged object. For example, two calls with the same `IUnknown` to the current method return two different RCWs, but two calls to the method with the same `IUnknown` return the same RCW. - + method is similar to the method, but does not attempt to maintain the identity of the unmanaged object. For example, two calls with the same `IUnknown` to the current method return two different RCWs, but two calls to the method with the same `IUnknown` return the same RCW. + ]]> The immediate caller does not have UnmanagedCode permission. diff --git a/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml b/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml index 01a37b5e43b..df27df87ffc 100644 --- a/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml +++ b/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml @@ -1,64 +1,64 @@ - - - - - - - - - System.Security.Cryptography.Primitives - 4.0.0.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - - - - - - - - - - System.Object - - - - System.IDisposable - - - - - [System.Runtime.InteropServices.ComVisible(true)] - [<System.Runtime.InteropServices.ComVisible(true)>] - - - - Represents the abstract base class from which all implementations of asymmetric algorithms must inherit. - + + + + + + + + + System.Security.Cryptography.Primitives + 4.0.0.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + + + + + + + + + + System.Object + + + + System.IDisposable + + + + + [System.Runtime.InteropServices.ComVisible(true)] + [<System.Runtime.InteropServices.ComVisible(true)>] + + + + Represents the abstract base class from which all implementations of asymmetric algorithms must inherit. + - - Cryptographic Services - How to: Create a Public/Private Key Pair - - - - - - - - - Constructor - - System.Security.Cryptography.Primitives - 4.0.0.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - Initializes a new instance of the class. - + ]]> + + Cryptographic Services + How to: Create a Public/Private Key Pair + + + + + + + + + Constructor + + System.Security.Cryptography.Primitives + 4.0.0.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + Initializes a new instance of the class. + and classes are the only currently supported implementations. - ]]> - - The implementation of the derived class is not valid. - Cryptographic Services - - - - - - - - - - Method - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography.Primitives - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Void - - - - Releases all resources used by the class. - + ]]> + + The implementation of the derived class is not valid. + Cryptographic Services + + + + + + + + + + Method + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography.Primitives + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Void + + + + Releases all resources used by the class. + - - Cryptographic Services - - - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - Creates a cryptographic object used to perform the asymmetric algorithm. - - - - - - - - - - Method - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography.Primitives - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - [System.Obsolete("The default implementation of this cryptography algorithm is not supported", DiagnosticId="SYSLIB0007", UrlFormat="https://aka.ms/dotnet-warnings/{0}")] - [<System.Obsolete("The default implementation of this cryptography algorithm is not supported", DiagnosticId="SYSLIB0007", UrlFormat="https://aka.ms/dotnet-warnings/{0}")>] - - - [System.Obsolete("The default implementation of this cryptography algorithm is not supported.", DiagnosticId="SYSLIB0007", UrlFormat="https://aka.ms/dotnet-warnings/{0}")] - [<System.Obsolete("The default implementation of this cryptography algorithm is not supported.", DiagnosticId="SYSLIB0007", UrlFormat="https://aka.ms/dotnet-warnings/{0}")>] - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Security.Cryptography.AsymmetricAlgorithm - - - - Creates a default cryptographic object used to perform the asymmetric algorithm. - A new instance, unless the default settings have been changed with the [<cryptoClass> element](/dotnet/framework/configure-apps/file-schema/cryptography/cryptoclass-element). - + ]]> + + Cryptographic Services + + + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + Creates a cryptographic object used to perform the asymmetric algorithm. + + + + + + + + + + Method + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography.Primitives + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + [System.Obsolete("The default implementation of this cryptography algorithm is not supported", DiagnosticId="SYSLIB0007", UrlFormat="https://aka.ms/dotnet-warnings/{0}")] + [<System.Obsolete("The default implementation of this cryptography algorithm is not supported", DiagnosticId="SYSLIB0007", UrlFormat="https://aka.ms/dotnet-warnings/{0}")>] + + + [System.Obsolete("The default implementation of this cryptography algorithm is not supported.", DiagnosticId="SYSLIB0007", UrlFormat="https://aka.ms/dotnet-warnings/{0}")] + [<System.Obsolete("The default implementation of this cryptography algorithm is not supported.", DiagnosticId="SYSLIB0007", UrlFormat="https://aka.ms/dotnet-warnings/{0}")>] + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Security.Cryptography.AsymmetricAlgorithm + + + + Creates a default cryptographic object used to perform the asymmetric algorithm. + A new instance, unless the default settings have been changed with the <cryptoClass> element. + - - .NET Core 2.0 - 3.1 and .NET 5 and later: In all cases. - Cryptographic Services - - - - - - - - - - - Method - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography.Primitives - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("The default algorithm implementations might be removed, use strong type references like 'RSA.Create()' instead.")] - [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("The default algorithm implementations might be removed, use strong type references like 'RSA.Create()' instead.")>] - - - [System.Obsolete("Cryptographic factory methods accepting an algorithm name are obsolete. Use the parameterless Create factory method on the algorithm type instead.", DiagnosticId="SYSLIB0045", UrlFormat="https://aka.ms/dotnet-warnings/{0}")] - [<System.Obsolete("Cryptographic factory methods accepting an algorithm name are obsolete. Use the parameterless Create factory method on the algorithm type instead.", DiagnosticId="SYSLIB0045", UrlFormat="https://aka.ms/dotnet-warnings/{0}")>] - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Security.Cryptography.AsymmetricAlgorithm - - - - - + ]]> + + .NET Core 2.0 - 3.1 and .NET 5 and later: In all cases. + Cryptographic Services + + + + + + + + + + + Method + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography.Primitives + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("The default algorithm implementations might be removed, use strong type references like 'RSA.Create()' instead.")] + [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("The default algorithm implementations might be removed, use strong type references like 'RSA.Create()' instead.")>] + + + [System.Obsolete("Cryptographic factory methods accepting an algorithm name are obsolete. Use the parameterless Create factory method on the algorithm type instead.", DiagnosticId="SYSLIB0045", UrlFormat="https://aka.ms/dotnet-warnings/{0}")] + [<System.Obsolete("Cryptographic factory methods accepting an algorithm name are obsolete. Use the parameterless Create factory method on the algorithm type instead.", DiagnosticId="SYSLIB0045", UrlFormat="https://aka.ms/dotnet-warnings/{0}")>] + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Security.Cryptography.AsymmetricAlgorithm + + + + + The asymmetric algorithm implementation to use. The following table shows the valid values for the parameter and the algorithms they map to. Parameter value @@ -391,10 +391,10 @@ This method is obsolete in .NET 5 and later versions. System.Security.Cryptography.ECDiffieHellmanCng - - Creates an instance of the specified implementation of an asymmetric algorithm. - A new instance of the specified asymmetric algorithm implementation. - + + Creates an instance of the specified implementation of an asymmetric algorithm. + A new instance of the specified asymmetric algorithm implementation. + - - Cryptographic Services - - - - - System.Security.Cryptography.Primitives - 4.0.0.0 - 4.1.0.0 - - - Releases all resources used by the current instance of the class. - - - - - - - - - - Method - - M:System.IDisposable.Dispose - - - System.Security.Cryptography.Primitives - 4.0.0.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Void - - - - Releases all resources used by the current instance of the class. - + ]]> + + Cryptographic Services + + + + + System.Security.Cryptography.Primitives + 4.0.0.0 + 4.1.0.0 + + + Releases all resources used by the current instance of the class. + + + + + + + + + + Method + + M:System.IDisposable.Dispose + + + System.Security.Cryptography.Primitives + 4.0.0.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Void + + + + Releases all resources used by the current instance of the class. + [!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. - ]]> - - - - - - - - - - - - - - - Method - - System.Security.Cryptography.Primitives - 4.0.0.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Void - - - - - - - to release both managed and unmanaged resources; to release only unmanaged resources. - Releases the unmanaged resources used by the class and optionally releases the managed resources. - + ]]> + + + + + + + + + + + + + + + Method + + System.Security.Cryptography.Primitives + 4.0.0.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Void + + + + + + + to release both managed and unmanaged resources; to release only unmanaged resources. + Releases the unmanaged resources used by the class and optionally releases the managed resources. + references. This method invokes the `Dispose()` method of each referenced object. - ]]> - - - - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - - Cryptographic Services - - - - - - - - - - Method - - System.Security.Cryptography.Primitives - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - netstandard - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Byte[] - - - - - - [System.Runtime.CompilerServices.Nullable(0)] - [<System.Runtime.CompilerServices.Nullable(0)>] - - - - - - - The bytes to use as a password when encrypting the key material. - The password-based encryption (PBE) parameters to use when encrypting the key material. - Exports the current key in the PKCS#8 EncryptedPrivateKeyInfo format with a byte-based password. - A byte array containing the PKCS#8 EncryptedPrivateKeyInfo representation of this key. - + ]]> + + + + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources. + + Cryptographic Services + + + + + + + + + + Method + + System.Security.Cryptography.Primitives + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + netstandard + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Byte[] + + + + + + [System.Runtime.CompilerServices.Nullable(0)] + [<System.Runtime.CompilerServices.Nullable(0)>] + + + + + + + The bytes to use as a password when encrypting the key material. + The password-based encryption (PBE) parameters to use when encrypting the key material. + Exports the current key in the PKCS#8 EncryptedPrivateKeyInfo format with a byte-based password. + A byte array containing the PKCS#8 EncryptedPrivateKeyInfo representation of this key. + - + ]]> + The key could not be exported. -or- indicates that should be used, which requires -based passwords. - - - - - - - - - - - - Method - - System.Security.Cryptography.Primitives - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - netstandard - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Byte[] - - - - - - [System.Runtime.CompilerServices.Nullable(0)] - [<System.Runtime.CompilerServices.Nullable(0)>] - - - - - - - The password to use when encrypting the key material. - The password-based encryption (PBE) parameters to use when encrypting the key material. - Exports the current key in the PKCS#8 EncryptedPrivateKeyInfo format with a char-based password. - A byte array containing the PKCS#8 EncryptedPrivateKeyInfo representation of this key. - + + + + + + + + + + + + Method + + System.Security.Cryptography.Primitives + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + netstandard + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Byte[] + + + + + + [System.Runtime.CompilerServices.Nullable(0)] + [<System.Runtime.CompilerServices.Nullable(0)>] + + + + + + + The password to use when encrypting the key material. + The password-based encryption (PBE) parameters to use when encrypting the key material. + Exports the current key in the PKCS#8 EncryptedPrivateKeyInfo format with a char-based password. + A byte array containing the PKCS#8 EncryptedPrivateKeyInfo representation of this key. + - - The key could not be exported. - - - - - - - - - - - Method - - System.Security.Cryptography - 8.0.0.0 - 9.0.0.0 - - - System.Security.Cryptography.Primitives - - - netstandard - - - mscorlib - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.String - - - - - - [System.Runtime.CompilerServices.Nullable(0)] - [<System.Runtime.CompilerServices.Nullable(0)>] - - - - - - - The bytes to use as a password when encrypting the key material. - The password-based encryption (PBE) parameters to use when encrypting the key material. - Exports the current key in the PKCS#8 EncryptedPrivateKeyInfo format with a byte-based password, PEM encoded. - A string containing the PEM-encoded PKCS#8 EncryptedPrivateKeyInfo. - + ]]> + + The key could not be exported. + + + + + + + + + + + Method + + System.Security.Cryptography + 8.0.0.0 + 9.0.0.0 + + + System.Security.Cryptography.Primitives + + + netstandard + + + mscorlib + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.String + + + + + + [System.Runtime.CompilerServices.Nullable(0)] + [<System.Runtime.CompilerServices.Nullable(0)>] + + + + + + + The bytes to use as a password when encrypting the key material. + The password-based encryption (PBE) parameters to use when encrypting the key material. + Exports the current key in the PKCS#8 EncryptedPrivateKeyInfo format with a byte-based password, PEM encoded. + A string containing the PEM-encoded PKCS#8 EncryptedPrivateKeyInfo. + A PEM-encoded PKCS#8 EncryptedPrivateKeyInfo will begin with -----BEGIN ENCRYPTED PRIVATE KEY----- and end with -----END ENCRYPTED PRIVATE KEY-----, with the base64 encoded DER contents of the key between the PEM boundaries. - + The PEM is encoded according to the IETF RFC 7468 "strict" encoding rules. - - + + An implementation for or - has not been provided. - The key could not be exported. - - - - - - - - - - Method - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Security.Cryptography.Primitives - - - netstandard - - - mscorlib - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.String - - - - - - [System.Runtime.CompilerServices.Nullable(0)] - [<System.Runtime.CompilerServices.Nullable(0)>] - - - - - - - The password to use when encrypting the key material. - The password-based encryption (PBE) parameters to use when encrypting the key material. - Exports the current key in the PKCS#8 EncryptedPrivateKeyInfo format with a char-based password, PEM encoded. - A string containing the PEM-encoded PKCS#8 EncryptedPrivateKeyInfo. - + has not been provided. + The key could not be exported. + + + + + + + + + + Method + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Security.Cryptography.Primitives + + + netstandard + + + mscorlib + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.String + + + + + + [System.Runtime.CompilerServices.Nullable(0)] + [<System.Runtime.CompilerServices.Nullable(0)>] + + + + + + + The password to use when encrypting the key material. + The password-based encryption (PBE) parameters to use when encrypting the key material. + Exports the current key in the PKCS#8 EncryptedPrivateKeyInfo format with a char-based password, PEM encoded. + A string containing the PEM-encoded PKCS#8 EncryptedPrivateKeyInfo. + - + ]]> + An implementation for or - has not been provided. - The key could not be exported. - - - - - - - - - - Method - - System.Security.Cryptography.Primitives - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - netstandard - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Byte[] - - - - Exports the current key in the PKCS#8 PrivateKeyInfo format. - A byte array containing the PKCS#8 PrivateKeyInfo representation of this key. - To be added. - The key could not be exported. - - - - - - - - - - - - Method - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Security.Cryptography.Primitives - - - netstandard - - - mscorlib - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.String - - - - Exports the current key in the PKCS#8 PrivateKeyInfo format, PEM encoded. - A string containing the PEM-encoded PKCS#8 PrivateKeyInfo. - + has not been provided. + The key could not be exported. + + + + + + + + + + Method + + System.Security.Cryptography.Primitives + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + netstandard + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Byte[] + + + + Exports the current key in the PKCS#8 PrivateKeyInfo format. + A byte array containing the PKCS#8 PrivateKeyInfo representation of this key. + To be added. + The key could not be exported. + + + + + + + + + + + + Method + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Security.Cryptography.Primitives + + + netstandard + + + mscorlib + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.String + + + + Exports the current key in the PKCS#8 PrivateKeyInfo format, PEM encoded. + A string containing the PEM-encoded PKCS#8 PrivateKeyInfo. + - + ]]> + An implementation for or - has not been provided. - The key could not be exported. - - - - - - - - - - Method - - System.Security.Cryptography.Primitives - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - netstandard - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Byte[] - - - - Exports the public-key portion of the current key in the X.509 SubjectPublicKeyInfo format. - A byte array containing the X.509 SubjectPublicKeyInfo representation of the public-key portion of this key. - To be added. - - - - - - - - - - - Method - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Security.Cryptography.Primitives - - - netstandard - - - mscorlib - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.String - - - - Exports the public-key portion of the current key in the X.509 SubjectPublicKeyInfo format, PEM encoded. - A string containing the PEM-encoded X.509 SubjectPublicKeyInfo. - + has not been provided. + The key could not be exported. + + + + + + + + + + Method + + System.Security.Cryptography.Primitives + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + netstandard + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Byte[] + + + + Exports the public-key portion of the current key in the X.509 SubjectPublicKeyInfo format. + A byte array containing the X.509 SubjectPublicKeyInfo representation of the public-key portion of this key. + To be added. + + + + + + + + + + + Method + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Security.Cryptography.Primitives + + + netstandard + + + mscorlib + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.String + + + + Exports the public-key portion of the current key in the X.509 SubjectPublicKeyInfo format, PEM encoded. + A string containing the PEM-encoded X.509 SubjectPublicKeyInfo. + - + ]]> + An implementation for or - has not been provided. - The key could not be exported. - - - - - - - - - - - - - - Method - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography.Primitives - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Void - - - - - - The XML string to use to reconstruct the object. - When overridden in a derived class, reconstructs an object from an XML string. Otherwise, throws a . - + has not been provided. + The key could not be exported. + + + + + + + + + + + + + + Method + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography.Primitives + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Void + + + + + + The XML string to use to reconstruct the object. + When overridden in a derived class, reconstructs an object from an XML string. Otherwise, throws a . + - - Cryptographic Services - - - - - - - - - - Method - - System.Security.Cryptography.Primitives - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - netstandard - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Void - - - - - - - - The bytes to use as a password when decrypting the key material. - The bytes of a PKCS#8 EncryptedPrivateKeyInfo structure in the ASN.1-BER encoding. - When this method returns, contains a value that indicates the number of bytes read from . This parameter is treated as uninitialized. - When overridden in a derived class, imports the public/private keypair from a PKCS#8 EncryptedPrivateKeyInfo structure after decrypting with a byte-based password, replacing the keys for this object. - + ]]> + + Cryptographic Services + + + + + + + + + + Method + + System.Security.Cryptography.Primitives + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + netstandard + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Void + + + + + + + + The bytes to use as a password when decrypting the key material. + The bytes of a PKCS#8 EncryptedPrivateKeyInfo structure in the ASN.1-BER encoding. + When this method returns, contains a value that indicates the number of bytes read from . This parameter is treated as uninitialized. + When overridden in a derived class, imports the public/private keypair from a PKCS#8 EncryptedPrivateKeyInfo structure after decrypting with a byte-based password, replacing the keys for this object. + throws a by default. - ]]> - + ]]> + The password is incorrect. -or- @@ -1143,49 +1143,49 @@ The contents of represent the key in a format that is -or- The algorithm-specific key import failed. - - A derived type has not overriden this member. - - - - - - - - - - Method - - System.Security.Cryptography.Primitives - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - netstandard - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Void - - - - - - - - The password to use for decrypting the key material. - The bytes of a PKCS#8 EncryptedPrivateKeyInfo structure in the ASN.1-BER encoding. - When this method returns, contains a value that indicates the number of bytes read from . This parameter is treated as uninitialized. - When overridden in a derived class, imports the public/private keypair from a PKCS#8 EncryptedPrivateKeyInfo structure after decrypting with a char-based password, replacing the keys for this object. - + + A derived type has not overriden this member. + + + + + + + + + + Method + + System.Security.Cryptography.Primitives + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + netstandard + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Void + + + + + + + + The password to use for decrypting the key material. + The bytes of a PKCS#8 EncryptedPrivateKeyInfo structure in the ASN.1-BER encoding. + When this method returns, contains a value that indicates the number of bytes read from . This parameter is treated as uninitialized. + When overridden in a derived class, imports the public/private keypair from a PKCS#8 EncryptedPrivateKeyInfo structure after decrypting with a char-based password, replacing the keys for this object. + throws a by default. - ]]> - + ]]> + The password is incorrect. -or- @@ -1215,60 +1215,60 @@ The contents of represent the key in a format that is -or- The algorithm-specific key import failed. - - A derived type has not overriden this member. - - - - - - - - - - Method - - System.Security.Cryptography.Primitives - 5.0.0.0 - 6.0.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - netstandard - - - System.Void - - - - - - - The PEM text of the encrypted key to import. - The bytes to use as a password when decrypting the key material. - When overridden in a derived class, imports an encrypted RFC 7468 PEM-encoded key, replacing the keys for this object. - + + A derived type has not overriden this member. + + + + + + + + + + Method + + System.Security.Cryptography.Primitives + 5.0.0.0 + 6.0.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + netstandard + + + System.Void + + + + + + + The PEM text of the encrypted key to import. + The bytes to use as a password when decrypting the key material. + When overridden in a derived class, imports an encrypted RFC 7468 PEM-encoded key, replacing the keys for this object. + . - ]]> - - A derived type has not overridden this member. - + ]]> + + A derived type has not overridden this member. + 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. @@ -1292,59 +1292,59 @@ The base-64 decoded contents of the PEM text from -or- The algorithm-specific key import failed. - - - - - - - - - - - Method - - System.Security.Cryptography.Primitives - 5.0.0.0 - 6.0.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - netstandard - - - System.Void - - - - - - - The PEM text of the encrypted key to import. - The password to use for decrypting the key material. - When overridden in a derived class, imports an encrypted RFC 7468 PEM-encoded key, replacing the keys for this object. - + + + + + + + + + + + Method + + System.Security.Cryptography.Primitives + 5.0.0.0 + 6.0.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + netstandard + + + System.Void + + + + + + + The PEM text of the encrypted key to import. + The password to use for decrypting the key material. + When overridden in a derived class, imports an encrypted RFC 7468 PEM-encoded key, replacing the keys for this object. + . - ]]> - - A derived type has not overridden this member. - + ]]> + + A derived type has not overridden this member. + 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. @@ -1368,51 +1368,51 @@ The base-64 decoded contents of the PEM text from -or- The algorithm-specific key import failed. - - - - - - - - - - - Method - - System.Security.Cryptography.Primitives - 5.0.0.0 - 6.0.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - netstandard - - - System.Void - - - - - - The text of the PEM key to import. - When overridden in a derived class, imports an RFC 7468 textually encoded key, replacing the keys for this object. - + + + + + + + + + + + Method + + System.Security.Cryptography.Primitives + 5.0.0.0 + 6.0.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + netstandard + + + System.Void + + + + + + The text of the PEM key to import. + When overridden in a derived class, imports an RFC 7468 textually encoded key, replacing the keys for this object. + . - ]]> - - A derived type has not overridden this member. - + ]]> + + A derived type has not overridden this member. + does not contain a PEM-encoded key with a recognized label. -or- @@ -1422,46 +1422,46 @@ Because each algorithm may have algorithm-specific PEM labels, the default behav -or- contains an encrypted PEM-encoded key. - - - - - - - - - - - Method - - System.Security.Cryptography.Primitives - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - netstandard - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Void - - - - - - - The bytes of a PKCS#8 PrivateKeyInfo structure in the ASN.1-BER encoding. - When this method returns, contains a value that indicates the number of bytes read from . This parameter is treated as uninitialized. - When overriden in a derived class, imports the public/private keypair from a PKCS#8 PrivateKeyInfo structure after decryption, replacing the keys for this object. - + + + + + + + + + + + Method + + System.Security.Cryptography.Primitives + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + netstandard + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Void + + + + + + + The bytes of a PKCS#8 PrivateKeyInfo structure in the ASN.1-BER encoding. + When this method returns, contains a value that indicates the number of bytes read from . This parameter is treated as uninitialized. + When overriden in a derived class, imports the public/private keypair from a PKCS#8 PrivateKeyInfo structure after decryption, replacing the keys for this object. + throws a by default. - ]]> - + ]]> + The contents of do not represent an ASN.1-BER-encoded PKCS#8 PrivateKeyInfo structure. -or- @@ -1485,47 +1485,47 @@ The contents of represent the key in a format that is -or- The algorithm-specific key import failed. - - A derived type has not overriden this member. - - - - - - - - - - Method - - System.Security.Cryptography.Primitives - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - netstandard - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Void - - - - - - - The bytes of an X.509 SubjectPublicKeyInfo structure in the ASN.1-DER encoding. - When this method returns, contains a value that indicates the number of bytes read from . This parameter is treated as uninitialized. - When overriden in a derived class, imports the public key from an X.509 SubjectPublicKeyInfo structure after decryption, replacing the keys for this object. - + + A derived type has not overriden this member. + + + + + + + + + + Method + + System.Security.Cryptography.Primitives + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + netstandard + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Void + + + + + + + The bytes of an X.509 SubjectPublicKeyInfo structure in the ASN.1-DER encoding. + When this method returns, contains a value that indicates the number of bytes read from . This parameter is treated as uninitialized. + When overriden in a derived class, imports the public key from an X.509 SubjectPublicKeyInfo structure after decryption, replacing the keys for this object. + throws a by default. - ]]> - + ]]> + The contents of do not represent an ASN.1-DER-encoded X.509 SubjectPublicKeyInfo structure. -or- @@ -1548,65 +1548,65 @@ The contents of represent the key in a format that is -or- The algorithm-specific key import failed. - - A derived type has not overriden this member. - - - - - - - - - - - - - - Property - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography.Primitives - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - [get: System.Runtime.CompilerServices.NullableContext(2)] - [<get: System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.String - - - When overridden in a derived class, gets the name of the key exchange algorithm. Otherwise, throws an . - The name of the key exchange algorithm. - + + A derived type has not overriden this member. + + + + + + + + + + + + + + Property + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography.Primitives + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + [get: System.Runtime.CompilerServices.NullableContext(2)] + [<get: System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.String + + + When overridden in a derived class, gets the name of the key exchange algorithm. Otherwise, throws an . + The name of the key exchange algorithm. + - - Cryptographic Services - - - - - - - - - - Property - - System.Security.Cryptography.Primitives - 4.0.0.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Int32 - - - Gets or sets the size, in bits, of the key modulus used by the asymmetric algorithm. - The size, in bits, of the key modulus used by the asymmetric algorithm. - + ]]> + + Cryptographic Services + + + + + + + + + + Property + + System.Security.Cryptography.Primitives + 4.0.0.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Int32 + + + Gets or sets the size, in bits, of the key modulus used by the asymmetric algorithm. + The size, in bits, of the key modulus used by the asymmetric algorithm. + - - The key modulus size is invalid. - Cryptographic Services - - - - - - - - - - Field - - System.Security.Cryptography.Primitives - 4.0.0.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Int32 - - - Represents the size, in bits, of the key modulus used by the asymmetric algorithm. - + ]]> + + The key modulus size is invalid. + Cryptographic Services + + + + + + + + + + Field + + System.Security.Cryptography.Primitives + 4.0.0.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Int32 + + + Represents the size, in bits, of the key modulus used by the asymmetric algorithm. + property. - ]]> - - Cryptographic Services - - - - - - - - - - Property - - System.Security.Cryptography.Primitives - 4.0.0.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - [get: System.Runtime.CompilerServices.NullableContext(1)] - [<get: System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Security.Cryptography.KeySizes[] - - - Gets the key sizes that are supported by the asymmetric algorithm. - An array that contains the key sizes supported by the asymmetric algorithm. - + ]]> + + Cryptographic Services + + + + + + + + + + Property + + System.Security.Cryptography.Primitives + 4.0.0.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + [get: System.Runtime.CompilerServices.NullableContext(1)] + [<get: System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Security.Cryptography.KeySizes[] + + + Gets the key sizes that are supported by the asymmetric algorithm. + An array that contains the key sizes supported by the asymmetric algorithm. + - - Cryptographic Services - - - - - - - - - - Field - - System.Security.Cryptography.Primitives - 4.0.0.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - [System.Diagnostics.CodeAnalysis.MaybeNull] - [<System.Diagnostics.CodeAnalysis.MaybeNull>] - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - - System.Security.Cryptography.KeySizes[] - - - Specifies the key sizes that are supported by the asymmetric algorithm. - + ]]> + + Cryptographic Services + + + + + + + + + + Field + + System.Security.Cryptography.Primitives + 4.0.0.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + [System.Diagnostics.CodeAnalysis.MaybeNull] + [<System.Diagnostics.CodeAnalysis.MaybeNull>] + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + + System.Security.Cryptography.KeySizes[] + + + Specifies the key sizes that are supported by the asymmetric algorithm. + property. - ]]> - - Cryptographic Services - - - - - - - - - - - - - - Property - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography.Primitives - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - [get: System.Runtime.CompilerServices.NullableContext(2)] - [<get: System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.String - - - When implemented in a derived class, gets the name of the signature algorithm. Otherwise, always throws a . - The name of the signature algorithm. - + ]]> + + Cryptographic Services + + + + + + + + + + + + + + Property + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography.Primitives + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + [get: System.Runtime.CompilerServices.NullableContext(2)] + [<get: System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.String + + + When implemented in a derived class, gets the name of the signature algorithm. Otherwise, always throws a . + The name of the signature algorithm. + - - Cryptographic Services - - - - - - - - - - Method - - M:System.IDisposable.Dispose - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - - - System.Security.Cryptography.Primitives - - - netstandard - - - System.Security.Cryptography - - - System.Void - - - - For a description of this member, see . - + ]]> + + Cryptographic Services + + + + + + + + + + Method + + M:System.IDisposable.Dispose + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + + + System.Security.Cryptography.Primitives + + + netstandard + + + System.Security.Cryptography + + + System.Void + + + + For a description of this member, see . + instance is cast to an interface. -]]> - - - Cryptographic Services - - - - - - - - - - - - - - Method - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography.Primitives - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.String - - - - - - - to include private parameters; otherwise, . - When overridden in a derived class, creates and returns an XML string representation of the current object. Otherwise, throws a . - An XML string encoding of the current object. - +]]> + + + Cryptographic Services + + + + + + + + + + + + + + Method + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography.Primitives + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.String + + + + + + + to include private parameters; otherwise, . + When overridden in a derived class, creates and returns an XML string representation of the current object. Otherwise, throws a . + An XML string encoding of the current object. + - - Cryptographic Services - - - - - - - - - - Method - - System.Security.Cryptography.Primitives - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - netstandard - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Boolean - - - - - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - - - - - - The bytes to use as a password when encrypting the key material. - The password-based encryption (PBE) parameters to use when encrypting the key material. - The byte span to receive the PKCS#8 EncryptedPrivateKeyInfo data. - When this method returns, contains a value that indicates the number of bytes written to . This parameter is treated as uninitialized. - When overridden in a derived class, attempts to export the current key in the PKCS#8 EncryptedPrivateKeyInfo format into a provided buffer, using a byte-based password. - - if is big enough to receive the output; otherwise, . - + ]]> + + Cryptographic Services + + + + + + + + + + Method + + System.Security.Cryptography.Primitives + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + netstandard + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Boolean + + + + + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + + + + + + The bytes to use as a password when encrypting the key material. + The password-based encryption (PBE) parameters to use when encrypting the key material. + The byte span to receive the PKCS#8 EncryptedPrivateKeyInfo data. + When this method returns, contains a value that indicates the number of bytes written to . This parameter is treated as uninitialized. + When overridden in a derived class, attempts to export the current key in the PKCS#8 EncryptedPrivateKeyInfo format into a provided buffer, using a byte-based password. + + if is big enough to receive the output; otherwise, . + throws a by default. - ]]> - + ]]> + The key could not be exported. -or- indicates that should be used, which requires -based passwords. - - A derived type has not overriden this member. - - - - - - - - - - - Method - - System.Security.Cryptography.Primitives - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - netstandard - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Boolean - - - - - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - - - - - - The password to use when encrypting the key material. - The password-based encryption (PBE) parameters to use when encrypting the key material. - The byte span to receive the PKCS#8 EncryptedPrivateKeyInfo data. - When this method returns, contains a value that indicates the number of bytes written to . This parameter is treated as uninitialized. - When overriden in a derived class, attempts to export the current key in the PKCS#8 EncryptedPrivateKeyInfo format into a provided buffer, using a char-based password. - - if is big enough to receive the output; otherwise, . - + + A derived type has not overriden this member. + + + + + + + + + + + Method + + System.Security.Cryptography.Primitives + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + netstandard + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Boolean + + + + + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + + + + + + The password to use when encrypting the key material. + The password-based encryption (PBE) parameters to use when encrypting the key material. + The byte span to receive the PKCS#8 EncryptedPrivateKeyInfo data. + When this method returns, contains a value that indicates the number of bytes written to . This parameter is treated as uninitialized. + When overriden in a derived class, attempts to export the current key in the PKCS#8 EncryptedPrivateKeyInfo format into a provided buffer, using a char-based password. + + if is big enough to receive the output; otherwise, . + throws a by default. - ]]> - - The key could not be exported. - A derived type has not overriden this member. - - - - - - - - - - - Method - - System.Security.Cryptography - 8.0.0.0 - 9.0.0.0 - - - System.Security.Cryptography.Primitives - - - netstandard - - - mscorlib - - - System.Boolean - - - - - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - - - - - - The bytes to use as a password when encrypting the key material. - The password-based encryption (PBE) parameters to use when encrypting the key material. - The character span to receive the PEM-encoded PKCS#8 EncryptedPrivateKeyInfo data. - When this method returns, contains a value that indicates the number of characters written to . This parameter is treated as uninitialized. - Attempts to export the current key in the PKCS#8 EncryptedPrivateKeyInfo format with a byte-based password, PEM encoded. - - if is big enough to receive the output; otherwise, . - + ]]> + + The key could not be exported. + A derived type has not overriden this member. + + + + + + + + + + + Method + + System.Security.Cryptography + 8.0.0.0 + 9.0.0.0 + + + System.Security.Cryptography.Primitives + + + netstandard + + + mscorlib + + + System.Boolean + + + + + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + + + + + + The bytes to use as a password when encrypting the key material. + The password-based encryption (PBE) parameters to use when encrypting the key material. + The character span to receive the PEM-encoded PKCS#8 EncryptedPrivateKeyInfo data. + When this method returns, contains a value that indicates the number of characters written to . This parameter is treated as uninitialized. + Attempts to export the current key in the PKCS#8 EncryptedPrivateKeyInfo format with a byte-based password, PEM encoded. + + if is big enough to receive the output; otherwise, . + A PEM-encoded PKCS#8 EncryptedPrivateKeyInfo will begin with -----BEGIN ENCRYPTED PRIVATE KEY----- and end with -----END ENCRYPTED PRIVATE KEY-----, with the base64 encoded DER contents of the key between the PEM boundaries. - + The PEM is encoded according to the IETF RFC 7468 "strict" encoding rules. - - + + An implementation for - has not been provided. - The key could not be exported. - - - - - - - - - - Method - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Security.Cryptography.Primitives - - - netstandard - - - mscorlib - - - System.Boolean - - - - - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - - - - - - The password to use when encrypting the key material. - The password-based encryption (PBE) parameters to use when encrypting the key material. - The character span to receive the PEM-encoded PKCS#8 EncryptedPrivateKeyInfo data. - When this method returns, contains a value that indicates the number of characters written to . This parameter is treated as uninitialized. - Exports the current key in the PKCS#8 EncryptedPrivateKeyInfo format with a char-based password, PEM encoded. - - if is big enough to receive the output; otherwise, . - + has not been provided. + The key could not be exported. + + + + + + + + + + Method + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Security.Cryptography.Primitives + + + netstandard + + + mscorlib + + + System.Boolean + + + + + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + + + + + + The password to use when encrypting the key material. + The password-based encryption (PBE) parameters to use when encrypting the key material. + The character span to receive the PEM-encoded PKCS#8 EncryptedPrivateKeyInfo data. + When this method returns, contains a value that indicates the number of characters written to . This parameter is treated as uninitialized. + Exports the current key in the PKCS#8 EncryptedPrivateKeyInfo format with a char-based password, PEM encoded. + + if is big enough to receive the output; otherwise, . + - + ]]> + An implementation for - has not been provided. - The key could not be exported. - - - - - - - - - - Method - - System.Security.Cryptography.Primitives - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - netstandard - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Boolean - - - - - - - The byte span to receive the PKCS#8 PrivateKeyInfo data. - When this method returns, contains a value that indicates the number of bytes written to . This parameter is treated as uninitialized. - When overridden in a derived class, attempts to export the current key in the PKCS#8 PrivateKeyInfo format into a provided buffer. - - if is big enough to receive the output; otherwise, . - + has not been provided. + The key could not be exported. + + + + + + + + + + Method + + System.Security.Cryptography.Primitives + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + netstandard + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Boolean + + + + + + + The byte span to receive the PKCS#8 PrivateKeyInfo data. + When this method returns, contains a value that indicates the number of bytes written to . This parameter is treated as uninitialized. + When overridden in a derived class, attempts to export the current key in the PKCS#8 PrivateKeyInfo format into a provided buffer. + + if is big enough to receive the output; otherwise, . + throws a by default. - ]]> - - The key could not be exported. - A derived type has not overriden this member. - - - - - - - - - - - Method - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Security.Cryptography.Primitives - - - netstandard - - - mscorlib - - - System.Boolean - - - - - - - The character span to receive the PEM-encoded PKCS#8 PrivateKeyInfo data. - When this method returns, contains a value that indicates the number of characters written to . This parameter is treated as uninitialized. - Attempts to export the current key in the PEM-encoded PKCS#8 PrivateKeyInfo format into a provided buffer. - - if is big enough to receive the output; otherwise, . - + ]]> + + The key could not be exported. + A derived type has not overriden this member. + + + + + + + + + + + Method + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Security.Cryptography.Primitives + + + netstandard + + + mscorlib + + + System.Boolean + + + + + + + The character span to receive the PEM-encoded PKCS#8 PrivateKeyInfo data. + When this method returns, contains a value that indicates the number of characters written to . This parameter is treated as uninitialized. + Attempts to export the current key in the PEM-encoded PKCS#8 PrivateKeyInfo format into a provided buffer. + + if is big enough to receive the output; otherwise, . + - + ]]> + An implementation for - has not been provided. - The key could not be exported. - - - - - - - - - - Method - - System.Security.Cryptography.Primitives - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - - - netstandard - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Boolean - - - - - - - The byte span to receive the X.509 SubjectPublicKeyInfo data. - When this method returns, contains a value that indicates the number of bytes written to . This parameter is treated as uninitialized. - When overridden in a derived class, attempts to export the current key in the X.509 SubjectPublicKeyInfo format into a provided buffer. - - if is big enough to receive the output; otherwise, . - + has not been provided. + The key could not be exported. + + + + + + + + + + Method + + System.Security.Cryptography.Primitives + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + + + netstandard + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Boolean + + + + + + + The byte span to receive the X.509 SubjectPublicKeyInfo data. + When this method returns, contains a value that indicates the number of bytes written to . This parameter is treated as uninitialized. + When overridden in a derived class, attempts to export the current key in the X.509 SubjectPublicKeyInfo format into a provided buffer. + + if is big enough to receive the output; otherwise, . + throws a by default. - ]]> - - The key could not be exported. - A derived type has not overriden this member. - - - - - - - - - - - Method - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Security.Cryptography.Primitives - - - netstandard - - - mscorlib - - - System.Boolean - - - - - - - The character span to receive the PEM-encoded X.509 SubjectPublicKeyInfo data. - When this method returns, contains a value that indicates the number of characters written to . This parameter is treated as uninitialized. - Attempts to export the current key in the PEM-encoded X.509 SubjectPublicKeyInfo format into a provided buffer. - - if is big enough to receive the output; otherwise, . - + ]]> + + The key could not be exported. + A derived type has not overriden this member. + + + + + + + + + + + Method + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Security.Cryptography.Primitives + + + netstandard + + + mscorlib + + + System.Boolean + + + + + + + The character span to receive the PEM-encoded X.509 SubjectPublicKeyInfo data. + When this method returns, contains a value that indicates the number of characters written to . This parameter is treated as uninitialized. + Attempts to export the current key in the PEM-encoded X.509 SubjectPublicKeyInfo format into a provided buffer. + + if is big enough to receive the output; otherwise, . + - + ]]> + An implementation for - has not been provided. - The key could not be exported. - - - - + has not been provided. + The key could not be exported. + + + + diff --git a/xml/System.Security.Cryptography/CryptoStream.xml b/xml/System.Security.Cryptography/CryptoStream.xml index 4d85f1305d6..4a733375a1c 100644 --- a/xml/System.Security.Cryptography/CryptoStream.xml +++ b/xml/System.Security.Cryptography/CryptoStream.xml @@ -762,9 +762,9 @@ When the `disposing` parameter is `true`, this method releases all resources hel - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. -For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). +For more information about and , see Cleaning Up Unmanaged Resources. Cryptographic Services diff --git a/xml/System.Security.Cryptography/DeriveBytes.xml b/xml/System.Security.Cryptography/DeriveBytes.xml index 458a13c4e6b..f223394a156 100644 --- a/xml/System.Security.Cryptography/DeriveBytes.xml +++ b/xml/System.Security.Cryptography/DeriveBytes.xml @@ -176,16 +176,16 @@ When overridden in a derived class, 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. + ]]> @@ -236,20 +236,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. When overridden in a derived class, releases the unmanaged resources used by the class and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources. Cryptographic Services diff --git a/xml/System.Security.Cryptography/ECDiffieHellmanPublicKey.xml b/xml/System.Security.Cryptography/ECDiffieHellmanPublicKey.xml index 6eba8bd85f6..ef51b33e504 100644 --- a/xml/System.Security.Cryptography/ECDiffieHellmanPublicKey.xml +++ b/xml/System.Security.Cryptography/ECDiffieHellmanPublicKey.xml @@ -148,11 +148,11 @@ A byte array that represents an object. Initializes a new instance of the class. - class. The class is the only currently supported implementation. - + class. The class is the only currently supported implementation. + ]]> @@ -218,13 +218,13 @@ Releases all resources used by the current instance of the class. - 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). - + 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). + ]]> @@ -273,28 +273,28 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the class and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources. diff --git a/xml/System.Security.Cryptography/FromBase64Transform.xml b/xml/System.Security.Cryptography/FromBase64Transform.xml index 733e41bce69..fe836c44d73 100644 --- a/xml/System.Security.Cryptography/FromBase64Transform.xml +++ b/xml/System.Security.Cryptography/FromBase64Transform.xml @@ -65,20 +65,20 @@ Converts a from base 64. - Cryptographic Services @@ -131,11 +131,11 @@ Initializes a new instance of the class. - for more details. - + for more details. + ]]> Cryptographic Services @@ -182,15 +182,15 @@ One of the values. Initializes a new instance of the class with the specified transformation mode. - Cryptographic Services @@ -287,11 +287,11 @@ Gets a value that indicates whether multiple blocks can be transformed. Always . - Cryptographic Services @@ -338,13 +338,13 @@ Releases all resources used by the . - . - - 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). - + . + + 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 @@ -402,16 +402,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. + ]]> @@ -461,20 +461,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes the protected `Dispose(Boolean)` method with the disposing parameter set to `true`. `Finalize` invokes `Dispose` with disposing set to `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. - + method, if it has been overridden. `Dispose()` invokes the protected `Dispose(Boolean)` method with the disposing parameter set to `true`. `Finalize` invokes `Dispose` with disposing set to `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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources. Cryptographic Services @@ -567,11 +567,11 @@ Gets the input block size. The size of the input data blocks in bytes. - Cryptographic Services @@ -621,11 +621,11 @@ Gets the output block size. The size of the output data blocks in bytes. - Cryptographic Services @@ -665,7 +665,7 @@ references. This method invokes the Dispose() method of each referenced object. @@ -747,23 +747,23 @@ For more information about Dispose and Finalize, see [Cleaning Up Unmanaged Reso Converts the specified region of the input byte array from base 64 and copies the result to the specified region of the output byte array. The number of bytes written. - The current object has already been disposed. - uses an invalid value. - - -or- - + uses an invalid value. + + -or- + has an invalid offset length. is out of range. This parameter requires a non-negative number. @@ -834,23 +834,23 @@ For more information about Dispose and Finalize, see [Cleaning Up Unmanaged Reso Converts the specified region of the specified byte array from base 64. The computed conversion. - The current object has already been disposed. - has an invalid offset length. - - -or- - + has an invalid offset length. + + -or- + has an invalid value. is out of range. This parameter requires a non-negative number. diff --git a/xml/System.Security.Cryptography/HMAC.xml b/xml/System.Security.Cryptography/HMAC.xml index aad953e4971..45746519639 100644 --- a/xml/System.Security.Cryptography/HMAC.xml +++ b/xml/System.Security.Cryptography/HMAC.xml @@ -229,7 +229,7 @@ Creates an instance of the default implementation of a Hash-based Message Authentication Code (HMAC). - A new SHA-1 instance, unless the default settings have been changed by using the [<cryptoClass> element](/dotnet/framework/configure-apps/file-schema/cryptography/cryptoclass-element). + A new SHA-1 instance, unless the default settings have been changed by using the <cryptoClass> element. - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + For more information about and , see Cleaning Up Unmanaged Resources. diff --git a/xml/System.Security.Cryptography/HashAlgorithm.xml b/xml/System.Security.Cryptography/HashAlgorithm.xml index ec8096af3ef..916d6493421 100644 --- a/xml/System.Security.Cryptography/HashAlgorithm.xml +++ b/xml/System.Security.Cryptography/HashAlgorithm.xml @@ -835,9 +835,9 @@ This method is obsolete in .NET 5 and later versions. - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + For more information about and , see Cleaning Up Unmanaged Resources. diff --git a/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml b/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml index 582d1a3035b..fe2cdaabde2 100644 --- a/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml +++ b/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml @@ -380,9 +380,9 @@ This method supports a number of algorithms, including MD5, SHA-1, SHA-256, and - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + For more information about and , see Cleaning Up Unmanaged Resources. Cryptographic Services diff --git a/xml/System.Security.Cryptography/MACTripleDES.xml b/xml/System.Security.Cryptography/MACTripleDES.xml index d6c3d4b8def..b5db233287a 100644 --- a/xml/System.Security.Cryptography/MACTripleDES.xml +++ b/xml/System.Security.Cryptography/MACTripleDES.xml @@ -25,23 +25,23 @@ Computes a Message Authentication Code (MAC) using for the input data . - uses a key that is 16 or 24 bytes long, and produces a hash sequence that is 8 bytes long. - - - -## Examples - The following example creates a MAC for a file named `input.txt`, which is located in the folder that contains the example executable. The MAC and the original text are written to a file named `encrypted.hsh` in the same folder. The signed file is then read, and the MAC is calculated for the text portion of the file and compared to the MAC that is included with the text. - + uses a key that is 16 or 24 bytes long, and produces a hash sequence that is 8 bytes long. + + + +## Examples + The following example creates a MAC for a file named `input.txt`, which is located in the folder that contains the example executable. The MAC and the original text are written to a file named `encrypted.hsh` in the same folder. The signed file is then read, and the MAC is calculated for the text portion of the file and compared to the MAC that is included with the text. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/MACTripleDES/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MAC3DES/VB/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MAC3DES/VB/program.vb" id="Snippet1"::: + ]]> @@ -79,11 +79,11 @@ Initializes a new instance of the class. - . - + . + ]]> @@ -115,16 +115,16 @@ The secret key for encryption. Initializes a new instance of the class with the specified key data. - . The `rgbKey` parameter must be 16 or 24 bytes in length. - - - -## Examples - For an example of how to use this constructor, see the class. - + . The `rgbKey` parameter must be 16 or 24 bytes in length. + + + +## Examples + For an example of how to use this constructor, see the class. + ]]> The parameter is . @@ -159,13 +159,13 @@ The secret key for encryption. Initializes a new instance of the class with the specified key data and using the specified implementation of . - implementation type. The default implementation is System.Security.Cryptography.TripleDES. - - The `rgbKey` parameter must be 16 or 24 bytes in length. - + implementation type. The default implementation is System.Security.Cryptography.TripleDES. + + The `rgbKey` parameter must be 16 or 24 bytes in length. + ]]> The parameter is . @@ -197,20 +197,20 @@ if the method is called from an implementation; otherwise, . Releases the resources used by the instance. - method, if it has been overridden. `Dispose()` invokes the protected `Dispose(Boolean)` method with the disposing parameter set to `true`. `Finalize` invokes `Dispose` with disposing set to `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. - + method, if it has been overridden. `Dispose()` invokes the protected `Dispose(Boolean)` method with the disposing parameter set to `true`. `Finalize` invokes `Dispose` with disposing set to `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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources. @@ -288,11 +288,11 @@ Returns the computed Message Authentication Code (MAC) after all data is written to the object. The computed MAC. - for each separate segment of data to compute the MAC for that data. - + for each separate segment of data to compute the MAC for that data. + ]]> @@ -318,11 +318,11 @@ Initializes an instance of . - @@ -353,13 +353,13 @@ Gets or sets the padding mode used in the hashing algorithm. The padding mode used in the hashing algorithm. - for a description of specific modes. - - This field is accessed through the property. - + for a description of specific modes. + + This field is accessed through the property. + ]]> The property cannot be set because the padding mode is invalid. diff --git a/xml/System.Security.Cryptography/PasswordDeriveBytes.xml b/xml/System.Security.Cryptography/PasswordDeriveBytes.xml index b0af77c8fcd..439950844f2 100644 --- a/xml/System.Security.Cryptography/PasswordDeriveBytes.xml +++ b/xml/System.Security.Cryptography/PasswordDeriveBytes.xml @@ -67,23 +67,23 @@ Derives a key from a password using an extension of the PBKDF1 algorithm. - [!IMPORTANT] -> Never hard-code a password within your source code. Hard coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) tool, a hex editor, or by simply opening up the assembly in a text editor like notepad.exe. - - - -## Examples - The following code example creates a key from a password using the class. - +> Never hard-code a password within your source code. Hard coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) tool, a hex editor, or by simply opening up the assembly in a text editor like notepad.exe. + + + +## Examples + The following code example creates a key from a password using the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.PasswordDerivedbytes/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/PasswordDeriveBytes/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.PasswordDerivedbytes/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.PasswordDerivedbytes/VB/sample.vb" id="Snippet1"::: + ]]> Cryptographic Services @@ -155,22 +155,22 @@ The key salt to use to derive the key. Initializes a new instance of the class specifying the password and key salt to use to derive the key. - [!IMPORTANT] -> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening up the assembly in a text editor such as Notepad.exe. - - - -## Examples - The following code example creates a key from a password using the class. - +> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening up the assembly in a text editor such as Notepad.exe. + + + +## Examples + The following code example creates a key from a password using the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.PasswordDerivedbytes/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/PasswordDeriveBytes/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.PasswordDerivedbytes/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.PasswordDerivedbytes/VB/sample.vb" id="Snippet1"::: + ]]> Cryptographic Services @@ -233,13 +233,13 @@ The key salt to use to derive the key. Initializes a new instance of the class with the password and key salt to use to derive the key. - [!IMPORTANT] -> Never hard-code a password within your source code. Hard coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) tool, a hex editor, or by simply opening up the assembly in a text editor like notepad.exe. - +> Never hard-code a password within your source code. Hard coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) tool, a hex editor, or by simply opening up the assembly in a text editor like notepad.exe. + ]]> Cryptographic Services @@ -307,22 +307,22 @@ The cryptographic service provider (CSP) parameters for the operation. Initializes a new instance of the class specifying the password, key salt, and cryptographic service provider (CSP) to use to derive the key. - [!IMPORTANT] -> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) l, a hex editor, or by simply opening up the assembly in a text editor such as Notepad.exe. - - - -## Examples - The following code example creates a key from a password using the class. - +> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) l, a hex editor, or by simply opening up the assembly in a text editor such as Notepad.exe. + + + +## Examples + The following code example creates a key from a password using the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.PasswordDerivedbytes/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/PasswordDeriveBytes/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.PasswordDerivedbytes/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.PasswordDerivedbytes/VB/sample.vb" id="Snippet1"::: + ]]> Cryptographic Services @@ -391,13 +391,13 @@ The CSP parameters for the operation. Initializes a new instance of the class with the password, key salt, and cryptographic service provider (CSP) parameters to use to derive the key. - [!IMPORTANT] -> Never hard-code a password within your source code. Hard coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) tool, a hex editor, or by simply opening up the assembly in a text editor like notepad.exe. - +> Never hard-code a password within your source code. Hard coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) tool, a hex editor, or by simply opening up the assembly in a text editor like notepad.exe. + ]]> Cryptographic Services @@ -467,15 +467,15 @@ The iteration count to use to derive the key. Initializes a new instance of the class specifying the password, key salt, hash name, and iterations to use to derive the key. - [!IMPORTANT] -> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening up the assembly in a text editor such as Notepad.exe. - - For a list of hash algorithm names, see the class. - +> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening up the assembly in a text editor such as Notepad.exe. + + For a list of hash algorithm names, see the class. + ]]> @@ -547,15 +547,15 @@ The number of iterations for the operation. Initializes a new instance of the class with the password, key salt, hash name, and number of iterations to use to derive the key. - [!IMPORTANT] -> Never hard-code a password within your source code. Hard coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) tool, a hex editor, or by simply opening up the assembly in a text editor like notepad.exe. - - For a list of hash algorithm names, see the class. - +> Never hard-code a password within your source code. Hard coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) tool, a hex editor, or by simply opening up the assembly in a text editor like notepad.exe. + + For a list of hash algorithm names, see the class. + ]]> @@ -635,15 +635,15 @@ The cryptographic service provider (CSP) parameters for the operation. Initializes a new instance of the class specifying the password, key salt, hash name, iterations, and cryptographic service provider (CSP) to use to derive the key. - [!IMPORTANT] -> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening up the assembly in a text editor such as Notepad.exe. - - For a list of hash algorithm names, see the class. - +> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening up the assembly in a text editor such as Notepad.exe. + + For a list of hash algorithm names, see the class. + ]]> @@ -724,15 +724,15 @@ The CSP parameters for the operation. Initializes a new instance of the class with the password, key salt, hash name, number of iterations, and cryptographic service provider (CSP) parameters to use to derive the key. - [!IMPORTANT] -> Never hard-code a password within your source code. Hard coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) tool, a hex editor, or by simply opening up the assembly in a text editor like notepad.exe. - - For a list of hash algorithm names, see the class. - +> Never hard-code a password within your source code. Hard coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) tool, a hex editor, or by simply opening up the assembly in a text editor like notepad.exe. + + For a list of hash algorithm names, see the class. + ]]> @@ -815,36 +815,36 @@ Derives a cryptographic key from the object. The derived key. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.PasswordDerivedbytes/cpp/sample.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/PasswordDeriveBytes/Overview/sample.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.PasswordDerivedbytes/VB/sample.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.PasswordDerivedbytes/VB/sample.vb" id="Snippet2"::: + ]]> - The parameter is incorrect. - - -or- - - The cryptographic service provider (CSP) cannot be acquired. - - -or- - - The parameter is not a valid algorithm name. - - -or- - + The parameter is incorrect. + + -or- + + The cryptographic service provider (CSP) cannot be acquired. + + -or- + + The parameter is not a valid algorithm name. + + -or- + The parameter is not a valid hash algorithm name. Cryptographic Services @@ -892,20 +892,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the class and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources. @@ -994,11 +994,11 @@ Returns pseudo-random key bytes. A byte array filled with pseudo-random key bytes. - Cryptographic Services @@ -1205,11 +1205,11 @@ Gets or sets the key salt value for the operation. The key salt value for the operation. - The key salt value is fixed and an attempt is made to change this value. diff --git a/xml/System.Security.Cryptography/RandomNumberGenerator.xml b/xml/System.Security.Cryptography/RandomNumberGenerator.xml index 1c06079907e..85e8c21d824 100644 --- a/xml/System.Security.Cryptography/RandomNumberGenerator.xml +++ b/xml/System.Security.Cryptography/RandomNumberGenerator.xml @@ -1,79 +1,79 @@ - - - - - - - - - - - - - - System.Security.Cryptography.Algorithms - 4.0.0.0 - 4.1.0.0 - 4.2.0.0 - 4.3.0.0 - 4.3.1.0 - 4.3.2.0 - 5.0.0.0 - 6.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - - - - - - - - - - System.Object - - - - System.IDisposable - - - - - [System.Runtime.CompilerServices.Nullable(0)] - [<System.Runtime.CompilerServices.Nullable(0)>] - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [System.Runtime.InteropServices.ComVisible(true)] - [<System.Runtime.InteropServices.ComVisible(true)>] - - - - Provides functionality for generating random values. - + + + + + + + + + + + + + + System.Security.Cryptography.Algorithms + 4.0.0.0 + 4.1.0.0 + 4.2.0.0 + 4.3.0.0 + 4.3.1.0 + 4.3.2.0 + 5.0.0.0 + 6.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + + + + + + + + + + System.Object + + + + System.IDisposable + + + + + [System.Runtime.CompilerServices.Nullable(0)] + [<System.Runtime.CompilerServices.Nullable(0)>] + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [System.Runtime.InteropServices.ComVisible(true)] + [<System.Runtime.InteropServices.ComVisible(true)>] + + + + Provides functionality for generating random values. + - - Cryptographic Services - - - - - - - - - - - - - Constructor - - System.Security.Cryptography.Algorithms - 4.0.0.0 - 4.1.0.0 - 4.2.0.0 - 4.3.0.0 - 4.3.1.0 - 4.3.2.0 - 5.0.0.0 - 6.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - Initializes a new instance of . - + ]]> + + Cryptographic Services + + + + + + + + + + + + + Constructor + + System.Security.Cryptography.Algorithms + 4.0.0.0 + 4.1.0.0 + 4.2.0.0 + 4.3.0.0 + 4.3.1.0 + 4.3.2.0 + 5.0.0.0 + 6.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + Initializes a new instance of . + . - ]]> - - Cryptographic Services - - - - - System.Security.Cryptography.Algorithms - 4.0.0.0 - 4.1.0.0 - 4.2.0.0 - 4.3.0.0 - - - Creates an instance of an implementation of a cryptographic random number generator. - - - - - - - - - - Method - - System.Security.Cryptography.Algorithms - 4.0.0.0 - 4.1.0.0 - 4.2.0.0 - 4.3.0.0 - 4.3.1.0 - 4.3.2.0 - 5.0.0.0 - 6.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Security.Cryptography.RandomNumberGenerator - - - - Creates an instance of the default implementation of a cryptographic random number generator that can be used to generate random data. - A new instance of a cryptographic random number generator. - To be added. - Cryptographic Services - - - - - - - - - - - Method - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography.Algorithms - 4.3.0.0 - 4.3.1.0 - 4.3.2.0 - 5.0.0.0 - 6.0.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - [System.Runtime.Versioning.UnsupportedOSPlatform("browser")] - [<System.Runtime.Versioning.UnsupportedOSPlatform("browser")>] - - - [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("The default algorithm implementations might be removed, use strong type references like 'RSA.Create()' instead.")] - [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("The default algorithm implementations might be removed, use strong type references like 'RSA.Create()' instead.")>] - - - [System.Obsolete("Cryptographic factory methods accepting an algorithm name are obsolete. Use the parameterless Create factory method on the algorithm type instead.", DiagnosticId="SYSLIB0045", UrlFormat="https://aka.ms/dotnet-warnings/{0}")] - [<System.Obsolete("Cryptographic factory methods accepting an algorithm name are obsolete. Use the parameterless Create factory method on the algorithm type instead.", DiagnosticId="SYSLIB0045", UrlFormat="https://aka.ms/dotnet-warnings/{0}")>] - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Security.Cryptography.RandomNumberGenerator - - - - - - The name of the random number generator implementation to use. - Creates an instance of the specified implementation of a cryptographic random number generator. - A new instance of a cryptographic random number generator. - To be added. - Cryptographic Services - - - - - System.Security.Cryptography.Algorithms - 4.0.0.0 - 4.1.0.0 - 4.2.0.0 - 4.3.0.0 - - - When overridden in a derived class, releases the unmanaged resources used by the current instance of the class. - - - - - - - - - - Method - - M:System.IDisposable.Dispose - - - System.Security.Cryptography.Algorithms - 4.0.0.0 - 4.1.0.0 - 4.2.0.0 - 4.3.0.0 - 4.3.1.0 - 4.3.2.0 - 5.0.0.0 - 6.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Void - - - - When overridden in a derived class, releases all resources used by the current instance of the class. - + ]]> + + Cryptographic Services + + + + + System.Security.Cryptography.Algorithms + 4.0.0.0 + 4.1.0.0 + 4.2.0.0 + 4.3.0.0 + + + Creates an instance of an implementation of a cryptographic random number generator. + + + + + + + + + + Method + + System.Security.Cryptography.Algorithms + 4.0.0.0 + 4.1.0.0 + 4.2.0.0 + 4.3.0.0 + 4.3.1.0 + 4.3.2.0 + 5.0.0.0 + 6.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Security.Cryptography.RandomNumberGenerator + + + + Creates an instance of the default implementation of a cryptographic random number generator that can be used to generate random data. + A new instance of a cryptographic random number generator. + To be added. + Cryptographic Services + + + + + + + + + + + Method + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography.Algorithms + 4.3.0.0 + 4.3.1.0 + 4.3.2.0 + 5.0.0.0 + 6.0.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + [System.Runtime.Versioning.UnsupportedOSPlatform("browser")] + [<System.Runtime.Versioning.UnsupportedOSPlatform("browser")>] + + + [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("The default algorithm implementations might be removed, use strong type references like 'RSA.Create()' instead.")] + [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("The default algorithm implementations might be removed, use strong type references like 'RSA.Create()' instead.")>] + + + [System.Obsolete("Cryptographic factory methods accepting an algorithm name are obsolete. Use the parameterless Create factory method on the algorithm type instead.", DiagnosticId="SYSLIB0045", UrlFormat="https://aka.ms/dotnet-warnings/{0}")] + [<System.Obsolete("Cryptographic factory methods accepting an algorithm name are obsolete. Use the parameterless Create factory method on the algorithm type instead.", DiagnosticId="SYSLIB0045", UrlFormat="https://aka.ms/dotnet-warnings/{0}")>] + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Security.Cryptography.RandomNumberGenerator + + + + + + The name of the random number generator implementation to use. + Creates an instance of the specified implementation of a cryptographic random number generator. + A new instance of a cryptographic random number generator. + To be added. + Cryptographic Services + + + + + System.Security.Cryptography.Algorithms + 4.0.0.0 + 4.1.0.0 + 4.2.0.0 + 4.3.0.0 + + + When overridden in a derived class, releases the unmanaged resources used by the current instance of the class. + + + + + + + + + + Method + + M:System.IDisposable.Dispose + + + System.Security.Cryptography.Algorithms + 4.0.0.0 + 4.1.0.0 + 4.2.0.0 + 4.3.0.0 + 4.3.1.0 + 4.3.2.0 + 5.0.0.0 + 6.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Void + + + + When overridden in a derived class, releases all resources used by the current instance of the class. + [!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. - ]]> - - - - - - - - - - - Method - - System.Security.Cryptography.Algorithms - 4.0.0.0 - 4.1.0.0 - 4.2.0.0 - 4.3.0.0 - 4.3.1.0 - 4.3.2.0 - 5.0.0.0 - 6.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Void - - - - - - - to release both managed and unmanaged resources; to release only unmanaged resources. - When overridden in a derived class, releases the unmanaged resources used by the and optionally releases the managed resources. - + ]]> + + + + + + + + + + + Method + + System.Security.Cryptography.Algorithms + 4.0.0.0 + 4.1.0.0 + 4.2.0.0 + 4.3.0.0 + 4.3.1.0 + 4.3.2.0 + 5.0.0.0 + 6.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Void + + + + + + + to release both managed and unmanaged resources; to release only unmanaged resources. + When overridden in a derived class, releases the unmanaged resources used by the and optionally releases the managed resources. + references. This method invokes the `Dispose()` method of each referenced object. - ]]> - - - - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + ]]> + + + + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - - Cryptographic Services - - - - - - - - - - Method - - System.Security.Cryptography.Algorithms - 4.3.1.0 - 4.3.2.0 - 5.0.0.0 - 6.0.0.0 - - - netstandard - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Void - - - - - - The span to fill with cryptographically strong random bytes. - Fills a span with cryptographically strong random bytes. - To be added. - - - - - System.Security.Cryptography.Algorithms - 4.0.0.0 - 4.1.0.0 - 4.2.0.0 - 4.3.0.0 - - - Fills an array of bytes with a cryptographically strong random sequence of values. - - - - - - - - - - Method - - System.Security.Cryptography.Algorithms - 4.0.0.0 - 4.1.0.0 - 4.2.0.0 - 4.3.0.0 - 4.3.1.0 - 4.3.2.0 - 5.0.0.0 - 6.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Void - - - - - - The array to fill with cryptographically strong random bytes. - When overridden in a derived class, fills an array of bytes with a cryptographically strong random sequence of values. - + For more information about and , see Cleaning Up Unmanaged Resources. + + Cryptographic Services + + + + + + + + + + Method + + System.Security.Cryptography.Algorithms + 4.3.1.0 + 4.3.2.0 + 5.0.0.0 + 6.0.0.0 + + + netstandard + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Void + + + + + + The span to fill with cryptographically strong random bytes. + Fills a span with cryptographically strong random bytes. + To be added. + + + + + System.Security.Cryptography.Algorithms + 4.0.0.0 + 4.1.0.0 + 4.2.0.0 + 4.3.0.0 + + + Fills an array of bytes with a cryptographically strong random sequence of values. + + + + + + + + + + Method + + System.Security.Cryptography.Algorithms + 4.0.0.0 + 4.1.0.0 + 4.2.0.0 + 4.3.0.0 + 4.3.1.0 + 4.3.2.0 + 5.0.0.0 + 6.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Void + + + + + + The array to fill with cryptographically strong random bytes. + When overridden in a derived class, fills an array of bytes with a cryptographically strong random sequence of values. + - - Cryptographic Services - - - - - - - - - - - Method - - System.Security.Cryptography.Algorithms - 6.0.0.0 - - - mscorlib - - - netstandard - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Byte[] - - - - - - The number of bytes of random values to create. - Creates an array of bytes with a cryptographically strong random sequence of values. - An array populated with cryptographically strong random values. - To be added. - - is less than zero. - - - - - - - - - - Method - - System.Security.Cryptography.Algorithms - 4.3.1.0 - 4.3.2.0 - 5.0.0.0 - 6.0.0.0 - - - netstandard - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Void - - - - - - The span to fill with cryptographically strong random bytes. - Fills a span with cryptographically strong random bytes. - To be added. - - - - - - - - - - - Method - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography.Algorithms - 4.3.0.0 - 4.3.1.0 - 4.3.2.0 - 5.0.0.0 - 6.0.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Void - - - - - - - - The array to fill with cryptographically strong random bytes. - The index of the array to start the fill operation. - The number of bytes to fill. - Fills the specified byte array with a cryptographically strong random sequence of values. - To be added. - - is . - - or is less than 0 - - plus exceeds the length of . - - - - - - - - - Method - - System.Security.Cryptography - 8.0.0.0 - 9.0.0.0 - - - System.Security.Cryptography.Algorithms - - - netstandard - - - mscorlib - - - System.String - - - - - - - The length of string to create. - + ]]> + + Cryptographic Services + + + + + + + + + + + Method + + System.Security.Cryptography.Algorithms + 6.0.0.0 + + + mscorlib + + + netstandard + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Byte[] + + + + + + The number of bytes of random values to create. + Creates an array of bytes with a cryptographically strong random sequence of values. + An array populated with cryptographically strong random values. + To be added. + + is less than zero. + + + + + + + + + + Method + + System.Security.Cryptography.Algorithms + 4.3.1.0 + 4.3.2.0 + 5.0.0.0 + 6.0.0.0 + + + netstandard + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Void + + + + + + The span to fill with cryptographically strong random bytes. + Fills a span with cryptographically strong random bytes. + To be added. + + + + + + + + + + + Method + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography.Algorithms + 4.3.0.0 + 4.3.1.0 + 4.3.2.0 + 5.0.0.0 + 6.0.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Void + + + + + + + + The array to fill with cryptographically strong random bytes. + The index of the array to start the fill operation. + The number of bytes to fill. + Fills the specified byte array with a cryptographically strong random sequence of values. + To be added. + + is . + + or is less than 0 + + plus exceeds the length of . + + + + + + + + + Method + + System.Security.Cryptography + 8.0.0.0 + 9.0.0.0 + + + System.Security.Cryptography.Algorithms + + + netstandard + + + mscorlib + + + System.String + + + + + + + The length of string to create. + if the hexadecimal characters should be lowercase; if they should be uppercase. - The default is . - Creates a string filled with cryptographically random hexadecimal characters. - A string populated with random hexadecimal characters. - The behavior of this is the same as using and specifying hexadecimal characters as the choices. This implementation is optimized specifically for hexadecimal characters. - - - - - - - - - Method - - System.Security.Cryptography - 8.0.0.0 - 9.0.0.0 - - - System.Security.Cryptography.Algorithms - - - netstandard - - - mscorlib - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Void - - - - - - - The buffer to receive the characters. - + The default is . + Creates a string filled with cryptographically random hexadecimal characters. + A string populated with random hexadecimal characters. + The behavior of this is the same as using and specifying hexadecimal characters as the choices. This implementation is optimized specifically for hexadecimal characters. + + + + + + + + + Method + + System.Security.Cryptography + 8.0.0.0 + 9.0.0.0 + + + System.Security.Cryptography.Algorithms + + + netstandard + + + mscorlib + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Void + + + + + + + The buffer to receive the characters. + if the hexadecimal characters should be lowercase; if they should be uppercase. - The default is . - Fills a buffer with cryptographically random hexadecimal characters. - The behavior of this is the same as using and specifying hexadecimal characters as the choices. This implementation is optimized specifically for hexadecimal characters. - - - - - - - - - - Method - - System.Security.Cryptography.Algorithms - 4.3.1.0 - 4.3.2.0 - 5.0.0.0 - 6.0.0.0 - - - netstandard - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Int32 - - - - - - The exclusive upper bound of the random range. - Generates a random integer between 0 (inclusive) and a specified exclusive upper bound using a cryptographically strong random number generator. - A random integer between 0 (inclusive) and (exclusive). - + The default is . + Fills a buffer with cryptographically random hexadecimal characters. + The behavior of this is the same as using and specifying hexadecimal characters as the choices. This implementation is optimized specifically for hexadecimal characters. + + + + + + + + + + Method + + System.Security.Cryptography.Algorithms + 4.3.1.0 + 4.3.2.0 + 5.0.0.0 + 6.0.0.0 + + + netstandard + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Int32 + + + + + + The exclusive upper bound of the random range. + Generates a random integer between 0 (inclusive) and a specified exclusive upper bound using a cryptographically strong random number generator. + A random integer between 0 (inclusive) and (exclusive). + - - The parameter is less than or equal to 0. - - - - - - - - - - Method - - System.Security.Cryptography.Algorithms - 4.3.1.0 - 4.3.2.0 - 5.0.0.0 - 6.0.0.0 - - - netstandard - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Int32 - - - - - - - The inclusive lower bound of the random range. - The exclusive upper bound of the random range. - Generates a random integer between a specified inclusive lower bound and a specified exclusive upper bound using a cryptographically strong random number generator. - A random integer between (inclusive) and (exclusive). - + ]]> + + The parameter is less than or equal to 0. + + + + + + + + + + Method + + System.Security.Cryptography.Algorithms + 4.3.1.0 + 4.3.2.0 + 5.0.0.0 + 6.0.0.0 + + + netstandard + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Int32 + + + + + + + The inclusive lower bound of the random range. + The exclusive upper bound of the random range. + Generates a random integer between a specified inclusive lower bound and a specified exclusive upper bound using a cryptographically strong random number generator. + A random integer between (inclusive) and (exclusive). + - - The parameter is less than or equal to the parameter. - - - - - - - - - - Method - - System.Security.Cryptography - 8.0.0.0 - 9.0.0.0 - - - System.Security.Cryptography.Algorithms - - - netstandard - - - mscorlib - - - T[] - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 1 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 1 })>] - - - - - - - The type of items. - The items to use to populate the array. - The length of array to return populated with items. - Creates an array populated with items chosen at random from choices. - An array populated with random choices. - To be added. - - is empty. - - is not zero or a positive number. - - - - - - - - - - Method - - System.Security.Cryptography - 8.0.0.0 - 9.0.0.0 - - - System.Security.Cryptography.Algorithms - - - netstandard - - - mscorlib - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Void - - - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 1 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 1 })>] - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 1 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 1 })>] - - - - - - The type of items. - The items to use to fill the buffer. - The buffer to receive the items. - Fills the elements of a specified span with items chosen at random from the provided set of choices. - To be added. - - is empty. - - - - - - - - - - - - - - Method - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Security.Cryptography.Algorithms - 4.3.0.0 - 4.3.1.0 - 4.3.2.0 - 5.0.0.0 - 6.0.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - System.Void - - - - - - The array to fill with cryptographically strong random nonzero bytes. - When overridden in a derived class, fills an array of bytes with a cryptographically strong random sequence of nonzero values. - + ]]> + + The parameter is less than or equal to the parameter. + + + + + + + + + + Method + + System.Security.Cryptography + 8.0.0.0 + 9.0.0.0 + + + System.Security.Cryptography.Algorithms + + + netstandard + + + mscorlib + + + T[] + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 1 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 1 })>] + + + + + + + The type of items. + The items to use to populate the array. + The length of array to return populated with items. + Creates an array populated with items chosen at random from choices. + An array populated with random choices. + To be added. + + is empty. + + is not zero or a positive number. + + + + + + + + + + Method + + System.Security.Cryptography + 8.0.0.0 + 9.0.0.0 + + + System.Security.Cryptography.Algorithms + + + netstandard + + + mscorlib + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.Void + + + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 1 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 1 })>] + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 1 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 1 })>] + + + + + + The type of items. + The items to use to fill the buffer. + The buffer to receive the items. + Fills the elements of a specified span with items chosen at random from the provided set of choices. + To be added. + + is empty. + + + + + + + + + + + + + + Method + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Security.Cryptography.Algorithms + 4.3.0.0 + 4.3.1.0 + 4.3.2.0 + 5.0.0.0 + 6.0.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + System.Void + + + + + + The array to fill with cryptographically strong random nonzero bytes. + When overridden in a derived class, fills an array of bytes with a cryptographically strong random sequence of nonzero values. + - - Cryptographic Services - - - - - - - - - - Method - - System.Security.Cryptography.Algorithms - 4.3.1.0 - 4.3.2.0 - 5.0.0.0 - 6.0.0.0 - - - netstandard - 2.1.0.0 - - - System.Security.Cryptography - 7.0.0.0 - 8.0.0.0 - 9.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Void - - - - - - The span to fill with cryptographically strong random nonzero bytes. - Fills a byte span with a cryptographically strong random sequence of nonzero values. - To be added. - - - - - - - - - - Method - - System.Security.Cryptography - 8.0.0.0 - 9.0.0.0 - - - System.Security.Cryptography.Algorithms - - - netstandard - - - mscorlib - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.String - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - - - - - - - The characters to use to populate the string. - The length of string to return. - Creates a string populated with characters chosen at random from choices. - A string populated with random choices. - To be added. - - is empty. - - is not zero or a positive number. - - - - - - - - - - Method - - System.Security.Cryptography - 8.0.0.0 - 9.0.0.0 - - - System.Security.Cryptography.Algorithms - - - netstandard - - - mscorlib - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Void - - - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 1 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 1 })>] - - - - - - The type of span. - The span to shuffle. - Performs an in-place shuffle of a span using cryptographically random number generation. - To be added. - - - - + ]]> + + Cryptographic Services + + + + + + + + + + Method + + System.Security.Cryptography.Algorithms + 4.3.1.0 + 4.3.2.0 + 5.0.0.0 + 6.0.0.0 + + + netstandard + 2.1.0.0 + + + System.Security.Cryptography + 7.0.0.0 + 8.0.0.0 + 9.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Void + + + + + + The span to fill with cryptographically strong random nonzero bytes. + Fills a byte span with a cryptographically strong random sequence of nonzero values. + To be added. + + + + + + + + + + Method + + System.Security.Cryptography + 8.0.0.0 + 9.0.0.0 + + + System.Security.Cryptography.Algorithms + + + netstandard + + + mscorlib + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.String + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + + + + + + + The characters to use to populate the string. + The length of string to return. + Creates a string populated with characters chosen at random from choices. + A string populated with random choices. + To be added. + + is empty. + + is not zero or a positive number. + + + + + + + + + + Method + + System.Security.Cryptography + 8.0.0.0 + 9.0.0.0 + + + System.Security.Cryptography.Algorithms + + + netstandard + + + mscorlib + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.Void + + + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 1 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 1 })>] + + + + + + The type of span. + The span to shuffle. + Performs an in-place shuffle of a span using cryptographically random number generation. + To be added. + + + + diff --git a/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml b/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml index 7fe5d605508..78b56810860 100644 --- a/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml +++ b/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml @@ -68,25 +68,25 @@ Implements password-based key derivation functionality, PBKDF2, by using a pseudo-random number generator based on . - 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. - + 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. + For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/info/rfc2898), titled "PKCS #5: Password-Based Cryptography Specification Version 2.0". See section 5.2, "PBKDF2," for complete details. - + > [!IMPORTANT] > Never hard-code a password within your source code. Hard-coded passwords can be retrieved from an assembly by using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), by using a hexadecimal editor, or by simply opening up the assembly in a text editor such as Notepad.exe. - -## Examples - The following code example uses the class to create two identical keys for the class. It then encrypts and decrypts some data using the keys. - + +## Examples + The following code example uses the class to create two identical keys for the class. It then encrypts and decrypts some data using the keys. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/rfc28981/CPP/rfc28981.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/Rfc2898DeriveBytes/Overview/rfc28981.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/rfc28981/vb/rfc28981.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/rfc28981/vb/rfc28981.vb" id="Snippet1"::: + ]]> Cryptographic Services @@ -155,25 +155,25 @@ The key salt used to derive the key. Initializes a new instance of the class using a password and salt to derive the key. - 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. - + 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. + For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/info/rfc2898), titled "PKCS #5: Password-Based Cryptography Specification Version 2.0". See section 5.2, "PBKDF2," for complete details. - + > [!IMPORTANT] > Never hard-code a password within your source code. Hard-coded passwords can be retrieved from an assembly by using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), by using a hexadecimal editor, or by simply opening up the assembly in a text editor such as Notepad.exe. - -## Examples - The following code example uses the class to create two identical keys for the class. It then encrypts and decrypts some data using the keys. - + +## Examples + The following code example uses the class to create two identical keys for the class. It then encrypts and decrypts some data using the keys. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/rfc28981/CPP/rfc28981.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/Rfc2898DeriveBytes/Overview/rfc28981.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/rfc28981/vb/rfc28981.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/rfc28981/vb/rfc28981.vb" id="Snippet1"::: + ]]> The specified salt size is smaller than 8 bytes or the iteration count is less than 1. @@ -232,18 +232,18 @@ The size of the random salt that you want the class to generate. Initializes a new instance of the class using the password and salt size to derive the key. - 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. - + 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. + For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/info/rfc2898), titled "PKCS #5: Password-Based Cryptography Specification Version 2.0". See section 5.2, "PBKDF2," for complete details. - + > [!IMPORTANT] -> Never hard-code a password within your source code. Hard-coded passwords can be retrieved from an assembly by using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), by using a hexadecimal editor, or by simply opening up the assembly in a text editor such as Notepad.exe. - +> Never hard-code a password within your source code. Hard-coded passwords can be retrieved from an assembly by using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), by using a hexadecimal editor, or by simply opening up the assembly in a text editor such as Notepad.exe. + ]]> The specified salt size is smaller than 8 bytes. @@ -308,18 +308,18 @@ For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/inf The number of iterations for the operation. Initializes a new instance of the class using a password, a salt, and number of iterations to derive the key. - 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. - + 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. + For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/info/rfc2898), titled "PKCS #5: Password-Based Cryptography Specification Version 2.0". See section 5.2, "PBKDF2," for complete details. - + > [!IMPORTANT] -> Never hard-code a password within your source code. Hard-coded passwords can be retrieved from an assembly by using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), by using a hexadecimal editor, or by simply opening up the assembly in a text editor such as Notepad.exe. - +> Never hard-code a password within your source code. Hard-coded passwords can be retrieved from an assembly by using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), by using a hexadecimal editor, or by simply opening up the assembly in a text editor such as Notepad.exe. + ]]> The specified salt size is smaller than 8 bytes or the iteration count is less than 1. @@ -379,25 +379,25 @@ For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/inf The number of iterations for the operation. Initializes a new instance of the class using a password, a salt, and number of iterations to derive the key. - 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. - + 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. + For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/info/rfc2898), titled "PKCS #5: Password-Based Cryptography Specification Version 2.0". See section 5.2, "PBKDF2," for complete details. - + > [!IMPORTANT] > Never hard-code a password within your source code. Hard-coded passwords can be retrieved from an assembly by using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), by using a hexadecimal editor, or by simply opening up the assembly in a text editor such as Notepad.exe. - -## Examples - The following code example uses the class to create two identical keys for the class. It then encrypts and decrypts some data using the keys. - + +## Examples + The following code example uses the class to create two identical keys for the class. It then encrypts and decrypts some data using the keys. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/rfc28981/CPP/rfc28981.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/Rfc2898DeriveBytes/Overview/rfc28981.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/rfc28981/vb/rfc28981.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/rfc28981/vb/rfc28981.vb" id="Snippet1"::: + ]]> The specified salt size is smaller than 8 bytes or the iteration count is less than 1. @@ -462,18 +462,18 @@ For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/inf The number of iterations for the operation. Initializes a new instance of the class using a password, a salt size, and number of iterations to derive the key. - 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. - + 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. + For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/info/rfc2898), titled "PKCS #5: Password-Based Cryptography Specification Version 2.0". See section 5.2, "PBKDF2," for complete details. - + > [!IMPORTANT] -> Never hard-code a password within your source code. Hard-coded passwords can be retrieved from an assembly by using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), by using a hexadecimal editor, or by simply opening up the assembly in a text editor such as Notepad.exe. - +> Never hard-code a password within your source code. Hard-coded passwords can be retrieved from an assembly by using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), by using a hexadecimal editor, or by simply opening up the assembly in a text editor such as Notepad.exe. + ]]> The specified salt size is smaller than 8 bytes or the iteration count is less than 1. @@ -699,27 +699,27 @@ For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/inf Derives a cryptographic key from the object. The derived key. - - The parameter is incorrect. - - -or- - - The cryptographic service provider (CSP) cannot be acquired. - - -or- - - The parameter is not a valid algorithm name. - - -or- - + The parameter is incorrect. + + -or- + + The cryptographic service provider (CSP) cannot be acquired. + + -or- + + The parameter is not a valid algorithm name. + + -or- + The parameter is not a valid hash algorithm name. @@ -769,20 +769,20 @@ For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/inf to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the class and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources. @@ -839,20 +839,20 @@ For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/inf Returns the pseudo-random key for this object. A byte array filled with pseudo-random key bytes. - 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. - + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/rfc28981/CPP/rfc28981.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/Rfc2898DeriveBytes/Overview/rfc28981.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/rfc28981/vb/rfc28981.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/rfc28981/vb/rfc28981.vb" id="Snippet2"::: + ]]> @@ -938,20 +938,20 @@ For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/inf Gets or sets the number of iterations for the operation. The number of iterations for the operation. - property to display the number of iterations used in the generation of the key. This code example is part of a larger example provided for the class. - + property to display the number of iterations used in the generation of the key. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/rfc28981/CPP/rfc28981.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/Rfc2898DeriveBytes/Overview/rfc28981.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/rfc28981/vb/rfc28981.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/rfc28981/vb/rfc28981.vb" id="Snippet3"::: + ]]> The number of iterations is less than 1. @@ -1385,20 +1385,20 @@ The `password` will be converted to bytes using the UTF8 encoding. For Resets the state of the operation. - method. This code example is part of a larger example provided for the class. - + method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/rfc28981/CPP/rfc28981.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/Rfc2898DeriveBytes/Overview/rfc28981.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/rfc28981/vb/rfc28981.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/rfc28981/vb/rfc28981.vb" id="Snippet5"::: + ]]> Cryptographic Services @@ -1447,11 +1447,11 @@ The `password` will be converted to bytes using the UTF8 encoding. For Gets or sets the key salt value for the operation. The key salt value for the operation. - The specified salt size is smaller than 8 bytes. diff --git a/xml/System.Security.Cryptography/SymmetricAlgorithm.xml b/xml/System.Security.Cryptography/SymmetricAlgorithm.xml index 48cd4df9976..0086792d17e 100644 --- a/xml/System.Security.Cryptography/SymmetricAlgorithm.xml +++ b/xml/System.Security.Cryptography/SymmetricAlgorithm.xml @@ -1407,9 +1407,9 @@ This method's behavior is defined by - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + For more information about and , see Cleaning Up Unmanaged Resources. Cryptographic Services @@ -3711,7 +3711,7 @@ Derived classes must override this and provide an implementation. Implementations of this method must write precisely `GetCiphertextLengthCbc(plaintext.Length, paddingMode)` bytes to `destination` and report that via `bytesWritten`. - + @@ -3844,7 +3844,7 @@ Derived classes must override this and provide an implementation. Implementations of this method must write precisely `GetCiphertextLengthCfb(plaintext.Length, paddingMode, feedbackSizeInBits)` bytes to `destination` and report that via `bytesWritten`. - + @@ -3960,7 +3960,7 @@ Derived classes must override this and provide an implementation. Implementations of this method must write precisely `GetCiphertextLengthEcb(plaintext.Length, paddingMode)` bytes to `destination` and report that via `bytesWritten`. - + diff --git a/xml/System.Security.Cryptography/ToBase64Transform.xml b/xml/System.Security.Cryptography/ToBase64Transform.xml index 93a7e949085..9141aaca8fd 100644 --- a/xml/System.Security.Cryptography/ToBase64Transform.xml +++ b/xml/System.Security.Cryptography/ToBase64Transform.xml @@ -65,20 +65,20 @@ Converts a to base 64. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.ToBase64Transform/CPP/members.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/ToBase64Transform/Overview/members.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.ToBase64Transform/VB/members.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.ToBase64Transform/VB/members.vb" id="Snippet1"::: + ]]> Cryptographic Services @@ -168,15 +168,15 @@ Gets a value indicating whether the current transform can be reused. Always . - property to determine if the current transform can be reused. This code example is part of a larger example provided for the class. - + property to determine if the current transform can be reused. 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.ToBase64Transform/CPP/members.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/ToBase64Transform/Overview/members.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.ToBase64Transform/VB/members.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.ToBase64Transform/VB/members.vb" id="Snippet3"::: + ]]> Cryptographic Services @@ -227,15 +227,15 @@ if multiple blocks can be transformed; otherwise, . - method to verify that multiple blocks can be transformed. This code example is part of a larger example provided for the class. - + method to verify that multiple blocks can be transformed. 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.ToBase64Transform/CPP/members.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/ToBase64Transform/Overview/members.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.ToBase64Transform/VB/members.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.ToBase64Transform/VB/members.vb" id="Snippet4"::: + ]]> Cryptographic Services @@ -282,22 +282,22 @@ Releases all resources used by the . - . - - 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. - + . + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.ToBase64Transform/CPP/members.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/ToBase64Transform/Overview/members.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.ToBase64Transform/VB/members.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.ToBase64Transform/VB/members.vb" id="Snippet7"::: + ]]> Cryptographic Services @@ -355,16 +355,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. + ]]> @@ -414,20 +414,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes the protected `Dispose(Boolean)` method with the disposing parameter set to `true`. `Finalize` invokes `Dispose` with disposing set to `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. - + method, if it has been overridden. `Dispose()` invokes the protected `Dispose(Boolean)` method with the disposing parameter set to `true`. `Finalize` invokes `Dispose` with disposing set to `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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources. Cryptographic Services @@ -520,20 +520,20 @@ Gets the input block size. The size of the input data blocks in bytes. - property to retrieve the input block size of the current transform. This code example is part of a larger example provided for the class. - + property to retrieve the input block size of 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.ToBase64Transform/CPP/members.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/ToBase64Transform/Overview/members.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.ToBase64Transform/VB/members.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.ToBase64Transform/VB/members.vb" id="Snippet5"::: + ]]> Cryptographic Services @@ -583,20 +583,20 @@ Gets the output block size. The size of the output data blocks in bytes. - property to create a new byte array with the size of the output block size. This code example is part of a larger example provided for the class. - + property to create a new byte array with the size of the output block size. 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.ToBase64Transform/CPP/members.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/ToBase64Transform/Overview/members.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.ToBase64Transform/VB/members.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.ToBase64Transform/VB/members.vb" id="Snippet6"::: + ]]> Cryptographic Services @@ -636,7 +636,7 @@ method, if it has been overridden. `Dispose()` invokes the protected `Dispose(Boolean)` method with the disposing parameter set to `true`. `Finalize` invokes `Dispose` with disposing set to `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. @@ -714,28 +714,28 @@ For more information about `Dispose` and `Finalize`, see [Cleaning Up Unmanaged Converts the specified region of the input byte array to base 64 and copies the result to the specified region of the output byte array. The number of bytes written. - 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. - + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.ToBase64Transform/CPP/members.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/ToBase64Transform/Overview/members.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.ToBase64Transform/VB/members.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.ToBase64Transform/VB/members.vb" id="Snippet8"::: + ]]> The current object has already been disposed. The data size is not valid. - The parameter contains an invalid offset length. - - -or- - + The parameter contains an invalid offset length. + + -or- + The parameter contains an invalid value. The parameter is . The parameter requires a non-negative number. @@ -800,22 +800,22 @@ For more information about `Dispose` and `Finalize`, see [Cleaning Up Unmanaged Converts the specified region of the specified byte array to base 64. The computed base 64 conversion. - method to transform the final block of data. This code example is part of a larger example provided for the class. - + method to transform the final block of data. 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.ToBase64Transform/CPP/members.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/ToBase64Transform/Overview/members.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.ToBase64Transform/VB/members.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.ToBase64Transform/VB/members.vb" id="Snippet9"::: + ]]> The current object has already been disposed. - The parameter contains an invalid offset length. - - -or- - + The parameter contains an invalid offset length. + + -or- + The parameter contains an invalid value. The parameter is . The parameter requires a non-negative number. diff --git a/xml/System.Security.Principal/WindowsIdentity.xml b/xml/System.Security.Principal/WindowsIdentity.xml index 120a44667e3..98913f56337 100644 --- a/xml/System.Security.Principal/WindowsIdentity.xml +++ b/xml/System.Security.Principal/WindowsIdentity.xml @@ -1006,9 +1006,9 @@ - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + For more information about and , see Cleaning Up Unmanaged Resources. diff --git a/xml/System.Security.Principal/WindowsImpersonationContext.xml b/xml/System.Security.Principal/WindowsImpersonationContext.xml index 733f3a74fbd..9b2d91f225b 100644 --- a/xml/System.Security.Principal/WindowsImpersonationContext.xml +++ b/xml/System.Security.Principal/WindowsImpersonationContext.xml @@ -155,9 +155,9 @@ - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + For more information about and , see Cleaning Up Unmanaged Resources. diff --git a/xml/System.Security.RightsManagement/CryptoProvider.xml b/xml/System.Security.RightsManagement/CryptoProvider.xml index e95ab1ee818..6424c6c488f 100644 --- a/xml/System.Security.RightsManagement/CryptoProvider.xml +++ b/xml/System.Security.RightsManagement/CryptoProvider.xml @@ -32,21 +32,21 @@ Provides digital rights management services for encrypting and decrypting protected content. - 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. - - - -## Examples - The following example shows how to use the class to create an . - + 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. + + + +## Examples + The following example shows how to use the class to create an . + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubencrypt"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: + ]]> @@ -78,25 +78,25 @@ Gets the cipher block size, in bytes. The cipher block size, in bytes. The default block size for Advanced Encryption Standard (AES) is 8. - 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 `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. - - - -## Examples - The following example shows how to use the property in converting clear-text data to encrypted-text data. - + 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 `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. + + + +## Examples + The following example shows how to use the property in converting 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/VS_Snippets_Wpf/RightsManagedContentPublish/visualbasic/window1.xaml.vb" id="Snippetrmcontpubencrypt"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedContentPublish/visualbasic/window1.xaml.vb" id="Snippetrmcontpubencrypt"::: + ]]> @@ -126,14 +126,14 @@ Gets a collection listing the rights that passed verification and that are granted to the user. A collection enumerating the rights that passed verification and that are granted to the user. - property to obtain a list rights granted through a . - + property to obtain a list rights granted through a . + :::code language="csharp" source="~/snippets/csharp/System.Security.RightsManagement/CryptoProvider/BoundGrants/Window1.xaml.cs" id="Snippetrmcontviewuselicense"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedContentViewer/visualbasic/window1.xaml.vb" id="Snippetrmcontviewuselicense"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedContentViewer/visualbasic/window1.xaml.vb" id="Snippetrmcontviewuselicense"::: + ]]> @@ -164,19 +164,19 @@ if the grants the user rights to decrypt; otherwise, . - returns `true` if the bound to this grants the user read access rights such as View, Edit, Print, or Owner. - - - -## Examples - The following example shows how to use the property to determine if decryption is allowed. - + returns `true` if the bound to this grants the user read access rights such as View, Edit, Print, or Owner. + + + +## Examples + The following example shows how to use the property to determine if decryption is allowed. + :::code language="csharp" source="~/snippets/csharp/System.Security.RightsManagement/CryptoProvider/BoundGrants/Window1.xaml.cs" id="Snippetrmcontviewuselicense"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedContentViewer/visualbasic/window1.xaml.vb" id="Snippetrmcontviewuselicense"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedContentViewer/visualbasic/window1.xaml.vb" id="Snippetrmcontviewuselicense"::: + ]]> @@ -209,11 +209,11 @@ if the grants the user rights to encrypt; otherwise, . - 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. + ]]> @@ -246,15 +246,15 @@ if the buffer passed to can be a different length from the buffer passed to ; otherwise, if the buffers passed to and must be the exact same length. For AES the default is . - 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 `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). - + 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 `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). + ]]> @@ -288,14 +288,14 @@ Decrypts cipher text to clear text. The decrypted clear text of . - method to convert encrypted data to unencrypted data. - + 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/VS_Snippets_Wpf/RightsManagedContentViewer/visualbasic/window1.xaml.vb" id="Snippetrmcontviewdecrypt"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedContentViewer/visualbasic/window1.xaml.vb" id="Snippetrmcontviewdecrypt"::: + ]]> @@ -342,16 +342,16 @@ Releases all resources used by the . - 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). - + 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). + > [!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. + ]]> @@ -385,20 +385,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -431,21 +431,21 @@ Encrypts clear text to cipher text. Encrypted cipher text of the given . - property. - - The digital rights management system uses AES block cipher. With AES, blocks are encrypted independently such that two blocks of identical clear text produce identical cipher text results. To minimize potential decryption threats from independent block encryption, applications should employ methods to modify content, such as compression, to avoid encrypting identical clear text blocks. - - - -## Examples - The following example shows how to use the method to convert clear-text data to encrypted-text data. - + property. + + The digital rights management system uses AES block cipher. With AES, blocks are encrypted independently such that two blocks of identical clear text produce identical cipher text results. To minimize potential decryption threats from independent block encryption, applications should employ methods to modify content, such as compression, to avoid encrypting identical clear text blocks. + + + +## Examples + 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/VS_Snippets_Wpf/RightsManagedContentPublish/visualbasic/window1.xaml.vb" id="Snippetrmcontpubencrypt"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedContentPublish/visualbasic/window1.xaml.vb" id="Snippetrmcontpubencrypt"::: + ]]> @@ -480,15 +480,15 @@ Frees resources and performs internal cleanup before the instance is reclaimed by garbage collection. - 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. - - 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)). - + 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. + + 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/SecureEnvironment.xml b/xml/System.Security.RightsManagement/SecureEnvironment.xml index 148fbbdc053..f20c9f05930 100644 --- a/xml/System.Security.RightsManagement/SecureEnvironment.xml +++ b/xml/System.Security.RightsManagement/SecureEnvironment.xml @@ -32,19 +32,19 @@ Represents a secure client session for user activation, license binding, and other rights management operations. - types, is only usable in full trust applications. - - - -## Examples - The following example shows use of the class - + types, is only usable in full trust applications. + + + +## Examples + The following example shows use of the class + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubsecenv"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubsecenv"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubsecenv"::: + ]]> @@ -74,14 +74,14 @@ Gets the specified when the was created. The application manifest specified to the method when the is created. - method. - + method. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubsecenv"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubsecenv"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubsecenv"::: + ]]> @@ -95,14 +95,14 @@ Creates a secure client session for rights management operations. - @@ -138,19 +138,19 @@ Creates a secure client session for a specified user with a given rights manifest. A secure client session for activation, license binding, and other rights management operations. - 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. - - - -## Examples - The following example shows how to use this method to create a secure environment. - + 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. + + + +## Examples + The following example shows how to use this method to create a secure environment. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubsecenv"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubsecenv"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubsecenv"::: + ]]> @@ -189,23 +189,23 @@ Creates a secure client session given an application rights manifest, , and . A secure client session for activation, license binding, and other rights management operations. - 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 . - - - -## Examples - The following example shows how to use this method to create a secure environment. - + 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 . + + + +## Examples + The following example shows how to use this method to create a secure environment. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubsecenv"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubsecenv"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubsecenv"::: + ]]> @@ -247,14 +247,14 @@ Releases all resources used by the . - 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). - + 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. + ]]> @@ -288,20 +288,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - 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. - + 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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -363,14 +363,14 @@ if the given has been activated for accessing rights managed content; otherwise, . - method to determine if given user has been authorized to access rights managed content. - + 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/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubsecenv"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubsecenv"::: + ]]> @@ -403,11 +403,11 @@ The user to remove the license activation for. Removes the license activation for a specified user. - The parameter is . @@ -439,14 +439,14 @@ Gets the user or user-group specified when the was created. The user or user-group specified to the method when the was created. - property - + property + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/PackageStore/AddPackage/Window1.xaml.cs" id="Snippetrmpkgviewsecenv"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackageViewer/visualbasic/window1.xaml.vb" id="Snippetrmpkgviewsecenv"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackageViewer/visualbasic/window1.xaml.vb" id="Snippetrmpkgviewsecenv"::: + ]]> diff --git a/xml/System.Security/HostSecurityManager.xml b/xml/System.Security/HostSecurityManager.xml index 2930f7a42b6..9e09816f33d 100644 --- a/xml/System.Security/HostSecurityManager.xml +++ b/xml/System.Security/HostSecurityManager.xml @@ -47,19 +47,19 @@ Allows the control and customization of security behavior for application domains. - , the common language runtime queries the for the presence of a , which participates in making security decisions for the . Host providers should implement a host security manager that inherits from the class. - - - -## Examples - The following example shows a very simple implementation of a . - + , the common language runtime queries the for the presence of a , which participates in making security decisions for the . Host providers should implement a host security manager that inherits from the class. + + + +## Examples + The following example shows a very simple implementation of a . + :::code language="csharp" source="~/snippets/csharp/System.Security/HostSecurityManager/Overview/customsecuritymanager.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.HostSecurityManager/VB/customsecuritymanager.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.HostSecurityManager/VB/customsecuritymanager.vb" id="Snippet1"::: + ]]> @@ -144,29 +144,29 @@ Determines whether an application should be executed. An object that contains trust information about the application. - method for a custom host security manager. This example is part of a larger example provided for the class. - + 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/VS_Snippets_CLR_System/system.Security.HostSecurityManager/VB/customsecuritymanager.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.HostSecurityManager/VB/customsecuritymanager.vb" id="Snippet3"::: + ]]> is . - An object could not be found in the application evidence. - - -or- - + An object could not be found in the application evidence. + + -or- + The property in the activation arguments is . The grant set does not contain the minimum request set specified by the . @@ -208,25 +208,25 @@ When overridden in a derived class, gets the security policy for the current application domain. The security policy for the current application domain. The default is . - creation time. It allows a host to supply a policy for the current . A policy level consists of the following: - -- A set of code groups organized into a single rooted tree. - -- 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. - -- A list of fully trusted assemblies. - + creation time. It allows a host to supply a policy for the current . A policy level consists of the following: + +- A set of code groups organized into a single rooted tree. + +- 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. + +- A list of fully trusted assemblies. + > [!IMPORTANT] -> See the Notes to Inheritors for the class for critical implementation information. - +> See the Notes to Inheritors for the class for critical implementation information. + ]]> - This method uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the [<legacyCasPolicy> element](/dotnet/framework/configure-apps/file-schema/runtime/netfx40-legacysecuritypolicy-element). + This method uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the <legacyCasPolicy> element. @@ -260,21 +260,21 @@ Gets the flag representing the security policy components of concern to the host. One of the enumeration values that specifies security policy components. The default is . - . - - The derived host can change the value of this property when only a subset of the is of interest. The possible subsets include none, the refused set, the policy level, and assembly evidence. - - - -## Examples - The following example shows how to override the property for a custom host security manager. This example is part of a larger example provided for the class. - + . + + The derived host can change the value of this property when only a subset of the is of interest. The possible subsets include none, the refused set, the policy level, and assembly evidence. + + + +## Examples + The following example shows how to override the property 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="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.HostSecurityManager/VB/customsecuritymanager.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.HostSecurityManager/VB/customsecuritymanager.vb" id="Snippet2"::: + ]]> @@ -312,29 +312,29 @@ Requests a specific evidence type for the application domain. The requested application domain evidence. - . 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 . - - 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 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 . + + 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. + :::code language="csharp" source="~/snippets/csharp/System.Security/HostSecurityManager/Overview/customsecuritymanager.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.HostSecurityManager/VB/customsecuritymanager.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.HostSecurityManager/VB/customsecuritymanager.vb" id="Snippet6"::: + ]]> @@ -374,21 +374,21 @@ Requests a specific evidence type for the assembly. The requested assembly evidence. - 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 . - - 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. - + 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 . + + 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. + ]]> @@ -423,13 +423,13 @@ Determines which evidence types the host can supply for the application domain, if requested. An array of evidence types. - 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. - + 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. + ]]> @@ -467,13 +467,13 @@ Determines which evidence types the host can supply for the assembly, if requested. An array of evidence types. - 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. - + 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. + ]]> @@ -513,16 +513,16 @@ Provides the application domain evidence for an assembly being loaded. The evidence to be used for the . - object is created. The `inputEvidence` parameter is the computed evidence from the common language runtime. The host implementation can choose to extend or reduce the evidence. The return value is the evidence to be used for the application domain. The base implementation always returns the evidence object passed in as the `inputEvidence` parameter. - + object is created. The `inputEvidence` parameter is the computed evidence from the common language runtime. The host implementation can choose to extend or reduce the evidence. The return value is the evidence to be used for the application domain. The base implementation always returns the evidence object passed in as the `inputEvidence` parameter. + > [!IMPORTANT] -> See the Notes to Inheritors for the class for critical implementation information. - +> See the Notes to Inheritors for the class for critical implementation information. + ]]> @@ -564,24 +564,24 @@ Provides the assembly evidence for an assembly being loaded. The evidence to be used for the assembly. - [!IMPORTANT] -> See the Notes to Inheritors for the class for critical implementation information. - - - -## 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. - +> See the Notes to Inheritors for the class for critical implementation information. + + + +## 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. + :::code language="csharp" source="~/snippets/csharp/System.Security/HostSecurityManager/Overview/customsecuritymanager.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.HostSecurityManager/VB/customsecuritymanager.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.HostSecurityManager/VB/customsecuritymanager.vb" id="Snippet5"::: + ]]> @@ -627,11 +627,11 @@ Determines what permissions to grant to code based on the specified evidence. The permission set that can be granted by the security system. - diff --git a/xml/System.Security/SecurityManager.xml b/xml/System.Security/SecurityManager.xml index 7f1a16c72c2..5d3c2d608d1 100644 --- a/xml/System.Security/SecurityManager.xml +++ b/xml/System.Security/SecurityManager.xml @@ -47,14 +47,14 @@ Provides the main access point for classes interacting with the security system. This class cannot be inherited. - . - + Security provides methods to access and manipulate the security policy configuration. You cannot create instances of . + ]]> @@ -102,13 +102,13 @@ if code must have in order to execute; otherwise, . - 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. - + 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. + ]]> The code that calls this method does not have . @@ -152,18 +152,18 @@ if the stack contains no partially trusted application domains, no partially trusted assemblies, and no currently active or modifiers; if the common language runtime cannot guarantee that the stack contains none of these. - 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. - + 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. + > [!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. - +> 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. + ]]> @@ -202,36 +202,36 @@ Gets a permission set that is safe to grant to an application that has the provided evidence. A permission set that can be used as a grant set for the application that has the provided evidence. - [!NOTE] -> In the .NET Framework 4, the host evidence in `evidence` must contain evidence. -> -> The following table shows the permission sets that are returned for each zone. - -|Zone|Permission set| -|----------|--------------------| -||`FullTrust`| -||`LocalIntranet`| -||`Internet`| -||`Internet`| -||None| -||None| - - Other evidence, such as or , may be considered. - - The returned permission set can be used by a sandbox to run the application. Note that this method does not specify policy, but helps a host to determine whether the permission set requested by an application is reasonable. This method can be used to map a zone to a sandbox. - - - -## Examples - The following example shows how to use the method to obtain the permission set for a sandboxed application. 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). - +> In the .NET Framework 4, the host evidence in `evidence` must contain evidence. +> +> The following table shows the permission sets that are returned for each zone. + +|Zone|Permission set| +|----------|--------------------| +||`FullTrust`| +||`LocalIntranet`| +||`Internet`| +||`Internet`| +||None| +||None| + + Other evidence, such as or , may be considered. + + The returned permission set can be used by a sandbox to run the application. Note that this method does not specify policy, but helps a host to determine whether the permission set requested by an application is reasonable. This method can be used to map a zone to a sandbox. + + + +## Examples + The following example shows how to use the method to obtain the permission set for a sandboxed application. 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). + :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityManager/GetStandardSandbox/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/SandboxingAPIs/VB/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/SandboxingAPIs/VB/program.vb" id="Snippet1"::: + ]]> @@ -281,14 +281,14 @@ An output parameter that contains an of granted objects. Gets the granted zone identity and URL identity permission sets for the current assembly. - 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. - + 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. - +> 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. + ]]> The request for failed. @@ -345,11 +345,11 @@ if the permissions granted to the caller include the permission ; otherwise, . - only tests the grant of the calling code assembly, independent of other callers on the stack. - + only tests the grant of the calling code assembly, independent of other callers on the stack. + ]]> @@ -408,20 +408,20 @@ To be added. The parameter is . The file indicated by the parameter does not exist. - The code that calls this method does not have . - - -or- - - The code that calls this method does not have . - - -or- - - The code that calls this method does not have . - - -or- - + The code that calls this method does not have . + + -or- + + The code that calls this method does not have . + + -or- + + The code that calls this method does not have . + + -or- + The code that calls this method does not have . - This method uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the [<legacyCasPolicy> element](/dotnet/framework/configure-apps/file-schema/runtime/netfx40-legacysecuritypolicy-element). + This method uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the <legacyCasPolicy> element. @@ -528,16 +528,16 @@ Provides an enumerator to access the security policy hierarchy by levels, such as computer policy and user policy. An enumerator for objects that compose the security policy hierarchy. - objects that represent the policy at the respective (machine, user, enterprise, application domain) level of the hierarchy. These objects are the live policy objects; altering these objects can have unpredictable results. - - Minimum policy hierarchy consists of a machine level, an enterprise level, and a user level. However, the hierarchy can include additional levels. - + objects that represent the policy at the respective (machine, user, enterprise, application domain) level of the hierarchy. These objects are the live policy objects; altering these objects can have unpredictable results. + + Minimum policy hierarchy consists of a machine level, an enterprise level, and a user level. However, the hierarchy can include additional levels. + ]]> - This method uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the [<legacyCasPolicy> element](/dotnet/framework/configure-apps/file-schema/runtime/netfx40-legacysecuritypolicy-element). + This method uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the <legacyCasPolicy> element. The code that calls this method does not have . @@ -601,14 +601,14 @@ Determines what permissions to grant to code based on the specified evidence. The set of permissions that can be granted by the security system. - - This method uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the [<legacyCasPolicy> element](/dotnet/framework/configure-apps/file-schema/runtime/netfx40-legacysecuritypolicy-element). + This method uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the <legacyCasPolicy> element. @@ -660,14 +660,14 @@ Determines what permissions to grant to code based on the specified evidence. The set of permissions that is appropriate for all of the provided evidence. - objects. The returned permission set represents only those permissions that apply to every evidence in the array. These permissions are either equivalent to, or a subset of the permissions that policy would have granted to each individual evidence. This method behaves as if you were performing an intersection on the results of resolving policy on each of the objects in the array. - + objects. The returned permission set represents only those permissions that apply to every evidence in the array. These permissions are either equivalent to, or a subset of the permissions that policy would have granted to each individual evidence. This method behaves as if you were performing an intersection on the results of resolving policy on each of the objects in the array. + ]]> - This method uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the [<legacyCasPolicy> element](/dotnet/framework/configure-apps/file-schema/runtime/netfx40-legacysecuritypolicy-element). + This method uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the <legacyCasPolicy> element. @@ -728,14 +728,14 @@ Determines what permissions to grant to code based on the specified evidence and requests. The set of permissions that would be granted by the security system. - - This method uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the [<legacyCasPolicy> element](/dotnet/framework/configure-apps/file-schema/runtime/netfx40-legacysecuritypolicy-element). + This method uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the <legacyCasPolicy> element. Policy fails to grant the minimum required permissions specified by the parameter. @@ -789,16 +789,16 @@ Gets a collection of code groups matching the specified evidence. An enumeration of the set of code groups matching the evidence. - - This method uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the [<legacyCasPolicy> element](/dotnet/framework/configure-apps/file-schema/runtime/netfx40-legacysecuritypolicy-element). + This method uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the <legacyCasPolicy> element. @@ -850,14 +850,14 @@ Determines which permissions to grant to code based on the specified evidence, excluding the policy for the level. The set of permissions that can be granted by the security system. - policy. - + policy. + ]]> - This method uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the [<legacyCasPolicy> element](/dotnet/framework/configure-apps/file-schema/runtime/netfx40-legacysecuritypolicy-element). + This method uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the <legacyCasPolicy> element. @@ -906,14 +906,14 @@ Saves the modified security policy state. - , , 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. - + , , 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 uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the [<legacyCasPolicy> element](/dotnet/framework/configure-apps/file-schema/runtime/netfx40-legacysecuritypolicy-element). + This method uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the <legacyCasPolicy> element. The code that calls this method does not have . @@ -966,15 +966,15 @@ The policy level object to be saved. Saves a modified security policy level loaded with . - will be saved to the same location from which it loaded. - + will be saved to the same location from which it loaded. + ]]> The code that calls this method does not have . - This method uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the [<legacyCasPolicy> element](/dotnet/framework/configure-apps/file-schema/runtime/netfx40-legacysecuritypolicy-element). + This method uses code access security (CAS) policy, which is obsolete in the .NET Framework 4. To enable CAS policy for compatibility with earlier versions of the .NET Framework, use the <legacyCasPolicy> element. @@ -1024,20 +1024,20 @@ if security is enabled; otherwise, . - 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. - +> 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. + ]]> The code that calls this method does not have . diff --git a/xml/System.ServiceModel.Description/ServiceDescription.xml b/xml/System.ServiceModel.Description/ServiceDescription.xml index 20e214f598a..49d82b148e7 100644 --- a/xml/System.ServiceModel.Description/ServiceDescription.xml +++ b/xml/System.ServiceModel.Description/ServiceDescription.xml @@ -184,7 +184,7 @@ Gets or sets the name of the <> configuration element. - The name of the [<service>](/dotnet/framework/configure-apps/file-schema/wcf/service) configuration element used to configure the service. + The name of the <see href="/dotnet/framework/configure-apps/file-schema/wcf/service"><service></see> configuration element used to configure the service. - + \ No newline at end of file diff --git a/xml/System.ServiceModel/NetNamedPipeBinding.xml b/xml/System.ServiceModel/NetNamedPipeBinding.xml index 79aa752098e..d93392013ab 100644 --- a/xml/System.ServiceModel/NetNamedPipeBinding.xml +++ b/xml/System.ServiceModel/NetNamedPipeBinding.xml @@ -168,7 +168,7 @@ - The binding configuration name for the [netNamedPipeBinding Element](/dotnet/framework/configure-apps/file-schema/wcf/netnamedpipebinding). + The binding configuration name for the <see href="/dotnet/framework/configure-apps/file-schema/wcf/netnamedpipebinding">netNamedPipeBinding Element</see>. Initializes a new instance of the class with a specified configuration name. - + \ No newline at end of file diff --git a/xml/System.ServiceProcess/ServiceController.xml b/xml/System.ServiceProcess/ServiceController.xml index 127f749a1e2..7ba7a8ecfc1 100644 --- a/xml/System.ServiceProcess/ServiceController.xml +++ b/xml/System.ServiceProcess/ServiceController.xml @@ -69,30 +69,30 @@ Represents a Windows service and allows you to connect to a running or stopped service, manipulate it, or get information about it. - class to connect to and control the behavior of existing services. When you create an instance of the class, you set its properties so it interacts with a specific Windows service. You can then use the class to start, stop, and otherwise manipulate the service. - - You will most likely use the component in an administrative capacity. For example, you could create a Windows or Web application that sends custom commands to a service through the instance. This would be useful, because the Service Control Manager (SCM) Microsoft Management Console snap-in does not support custom commands. - - 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. - + class to connect to and control the behavior of existing services. When you create an instance of the class, you set its properties so it interacts with a specific Windows service. You can then use the class to start, stop, and otherwise manipulate the service. + + You will most likely use the component in an administrative capacity. For example, you could create a Windows or Web application that sends custom commands to a service through the instance. This would be useful, because the Service Control Manager (SCM) Microsoft Management Console snap-in does not support custom commands. + + 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. - - 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`." - - - -## Examples - The following example demonstrates the use of the class to control the `SimpleService` service example. - +> 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. + + 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`." + + + +## Examples + The following example demonstrates the use of the class to control the `SimpleService` service example. + :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceControllerClass/VB/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceControllerClass/VB/program.vb" id="Snippet1"::: + ]]> @@ -160,14 +160,14 @@ The name that identifies the service to the system. This can also be the display name for the service. Initializes a new instance of the class that is associated with an existing service on the local computer. - 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. - + 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/VS_Snippets_CLR/ServiceControllerClass/VB/program.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceControllerClass/VB/program.vb" id="Snippet2"::: + ]]> @@ -203,18 +203,18 @@ The computer on which the service resides. Initializes a new instance of the class that is associated with an existing service on the specified computer. - - is invalid. - - -or- - + is invalid. + + -or- + is invalid. @@ -256,14 +256,14 @@ if the service can be paused; otherwise, . - property to determine whether a service can pause and continue. This example is part of a larger example that is provided for the class. - + property to determine whether a service can pause and continue. 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/VS_Snippets_CLR/ServiceControllerClass/VB/program.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceControllerClass/VB/program.vb" id="Snippet2"::: + ]]> An error occurred when accessing a system API. @@ -308,14 +308,14 @@ if the service should be notified when the system is shutting down; otherwise, . - property to determine whether a service provides a handler for a shutdown event. This example is part of a larger example that is provided for the class. - + property to determine whether a service provides a handler for a shutdown event. 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/VS_Snippets_CLR/ServiceControllerClass/VB/program.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceControllerClass/VB/program.vb" id="Snippet2"::: + ]]> An error occurred when accessing a system API. @@ -360,14 +360,14 @@ if the service can be stopped and the method called; otherwise, . - property to determine whether a service provides a handler for a stop event. This example is part of a larger example that is provided for the class. - + property to determine whether a service provides a handler for a stop event. 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/VS_Snippets_CLR/ServiceControllerClass/VB/program.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceControllerClass/VB/program.vb" id="Snippet2"::: + ]]> An error occurred when accessing a system API. @@ -400,11 +400,11 @@ Disconnects this instance from the service and frees all the resources that the instance allocated. - releases all the handles associated with the instance. - + releases all the handles associated with the instance. + ]]> @@ -436,21 +436,21 @@ Continues a service after it has been paused. - 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`. - - - -## 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. - + 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`. + + + +## 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. + :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/Overview/program.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceControllerClass/VB/program.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceControllerClass/VB/program.vb" id="Snippet5"::: + ]]> An error occurred when accessing a system API. @@ -497,20 +497,20 @@ Gets the set of services that depends on the service associated with this instance. An array of instances, each of which is associated with a service that depends on this service. - array represents the services that the system stops if your application calls for this service. - - - -## Examples - The following example uses the class to display the set of services that are dependent on the Event Log service. - + array represents the services that the system stops if your application calls for this service. + + + +## Examples + The following example uses the class to display the set of services that are dependent on the Event Log service. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ServiceController/CPP/servicecontroller.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/DependentServices/servicecontroller.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet3"::: + ]]> An error occurred when accessing a system API. @@ -562,20 +562,20 @@ Gets or sets a friendly name for the service. The friendly name of the service, which can be used to identify the service. - to an empty string (""), but setting the property to `null` throws an exception. - - - -## Examples - The following example uses the class to display the set of services that are dependent on the Event Log service. - + to an empty string (""), but setting the property to `null` throws an exception. + + + +## Examples + The following example uses the class to display the set of services that are dependent on the Event Log service. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ServiceController/CPP/servicecontroller.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/DependentServices/servicecontroller.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet3"::: + ]]> The is . @@ -646,20 +646,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - For more information about and , see [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)). + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see Implementing a Dispose Method. + + For more information about and , see Cleaning Up Unmanaged Resources and Overriding the Finalize Method. @@ -692,19 +692,19 @@ An application-defined command flag that indicates which custom command to execute. The value must be between 128 and 256, inclusive. Executes a custom command on the service. - , 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 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. + :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/ExecuteCommand/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceContoller_ExecuteCommand/VB/module1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceContoller_ExecuteCommand/VB/module1.vb" id="Snippet1"::: + ]]> An error occurred when accessing a system API. @@ -749,20 +749,20 @@ Retrieves the device driver services on the local computer. An array of type in which each element is associated with a device driver service on the local 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. - - - -## Examples - The following example uses the class to display the device driver services on the local 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. + + + +## Examples + The following example uses the class to display the device driver services on the local computer. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ServiceController/CPP/servicecontroller.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/DependentServices/servicecontroller.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet5"::: + ]]> An error occurred when accessing a system API. @@ -800,11 +800,11 @@ Retrieves the device driver services on the specified computer. An array of type in which each element is associated with a device driver service on the specified 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. - + 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. + ]]> An error occurred when accessing a system API. @@ -849,20 +849,20 @@ Retrieves all the services on the local computer, except for the device driver services. An array of type in which each element is associated with a service on the local 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. - - - -## Examples - The following example uses the class to display the services that are running on the local 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. + + + +## Examples + The following example uses the class to display the services that are running on the local computer. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ServiceController/CPP/servicecontroller.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/DependentServices/servicecontroller.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet6"::: + ]]> An error occurred when accessing a system API. @@ -900,11 +900,11 @@ Retrieves all the services on the specified computer, except for the device driver services. An array of type in which each element is associated with a service on the specified 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. - + 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. + ]]> An error occurred when accessing a system API. @@ -965,11 +965,11 @@ Gets or sets the name of the computer on which this service resides. The name of the computer that is running the service associated with this instance. The default is the local computer ("."). - The syntax is invalid. @@ -1002,19 +1002,19 @@ Suspends a service's operation. - 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. - + 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. + :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/Overview/program.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceControllerClass/VB/program.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceControllerClass/VB/program.vb" id="Snippet4"::: + ]]> An error occurred when accessing a system API. @@ -1051,19 +1051,19 @@ Refreshes property values by resetting the properties to their current values. - 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. - + 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. + :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/Overview/program.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceControllerClass/VB/program.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceControllerClass/VB/program.vb" id="Snippet4"::: + ]]> @@ -1164,15 +1164,15 @@ Gets or sets the name that identifies the service that this instance references. The name that identifies the service that this instance references. The default is an empty string (""). - 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 reset the property, the method that sets the property sets this instance's to an empty string (""). - + 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 reset the property, the method that sets the property sets this instance's to an empty string (""). + ]]> The is . @@ -1217,20 +1217,20 @@ The set of services that this service depends on. An array of instances, each of which is associated with a service that must be running for this service to run. - array is not running, you will not be able to start this service. - - - -## Examples - The following example uses the class to display the set of services that the Messenger service is dependent on. - + array is not running, you will not be able to start this service. + + + +## Examples + The following example uses the class to display the set of services that the Messenger service is dependent on. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ServiceController/CPP/servicecontroller.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/DependentServices/servicecontroller.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet4"::: + ]]> An error occurred when accessing a system API. @@ -1274,20 +1274,20 @@ Gets the type of service that this object references. One of the values, used to indicate the network service type. - property represents a set of flags combined using the bitwise OR operator. - - - -## Examples - The following example uses the class to display the device driver services on the local computer. - + property represents a set of flags combined using the bitwise OR operator. + + + +## Examples + The following example uses the class to display the device driver services on the local computer. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ServiceController/CPP/servicecontroller.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/DependentServices/servicecontroller.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet5"::: + ]]> An error occurred when accessing a system API. @@ -1331,20 +1331,20 @@ Starts the service, passing no arguments. - for the service until the service controller status is `Running`. - - - -## Examples - The following example uses the class to check whether the Alerter service is stopped. If the service is stopped, the example starts the service and waits until the service status is set to . - + for the service until the service controller status is `Running`. + + + +## Examples + The following example uses the class to check whether the Alerter service is stopped. If the service is stopped, the example starts the service and waits until the service status is set to . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ServiceController/CPP/servicecontroller.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/DependentServices/servicecontroller.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet1"::: + ]]> An error occurred when accessing a system API. @@ -1383,20 +1383,20 @@ An array of arguments to pass to the service when it starts. Starts a service, passing the specified arguments. - for the service until the service controller status is `Running`. - + for the service until the service controller status is `Running`. + ]]> An error occurred when accessing a system API. The service cannot be started. - is . - - -or- - + is . + + -or- + A member of the array is . @@ -1478,20 +1478,20 @@ Gets the status of the service that is referenced by this instance. One of the values that indicates whether the service is running, stopped, or paused, or whether a start, stop, pause, or continue command is pending. - class to check the current status of the Telnet service. If the service is stopped, the example starts the service. If the service is running, the example stops the service. - + class to check the current status of the Telnet service. If the service is stopped, the example starts the service. If the service is running, the example stops the service. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ServiceController/CPP/servicecontroller.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/DependentServices/servicecontroller.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet2"::: + ]]> An error occurred when accessing a system API. @@ -1525,22 +1525,22 @@ Stops this service and any services that are dependent on this service. - 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. - - - -## Examples - The following example uses the class to check the current status of the Telnet service. If the service is stopped, the example starts the service. If the service is running, the example stops the service. - + 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. + + + +## Examples + The following example uses the class to check the current status of the Telnet service. If the service is stopped, the example starts the service. If the service is running, the example stops the service. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ServiceController/CPP/servicecontroller.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/DependentServices/servicecontroller.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet2"::: + ]]> An error occurred when accessing a system API. @@ -1627,23 +1627,23 @@ If any other services depend on this one, you need to either pass `true` for The status to wait for. Infinitely waits for the service to reach the specified status. - to suspend an application's processing until the service has reached the required status. - + 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. - - - -## Examples - The following example uses the class to check whether the Alerter service is stopped. If the service is stopped, the example starts the service and waits until the service status is set to . - +> 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. + + + +## Examples + The following example uses the class to check whether the Alerter service is stopped. If the service is stopped, the example starts the service and waits until the service status is set to . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ServiceController/CPP/servicecontroller.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/DependentServices/servicecontroller.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ServiceController/VB/servicecontroller.vb" id="Snippet1"::: + ]]> The parameter is not any of the values defined in the enumeration. @@ -1682,14 +1682,14 @@ If any other services depend on this one, you need to either pass `true` for A object specifying the amount of time to wait for the service to reach the specified status. Waits for the service to reach the specified status or for the specified time-out to expire. - to suspend an application's processing until the service has reached the required status. - + 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. + ]]> The parameter is not any of the values defined in the enumeration. diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsDocument.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsDocument.xml index 3afee5628c0..2c1be3ffb51 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsDocument.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsDocument.xml @@ -790,7 +790,7 @@ public void WorldSoccerWinners () The that is used to write the instance. - Writes the contents of the object to an XML-format grammar file that conforms to the [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761). + Writes the contents of the object to an XML-format grammar file that conforms to the Speech Recognition Grammar Specification (SRGS) Version 1.0. Represents a tag that contains ECMAScript that's run when the rule is matched. - objects using this format. In the syntax of `semantics/1.0`: - -- The Rule Variable of the containing rule element is identified by "out". - -- The name of the object that has access to the Rule Variable of rule elements outside the containing rule element is identified by "rules". - -- The result from the latest referenced rule that matches the utterance can be represented by "rules.latest()". - - You can also associate a semantic value with a phrase in a grammar without using script, using the object. - - - -## 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 example also uses to assign a separate semantic key for each of the two references made by the object named `cityRef` to the object named `cities`. The semantic keys identify 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 from the recognition result. - - 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. - -``` -using System; -using System.Speech.Recognition; -using System.Speech.Recognition.SrgsGrammar; - -namespace SampleRecognition -{ - class Program - { - static void Main(string[] args) - - // Initialize a SpeechRecognitionEngine object. - { - using (SpeechRecognitionEngine recognizer = - new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US"))) - { - - // Create a rule for the cities, assign a semantic value to each city. - SrgsRule cities = new SrgsRule("flightCities"); - SrgsItem chi = new SrgsItem("Chicago"); - chi.Add(new SrgsSemanticInterpretationTag("out = \"ORD\";")); - SrgsItem bos = new SrgsItem("Boston"); - bos.Add(new SrgsSemanticInterpretationTag("out = \"BOS\";")); - SrgsItem mia = new SrgsItem("Miami"); - mia.Add(new SrgsSemanticInterpretationTag("out = \"MIA\";")); - SrgsItem dal = new SrgsItem("Dallas"); - dal.Add(new SrgsSemanticInterpretationTag("out = \"DFW\";")); - - SrgsOneOf airports = new SrgsOneOf(chi, bos, mia, dal); - cities.Add(airports); - cities.Scope = SrgsRuleScope.Private; - - // Create a rule reference to the rule for cities. - SrgsRuleRef cityRef = new SrgsRuleRef(cities); - - // Create the root rule for the grammar. - SrgsRule bookFlight = new SrgsRule("flightBooker"); - bookFlight.Add(new SrgsItem("I want to fly from")); - bookFlight.Add(cityRef); - bookFlight.Add(new SrgsSemanticInterpretationTag("out.LeavingFrom=rules.flightCities;")); - bookFlight.Add(new SrgsItem("to")); - bookFlight.Add(cityRef); - bookFlight.Add(new SrgsSemanticInterpretationTag("out.GoingTo=rules.flightCities;")); - bookFlight.Scope = SrgsRuleScope.Public; - - // Initialize the SrgsDocument, set the root rule, add rules to the collection. - SrgsDocument itinerary = new SrgsDocument(bookFlight); - itinerary.Rules.Add(cities); - - // Create a Grammar object and load it to the recognizer. - Grammar g = new Grammar(itinerary); - g.Name = ("City Chooser"); - recognizer.LoadGrammarAsync(g); - - // Configure recognizer input. - recognizer.SetInputToDefaultAudioDevice(); - - // Attach a handler for the SpeechRecognized event. - recognizer.SpeechRecognized += - new EventHandler(recognizer_SpeechRecognized); - - // Start recognition. - recognizer.RecognizeAsync(); - Console.WriteLine("Starting asynchronous recognition..."); - - // Keep the console window open. - Console.ReadLine(); - } - } - - // Write to the console the text and the semantics from the recognition result. - static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) - { - Console.WriteLine("Speech recognized: " + e.Result.Text); - Console.WriteLine(); - Console.WriteLine("Semantic results:"); - Console.WriteLine(" The departure city is: " + e.Result.Semantics["LeavingFrom"].Value); - Console.WriteLine(" The arrival city is: " + e.Result.Semantics["GoingTo"].Value); - } - } -} - -``` - - The following is the XML form of the grammar generated by the code in the example above. - -```xml - - - - - I want to fly from - - out.LeavingFrom=rules.flightCities; - to - - out.GoingTo=rules.flightCities; - - - - - Chicago out="ORD"; - Boston out="BOS"; - Miami out="MIA"; - Dallas out="DFW"; - - - - -``` - + objects using this format. In the syntax of `semantics/1.0`: + +- The Rule Variable of the containing rule element is identified by "out". + +- The name of the object that has access to the Rule Variable of rule elements outside the containing rule element is identified by "rules". + +- The result from the latest referenced rule that matches the utterance can be represented by "rules.latest()". + + You can also associate a semantic value with a phrase in a grammar without using script, using the object. + + + +## 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 example also uses to assign a separate semantic key for each of the two references made by the object named `cityRef` to the object named `cities`. The semantic keys identify 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 from the recognition result. + + 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. + +``` +using System; +using System.Speech.Recognition; +using System.Speech.Recognition.SrgsGrammar; + +namespace SampleRecognition +{ + class Program + { + static void Main(string[] args) + + // Initialize a SpeechRecognitionEngine object. + { + using (SpeechRecognitionEngine recognizer = + new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US"))) + { + + // Create a rule for the cities, assign a semantic value to each city. + SrgsRule cities = new SrgsRule("flightCities"); + SrgsItem chi = new SrgsItem("Chicago"); + chi.Add(new SrgsSemanticInterpretationTag("out = \"ORD\";")); + SrgsItem bos = new SrgsItem("Boston"); + bos.Add(new SrgsSemanticInterpretationTag("out = \"BOS\";")); + SrgsItem mia = new SrgsItem("Miami"); + mia.Add(new SrgsSemanticInterpretationTag("out = \"MIA\";")); + SrgsItem dal = new SrgsItem("Dallas"); + dal.Add(new SrgsSemanticInterpretationTag("out = \"DFW\";")); + + SrgsOneOf airports = new SrgsOneOf(chi, bos, mia, dal); + cities.Add(airports); + cities.Scope = SrgsRuleScope.Private; + + // Create a rule reference to the rule for cities. + SrgsRuleRef cityRef = new SrgsRuleRef(cities); + + // Create the root rule for the grammar. + SrgsRule bookFlight = new SrgsRule("flightBooker"); + bookFlight.Add(new SrgsItem("I want to fly from")); + bookFlight.Add(cityRef); + bookFlight.Add(new SrgsSemanticInterpretationTag("out.LeavingFrom=rules.flightCities;")); + bookFlight.Add(new SrgsItem("to")); + bookFlight.Add(cityRef); + bookFlight.Add(new SrgsSemanticInterpretationTag("out.GoingTo=rules.flightCities;")); + bookFlight.Scope = SrgsRuleScope.Public; + + // Initialize the SrgsDocument, set the root rule, add rules to the collection. + SrgsDocument itinerary = new SrgsDocument(bookFlight); + itinerary.Rules.Add(cities); + + // Create a Grammar object and load it to the recognizer. + Grammar g = new Grammar(itinerary); + g.Name = ("City Chooser"); + recognizer.LoadGrammarAsync(g); + + // Configure recognizer input. + recognizer.SetInputToDefaultAudioDevice(); + + // Attach a handler for the SpeechRecognized event. + recognizer.SpeechRecognized += + new EventHandler(recognizer_SpeechRecognized); + + // Start recognition. + recognizer.RecognizeAsync(); + Console.WriteLine("Starting asynchronous recognition..."); + + // Keep the console window open. + Console.ReadLine(); + } + } + + // Write to the console the text and the semantics from the recognition result. + static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) + { + Console.WriteLine("Speech recognized: " + e.Result.Text); + Console.WriteLine(); + Console.WriteLine("Semantic results:"); + Console.WriteLine(" The departure city is: " + e.Result.Semantics["LeavingFrom"].Value); + Console.WriteLine(" The arrival city is: " + e.Result.Semantics["GoingTo"].Value); + } + } +} + +``` + + The following is the XML form of the grammar generated by the code in the example above. + +```xml + + + + + I want to fly from + + out.LeavingFrom=rules.flightCities; + to + + out.GoingTo=rules.flightCities; + + + + + Chicago out="ORD"; + Boston out="BOS"; + Miami out="MIA"; + Dallas out="DFW"; + + + + +``` + ]]> @@ -199,11 +199,11 @@ version="1.0" xmlns="http://www.w3.org/2001/06/grammar"> Creates an instance of the class. - property contains an empty string. - + property contains an empty string. + ]]> @@ -227,14 +227,14 @@ version="1.0" xmlns="http://www.w3.org/2001/06/grammar"> - A string that contains the [ECMAScript](https://www.ecma-international.org/publications-and-standards/standards/ecma-327/) for the tag. + A string that contains the ECMAScript for the tag. Creates an instance of the class, specifying the script contents of the tag. - property is set to the value in `script`. - + property is set to the value in `script`. + ]]> diff --git a/xml/System.Text.RegularExpressions/Regex.xml b/xml/System.Text.RegularExpressions/Regex.xml index 6e7ff72e9b3..c50e0047198 100644 --- a/xml/System.Text.RegularExpressions/Regex.xml +++ b/xml/System.Text.RegularExpressions/Regex.xml @@ -71,7 +71,7 @@ Represents an immutable regular expression. For more information about this API, see Supplemental API remarks for Regex. - The class is immutable (read-only) and thread safe. objects can be created on any thread and shared between threads. For more information, see [Thread Safety](/dotnet/standard/base-types/thread-safety-in-regular-expressions). + The class is immutable (read-only) and thread safe. objects can be created on any thread and shared between threads. For more information, see Thread Safety. .NET Regular Expressions Regular Expression Language Elements diff --git a/xml/System.Text/Encoding.xml b/xml/System.Text/Encoding.xml index aae2f64a5c7..cf4b2b76857 100644 --- a/xml/System.Text/Encoding.xml +++ b/xml/System.Text/Encoding.xml @@ -4522,7 +4522,7 @@ The goal is to save this file, then open and decode it as a binary stream. is a null pointer. is less than zero. - A fallback occurred (see Character Encoding in .NET) for a complete explanation) + A fallback occurred (see Character Encoding in .NET for a complete explanation) -and- diff --git a/xml/System.Threading.Tasks/TaskContinuationOptions.xml b/xml/System.Threading.Tasks/TaskContinuationOptions.xml index 47f03d8c366..dead5504028 100644 --- a/xml/System.Threading.Tasks/TaskContinuationOptions.xml +++ b/xml/System.Threading.Tasks/TaskContinuationOptions.xml @@ -105,11 +105,11 @@ 4 - Specifies that the continuation, if it is a child task, is attached to a parent in the task hierarchy. The continuation can be a child task only if its antecedent is also a child task. By default, a child task (that is, an inner task created by an outer task) executes independently of its parent. You can use the option so that the parent and child tasks are synchronized. - - Note that if a parent task is configured with the option, the option in the child task has no effect, and the child task will execute as a detached child task. - - For more information, see [Attached and Detached Child Tasks](/dotnet/standard/parallel-programming/attached-and-detached-child-tasks). + Specifies that the continuation, if it is a child task, is attached to a parent in the task hierarchy. The continuation can be a child task only if its antecedent is also a child task. By default, a child task (that is, an inner task created by an outer task) executes independently of its parent. You can use the option so that the parent and child tasks are synchronized. + + Note that if a parent task is configured with the option, the option in the child task has no effect, and the child task will execute as a detached child task. + + For more information, see Attached and Detached Child Tasks. @@ -151,7 +151,7 @@ 8 - Specifies that any child task (that is, any nested inner task created by this continuation) that is created with the option and attempts to execute as an attached child task will not be able to attach to the parent task and will execute instead as a detached child task. For more information, see [Attached and Detached Child Tasks](/dotnet/standard/parallel-programming/attached-and-detached-child-tasks). + Specifies that any child task (that is, any nested inner task created by this continuation) that is created with the option and attempts to execute as an attached child task will not be able to attach to the parent task and will execute instead as a detached child task. For more information, see Attached and Detached Child Tasks. @@ -193,8 +193,8 @@ 524288 - Specifies that the continuation task should be executed synchronously. With this option specified, the continuation runs on the same thread that causes the antecedent task to transition into its final state. If the antecedent is already complete when the continuation is created, the continuation will run on the thread that creates the continuation. If the antecedent's is disposed in a block ( in Visual Basic), a continuation with this option will run in that block. Only very short-running continuations should be executed synchronously. - + Specifies that the continuation task should be executed synchronously. With this option specified, the continuation runs on the same thread that causes the antecedent task to transition into its final state. If the antecedent is already complete when the continuation is created, the continuation will run on the thread that creates the continuation. If the antecedent's is disposed in a block ( in Visual Basic), a continuation with this option will run in that block. Only very short-running continuations should be executed synchronously. + Because the task executes synchronously, there is no need to call a method such as to ensure that the calling thread waits for the task to complete. @@ -573,10 +573,10 @@ 327680 - Specifies that the continuation task should be scheduled only if its antecedent threw an unhandled exception. An antecedent throws an unhandled exception if its property upon completion is . - - The option guarantees that the property in the antecedent is not . You can use that property to catch the exception and see which exception caused the task to fault. If you do not access the property, the exception is unhandled. Also, if you attempt to access the property of a task that has been canceled or has faulted, a new exception is thrown. - + Specifies that the continuation task should be scheduled only if its antecedent threw an unhandled exception. An antecedent throws an unhandled exception if its property upon completion is . + + The option guarantees that the property in the antecedent is not . You can use that property to catch the exception and see which exception caused the task to fault. If you do not access the property, the exception is unhandled. Also, if you attempt to access the property of a task that has been canceled or has faulted, a new exception is thrown. + This option is not valid for multi-task continuations. diff --git a/xml/System.Threading.Tasks/TaskCreationOptions.xml b/xml/System.Threading.Tasks/TaskCreationOptions.xml index 13458880fcc..0b957336abb 100644 --- a/xml/System.Threading.Tasks/TaskCreationOptions.xml +++ b/xml/System.Threading.Tasks/TaskCreationOptions.xml @@ -64,21 +64,21 @@ Specifies flags that control optional behavior for the creation and execution of tasks. - 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 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 constructors with a `creationOptions` parameter, to specify the options used to customize the behavior of the underlying task. - + 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 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 constructors with a `creationOptions` parameter, to specify the options used to customize the behavior of the underlying task. + ]]> Samples for Parallel Programming with the .NET Core and .NET Standard @@ -123,11 +123,11 @@ 4 - Specifies that a task is attached to a parent in the task hierarchy. By default, a child task (that is, an inner task created by an outer task) executes independently of its parent. You can use the option so that the parent and child tasks are synchronized. - - Note that if a parent task is configured with the option, the option in the child task has no effect, and the child task will execute as a detached child task. - - For more information, see [Attached and Detached Child Tasks](/dotnet/standard/parallel-programming/attached-and-detached-child-tasks). + Specifies that a task is attached to a parent in the task hierarchy. By default, a child task (that is, an inner task created by an outer task) executes independently of its parent. You can use the option so that the parent and child tasks are synchronized. + + Note that if a parent task is configured with the option, the option in the child task has no effect, and the child task will execute as a detached child task. + + For more information, see Attached and Detached Child Tasks. @@ -169,7 +169,7 @@ 8 - Specifies that any child task that attempts to execute as an attached child task (that is, it is created with the option) will not be able to attach to the parent task and will execute instead as a detached child task. For more information, see [Attached and Detached Child Tasks](/dotnet/standard/parallel-programming/attached-and-detached-child-tasks). + Specifies that any child task that attempts to execute as an attached child task (that is, it is created with the option) will not be able to attach to the parent task and will execute instead as a detached child task. For more information, see Attached and Detached Child Tasks. @@ -378,8 +378,8 @@ 64 - Forces continuations added to the current task to be executed asynchronously. - + Forces continuations added to the current task to be executed asynchronously. + Note that the member is available in the enumeration starting with the .NET Framework 4.6. diff --git a/xml/System.Threading.Tasks/TaskStatus.xml b/xml/System.Threading.Tasks/TaskStatus.xml index 2621ea36a50..bf9fac2bf85 100644 --- a/xml/System.Threading.Tasks/TaskStatus.xml +++ b/xml/System.Threading.Tasks/TaskStatus.xml @@ -53,19 +53,19 @@ Represents the current stage in the lifecycle of a . - property returns a member of the enumeration to indicate the task's current status. - - - -## Examples - The following example creates 20 tasks that will loop until a counter is incremented to a value of 2 million. When the first 10 tasks reach 2 million, the cancellation token is cancelled, and any tasks whose counters have not reached 2 million are cancelled. The example then examines the property of each task to indicate whether the task has completed successfully or been cancelled. For those that have completed, it displays the value returned by the task. - + property returns a member of the enumeration to indicate the task's current status. + + + +## Examples + The following example creates 20 tasks that will loop until a counter is incremented to a value of 2 million. When the first 10 tasks reach 2 million, the cancellation token is cancelled, and any tasks whose counters have not reached 2 million are cancelled. The example then examines the property of each task to indicate whether the task has completed successfully or been cancelled. For those that have completed, it displays the value returned by the task. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/Run7.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/Run7.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/Run7.vb" id="Snippet7"::: + ]]> @@ -110,7 +110,7 @@ 6 - The task acknowledged cancellation by throwing an OperationCanceledException with its own CancellationToken while the token was in signaled state, or the task's CancellationToken was already signaled before the task started executing. For more information, see [Task Cancellation](/dotnet/standard/parallel-programming/task-cancellation). + The task acknowledged cancellation by throwing an OperationCanceledException with its own CancellationToken while the token was in signaled state, or the task's CancellationToken was already signaled before the task started executing. For more information, see Task Cancellation. diff --git a/xml/System.Threading/EventWaitHandle.xml b/xml/System.Threading/EventWaitHandle.xml index a7aae26f6a6..edc2406811e 100644 --- a/xml/System.Threading/EventWaitHandle.xml +++ b/xml/System.Threading/EventWaitHandle.xml @@ -258,7 +258,7 @@ The class allows threads to communicate -or- There was some other error. The `HResult` property may provide more information. - Windows only: specified an unknown namespace. See [Object Names](https://learn.microsoft.com/windows/win32/sync/object-names) for more information. + Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions may depend on the operating system or configuration. The named event exists and has access control security, but the user does not have . A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. @@ -350,7 +350,7 @@ There was some other error. The `HResult` property may provide more information. -or- There was some other error. The `HResult` property may provide more information. - Windows only: specified an unknown namespace. See [Object Names](https://learn.microsoft.com/windows/win32/sync/object-names) for more information. + Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions may depend on the operating system or configuration. The named event exists and has access control security, but the user does not have . A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. @@ -448,7 +448,7 @@ There was some other error. The `HResult` property may provide more information. -or- There was some other error. The `HResult` property may provide more information. - Windows only: specified an unknown namespace. See [Object Names](https://learn.microsoft.com/windows/win32/sync/object-names) for more information. + Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions may depend on the operating system or configuration. The named event exists and has access control security, but the user does not have . A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. @@ -622,7 +622,7 @@ There was some other error. The `HResult` property may provide more information. -or- There was some other error. The `HResult` property may provide more information. - Windows only: specified an unknown namespace. See [Object Names](/windows/win32/sync/object-names) for more information. + Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions may depend on the operating system or configuration. The named event exists, but the user does not have the security access required to use it. Overview of synchronization primitives @@ -709,7 +709,7 @@ There was some other error. The `HResult` property may provide more information. -or- There was some other error. The `HResult` property may provide more information. - Windows only: specified an unknown namespace. See [Object Names](https://learn.microsoft.com/windows/win32/sync/object-names) for more information. + Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions may depend on the operating system or configuration. The named event exists, but the user does not have the desired security access. Overview of synchronization primitives diff --git a/xml/System.Threading/EventWaitHandleAcl.xml b/xml/System.Threading/EventWaitHandleAcl.xml index 26ea6aeee3a..aeec5aef5f8 100644 --- a/xml/System.Threading/EventWaitHandleAcl.xml +++ b/xml/System.Threading/EventWaitHandleAcl.xml @@ -80,7 +80,7 @@ The `name` may be prefixed with `Global\` or `Local\` to specify a namespace. When the `Global` namespace is specified, the synchronization object may 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 may 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 may 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](https://learn.microsoft.com/windows/win32/sync/object-names). If a `name` is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is opened. If a synchronization object of a different type already exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown. Otherwise, a new synchronization object is created. - + > [!CAUTION] > By default, a named event is not restricted to the user that created it. Other users may 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 pass in an when creating the named event. Avoid using named events without access restrictions on systems that might have untrusted users running code. @@ -99,7 +99,7 @@ -or- There was some other error. The `HResult` property may provide more information. - Windows only: specified an unknown namespace. See [Object Names](https://learn.microsoft.com/windows/win32/sync/object-names) for more information. + Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions may depend on the operating system or configuration. A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. The named event exists, but the user does not have the desired security access. diff --git a/xml/System.Threading/Mutex.xml b/xml/System.Threading/Mutex.xml index a4e805eb25c..d2ae685496b 100644 --- a/xml/System.Threading/Mutex.xml +++ b/xml/System.Threading/Mutex.xml @@ -365,7 +365,7 @@ -or- There was some other error. The `HResult` property may provide more information. - Windows only: specified an unknown namespace. See [Object Names](https://learn.microsoft.com/windows/win32/sync/object-names) for more information. + Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions may depend on the operating system or configuration. A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. @@ -475,7 +475,7 @@ There was some other error. The `HResult` property may provide more information. -or- There was some other error. The `HResult` property may provide more information. - Windows only: specified an unknown namespace. See [Object Names](https://learn.microsoft.com/windows/win32/sync/object-names) for more information. + Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions may depend on the operating system or configuration. A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. @@ -581,7 +581,7 @@ There was some other error. The `HResult` property may provide more information. -or- There was some other error. The `HResult` property may provide more information. - Windows only: specified an unknown namespace. See [Object Names](https://learn.microsoft.com/windows/win32/sync/object-names) for more information. + Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions may depend on the operating system or configuration. The named mutex exists and has access control security, but the user does not have . A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. @@ -763,7 +763,7 @@ There was some other error. The `HResult` property may provide more information. -or- There was some other error. The `HResult` property may provide more information. - Windows only: specified an unknown namespace. See [Object Names](https://learn.microsoft.com/windows/win32/sync/object-names) for more information. + Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions may depend on the operating system or configuration. The named mutex exists, but the user does not have the security access required to use it. @@ -853,7 +853,7 @@ There was some other error. The `HResult` property may provide more information. -or- There was some other error. The `HResult` property may provide more information. - Windows only: specified an unknown namespace. See [Object Names](https://learn.microsoft.com/windows/win32/sync/object-names) for more information. + Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions may depend on the operating system or configuration. The named mutex exists, but the user does not have the desired security access. diff --git a/xml/System.Threading/MutexAcl.xml b/xml/System.Threading/MutexAcl.xml index 9c09c656cbf..330e99c9a11 100644 --- a/xml/System.Threading/MutexAcl.xml +++ b/xml/System.Threading/MutexAcl.xml @@ -78,7 +78,7 @@ The `name` may be prefixed with `Global\` or `Local\` to specify a namespace. When the `Global` namespace is specified, the synchronization object may 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 may 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 may 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](https://learn.microsoft.com/windows/win32/sync/object-names). If a `name` is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is opened. If a synchronization object of a different type already exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown. Otherwise, a new synchronization object is created. - + > [!CAUTION] > By default, a named mutex is not restricted to the user that created it. Other users may be able to open and use the mutex, including interfering with the mutex by entering the mutex and not exiting it. To restrict access to specific users, you can pass in a when creating the named mutex. Avoid using named mutexes without access restrictions on systems that might have untrusted users running code. @@ -92,7 +92,7 @@ -or- There was some other error. The `HResult` property may provide more information. - Windows only: specified an unknown namespace. See [Object Names](https://learn.microsoft.com/windows/win32/sync/object-names) for more information. + Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions may depend on the operating system or configuration. A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. diff --git a/xml/System.Threading/Semaphore.xml b/xml/System.Threading/Semaphore.xml index bc0ee9bd62e..23acc03453f 100644 --- a/xml/System.Threading/Semaphore.xml +++ b/xml/System.Threading/Semaphore.xml @@ -288,7 +288,7 @@ -or- There was some other error. The `HResult` property may provide more information. - Windows only: specified an unknown namespace. See [Object Names](https://learn.microsoft.com/windows/win32/sync/object-names) for more information. + Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions may depend on the operating system or configuration. The named semaphore exists and has access control security, and the user does not have . A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. @@ -401,7 +401,7 @@ There was some other error. The `HResult` property may provide more information. -or- There was some other error. The `HResult` property may provide more information. - Windows only: specified an unknown namespace. See [Object Names](https://learn.microsoft.com/windows/win32/sync/object-names) for more information. + Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions may depend on the operating system or configuration. The named semaphore exists and has access control security, and the user does not have . A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. @@ -502,7 +502,7 @@ There was some other error. The `HResult` property may provide more information. -or- There was some other error. The `HResult` property may provide more information. - Windows only: specified an unknown namespace. See [Object Names](https://learn.microsoft.com/windows/win32/sync/object-names) for more information. + Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions may depend on the operating system or configuration. A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. Managed Threading diff --git a/xml/System.Threading/SemaphoreAcl.xml b/xml/System.Threading/SemaphoreAcl.xml index dfc2475e266..a9d4a236cef 100644 --- a/xml/System.Threading/SemaphoreAcl.xml +++ b/xml/System.Threading/SemaphoreAcl.xml @@ -79,7 +79,7 @@ The `name` may be prefixed with `Global\` or `Local\` to specify a namespace. When the `Global` namespace is specified, the synchronization object may 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 may 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 may 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](https://learn.microsoft.com/windows/win32/sync/object-names). If a `name` is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is opened. If a synchronization object of a different type already exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown. Otherwise, a new synchronization object is created. - + > [!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 pass in a when creating the named semaphore. Avoid using named semaphores without access restrictions on systems that might have untrusted users running code. @@ -87,7 +87,7 @@ is a negative number. - -or- + -or- is not a positive number. @@ -102,7 +102,7 @@ -or- There was some other error. The `HResult` property may provide more information. - Windows only: specified an unknown namespace. See [Object Names](https://learn.microsoft.com/windows/win32/sync/object-names) for more information. + Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions may depend on the operating system or configuration. A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. diff --git a/xml/System.Xml.Schema/XmlSchemaAttributeGroupRef.xml b/xml/System.Xml.Schema/XmlSchemaAttributeGroupRef.xml index 2893b5b0850..f67f7b453b8 100644 --- a/xml/System.Xml.Schema/XmlSchemaAttributeGroupRef.xml +++ b/xml/System.Xml.Schema/XmlSchemaAttributeGroupRef.xml @@ -50,18 +50,18 @@ - Represents the element with the attribute from the XML Schema as specified by the [World Wide Web Consortium (W3C)](https://go.microsoft.com/fwlink/?LinkId=49454). AttributesGroupRef is the reference for an attributeGroup, name property contains the attribute group being referenced. + Represents the element with the attribute from the XML Schema as specified by the World Wide Web Consortium (W3C). AttributesGroupRef is the reference for an attributeGroup, name property contains the attribute group being referenced. - for an example using this class. - + for an example using this class. + ]]> @@ -150,13 +150,13 @@ Gets or sets the name of the referenced element. The name of the referenced attribute group. The value must be a QName. - diff --git a/xml/System.Xml.Xsl.Runtime/XsltFunctions.xml b/xml/System.Xml.Xsl.Runtime/XsltFunctions.xml index 4ff522b62e1..aebba01dd6d 100644 --- a/xml/System.Xml.Xsl.Runtime/XsltFunctions.xml +++ b/xml/System.Xml.Xsl.Runtime/XsltFunctions.xml @@ -55,7 +55,7 @@ The instance that contains the node to be identified by URI. - Returns the value of the base URI of the node of the node passed in by the parameter. Implements XPath function according to the [W3C specification](https://go.microsoft.com/fwlink/?LinkID=4873). + Returns the value of the base URI of the node of the node passed in by the parameter. Implements XPath function according to the W3C specification. The base URI as . To be added. @@ -88,7 +88,7 @@ The string in which to locate . The string to locate in s1. - Implements XPath function according to the [W3C specification](https://go.microsoft.com/fwlink/?LinkID=4873). + Implements XPath function according to the W3C specification. if the first argument string contains the second argument string; otherwise, . To be added. @@ -154,7 +154,7 @@ The specified string. object that contains context. - Implements the function according to the [W3C XPath specification](https://go.microsoft.com/fwlink/?LinkId=143942). + Implements the function according to the W3C XPath specification. . To be added. @@ -192,7 +192,7 @@ String that contains format. String that contains language. Boolean value that indicates whether date/time contains a date. - Implements the and [Microsoft XPath extension functions](https://go.microsoft.com/fwlink/?LinkId=143943). + Implements the and Microsoft XPath extension functions. String that contains formatted date and time. To be added. @@ -223,7 +223,7 @@ The name. - Implements the [Microsoft XPath extension function](https://go.microsoft.com/fwlink/?LinkId=143943). + Implements the Microsoft XPath extension function. Name as . To be added. @@ -256,7 +256,7 @@ The name. The instance. - Implements the [Microsoft XPath extension function](https://go.microsoft.com/fwlink/?LinkId=143943). + Implements the Microsoft XPath extension function. Namespace URI as . To be added. @@ -288,7 +288,7 @@ of . - Implements [Microsoft XPath extension function](https://go.microsoft.com/fwlink/?LinkId=143943). + Implements Microsoft XPath extension function. . To be added. @@ -326,7 +326,7 @@ The second string to compare. The language. Optional. Specifies whether the comparison is case-sensitive. - Implements [Microsoft XPath extension function](https://go.microsoft.com/fwlink/?LinkId=143943). + Implements Microsoft XPath extension function. If < the method returns -1. If == the method returns 0. If > the method returns 1. To be added. @@ -357,14 +357,14 @@ String that contains date/time data. - Implements the [Microsoft XPath extension function](https://go.microsoft.com/fwlink/?LinkId=143943). + Implements the Microsoft XPath extension function. A string that contains date/time information. If a string cannot be interpreted as a valid XSD date/time-related format, it returns an empty string. - @@ -395,7 +395,7 @@ The specified string. - Removes leading and trailing spaces from the specified string and returns the result. Implements function from the [W3C XPath standard](https://go.microsoft.com/fwlink/?LinkID=4873). + Removes leading and trailing spaces from the specified string and returns the result. Implements function from the W3C XPath standard. A normalized string. To be added. @@ -492,7 +492,7 @@ A string, the beginning of which is compared to . The string to compare to the beginning of . - Implements XPath function according to the [W3C specification](https://go.microsoft.com/fwlink/?LinkID=4873). + Implements XPath function according to the W3C specification. if the first argument string starts with the second argument string; otherwise, . To be added. @@ -505,7 +505,7 @@ 4.0.0.0 - Implements XPath function according to [W3C specification](https://go.microsoft.com/fwlink/?LinkID=4873). + Implements XPath function according to W3C specification. @@ -535,7 +535,7 @@ The string from which to retrieve the substring. The starting character position of a substring in . - Implements XPath function according to the [W3C specification](https://go.microsoft.com/fwlink/?LinkID=4873). + Implements XPath function according to the W3C specification. The substring of the first argument starting at the position specified in the second argument. To be added. @@ -570,7 +570,7 @@ The string from which to retrieve the substring. The starting character position of a substring in . The number of characters in the substring. - Implements XPath function according to the [W3C specification](https://go.microsoft.com/fwlink/?LinkID=4873). + Implements XPath function according to the W3C specification. The substring of the first argument, starting at the position specified in the second argument, with the length specified in the third argument. To be added. @@ -603,14 +603,14 @@ The string in which to locate s2. The string to locate in . - Implements XPath function according to the [W3C specification](https://go.microsoft.com/fwlink/?LinkID=4873). + Implements XPath function according to the W3C specification. The characters in s1 that occur after s2, or the empty string if s1 does not contain s2. - @@ -643,14 +643,14 @@ The string in which to locate s2. The string to locate in . - Implements XPath function according to the [W3C specification](https://go.microsoft.com/fwlink/?LinkID=4873). + Implements XPath function according to the W3C specification. The characters in s1 that occur before s2, or the empty string if s1 does not contain s2. - @@ -681,7 +681,7 @@ The name of the system property. - Implements XSLT function according to the [W3C specification](https://go.microsoft.com/fwlink/?LinkID=49919). + Implements XSLT function according to the W3C specification. The value of the system property specified by the . To be added. @@ -716,14 +716,14 @@ The original string. The substring in that should be replaced with . The string to replace with. - Implements XPath function according to the [W3C specification](https://go.microsoft.com/fwlink/?LinkID=4873). + Implements XPath function according to the W3C specification. The translated value as . - diff --git a/xml/System.Xml.Xsl.Runtime/XsltLibrary.xml b/xml/System.Xml.Xsl.Runtime/XsltLibrary.xml index 244f5044195..91eedb0dda1 100644 --- a/xml/System.Xml.Xsl.Runtime/XsltLibrary.xml +++ b/xml/System.Xml.Xsl.Runtime/XsltLibrary.xml @@ -86,15 +86,15 @@ The XML qualified name. - Evaluates the argument to a string that is an XML qualified name. This method implements the element-available function specified by [W3C XSL Transformations (XSLT)](https://go.microsoft.com/fwlink/?LinkID=49919). + Evaluates the argument to a string that is an XML qualified name. This method implements the element-available function specified by W3C XSL Transformations (XSLT). if the expanded name is the name of an instruction. If the has a namespace URI equal to the XSLT namespace URI, then it refers to an element defined by XSLT. Otherwise, the expanded-name refers to an extension element. If the has a null namespace URI, the element-available function will return . - function returns `true` if and only if the `expanded name` is the name of an instruction. - + function returns `true` if and only if the `expanded name` is the name of an instruction. + ]]> @@ -205,11 +205,11 @@ Implements the format-number() XSLT function. For more information, see the number formatting section in the W3C Recommendation. A string that indicates the number format. For more information, see the number formatting section in the W3C Recommendation. - method formats `value` by using the `formatPicture` and decimal-format [expanded name](https://go.microsoft.com/fwlink/?LinkID=148269). The `errorMessageName` is used only for error reporting and must contain the qualified name of the decimal-format object. - + method formats `value` by using the `formatPicture` and decimal-format [expanded name](https://go.microsoft.com/fwlink/?LinkID=148269). The `errorMessageName` is used only for error reporting and must contain the qualified name of the decimal-format object. + ]]> @@ -245,11 +245,11 @@ Implements the format-number() XSLT function. For more information, see the number formatting section in the W3C Recommendation. A string that indicates the format. For more information, see the number formatting section in the W3C Recommendation. - method formats the given value by using the given decimal formatter object, created by . - + method formats the given value by using the given decimal formatter object, created by . + ]]> @@ -506,14 +506,14 @@ - Specifies how to perform the evaluation of two expressions: - - If opCode is equal to 2, evaluates the XPath expression "left < right". - - If opCode is equal to 3, evaluates the XPath expression "left <= right". - - If opCode is equal to 4, evaluates the XPath expression "left > right". - + Specifies how to perform the evaluation of two expressions: + + If opCode is equal to 2, evaluates the XPath expression "left < right". + + If opCode is equal to 3, evaluates the XPath expression "left <= right". + + If opCode is equal to 4, evaluates the XPath expression "left > right". + If opCode is equal to 5, evaluates the XPath expression "left >= right" Expression to evaluate. Expression to evaluate. diff --git a/xml/System.Xml/XmlNode.xml b/xml/System.Xml/XmlNode.xml index b9413a99af7..e87fbffd98c 100644 --- a/xml/System.Xml/XmlNode.xml +++ b/xml/System.Xml/XmlNode.xml @@ -2998,7 +2998,7 @@ nodeList = root.SelectNodes("//book[contains(title,""'Emma'"")]") ]]> - The XPath expression contains a prefix. See [XPath Examples](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/ms256086(v=vs.100)). + The XPath expression contains a prefix. See XPath Examples. XPath Selections and Custom Functions, and More W3C XPath 1.0 recommendation @@ -3047,7 +3047,7 @@ nodeList = root.SelectNodes("//book[contains(title,""'Emma'"")]") - The XPath expression. See [XPath Examples](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/ms256086(v=vs.100)). + The XPath expression. See XPath Examples. An to use for resolving namespaces for prefixes in the XPath expression. Selects a list of nodes matching the XPath expression. Any prefixes found in the XPath expression are resolved using the supplied . An containing a collection of nodes matching the XPath query. @@ -3201,7 +3201,7 @@ nodeList = root.SelectNodes("//ab:book[contains(ab:title,""'Emma'"")]", nsmgr) - The XPath expression. See [XPath Examples](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/ms256086(v=vs.100)). + The XPath expression. See XPath Examples. Selects the first that matches the XPath expression. The first that matches the XPath query or if no matching node is found. @@ -3298,7 +3298,7 @@ book = root.SelectSingleNode("descendant::book[title=""'Emma'""]") - The XPath expression. See [XPath Examples](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/ms256086(v=vs.100)). + The XPath expression. See XPath Examples. An to use for resolving namespaces for prefixes in the XPath expression. Selects the first that matches the XPath expression. Any prefixes found in the XPath expression are resolved using the supplied . The first that matches the XPath query or if no matching node is found. diff --git a/xml/System.Xml/XmlWriterSettings.xml b/xml/System.Xml/XmlWriterSettings.xml index 4509b7d9a55..cbf4430f72e 100644 --- a/xml/System.Xml/XmlWriterSettings.xml +++ b/xml/System.Xml/XmlWriterSettings.xml @@ -271,7 +271,7 @@ System.Boolean - Gets or sets a value that indicates whether the XML writer should check to ensure that all characters in the document conform to the "2.2 Characters" section of the W3C [XML 1.0 Recommendation](https://www.w3.org/TR/REC-xml/#charsets). + Gets or sets a value that indicates whether the XML writer should check to ensure that all characters in the document conform to the "2.2 Characters" section of the W3C XML 1.0 Recommendation. to do character checking; otherwise, . The default is .