From b1462f8602814b80d5d7786b77ab1594395327f9 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 29 May 2026 13:44:59 -0700 Subject: [PATCH 1/3] Remove .NET Framework remarks (System.InteropServices) (#12670) --- .../CALLCONV.xml | 5 +- .../IPersistFile.xml | 78 +++++++++---------- .../ClassInterfaceType.xml | 26 +++---- .../ComRegisterFunctionAttribute.xml | 9 +-- .../ComUnregisterFunctionAttribute.xml | 4 +- .../CriticalHandle.xml | 8 +- .../DllImportAttribute.xml | 19 +---- .../Marshal.xml | 36 ++++----- .../RuntimeEnvironment.xml | 59 ++------------ .../RuntimeInformation.xml | 2 - .../SEHException.xml | 2 +- .../SafeBuffer.xml | 5 +- .../SafeHandle.xml | 6 +- .../StructLayoutAttribute.xml | 2 +- .../UnmanagedType.xml | 6 +- .../VariantWrapper.xml | 8 +- 16 files changed, 92 insertions(+), 183 deletions(-) diff --git a/xml/System.Runtime.InteropServices.ComTypes/CALLCONV.xml b/xml/System.Runtime.InteropServices.ComTypes/CALLCONV.xml index 11e8c0c15f1..c89034ab99a 100644 --- a/xml/System.Runtime.InteropServices.ComTypes/CALLCONV.xml +++ b/xml/System.Runtime.InteropServices.ComTypes/CALLCONV.xml @@ -61,14 +61,11 @@ The calling conventions in this class describe how functions pass arguments and return values. They specify the order in which parameters are set up for the called functions, where the parameters are stored (in registers or in memory), and who (caller or called function) is responsible for cleaning up the stack after the function returns. For example: - CC_CDECL uses the naming and calling conventions of the C language. The caller pushes the parameters onto the stack in reverse (right-to-left) order, and cleans the stack after the function returns. This calling convention enables you to call functions with `varargs`, which makes it appropriate for use with methods that accept a variable number of parameters, such as the C run-time functions [printf, _printf_l, wprintf, _wprintf_l](https://learn.microsoft.com/cpp/c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l). - - CC_PASCAL uses the Pascal calling convention. The caller pushes the parameters onto the stack in left-to-right order. The called function cleans the stack before returning. - - CC_STDCALL is the standard calling convention for Win32 functions. It is the default convention for calling unmanaged functions with platform invoke. The caller pushes the parameters onto the stack in reverse (right to left) order, and the called function cleans the stack before returning. - - CC_SYSCALL is similar to CDECL in that arguments are pushed from right to left. The EAX, ECX, and EDX registers are not preserved. - These calling convention identifiers are used by the .NET Framework, the Windows Embedded CE platform, and by Automation. +These calling convention identifiers are used by .NET, the Windows Embedded CE platform, and by Automation. The common language runtime throws an exception when a COM method in native code returns an HRESULT. For more information, see [How to: Map HRESULTs and Exceptions](/dotnet/framework/interop/how-to-map-hresults-and-exceptions). diff --git a/xml/System.Runtime.InteropServices.ComTypes/IPersistFile.xml b/xml/System.Runtime.InteropServices.ComTypes/IPersistFile.xml index e0394989eae..445d3692914 100644 --- a/xml/System.Runtime.InteropServices.ComTypes/IPersistFile.xml +++ b/xml/System.Runtime.InteropServices.ComTypes/IPersistFile.xml @@ -58,13 +58,13 @@ Provides the managed definition of the interface, with functionality from . - @@ -113,11 +113,11 @@ When this method returns, contains a reference to the CLSID. This parameter is passed uninitialized. Retrieves the class identifier (CLSID) of an object. - @@ -166,11 +166,11 @@ When this method returns, contains the address of a pointer to a zero-terminated string containing the path for the current file, or the default file name prompt (such as *.txt). This parameter is passed uninitialized. Retrieves either the absolute path to the current working file of the object or, if there is no current working file, the default file name prompt of the object. - @@ -218,11 +218,11 @@ if the file has changed since it was last saved; if the file has not changed since it was last saved. - @@ -273,13 +273,13 @@ A combination of values from the enumeration to indicate the access mode in which to open . Opens the specified file and initializes an object from the file contents. - @@ -332,11 +332,11 @@ to used the parameter as the current working file; otherwise . Saves a copy of the object into the specified file. - @@ -385,11 +385,11 @@ The absolute path of the file where the object was previously saved. Notifies the object that it can write to its file. - diff --git a/xml/System.Runtime.InteropServices/ClassInterfaceType.xml b/xml/System.Runtime.InteropServices/ClassInterfaceType.xml index 81dff0d3e2b..20188f01e20 100644 --- a/xml/System.Runtime.InteropServices/ClassInterfaceType.xml +++ b/xml/System.Runtime.InteropServices/ClassInterfaceType.xml @@ -50,20 +50,20 @@ Identifies the type of class interface that is generated for a class. - attribute. - - - -## Examples - This example shows how to apply the to a type, setting the . Classes defined this way can be used from unmanaged COM. - + attribute. + + + +## Examples + This example shows how to apply the to a type, setting the . Classes defined this way can be used from unmanaged COM. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ClassInterfaceType/cpp/ClassInterfaceType.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/ClassInterfaceType/Overview/ClassInterfaceType.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.InteropServices/ClassInterfaceType/Overview/ClassInterfaceType.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.InteropServices/ClassInterfaceType/Overview/ClassInterfaceType.vb" id="Snippet1"::: + ]]> Tlbexp.exe (Type Library Exporter) @@ -221,7 +221,7 @@ Indicates that no class interface is generated for the class. If no interfaces are implemented explicitly, the class can only provide late-bound access through the interface. This is the recommended setting for . Using is the only way to expose functionality through interfaces implemented explicitly by the class. - Tlbexp.exe (Type Library Exporter) exposes the first public, COM-visible interface implemented by the class as the default interface of the coclass. In .NET Framework 2.0 and later versions, you can specify the default interface exposed to COM by using the attribute. If the class implements no interfaces, the first public, COM-visible interface implemented by a base class becomes the default interface (starting with the most recently derived base class and working backward). Tlbexp.exe exposes as the default interface if neither the class nor its base classes implement interfaces. + Tlbexp.exe (Type Library Exporter) exposes the first public, COM-visible interface implemented by the class as the default interface of the coclass. You can specify the default interface exposed to COM by using the attribute. If the class implements no interfaces, the first public, COM-visible interface implemented by a base class becomes the default interface (starting with the most recently derived base class and working backward). Tlbexp.exe exposes as the default interface if neither the class nor its base classes implement interfaces. diff --git a/xml/System.Runtime.InteropServices/ComRegisterFunctionAttribute.xml b/xml/System.Runtime.InteropServices/ComRegisterFunctionAttribute.xml index f23484d807e..8ad617251a6 100644 --- a/xml/System.Runtime.InteropServices/ComRegisterFunctionAttribute.xml +++ b/xml/System.Runtime.InteropServices/ComRegisterFunctionAttribute.xml @@ -59,22 +59,15 @@ `ComRegisterFunctionAttribute` enables you to add arbitrary registration code to accommodate the requirements of COM clients. For example, you can update the registry using registration functions from the namespace. If you provide a registration method, you should also apply to an unregistration method, which reverses the operations done in the registration method. -**.NET Framework:** The common language runtime calls the method with this attribute when its containing assembly is registered (directly or indirectly) with the [Regasm.exe (Assembly Registration) tool)](/dotnet/framework/tools/regasm-exe-assembly-registration-tool) or through the method. - -**.NET Core:** The common language runtime calls the method with this attribute when its containing assembly's COM host is registered via the [RegSvr32.exe tool](https://learn.microsoft.com/windows-server/administration/windows-commands/regsvr32). +The common language runtime calls the method with this attribute when its containing assembly's COM host is registered via the [RegSvr32.exe tool](https://learn.microsoft.com/windows-server/administration/windows-commands/regsvr32). This attribute can be applied only to methods that have the following characteristics: - Scope: Any (public, private, and so on). - - Type: `static`. - - Parameters: Accepts a single parameter or a parameter type. - - Return type: `void`. - - ## Examples The following example demonstrates how to apply and to methods with the appropriate signature. diff --git a/xml/System.Runtime.InteropServices/ComUnregisterFunctionAttribute.xml b/xml/System.Runtime.InteropServices/ComUnregisterFunctionAttribute.xml index 89978431ccc..f50bf62e663 100644 --- a/xml/System.Runtime.InteropServices/ComUnregisterFunctionAttribute.xml +++ b/xml/System.Runtime.InteropServices/ComUnregisterFunctionAttribute.xml @@ -59,9 +59,7 @@ `ComUnregisterFunctionAttribute` enables you to add code that reverses the operations performed by a registration method. If you apply the to provide a registration method, you should also provide an unregistration method to reverse the operations done in the registration method. You can have only one unregistration method for a class. -**.NET Framework:** The common language runtime calls the method with this attribute when its containing assembly is unregistered (directly or indirectly) with the [Regasm.exe (Assembly Registration) tool)](/dotnet/framework/tools/regasm-exe-assembly-registration-tool) or through the method. - - **.NET Core:** The common language runtime calls the method with this attribute when its containing assembly's COM host is unregistered via the [RegSvr32.exe tool](https://learn.microsoft.com/windows-server/administration/windows-commands/regsvr32). +The common language runtime calls the method with this attribute when its containing assembly's COM host is unregistered via the [RegSvr32.exe tool](https://learn.microsoft.com/windows-server/administration/windows-commands/regsvr32). ## Examples The following example demonstrates applying and to methods with the appropriate signature. diff --git a/xml/System.Runtime.InteropServices/CriticalHandle.xml b/xml/System.Runtime.InteropServices/CriticalHandle.xml index 0b7bb4d835b..30097cc5471 100644 --- a/xml/System.Runtime.InteropServices/CriticalHandle.xml +++ b/xml/System.Runtime.InteropServices/CriticalHandle.xml @@ -652,11 +652,9 @@ method is guaranteed to be called only once, provided that you employ proper synchronization mechanisms to ensure that only one call to the or method is made. The method will not be called if the or property is `true`. Implement this method in your derived classes to execute any code that is required to free the handle. Because one of the functions of is to guarantee prevention of resource leaks, the code in your implementation of must never fail. The garbage collector calls after normal finalizers have been run for objects that were garbage collected at the same time, and guarantees the resources to invoke it and that it will not be interrupted while it is in progress. This method will be prepared as a constrained execution region (CER) at instance construction time (along with all the methods in its statically determinable call graph). Although this prevents thread abort interrupts, you must still be careful not to introduce any fault paths in your overridden method. In particular, apply the attribute to any methods you call from . In most cases this code should be: + The method is guaranteed to be called only once, provided that you employ proper synchronization mechanisms to ensure that only one call to the or method is made. The method will not be called if the or property is `true`. Implement this method in your derived classes to execute any code that is required to free the handle. Because one of the functions of is to guarantee prevention of resource leaks, the code in your implementation of must never fail. The garbage collector calls after normal finalizers have been run for objects that were garbage collected at the same time, and guarantees the resources to invoke it and that it will not be interrupted while it is in progress. - `ReliabilityContract(Consistency.WillNotCorruptState, Cer.Success)` - - Additionally, for simple cleanup (for example, calling the Windows API `CloseHandle` on a file handle) you can check the return value for the single platform invoke call. For complex cleanup, you may have a lot of program logic and many method calls, some of which might fail. You must ensure that your program logic has fallback code for each of those cases. +For simple cleanup (for example, calling the Windows API `CloseHandle` on a file handle) you can check the return value for the single platform invoke call. For complex cleanup, you might have a lot of program logic and many method calls, some of which might fail. You must ensure that your program logic has fallback code for each of those cases. If the method returns `false` for any reason, it generates a [releaseHandleFailed](/dotnet/framework/debug-trace-profile/releasehandlefailed-mda) Managed Debugging Assistant. @@ -720,7 +718,7 @@ method only if you need to support a pre-existing handle (for example, if the handle is returned in a structure) because the .NET Framework COM interop infrastructure does not support marshaling handles in a structure. + Use the method only if you need to support a pre-existing handle (for example, if the handle is returned in a structure) because the COM interop infrastructure does not support marshaling handles in a structure. ]]> diff --git a/xml/System.Runtime.InteropServices/DllImportAttribute.xml b/xml/System.Runtime.InteropServices/DllImportAttribute.xml index 16e46f1ec95..7ef58fbc814 100644 --- a/xml/System.Runtime.InteropServices/DllImportAttribute.xml +++ b/xml/System.Runtime.InteropServices/DllImportAttribute.xml @@ -131,20 +131,11 @@ For additional information about using the platform invoke service to access fun - The name of the DLL that contains the unmanaged method. In .NET Framework, this can include an assembly display name, if the DLL is included in an assembly. + The name of the DLL that contains the unmanaged method. Initializes a new instance of the class with the name of the DLL containing the method to import. attribute to import the Win32 `MessageBox` function. The code example then calls the imported method. @@ -593,13 +584,9 @@ For additional information about using the platform invoke service to access fun `true` to indicate that the callee will set an error via `SetLastError` on Windows or `errno` on other platforms; otherwise, `false`. The default is `false`. If this field is set to `true`, the runtime marshaler calls `GetLastError` or `errno` and caches the value returned to prevent it from being overwritten by other API calls. - You can retrieve the error code by calling on .NET 6.0 and above - or on .NET 5 and below or .NET Framework. + On .NET 6 and later, you can retrieve the error code by calling . On earlier .NET versions, call . - On .NET, the error information is cleared (set to `0`) before invoking the callee when this field is set to `true`. On .NET Framework, the error information is not cleared. - This means that error information returned by and - on .NET represents only the error information from the last p/invoke with - set to `true`. On .NET Framework, the error information can persist from one p/invoke to the next. +The error information is cleared (set to `0`) before invoking the callee when this field is set to `true`. This means that error information returned by and represents only the error information from the last p/invoke with set to `true`. ## Examples In some cases, Visual Basic developers use the , instead of using the `Declare` statement, to define a DLL function in managed code. Setting the field is one of those cases. diff --git a/xml/System.Runtime.InteropServices/Marshal.xml b/xml/System.Runtime.InteropServices/Marshal.xml index 834ffa63a47..1e1f5ce4d95 100644 --- a/xml/System.Runtime.InteropServices/Marshal.xml +++ b/xml/System.Runtime.InteropServices/Marshal.xml @@ -286,14 +286,12 @@ ## Remarks > [!IMPORTANT] -> This native memory allocator is a legacy API that should be used exclusively when called for by specific Win32 APIs on the Windows platform. When targeting .NET 6 or later, use the class on all platforms to allocate native memory. When targeting .NET Framework, use on all platforms to allocate native memory. +> This native memory allocator is a legacy API that should be used exclusively when called for by specific Win32 APIs on the Windows platform. On .NET 6 and later, use the class on all platforms to allocate native memory. is one of two memory allocation methods in the class. ( is the other.) This method exposes the Win32 [LocalAlloc](https://learn.microsoft.com/windows/win32/api/winbase/nf-winbase-localalloc) function from Kernel32.dll. When calls `LocalAlloc`, it passes a `LMEM_FIXED` flag, which causes the allocated memory to be locked in place. Also, the allocated memory is not zero-filled. - - ## Examples The following example demonstrates calling the method. This code example is part of a larger example provided for the class. @@ -364,7 +362,7 @@ ## Remarks > [!IMPORTANT] -> This native memory allocator is a legacy API that should be used exclusively when called for by specific Win32 APIs on the Windows platform. When targeting .NET 6 or later, use the class on all platforms to allocate native memory. When targeting .NET Framework, use on all platforms to allocate native memory. +> This native memory allocator is a legacy API that should be used exclusively when called for by specific Win32 APIs on the Windows platform. On .NET 6 and later versions, use the class on all platforms to allocate native memory. is one of two memory allocation methods in the class. ( is the other.) This method exposes the Win32 [LocalAlloc](https://learn.microsoft.com/windows/win32/api/winbase/nf-winbase-localalloc) function from Kernel32.dll. @@ -2600,7 +2598,7 @@ ## Remarks > [!IMPORTANT] -> This native memory allocator is a legacy API that should be used exclusively when called for by specific Win32 APIs on the Windows platform. When targeting .NET 6 or later, use the class on all platforms to allocate native memory. When targeting .NET Framework, use on all platforms to allocate native memory. +> This native memory allocator is a legacy API that should be used exclusively when called for by specific Win32 APIs on the Windows platform. On .NET 6 and later versions, use the class on all platforms to allocate native memory. You can use to free any memory from the global heap allocated by , , or any equivalent unmanaged API method. If the `hglobal` parameter is the method does nothing. @@ -3496,7 +3494,7 @@ The current [IErrorInfo](/windows/win32/api/oaidl/nn-oaidl-ierrorinfo) interface is used to construct the exception. - For the mapping from each HRESULT to its comparable exception class in the .NET Framework, see [How to: Map HRESULTs and Exceptions](/dotnet/framework/interop/how-to-map-hresults-and-exceptions). + For the mapping from each HRESULT to its comparable exception class in .NET, see [How to: Map HRESULTs and Exceptions](/dotnet/framework/interop/how-to-map-hresults-and-exceptions). ]]> @@ -3565,7 +3563,7 @@ Use this method overload if you have custom error information that you have to supply in the conversion. - For the mapping from each HRESULT to its comparable exception class in the .NET Framework, see [How to: Map HRESULTs and Exceptions](/dotnet/framework/interop/how-to-map-hresults-and-exceptions). + For the mapping from each HRESULT to its comparable exception class in .NET, see [How to: Map HRESULTs and Exceptions](/dotnet/framework/interop/how-to-map-hresults-and-exceptions). ]]> @@ -4357,9 +4355,9 @@ On Windows systems, to the method signature and set the field to `true`. The process for this varies depending upon the source language used: C# and C++ are `false` by default, but the `Declare` statement in Visual Basic is `true`. -There is a difference in the behavior of the `GetLastWin32Error` method on .NET Core and .NET Framework when is `true`. On .NET Framework, the `GetLastWin32Error` method can retain error information from one P/Invoke call to the next. On .NET Core, error information is cleared before P/Invoke call, and the `GetLastWin32Error` represents only error information from the last method call. +Error information is cleared before P/Invoke call, and the `GetLastWin32Error` represents only error information from the last method call. -On .NET 6 and later versions, this method is functionally equivalent to , which is named to better reflect the intent of the API and its cross-platform nature. should be preferred over . +This method is functionally equivalent to , which is named to better reflect the intent of the API and its cross-platform nature. On .NET 6 and later versions, prefer over . ## Examples The following example calls the `GetLastWin32Error` method. The example first demonstrates calling the method with no error present and then demonstrates calling the method with an error present. @@ -8242,7 +8240,7 @@ On .NET 6 and later versions, this method is functionally equivalent to [!IMPORTANT] -> This native memory allocator is a legacy API that should be used exclusively when called for by specific Win32 APIs on the Windows platform. When targeting .NET 6 or later, use the class on all platforms to allocate native memory. When targeting .NET Framework, use on all platforms to allocate native memory. +> This native memory allocator is a legacy API that should be used exclusively when called for by specific Win32 APIs on the Windows platform. For .NET 6 and later, use the class instead to allocate native memory. On earlier targets where is unavailable, continue to use the appropriate allocation APIs. is one of two memory reallocation API methods in the class. ( is the other.) @@ -8401,13 +8399,13 @@ On .NET 6 and later versions, this method is functionally equivalent to method decrements the reference count of an RCW. When the reference count reaches zero, the runtime releases all its references on the unmanaged COM object, and throws a if you attempt to use the object further. If the same COM interface is passed more than one time from unmanaged to managed code, the reference count on the wrapper is incremented every time, and calling returns the number of remaining references. - This method enables you to force an RCW reference count release so that it occurs precisely when you want it to. However, improper use of may cause your application to fail, or may cause an access violation. + This method enables you to force an RCW reference count release so that it occurs precisely when you want it to. However, improper use of might cause your application to fail, or might cause an access violation. - Consider a scenario in which managed code in an application domain is holding onto an RCW that represents a COM component. If you call the method on the RCW, the managed code will be unable to access the RCW and will raise an exception. + Consider a scenario in which managed code is holding onto an RCW that represents a COM component. If you call the method on the RCW, the managed code will be unable to access the RCW and will raise an exception. - A more serious error may occur if a call to the RCW is executing when the RCW is released. In this case, there is a good chance that the thread making the call will cause an access violation. However, process memory may become corrupted, and the process may continue to run until it fails for reasons that are very difficult to debug. + A more serious error can occur if a call to the RCW is executing when the RCW is released. In this case, there is a good chance that the thread making the call will cause an access violation. However, process memory can become corrupted, and the process might continue to run until it fails for reasons that are very difficult to debug. - This risk is compounded when the COM component that is being used is a singleton, for the following reason: The CLR activates COM components by calling the COM [CoCreateInstance](https://learn.microsoft.com/windows/win32/api/combaseapi/nf-combaseapi-cocreateinstance) function, which returns the same interface pointer every time it is called for singleton COM components. Thus, separate and independent pieces of managed code in an application domain can be using the same RCW for a singleton COM component, and if either one calls the method on the COM component, the other will be broken. + This risk is compounded when the COM component that is being used is a singleton, for the following reason: The CLR activates COM components by calling the COM [CoCreateInstance](https://learn.microsoft.com/windows/win32/api/combaseapi/nf-combaseapi-cocreateinstance) function, which returns the same interface pointer every time it is called for singleton COM components. Thus, separate and independent pieces of managed code can be using the same RCW for a singleton COM component, and if either one calls the method on the COM component, the other will be broken. Therefore, use the only if it is absolutely required. If you want to call this method to ensure that a COM component is released at a determined time, consider using the method instead. will release the underlying COM component regardless of how many times it has re-entered the CLR. The internal reference count of the RCW is incremented by one every time the COM component re-enters the CLR. Therefore, you could call the method in a loop until the value returned is zero. This achieves the same result as the method. @@ -9830,11 +9828,7 @@ The system error is based on the current operating system—that is, `errno` ]]> - is a reference type that is not a formatted class. - - -or- - - is an instance of a generic type (in the .NET Framework 4.5 and earlier versions only). + is a reference type that is not a formatted class. @@ -10131,7 +10125,7 @@ The system error is based on the current operating system—that is, `errno` Some failure HRESULTs map to defined exceptions, whereas others do not. If the HRESULT maps to a defined exception, creates an instance of the exception and throws it. Otherwise, it creates an instance of , initializes the error code field with the HRESULT, and throws that exception. When is invoked, it attempts to retrieve extra information regarding the error by using the unmanaged [GetErrorInfo](/windows/win32/api/oleauto/nf-oleauto-geterrorinfo) function. - For the mapping from each HRESULT to its comparable exception class in the .NET Framework, see [How to: Map HRESULTs and Exceptions](/dotnet/framework/interop/how-to-map-hresults-and-exceptions). + For the mapping from each HRESULT to its comparable exception class in .NET, see [How to: Map HRESULTs and Exceptions](/dotnet/framework/interop/how-to-map-hresults-and-exceptions). Occasionally, might return an exception from a previous COM call. In this case, you can use the following workaround and pass `IntPtr(-1)` as the second parameter (`errorInfo`): @@ -10208,7 +10202,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) Some failure HRESULTs map to defined exceptions, whereas others do not. If the HRESULT maps to a defined exception, creates an instance of the exception and throws it. Otherwise, it creates an instance of , initializes the error code field with the HRESULT, and throws that exception. The `errorInfo` parameter is used to retrieve extra information regarding the error. - For the mapping from each HRESULT to its comparable exception class in the .NET Framework, see [How to: Map HRESULTs and Exceptions](/dotnet/framework/interop/how-to-map-hresults-and-exceptions). + For the mapping from each HRESULT to its comparable exception class in .NET, see [How to: Map HRESULTs and Exceptions](/dotnet/framework/interop/how-to-map-hresults-and-exceptions). ]]> diff --git a/xml/System.Runtime.InteropServices/RuntimeEnvironment.xml b/xml/System.Runtime.InteropServices/RuntimeEnvironment.xml index 33bc139926f..b819120e480 100644 --- a/xml/System.Runtime.InteropServices/RuntimeEnvironment.xml +++ b/xml/System.Runtime.InteropServices/RuntimeEnvironment.xml @@ -226,29 +226,8 @@ The identifier for the desired interface. Returns the specified interface on the specified class. An unmanaged pointer to the requested interface. - - is similar to the method. - - ]]> - - - IUnknown::QueryInterface failure. - .NET Core and .NET 5+ only: In all cases. + To be added. + In all cases. @@ -300,17 +279,8 @@ The following table shows the supported combinations for `clsid` and `riid`. The identifier for the desired interface. Returns an instance of a type that represents a COM object by a pointer to its interface. An object that represents the specified unmanaged COM object. - - is similar to the method. - - ]]> - - - IUnknown::QueryInterface failure. - .NET Core and .NET 5+ only: In all cases. + To be added. + In all cases. @@ -353,11 +323,7 @@ The following table shows the supported combinations for `clsid` and `riid`. Gets the version number of the common language runtime that's running the current process. A string containing the version number of the common language runtime. - On .NET 8 and later versions, this method returns v concatenated with , which is the version of the CLR. For example: v8.0.0. - - On .NET Framework, this method returns , for example, v4.0.30319. - - + On .NET 8 and later, this method returns v concatenated with , which is the version of the CLR. For example: v8.0.0. @@ -405,19 +371,8 @@ The following table shows the supported combinations for `clsid` and `riid`. Gets the path to the system configuration file. The path to the system configuration file. - - property. This code example is part of a larger example provided for the class. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/RuntimeEnvironment/cpp/RuntimeEnvironment.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/RuntimeEnvironment/Overview/RuntimeEnvironment.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.InteropServices/RuntimeEnvironment/Overview/RuntimeEnvironment.vb" id="Snippet5"::: - - ]]> - - .NET Core and .NET 5+ only: In all cases. + To be added. + In all cases. diff --git a/xml/System.Runtime.InteropServices/RuntimeInformation.xml b/xml/System.Runtime.InteropServices/RuntimeInformation.xml index 07493a7185f..4432c56bce8 100644 --- a/xml/System.Runtime.InteropServices/RuntimeInformation.xml +++ b/xml/System.Runtime.InteropServices/RuntimeInformation.xml @@ -111,8 +111,6 @@ The property returns a string that indicates the name of the currently executing - ".NET" (for .NET 5 and later versions) - ".NET Core" (for .NET Core 1.0 - 3.1) -- ".NET Framework" -- ".NET Native" ]]> diff --git a/xml/System.Runtime.InteropServices/SEHException.xml b/xml/System.Runtime.InteropServices/SEHException.xml index 41144b6db80..3a8e298e19a 100644 --- a/xml/System.Runtime.InteropServices/SEHException.xml +++ b/xml/System.Runtime.InteropServices/SEHException.xml @@ -67,7 +67,7 @@ ## Remarks -The class handles SEH errors that are thrown from unmanaged code, but that have not been mapped to another .NET Framework exception. The class also corresponds to the `HRESULT` `E_FAIL` (0x80004005). +The class handles SEH errors that are thrown from unmanaged code, but that have not been mapped to another .NET exception. The class also corresponds to the `HRESULT` `E_FAIL` (0x80004005). .NET often encounters unmanaged SEH exceptions that are automatically mapped to managed equivalents. There are two common unmanaged SEH exceptions: diff --git a/xml/System.Runtime.InteropServices/SafeBuffer.xml b/xml/System.Runtime.InteropServices/SafeBuffer.xml index abfd1d43936..79c7b9ff1ca 100644 --- a/xml/System.Runtime.InteropServices/SafeBuffer.xml +++ b/xml/System.Runtime.InteropServices/SafeBuffer.xml @@ -194,15 +194,14 @@ returns, you should perform bounds checking by verifying that the `pointer` parameter is `null`. If it is not `null`, you must call the method in a constrained execution region (CER). + When returns, you should perform bounds checking by verifying that the `pointer` parameter is `null`. If it is not `null`, you must call the method. calls the method and exposes the pointer. The following example demonstrates how to use the method: -``` +```csharp byte* pointer = null; -RuntimeHelpers.PrepareConstrainedRegions(); try { MySafeBuffer.AcquirePointer(ref pointer); // Use pointer here, with your own bounds checking. diff --git a/xml/System.Runtime.InteropServices/SafeHandle.xml b/xml/System.Runtime.InteropServices/SafeHandle.xml index ec626c1f0cd..bc99b8c4786 100644 --- a/xml/System.Runtime.InteropServices/SafeHandle.xml +++ b/xml/System.Runtime.InteropServices/SafeHandle.xml @@ -364,7 +364,7 @@ If this call is successful, it will set the `ref bool success` parameter to `tru derived class. This method is needed for backwards compatibility because many properties in the .NET Framework return `IntPtr` handle types. `IntPtr` handle types are platform-specific types used to represent a pointer or a handle. + You can use this method to retrieve the actual handle value from an instance of the derived class. This method is needed for backwards compatibility because many properties in .NET return `IntPtr` handle types. `IntPtr` handle types are platform-specific types used to represent a pointer or a handle. > [!CAUTION] > Using the method can pose security risks because, if the handle has been marked as invalid with , still returns the original, potentially stale handle value. The returned handle can also be recycled at any point. At best, this means the handle might suddenly stop working. At worst, if the handle or the resource that the handle represents is exposed to untrusted code, this can lead to a recycling security attack on the reused or returned handle. For example, an untrusted caller can query data on the handle just returned and receive information for an entirely unrelated resource. See the and the methods for more information about using the method safely. @@ -887,8 +887,6 @@ If this call is successful, it will set the `ref bool success` parameter to `tru Additionally, for simple cleanup (for example, calling the Windows API `CloseHandle` on a file handle) you can check the return value for the single platform invoke call. For complex cleanup, you may have a lot of program logic and many method calls, some of which might fail. You must ensure that your program logic has fallback code for each of those cases. - If returns `false` for any reason, it generates a [releaseHandleFailed](/dotnet/framework/debug-trace-profile/releasehandlefailed-mda) Managed Debugging Assistant when running on .NET Framework. This helps you detect cases where your attempt to release resources fails. - ## Examples The following code example releases the handle and is part of a larger example provided for the class. @@ -954,7 +952,7 @@ If this call is successful, it will set the `ref bool success` parameter to `tru method only if you need to support a pre-existing handle (for example, if the handle is returned in a structure) because the .NET Framework COM interop infrastructure does not support marshaling output handles in a structure. + Use the method only if you need to support a pre-existing handle (for example, if the handle is returned in a structure) because the .NET COM interop infrastructure does not support marshaling output handles in a structure. ]]> diff --git a/xml/System.Runtime.InteropServices/StructLayoutAttribute.xml b/xml/System.Runtime.InteropServices/StructLayoutAttribute.xml index 9b56706ac6c..32f579caa0b 100644 --- a/xml/System.Runtime.InteropServices/StructLayoutAttribute.xml +++ b/xml/System.Runtime.InteropServices/StructLayoutAttribute.xml @@ -308,7 +308,7 @@ If is set to 8, :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/StructLayoutAttribute/Pack/packex4.cs" id="Snippet5"::: -To take another example, consider the following structure, which consists of two byte fields, one 32-bit signed integer field, one single-element byte array, and a decimal value. With the default packing size, the size of the structure is 28 bytes in .NET Framework and 32 bytes in .NET 5+. The two bytes occupy the first two bytes of memory, followed by two bytes of padding, followed by the integer. Next is the one-byte array, followed by three bytes of padding. Because a decimal value consists of several fields, the alignment is based on the largest of its fields rather than the size of the structure as a whole. In .NET 5 and later versions, the structure consists of two fields and one 8-byte field, so the field, d5, aligns on an 8-byte boundary. In .NET Framework, the structure consists of four fields, so the field, d5, aligns on an 4-byte boundary. +To take another example, consider the following structure, which consists of two byte fields, one 32-bit signed integer field, one single-element byte array, and a decimal value. With the default packing size, the size of the structure is 32 bytes. The two bytes occupy the first two bytes of memory, followed by two bytes of padding, followed by the integer. Next is the one-byte array, followed by three bytes of padding. Because a decimal value consists of several fields, the alignment is based on the largest of its fields rather than the size of the structure as a whole. The structure consists of two fields and one 8-byte field, so the field, d5, aligns on an 8-byte boundary. :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/StructLayoutAttribute/Pack/packex5.cs" id="Snippet6"::: diff --git a/xml/System.Runtime.InteropServices/UnmanagedType.xml b/xml/System.Runtime.InteropServices/UnmanagedType.xml index c6a33993fd3..47c4ae506a4 100644 --- a/xml/System.Runtime.InteropServices/UnmanagedType.xml +++ b/xml/System.Runtime.InteropServices/UnmanagedType.xml @@ -61,11 +61,7 @@ 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/). - - + Use the 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 .NET, and various miscellaneous types. ## 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. diff --git a/xml/System.Runtime.InteropServices/VariantWrapper.xml b/xml/System.Runtime.InteropServices/VariantWrapper.xml index 3647ac1a03b..e9d585cb82d 100644 --- a/xml/System.Runtime.InteropServices/VariantWrapper.xml +++ b/xml/System.Runtime.InteropServices/VariantWrapper.xml @@ -70,13 +70,9 @@ ## Remarks The purpose of is to add one level of indirection when marshaling a managed type to the corresponding `VARIANT` type. - You can use this class to wrap an that the interop marshaler passes as `VT_VARIANT | VT_BYREF`. In versions 1.0 and 1.1 of the .NET Framework, it was not possible to marshal variant data of type `VT_VARIANT | VT_BYREF` to unmanaged code. The interop marshaler passed a variant of the managed type (for example, `VT_BSTR | VT_BYREF` for , or `VT_I4 | VT_BYREF` for ), but not `VT_VARIANT | VT_BYREF`. - - One advantage of using `VT_VARIANT | VT_BYREF` variant types is that the type of data can be changed during a method call. For example, you can pass a `VT_VARIANT | VT_BYREF` variant type that contains a `VT_BSTR` and get a variant returned that contains a `VT_I4` after a method call. Because the COM interop marshaler has no way of knowing when to pass `VT_BSTR | VT_BYREF` and when to pass `VT_VARIANT | VT_BYREF`, which points to a variant that contains a `BSTR` for parameters declared as `VARIANT *`, you can instruct the marshaler by using . - - Note that early binding is not supported; you can use only when calling or with a Dispatch-only interface called in an early bound fashion. In C#, you must also use the `ref` keyword to specify `ByRef` semantics for any parameter of type . In Visual Basic, `ByRef` semantics are added automatically for every implicit late binding call. Also note that nesting objects and arrays of objects is not supported. - + You can use this class to wrap an that the interop marshaler passes as `VT_VARIANT | VT_BYREF`. One advantage of using `VT_VARIANT | VT_BYREF` variant types is that the type of data can be changed during a method call. For example, you can pass a `VT_VARIANT | VT_BYREF` variant type that contains a `VT_BSTR` and get a variant returned that contains a `VT_I4` after a method call. Because the COM interop marshaler has no way of knowing when to pass `VT_BSTR | VT_BYREF` and when to pass `VT_VARIANT | VT_BYREF`, which points to a variant that contains a `BSTR` for parameters declared as `VARIANT *`, you can instruct the marshaler by using . +Early binding is not supported; you can use only when calling or with a Dispatch-only interface called in an early bound fashion. In C#, you must also use the `ref` keyword to specify `ByRef` semantics for any parameter of type . In Visual Basic, `ByRef` semantics are added automatically for every implicit late binding call. Also note that nesting objects and arrays of objects is not supported. ## Examples The following code example demonstrates how to use the class to wrap an that the interop marshaler passes as `VT_VARIANT | VT_BYREF`. From fbb61044b39afc042b52ff819c2717d1a0114d57 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 29 May 2026 13:49:09 -0700 Subject: [PATCH 2/3] Remove .NET Framework remarks (System.Security.Cryptography) (#12655) --- .../CmsSigner.xml | 20 +-- .../EnvelopedCms.xml | 47 +----- .../SignedCms.xml | 26 +--- .../SignerInfo.xml | 20 +-- .../X509Certificate.xml | 141 +++--------------- .../X509Certificate2.xml | 42 +----- .../X509Chain.xml | 37 +---- .../X509ChainStatusFlags.xml | 2 - .../X509Extension.xml | 17 +-- .../X509ExtensionCollection.xml | 2 +- .../X509Store.xml | 17 +-- .../EncryptedXml.xml | 9 +- .../SignedXml.xml | 5 +- .../AsnEncodedData.xml | 4 +- .../AsymmetricAlgorithm.xml | 21 +-- .../CngAlgorithm.xml | 2 +- .../CngAlgorithmGroup.xml | 2 +- .../CngKeyBlobFormat.xml | 2 +- .../CngProvider.xml | 2 +- .../CryptoConfig.xml | 22 +-- .../CryptoStream.xml | 12 +- .../DSACryptoServiceProvider.xml | 3 +- .../ECDiffieHellman.xml | 17 +-- .../ECDiffieHellmanCng.xml | 15 +- .../ECDiffieHellmanCngPublicKey.xml | 58 +++---- .../ECDiffieHellmanPublicKey.xml | 6 +- xml/System.Security.Cryptography/ECDsa.xml | 6 +- .../FromBase64Transform.xml | 10 +- xml/System.Security.Cryptography/HMAC.xml | 19 +-- .../HMACSHA384.xml | 21 +-- .../HMACSHA512.xml | 21 +-- .../HashAlgorithm.xml | 18 +-- .../KeyedHashAlgorithm.xml | 17 +-- xml/System.Security.Cryptography/Oid.xml | 2 +- .../ProtectedData.xml | 11 +- xml/System.Security.Cryptography/RSA.xml | 86 ++--------- xml/System.Security.Cryptography/RSACng.xml | 6 +- .../RSACryptoServiceProvider.xml | 5 +- .../RijndaelManaged.xml | 6 +- xml/System.Security.Cryptography/SHA256.xml | 19 +-- .../SymmetricAlgorithm.xml | 23 +-- 41 files changed, 149 insertions(+), 672 deletions(-) diff --git a/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml b/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml index 436892c6696..950cc886eaf 100644 --- a/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml +++ b/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml @@ -135,24 +135,8 @@ The CSP parameters to describe which signing key to use. Initializes a new instance of the class from a persisted key. - - || -||2.16.840.1.101.3.4.2.1 (SHA-256)| -||| - -> [!IMPORTANT] -> This method is only supported on .NET Framework. Its use on .NET Core throws a . - - ]]> - - .NET Core and .NET 5+ only: In all cases. + To be added. + In all cases. diff --git a/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml b/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml index ee2d2eddfea..f16f5e91485 100644 --- a/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml +++ b/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml @@ -107,9 +107,7 @@ The default for recipients is . - On .NET Framework, the default symmetric encryption algorithm is determined by the version of the .NET Framework that the application executable was built against. Starting with .NET Framework 4.8, the default algorithm is AES-256 in CBC mode; in prior versions, the default is TripleDES (DES3-EDE) in CBC mode. - - On .NET Core, the default symmetric encryption algorithm is determined by the version of the System.Security.Cryptography.Pkcs assembly that is loaded. Starting with the 4.6.0 version of the System.Security.Cryptography.Pkcs NuGet package, the default algorithm is AES-256 in CBC mode; in prior versions, the default is TripleDES (DES3-EDE) in CBC mode. +The default symmetric encryption algorithm is determined by the version of the System.Security.Cryptography.Pkcs assembly that is loaded. Starting with the 4.6.0 version of the System.Security.Cryptography.Pkcs NuGet package, the default algorithm is AES-256 in CBC mode; in prior versions, the default is TripleDES (DES3-EDE) in CBC mode. ]]> @@ -155,10 +153,7 @@ The default for recipients is . - On .NET Framework, the default symmetric encryption algorithm is determined by the version of the .NET Framework that the application executable was built against. Starting with .NET Framework 4.8, the default algorithm is AES-256 in CBC mode; in prior versions, the default is TripleDES (DES3-EDE) in CBC mode. - - On .NET Core, the default symmetric encryption algorithm is determined by the version of the System.Security.Cryptography.Pkcs assembly that is loaded. Starting with the 4.6.0 version of the System.Security.Cryptography.Pkcs NuGet package, the default algorithm is AES-256 in CBC mode; in prior versions, the default is TripleDES (DES3-EDE) in CBC mode. - +The default symmetric encryption algorithm is determined by the version of the System.Security.Cryptography.Pkcs assembly that is loaded. Starting with the 4.6.0 version of the System.Security.Cryptography.Pkcs NuGet package, the default algorithm is AES-256 in CBC mode; in prior versions, the default is TripleDES (DES3-EDE) in CBC mode. ]]> @@ -477,11 +472,6 @@ The method does not search the computer My store if it is inaccessible. -The following permissions are required to access the decryption key on .NET Framework: - -- -- - ]]> A cryptographic operation could not be completed. @@ -524,16 +514,7 @@ The following permissions are required to access the decryption key on .NET Fram The recipient info to use for decryption. Decrypts the contents of the decoded enveloped CMS/PKCS#7 message via a specified recipient info by searching certificate stores for a matching certificate and key. - - -- - - ]]> - + To be added. The parameter is . A cryptographic operation could not be completed. A method call was invalid for the object's current state. @@ -575,16 +556,7 @@ The following permissions are required to access the decryption key on .NET Fram A collection of certificates to use in addition to the certificate stores for finding a recipient certificate and private key. Decrypts the contents of the decoded enveloped CMS/PKCS#7 message via any available recipient info by searching certificate stores and a provided collection for a matching certificate and key. - - -- - - ]]> - + To be added. The parameter was . A cryptographic operation could not be completed. A method call was invalid for the object's current state. @@ -684,16 +656,7 @@ Unlike the other overloads of `Decrypt`, this overload does not search certifica The recipient info to use for decryption. A collection of certificates to use in addition to the certificate stores for finding a recipient certificate and private key. Decrypts the contents of the decoded enveloped CMS/PKCS#7 message via a specified recipient info by searching certificate stores and a provided collection for a matching certificate and key. - - -- - - ]]> - + To be added. The or parameter is . A cryptographic operation could not be completed. A method call was invalid for the object's current state. diff --git a/xml/System.Security.Cryptography.Pkcs/SignedCms.xml b/xml/System.Security.Cryptography.Pkcs/SignedCms.xml index 3c685e8146d..4db5eae22df 100644 --- a/xml/System.Security.Cryptography.Pkcs/SignedCms.xml +++ b/xml/System.Security.Cryptography.Pkcs/SignedCms.xml @@ -634,11 +634,6 @@ This method succeeds if was provided as the `signerIdentifierType` argument of one of the constructor overloads. Otherwise, it throws an exception. -The following permissions are required to access the signature key on .NET Framework: - -- -- - ]]> The recipient certificate is not specified. @@ -681,11 +676,6 @@ The following permissions are required to access the signature key on .NET Frame -- - ## Examples The following example shows the steps to compute a signature on a message with message content that is not detached. In this case, the message content is included in the message. @@ -737,31 +727,21 @@ The following permissions are required to access the signature key on .NET Frame A object that represents the signer. - .NET Core and .NET 5+ only: to request opening keys with PIN prompts disabled, where supported; otherwise, . In .NET Framework, this parameter is not used and a PIN prompt is always shown, if required. + to request opening keys with PIN prompts disabled, where supported; otherwise, . Creates a signature using the specified signer and adds the signature to the CMS/PKCS #7 message. value is not null. The provided value controls whether or not computing the signature shows a PIN prompt. Even when the property is null and the `silent` parameter is set to `true`, some combinations of operating system and signer options can still result in a PIN prompt. - -The following permissions are required to display the user interface on .NET Framework: - -- - -The following permissions are required to access the signature key on .NET Framework: - -- -- +The `silent` parameter has no effect if the value is not null. The provided value controls whether or not computing the signature shows a PIN prompt. Even when the property is null and the `silent` parameter is set to `true`, some combinations of operating system and signer options can still result in a PIN prompt. ]]> is . A cryptographic operation could not be completed. - .NET Framework only: A signing certificate is not specified. - .NET Core and .NET 5+ only: A signing certificate is not specified. + A signing certificate is not specified. diff --git a/xml/System.Security.Cryptography.Pkcs/SignerInfo.xml b/xml/System.Security.Cryptography.Pkcs/SignerInfo.xml index 9b47218ed77..11961ba928f 100644 --- a/xml/System.Security.Cryptography.Pkcs/SignerInfo.xml +++ b/xml/System.Security.Cryptography.Pkcs/SignerInfo.xml @@ -45,7 +45,7 @@ ## Remarks The signatures represented by the class can be either over message content or a signature. The latter kind of signature is referred to as a *countersignature*. - This implementation of CMS/PKCS #7 supports only one level of countersignature. That is, a signature can be signed, which forms a countersignature, but that countersignature cannot be signed again. + This implementation of CMS/PKCS #7 supports only one level of countersignature. That is, a signature can be signed, which forms a countersignature, but that countersignature cannot be signed again. This class does not have a public constructor; therefore, it cannot be publicly instantiated. It is a read-only class accessible from the property. @@ -371,7 +371,7 @@ ASN1 corrupted data. ## Remarks -This implementation of CMS/PKCS #7 supports only one level of countersignature. That is, a signature can be signed, which forms a countersignature, but that countersignature cannot be signed again. +This implementation of CMS/PKCS #7 supports only one level of countersignature. That is, a signature can be signed, which forms a countersignature, but that countersignature cannot be signed again. This method displays a user interface in which you choose signers for this message. This requires that the current process is running in *user interactive mode*, meaning that the property is set to `true`. A process is normally in user interactive mode unless it is a service process or running inside a Web application. @@ -383,15 +383,6 @@ Signers whose certificates meet the following conditions will be displayed in th Signer certificates are chosen from the My store. -The following permissions are required to display the user interface on .NET Framework: - -- - -The following permissions are required to access the signature key on .NET Framework: - -- -- - ]]> A null reference was passed to a method that does not accept it as a valid argument. @@ -437,12 +428,7 @@ The following permissions are required to access the signature key on .NET Frame ## Remarks -This implementation of CMS/PKCS #7 supports only one level of countersignature. That is, a signature can be signed, which forms a countersignature, but that countersignature cannot be signed again. - -The following permissions are required to access the signature key on .NET Framework: - -- -- +This implementation of CMS/PKCS #7 supports only one level of countersignature. That is, a signature can be signed, which forms a countersignature, but that countersignature cannot be signed again. ]]> diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml b/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml index f5ee4db676e..508df69b49b 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml @@ -87,11 +87,7 @@ For most scenarios, you should use the class instead. > [!IMPORTANT] -> Starting with the .NET Framework 4.6, this type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. -> -> For apps that target the .NET Framework 4.5.2 and earlier versions, the class does not implement the interface and therefore does not have a `Dispose` method. - - +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. ## Examples The following example loads an X.509 certificate from a file, calls the method, and displays the results to the console. @@ -1411,16 +1407,7 @@ Releases the resources used by the current object. - - [!NOTE] -> implements the interface starting with the .NET Framework 4.6; in previous versions of the .NET Framework, the class does not implement this interface, and therefore the `Dispose` method does not exist. - - ]]> - + To be added. @@ -1468,16 +1455,7 @@ Releases all resources used by the current object. - - [!NOTE] -> implements the interface starting with the .NET Framework 4.6; in previous versions of the .NET Framework, the class does not implement this interface, and therefore the `Dispose` method does not exist. - - ]]> - + To be added. @@ -1526,16 +1504,7 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases all of the unmanaged resources used by this and optionally releases the managed resources. - - [!NOTE] -> implements the interface starting with the .NET Framework 4.6; in previous versions of the .NET Framework, the class does not implement this interface, and therefore the `Dispose` method does not exist. - - ]]> - + To be added. @@ -3349,20 +3318,8 @@ The output of this method is equivalent to the output of the A byte array containing data from an X.509 certificate. Populates the object with data from a byte array. - - object with its associated values. - - ]]> - - The parameter is . - - -or- - - The length of the parameter is 0. - .NET Core and .NET 5+ only: In all cases. + To be added. + In all cases. @@ -3419,24 +3376,8 @@ The output of this method is equivalent to the output of the The name of a certificate file represented as a string. Populates the object with information from a certificate file. - - object with the certificate that the file contains. - - - -## Examples - The following example loads an X.509 certificate from a file, calls the method, and displays the results to the console. - - :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Certificate/Import/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Certificate/Import/sample.vb" id="Snippet1"::: - - ]]> - - The parameter is . - .NET Core and .NET 5+ only: In all cases. + To be added. + In all cases. @@ -3509,22 +3450,8 @@ The output of this method is equivalent to the output of the The password required to access the X.509 certificate data. A bitwise combination of the enumeration values that control where and how to import the certificate. Populates an object using data from a byte array, a password, and a key storage flag. - - [!IMPORTANT] -> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening the assembly in a text editor such as Notepad.exe. - - ]]> - - The parameter is . - - -or- - - The length of the parameter is 0. - .NET Core and .NET 5+ only: In all cases. + To be added. + In all cases. @@ -3593,20 +3520,8 @@ The output of this method is equivalent to the output of the The password required to access the X.509 certificate data. A bitwise combination of the enumeration values that control where and how to import the certificate. Populates the object using data from a byte array, a password, and flags for determining how the private key is imported. - - object using a password for the certificate represented by the byte array. The value can be used to control where and how the private key is imported. - - ]]> - - The parameter is . - - -or- - - The length of the parameter is 0. - .NET Core and .NET 5+ only: In all cases. + To be added. + In all cases. @@ -3679,18 +3594,8 @@ The output of this method is equivalent to the output of the The password required to access the X.509 certificate data. A bitwise combination of the enumeration values that control where and how to import the certificate. Populates an object with information from a certificate file, a password, and a key storage flag. - - [!IMPORTANT] -> Never hard code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening the assembly in a text editor such as Notepad.exe. - - ]]> - - The parameter is . - .NET Core and .NET 5+ only: In all cases. + To be added. + In all cases. @@ -3759,18 +3664,8 @@ The output of this method is equivalent to the output of the The password required to access the X.509 certificate data. A bitwise combination of the enumeration values that control where and how to import the certificate. Populates the object with information from a certificate file, a password, and a value. - - [!IMPORTANT] -> Never hard-code a password within your source code. Hard-coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), a hex editor, or by simply opening the assembly in a text editor such as Notepad.exe. - - ]]> - - The parameter is . - .NET Core and .NET 5+ only: In all cases. + To be added. + In all cases. @@ -4003,7 +3898,7 @@ The output of this method is equivalent to the output of the The source of the deserialization event. Implements the interface and is called back by the deserialization event when deserialization is complete. To be added. - .NET Core and .NET 5+ only: In all cases. + In all cases. @@ -4056,7 +3951,7 @@ The output of this method is equivalent to the output of the The destination context of the serialization. Gets serialization information with all the data needed to recreate an instance of the current object. To be added. - .NET Core and .NET 5+ only: In all cases. + In all cases. diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2.xml b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2.xml index c2132c1a7e8..489a6a2e833 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2.xml @@ -68,11 +68,7 @@ The X.509 structure originated in the International Organization for Standardization (ISO) working groups. This structure can be used to represent various types of information including identity, entitlement, and holder attributes (permissions, age, sex, location, affiliation, and so forth). Although the ISO specifications are most informative on the structure itself, the class is designed to model the usage scenarios defined in specifications issued by the Internet Engineering Task Force (IETF) Public Key Infrastructure, X.509 (PKIX) working group. The most informative of these specifications is RFC 3280, "[Certificate and Certificate Revocation List (CRL) Profile](https://www.ietf.org/rfc/)." > [!IMPORTANT] -> Starting with the .NET Framework 4.6, this type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. -> -> For apps that target the .NET Framework 4.5.2 and earlier versions, the class does not implement the interface and therefore does not have a `Dispose` method. - - +> When you have finished using the type, you should dispose of it either directly or indirectly. ## Examples The following example demonstrates how to use an object to encrypt and decrypt a file. @@ -296,7 +292,7 @@ object using a handle for the Microsoft Cryptographic API certificate context, `PCCERT_CONTEXT`. Note that the immediate caller of this constructor requires unmanaged code permission. + This constructor creates a new object using a handle for the Microsoft Cryptographic API certificate context, `PCCERT_CONTEXT`. > [!IMPORTANT] > The constructor creates a copy of the certificate context. Do not assume that the context structure you passed to the constructor is valid; it may have been released. You can get a copy of the current `PCCERT_CONTEXT` structure from the property, but it is valid only during the lifetime of the object. @@ -717,7 +713,7 @@ Contextual information about the source of the stream to be deserialized. Initializes a new instance of the class using the specified serialization and stream context information. To be added. - .NET Core and .NET 5+ only: In all cases. + In all cases. @@ -3707,33 +3703,13 @@ The Subject Alternative Name extension or Subject Name could not be decoded. Gets or sets the object that represents the private key associated with a certificate. An object, which is either an RSA or DSA cryptographic service provider. - - or a object in .NET Core or an or a object in .NET Framework. If no private key is associated with the certificate, it returns `null`. - -> [!WARNING] -> If you set this property to `null` or to another key without first deleting it, a private key file is left on the disk. - - To properly delete the private key associated with this property, set `PersistKeyInCsp` to `false`, and then call the method. - - - -## Examples - The following code example opens the current user certificate store, selects only active certificates, then allows the user to select one or more certificates. The example then writes certificate information to the console. - - :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/PublicKey/Key/certselect.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/PublicKey/Key/certselect.vb" id="Snippet1"::: - - ]]> - + To be added. The key value is not an RSA or DSA key, or the key is unreadable. The value being set for this property is . The key algorithm for this private key is not supported. The X.509 keys do not match. The cryptographic service provider key is . - .NET Core and .NET 5+ only: An attempt was made to set this property. + An attempt was made to set this property. @@ -4261,12 +4237,10 @@ Unlike object to obtain precise information about the content or use the method to obtain information about the certificate. + As with all `ToString` methods, the output might not be consistent across versions of .NET, so the method results should not be parsed for content. Use the properties on the object to obtain precise information about the content or use the method to obtain information about the certificate. This method displays the certificate in text format. - - ## Examples The following code example creates a command-line executable that takes a certificate file as an argument and prints various certificate properties to the console. @@ -4329,12 +4303,10 @@ Unlike object to obtain precise information. + As with all `ToString` methods, the output might not be consistent across versions of .NET, so the method results should not be parsed for content. Use the properties on the object to obtain precise information. This method displays the certificate in text format. If the `verbose` parameter is set to `true`, the text display includes the public key, private key, and extensions. If `verbose` is set to `false`, the text display includes those fields available from the X.509 certificate, including thumbprint, serial number, subject and issuer names, and validity date information. - - ## Examples The following code example creates a command line executable that takes a certificate file as an argument and prints various certificate properties to the console. diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Chain.xml b/xml/System.Security.Cryptography.X509Certificates/X509Chain.xml index 6a470c44c13..e936f19df7d 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Chain.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Chain.xml @@ -72,9 +72,7 @@ The object has a global error status called that should be used for certificate validation. The rules governing certificate validation are complex, and it is easy to oversimplify the validation logic by ignoring the error status of one or more of the elements involved. The global error status takes into consideration the status of each element in the chain. > [!IMPORTANT] -> Starting with the .NET Framework 4.6, this type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. -> -> For apps that target the .NET Framework 4.5.2 and earlier versions, the class does not implement the interface and therefore does not have a `Dispose` method. +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. When disposing , the certificates in are not disposed. You should dispose of the certificates in this collection when the certificate instances are no longer needed. @@ -637,16 +635,7 @@ The following code example demonstrates the ordering of chain elements: Releases the resources used by this . - - [!NOTE] -> implements the interface starting with the .NET Framework 4.6; in previous versions of the .NET Framework, the class does not implement this interface, and therefore the `Dispose` method does not exist. - - ]]> - + To be added. @@ -694,16 +683,7 @@ The following code example demonstrates the ordering of chain elements: Releases all of the resources used by this . - - [!NOTE] -> implements the interface starting with the .NET Framework 4.6; in previous versions of the .NET Framework, the class does not implement this interface, and therefore the `Dispose` method does not exist. - - ]]> - + To be added. @@ -752,16 +732,7 @@ The following code example demonstrates the ordering of chain elements: to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by this , and optionally releases the managed resources. - - [!NOTE] -> implements the interface starting with the .NET Framework 4.6; in previous versions of the .NET Framework, the class does not implement this interface, and therefore the `Dispose` method does not exist. - - ]]> - + To be added. diff --git a/xml/System.Security.Cryptography.X509Certificates/X509ChainStatusFlags.xml b/xml/System.Security.Cryptography.X509Certificates/X509ChainStatusFlags.xml index 434e9ceb793..759a7fbb01c 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509ChainStatusFlags.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509ChainStatusFlags.xml @@ -66,8 +66,6 @@ ## Remarks This enumeration is used in conjunction with the structure and the property. - The flags ExplicitDistrust, HasNotSupportedCriticalExtension and HasWeakSignature were introduced with the .NET Framework 4.6.1. - ]]> diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Extension.xml b/xml/System.Security.Cryptography.X509Certificates/X509Extension.xml index 377a1efd86e..7cd3aae4098 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Extension.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Extension.xml @@ -69,21 +69,16 @@ In its most basic form, an X509 extension has an object identifier (OID), a Boolean value describing whether the extension is considered critical or not, and ASN-encoded data. Custom extensions can be registered in a file. - The.NET Framework includes implementations of several common X509 extensions: - -- . Describes the key usages of a certificate. - -- . Describes the constraints for a certificate. - -- . Describes the enhanced key usages of a certificate. - -- . Describes the key identifier. For example, used with XMLDSIG. - +.NET includes implementations of several common X509 extensions: +- . Describes the key usages of a certificate. +- . Describes the constraints for a certificate. +- . Describes the enhanced key usages of a certificate. +- . Describes the key identifier. For example, used with XMLDSIG. ## Examples The following code example demonstrates using the class. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509BasicConstraintsExtension/Overview/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509BasicConstraintsExtension/Overview/sample.vb" id="Snippet1"::: diff --git a/xml/System.Security.Cryptography.X509Certificates/X509ExtensionCollection.xml b/xml/System.Security.Cryptography.X509Certificates/X509ExtensionCollection.xml index b3ff94e197e..0a158dc577e 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509ExtensionCollection.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509ExtensionCollection.xml @@ -585,7 +585,7 @@ interface. The .NET Framework classes based on provide their own synchronized version of the collection using the property. Classes that use arrays can also implement their own synchronization using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection. Note that some implementations of might return the array itself. + This property implements the interface. The .NET classes based on provide their own synchronized version of the collection using the property. Classes that use arrays can also implement their own synchronization using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection. Note that some implementations of might return the array itself. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Store.xml b/xml/System.Security.Cryptography.X509Certificates/X509Store.xml index db4fb0988ae..7a4480a37ea 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Store.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Store.xml @@ -72,11 +72,7 @@ Use this class to work with an X.509 store. > [!IMPORTANT] -> Starting with the .NET Framework 4.6, this type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. -> -> For apps that target the .NET Framework 4.5.2 and earlier versions, the class does not implement the interface and therefore does not have a `Dispose` method. - - +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. ## Examples This section contains two examples. The first example demonstrates how you can open standard X.509 stores and list the number of certificates in each. @@ -932,16 +928,7 @@ Releases the resources used by this . - - [!NOTE] -> implements the interface starting with the .NET Framework 4.6; in previous versions of the .NET Framework, the class does not implement this interface, and therefore the `Dispose` method does not exist. - - ]]> - + To be added. diff --git a/xml/System.Security.Cryptography.Xml/EncryptedXml.xml b/xml/System.Security.Cryptography.Xml/EncryptedXml.xml index 0da1b62371e..143b4bfacb2 100644 --- a/xml/System.Security.Cryptography.Xml/EncryptedXml.xml +++ b/xml/System.Security.Cryptography.Xml/EncryptedXml.xml @@ -42,7 +42,7 @@ class is the main class used for XML encryption in the .NET Framework. XML Encryption is a standards-based, interoperable way to encrypt all or part of an XML document or any arbitrary data. The .NET Framework XML encryption classes implement the World Wide Web Consortium (W3C) [XML Encryption Syntax and Processing Version 1.0](https://www.w3.org/TR/2002/REC-xmlenc-core-20021210/) specification. + The class is the main class used for XML encryption in .NET. XML Encryption is a standards-based, interoperable way to encrypt all or part of an XML document or any arbitrary data. The .NET XML encryption classes implement the World Wide Web Consortium (W3C) [XML Encryption Syntax and Processing Version 1.0](https://www.w3.org/TR/2002/REC-xmlenc-core-20021210/) specification. Use the class whenever you need to share encrypted XML data between applications or organizations in a standard way. Any data encrypted using this class can be decrypted by any implementation of the W3C specification for XML encryption. @@ -60,8 +60,6 @@ - Include an encrypted key in the `` element. Both parties must agree on the key that decrypts the encrypted key before they exchange encrypted data. You can optionally include a name or location of the key that will decrypt the key in the `` element. - - ## Examples The following code example demonstrates how to create a simple utility class that uses the algorithm to encrypt an XML document. @@ -167,11 +165,6 @@ method will search the "AddressBook" store for certificates suitable for the verification. For example, if the certificate is referenced by a Subject Key Identifier (SKI), the method will select certificates with this SKI and try them one after another until it can verify the certificate. - +The X.509 certificate is verified. The method will search the "AddressBook" store for certificates suitable for the verification. For example, if the certificate is referenced by a Subject Key Identifier (SKI), the method will select certificates with this SKI and try them one after another until it can verify the certificate. ## Examples The following code example uses an X.509 certificate from a certificate store to sign and verify an XML document. diff --git a/xml/System.Security.Cryptography/AsnEncodedData.xml b/xml/System.Security.Cryptography/AsnEncodedData.xml index a7580bb2554..000394f574e 100644 --- a/xml/System.Security.Cryptography/AsnEncodedData.xml +++ b/xml/System.Security.Cryptography/AsnEncodedData.xml @@ -63,12 +63,10 @@ class. diff --git a/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml b/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml index 779626f2d19..18916b0a40c 100644 --- a/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml +++ b/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml @@ -275,24 +275,9 @@ 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. - - method in an extended class. This code example is part of a larger example provided for the class. - - :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.vb" id="Snippet11"::: - - ]]> - - .NET Core 2.0 - 3.1 and .NET 5 and later: In all cases. - Cryptographic Services + This method doesn't return a value. + To be added. + In all cases. diff --git a/xml/System.Security.Cryptography/CngAlgorithm.xml b/xml/System.Security.Cryptography/CngAlgorithm.xml index 98a4744547a..db191b72f8c 100644 --- a/xml/System.Security.Cryptography/CngAlgorithm.xml +++ b/xml/System.Security.Cryptography/CngAlgorithm.xml @@ -125,7 +125,7 @@ ## Remarks Instances of the class internally maintain the algorithm name that is specified by the `algorithm` parameter. - The primary purpose of this constructor is to provide a method for creating objects for algorithm types that are not represented by the static properties of the class. This capacity enables future .NET Framework releases, service packs, and third-party developers to add new algorithms, which can be accessed just like the algorithms that are currently available. + The primary purpose of this constructor is to provide a method for creating objects for algorithm types that are not represented by the static properties of the class. This capacity enables future .NET releases and third-party developers to add new algorithms, which can be accessed just like the algorithms that are currently available. ]]> diff --git a/xml/System.Security.Cryptography/CngAlgorithmGroup.xml b/xml/System.Security.Cryptography/CngAlgorithmGroup.xml index bc6a3d1311e..c5458dc6e15 100644 --- a/xml/System.Security.Cryptography/CngAlgorithmGroup.xml +++ b/xml/System.Security.Cryptography/CngAlgorithmGroup.xml @@ -125,7 +125,7 @@ ## Remarks Instances of the class internally maintain the algorithm group name that is specified by the `algorithmGroup` parameter. - The primary purpose of this constructor is to provide a method for creating objects for algorithm groups that are not represented by the static properties of the class. This capacity enables future .NET Framework releases, service packs, and third-party developers to add new algorithm groups, which can be accessed just like the algorithm groups that are currently available. + The primary purpose of this constructor is to provide a method for creating objects for algorithm groups that are not represented by the static properties of the class. This capacity enables future .NET releases and third-party developers to add new algorithm groups, which can be accessed just like the algorithm groups that are currently available. ]]> diff --git a/xml/System.Security.Cryptography/CngKeyBlobFormat.xml b/xml/System.Security.Cryptography/CngKeyBlobFormat.xml index b23aafa4827..c93186c9140 100644 --- a/xml/System.Security.Cryptography/CngKeyBlobFormat.xml +++ b/xml/System.Security.Cryptography/CngKeyBlobFormat.xml @@ -123,7 +123,7 @@ objects for format types that are not represented by the static properties of the class. This capacity allows future .NET Framework releases, service packs, and third-party developers to add new key BLOB formats, which can be accessed just like the key BLOB formats that are currently available. + The primary purpose of this constructor is to provide a method for creating objects for format types that are not represented by the static properties of the class. This capacity allows future .NET releases and third-party developers to add new key BLOB formats, which can be accessed just like the key BLOB formats that are currently available. ]]> diff --git a/xml/System.Security.Cryptography/CngProvider.xml b/xml/System.Security.Cryptography/CngProvider.xml index 369710acab0..52c4cf1e659 100644 --- a/xml/System.Security.Cryptography/CngProvider.xml +++ b/xml/System.Security.Cryptography/CngProvider.xml @@ -125,7 +125,7 @@ ## Remarks Instances of the class internally maintain the provider name specified by the `provider` parameter. - The primary purpose of this constructor is to provide a method for creating objects for KSPs that are not represented by the static properties of the class. This capacity enables future .NET Framework releases, service packs, and third-party developers to add new providers, which can be accessed just like the providers that are currently available. + The primary purpose of this constructor is to provide a method for creating objects for KSPs that are not represented by the static properties of the class. This capacity enables future .NET releases and third-party developers to add new providers, which can be accessed just like the providers that are currently available. ]]> diff --git a/xml/System.Security.Cryptography/CryptoConfig.xml b/xml/System.Security.Cryptography/CryptoConfig.xml index f1583c29835..ccbe12013d1 100644 --- a/xml/System.Security.Cryptography/CryptoConfig.xml +++ b/xml/System.Security.Cryptography/CryptoConfig.xml @@ -67,7 +67,7 @@ | |System.Security.Cryptography.SymmetricAlgorithm|| - - ## Examples The following code example demonstrates how to use members of the class. @@ -222,14 +220,7 @@ The algorithm to map to. An array of names to map to the algorithm. Adds a set of names to algorithm mappings to be used for the current application domain. - - - + The specified mappings take precedence over the built-in mappings. The or parameter is . cannot be accessed from outside the assembly. @@ -297,14 +288,7 @@ The object identifier (OID) to map to. An array of names to map to the OID. Adds a set of names to object identifier (OID) mappings to be used for the current application domain. - - - + The specified mappings take precedence over the built-in mappings. The or parameter is . One of the entries in the parameter is empty or . diff --git a/xml/System.Security.Cryptography/CryptoStream.xml b/xml/System.Security.Cryptography/CryptoStream.xml index 976a2f50f71..328ae139c1e 100644 --- a/xml/System.Security.Cryptography/CryptoStream.xml +++ b/xml/System.Security.Cryptography/CryptoStream.xml @@ -70,7 +70,7 @@ The common language runtime uses a stream-oriented design for cryptography. The core of this design is . Any cryptographic objects that implement can be chained together with any objects that implement , so the streamed output from one object can be fed into the input of another object. The intermediate result (the output from the first object) does not need to be stored separately. > [!IMPORTANT] -> In .NET 6 and later versions, when `Stream.Read` or `Stream.ReadAsync` is called with a buffer of length `N`, the operation completes when either at least 1 byte has been read from the stream, or the underlying stream that it wraps returns 0 from a call to `Read`, indicating no more data is available. In .NET Framework, `Stream.Read` and `Stream.ReadAsync` do not return until all `N` bytes have been read from the stream or the underlying stream returns 0 from a call to `Read`. If your code assumes the `Read` methods won't return until all `N` bytes have been read, it could fail to read all the content. For more information, see [Partial and zero-byte reads in streams](/dotnet/core/compatibility/core-libraries/6.0/partial-byte-reads-in-streams). +> When `Stream.Read` or `Stream.ReadAsync` is called with a buffer of length `N`, the operation completes when either at least 1 byte has been read from the stream, or the underlying stream that it wraps returns 0 from a call to `Read`, indicating no more data is available. If your code assumes the `Read` methods won't return until all `N` bytes have been read, it could fail to read all the content. For more information, see [Partial and zero-byte reads in streams](/dotnet/core/compatibility/core-libraries/6.0/partial-byte-reads-in-streams). You should always explicitly close your object after you're finished using it by calling the method. Doing so flushes the underlying stream and causes all remaining blocks of data to be processed by the object. However, if an exception occurs before you call the method, the object might not be closed. To ensure that the method always gets called, place your call to the method within the `finally` block of a `try`/`catch` statement. @@ -262,9 +262,9 @@ Any object that derives from can be passed into the `str [!IMPORTANT] -> Starting in .NET 6, this method might not read as many bytes as were requested. For more information, see [Partial and zero-byte reads in DeflateStream, GZipStream, and CryptoStream](/dotnet/core/compatibility/core-libraries/6.0/partial-byte-reads-in-streams). +> This method might not read as many bytes as were requested. For more information, see [Partial and zero-byte reads in DeflateStream, GZipStream, and CryptoStream](/dotnet/core/compatibility/core-libraries/6.0/partial-byte-reads-in-streams). -In .NET Framework 4 and earlier versions, you have to use methods such as and to implement asynchronous I/O operations. These methods are still available in current versions to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. +This method is available to support legacy code; however, the newer async methods, such as , , , and , help you implement asynchronous I/O operations more easily. Pass the `IAsyncResult` return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. must be called once for every call to . You can do this either by using the same code that called `BeginRead` or in a callback passed to `BeginRead`. @@ -347,7 +347,7 @@ If a stream is closed or you pass an invalid argument, exceptions are thrown imm and to implement asynchronous I/O operations. These methods are still available in current versions to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. +This method is available to support legacy code; however, the newer async methods, such as , , , and , help you implement asynchronous I/O operations more easily. Pass the `IAsyncResult` returned by the current method to to ensure that the write completes and frees resources appropriately. must be called once for every call to . You can do this either by using the same code that called `BeginWrite` or in a callback passed to `BeginWrite`. If an error occurs during an asynchronous write, an exception will not be thrown until `EndWrite` is called with the `IAsyncResult` returned by this method. @@ -835,7 +835,7 @@ Calling `DisposeAsync` allows the resources used by the and to implement asynchronous I/O operations. These methods are still available in current versions to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. +This method is available to support legacy code; however, the newer async methods, such as , , , and , help you implement asynchronous I/O operations more easily. Call `EndRead` to determine how many bytes were read from the stream. @@ -896,7 +896,7 @@ This method blocks until the I/O operation has completed. and to implement asynchronous I/O operations. These methods are still available in current versions to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. +This method is available to support legacy code; however, the newer async methods, such as , , , and , help you implement asynchronous I/O operations more easily. `EndWrite` must be called exactly once on every from . diff --git a/xml/System.Security.Cryptography/DSACryptoServiceProvider.xml b/xml/System.Security.Cryptography/DSACryptoServiceProvider.xml index 316216a0f24..49c574a701f 100644 --- a/xml/System.Security.Cryptography/DSACryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/DSACryptoServiceProvider.xml @@ -1499,8 +1499,7 @@ This algorithm supports key lengths from 512 bits to 1024 bits in increments of flag to a object. The property applies to all code in the current application domain, while the object applies only to classes that explicitly reference it. These settings are useful when impersonating or running under an account whose user profile is not loaded. +Setting this property to `true` is equivalent to passing the flag to a object. The property applies to all code in the application domain, while the object applies only to classes that explicitly reference it. These settings are useful when impersonating or running under an account whose user profile is not loaded. ]]> diff --git a/xml/System.Security.Cryptography/ECDiffieHellman.xml b/xml/System.Security.Cryptography/ECDiffieHellman.xml index 300b66148b5..a696331dd6e 100644 --- a/xml/System.Security.Cryptography/ECDiffieHellman.xml +++ b/xml/System.Security.Cryptography/ECDiffieHellman.xml @@ -113,7 +113,7 @@ class. The class is the only implementation that is currently included in the .NET Framework. For information about how to create a new implementation of the Elliptic Curve Diffie-Hellman (ECDH) algorithm, see the method. + This constructor is called by classes that derive from the class. The class is the only implementation that is currently included in .NET. For information about how to create a new implementation of the Elliptic Curve Diffie-Hellman (ECDH) algorithm, see the method. ]]> @@ -365,15 +365,12 @@ ## Remarks If you develop your own implementation of an object, you can use the method overload to create a custom `algorithm` string that specifies your implementation. - The `algorithm` parameter specifies the name of an implementation of the ECDH algorithm. The following strings all refer to the same implementation, which is the only implementation currently supported in the .NET Framework: + The `algorithm` parameter specifies the name of an implementation of the ECDH algorithm. The following strings all refer to the same implementation, which is the only implementation currently supported in .NET: -- "ECDH" - -- "ECDiffieHellman" - -- "ECDiffieHellmanCng" - -- "System.Security.Cryptography.ECDiffieHellmanCng" +- "ECDH" +- "ECDiffieHellman" +- "ECDiffieHellmanCng" +- "System.Security.Cryptography.ECDiffieHellmanCng" You can also provide the name of a custom ECDH implementation for the `algorithm` parameter. If you do that, the object will use it to determine whether an ECDH object can be created. @@ -1854,7 +1851,7 @@ The algorithm-specific key import failed. to include private parameters; otherwise, . This method throws in all cases. - This method does not return a value. + This method doesn't return a value. To be added. In all cases. diff --git a/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml b/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml index ff644c5f94f..ba25c2ec31d 100644 --- a/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml +++ b/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml @@ -1003,14 +1003,7 @@ This instance represents only a public key. One of the enumeration values that specifies the format of the XML string. The only currently accepted format is . Deserializes the key information from an XML string by using the specified format. To be added. - - is . - - is malformed. - - specifies an invalid format. The only accepted value is . - All other errors. - .NET Core and .NET 5+: In all cases. + In all cases. @@ -1778,11 +1771,9 @@ Because key sizes do not uniquely identify elliptic curves, the use of the prope One of the enumeration values that specifies the format of the XML string. The only currently accepted format is . Serializes the key information to an XML string by using the specified format. - A string object that contains the key information, serialized to an XML string, according to the requested format. + This method doesn't return a value To be added. - - specifies an invalid format. The only accepted value is . - .NET Core and .NET 5+: In all cases. + In all cases. diff --git a/xml/System.Security.Cryptography/ECDiffieHellmanCngPublicKey.xml b/xml/System.Security.Cryptography/ECDiffieHellmanCngPublicKey.xml index d71e4bdeccf..33eefdc0abe 100644 --- a/xml/System.Security.Cryptography/ECDiffieHellmanCngPublicKey.xml +++ b/xml/System.Security.Cryptography/ECDiffieHellmanCngPublicKey.xml @@ -47,11 +47,11 @@ Specifies an Elliptic Curve Diffie-Hellman (ECDH) public key for use with the class. - objects are used in key exchanges with objects. - + objects are used in key exchanges with objects. + ]]> @@ -207,11 +207,11 @@ Exports the key used by the object into an object. The key and named curve parameters used by the object. - field contains named curve parameters; otherwise, it contains explicit parameters. - + field contains named curve parameters; otherwise, it contains explicit parameters. + ]]> The method cannot obtain curve values. @@ -264,11 +264,11 @@ Converts a byte array that contains a public key to a object according to the specified format. An object that contains the ECDH public key that is serialized in the byte array. - instances. - + instances. + ]]> The or parameter is . @@ -318,18 +318,9 @@ An XML string that contains an Elliptic Curve Diffie-Hellman (ECDH) key. Converts an XML string to an object. - An object that contains the ECDH public key that is specified by the given XML. - - instances. - - ]]> - - The parameter is . - The parameter does not specify an key. - .NET Core and .NET 5+: In all cases. + This method doesn't return a value. + To be added. + In all cases. @@ -410,16 +401,9 @@ Serializes the public key to an XML string in RFC 4050 format. - An XML string that contains the serialized public key. - - for information about the XML format that this method uses. - - ]]> - - .NET Core and .NET 5+: In all cases. + This method doesn't return a value. + To be added. + In all cases. diff --git a/xml/System.Security.Cryptography/ECDiffieHellmanPublicKey.xml b/xml/System.Security.Cryptography/ECDiffieHellmanPublicKey.xml index cbb3572c4d7..622ec47f61d 100644 --- a/xml/System.Security.Cryptography/ECDiffieHellmanPublicKey.xml +++ b/xml/System.Security.Cryptography/ECDiffieHellmanPublicKey.xml @@ -466,7 +466,7 @@ Serializes the key BLOB to a byte array. A byte array that contains the serialized Elliptic Curve Diffie-Hellman (ECDH) public key. To be added. - Linux and macOS: In all cases. + On macOS and Linux: In all cases. @@ -516,9 +516,9 @@ Serializes the public key to an XML string. - An XML string that contains the serialized Elliptic Curve Diffie-Hellman (ECDH) public key. + This method doesn't return a value. To be added. - .NET Core and .NET 5+: In all cases. + In all cases. diff --git a/xml/System.Security.Cryptography/ECDsa.xml b/xml/System.Security.Cryptography/ECDsa.xml index 53ceacefd67..e054fa7658b 100644 --- a/xml/System.Security.Cryptography/ECDsa.xml +++ b/xml/System.Security.Cryptography/ECDsa.xml @@ -123,7 +123,7 @@ class. The class is the only implementation currently supported by the .NET Framework. You may provide your own custom implementation. + This constructor is called by classes that derive from the class. The class is the only implementation currently supported by .NET. You may provide your own custom implementation. ]]> @@ -360,12 +360,10 @@ - The name of an ECDSA implementation. The following strings all refer to the same implementation, which is the only implementation currently supported in the .NET Framework: + The name of an ECDSA implementation. The following strings all refer to the same implementation, which is the only implementation currently supported in .NET: - "ECDsa" - - "ECDsaCng" - - "System.Security.Cryptography.ECDsaCng" You can also provide the name of a custom ECDSA implementation. diff --git a/xml/System.Security.Cryptography/FromBase64Transform.xml b/xml/System.Security.Cryptography/FromBase64Transform.xml index b8f3da88583..e8e791ebcac 100644 --- a/xml/System.Security.Cryptography/FromBase64Transform.xml +++ b/xml/System.Security.Cryptography/FromBase64Transform.xml @@ -289,14 +289,8 @@ Gets a value that indicates whether multiple blocks can be transformed. A value that indicates whether multiple blocks can be transformed. - + Prior to .NET 5, only one block can be transformed at a time, so this property returns . + Starting in .NET 5, multiple blocks can be transformed, so this property returns . Cryptographic Services diff --git a/xml/System.Security.Cryptography/HMAC.xml b/xml/System.Security.Cryptography/HMAC.xml index 1091ca9b1cf..8804798cfcc 100644 --- a/xml/System.Security.Cryptography/HMAC.xml +++ b/xml/System.Security.Cryptography/HMAC.xml @@ -229,21 +229,9 @@ 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. - - overload, which lets you specify an algorithm name, instead. - - Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better. - - ]]> - - .NET Core 2.0 - 3.1 and .NET 5 and later: In all cases. + This method doesn't return a value. + To be added. + In all cases. @@ -458,6 +446,7 @@ This method is obsolete in .NET 5 and later versions. The input to compute the HMAC code for. Routes data written to the object into the HMAC algorithm for computing the HMAC. + This method doesn't return a value. Provides a workaround for the .NET Framework 2.0 implementation of the algorithm, which is inconsistent with the .NET Framework 2.0 Service Pack 1 implementation of the algorithm. to enable .NET Framework 2.0 Service Pack 1 applications to interact with .NET Framework 2.0 applications; otherwise, . - - Boolean property is to enable .NET Framework 2.0 Service Pack 1 applications to interact with .NET Framework 2.0 applications. When you set this property to `true`, the object produces values that match the values produced by .NET Framework 2.0. You should set this property only once after you create your HMAC object. You will need to reset your key afterwards, as shown in the following example. - -```csharp -public static void Test() -{ - var hmac = new HMACSHA384(); - hmac.ProduceLegacyHmacValues = true; - hmac.Key = // ...Get the HMAC key. - // ... - // Use the HMAC algorithm. - // ... -} -``` - - ]]> - + To be added. Cryptographic Services diff --git a/xml/System.Security.Cryptography/HMACSHA512.xml b/xml/System.Security.Cryptography/HMACSHA512.xml index 609144cdac7..64f19bd498b 100644 --- a/xml/System.Security.Cryptography/HMACSHA512.xml +++ b/xml/System.Security.Cryptography/HMACSHA512.xml @@ -1040,26 +1040,7 @@ Provides a workaround for the .NET Framework 2.0 implementation of the algorithm, which is inconsistent with the .NET Framework 2.0 Service Pack 1 implementation. to enable .NET Framework 2.0 Service Pack 1 applications to interact with .NET Framework 2.0 applications; otherwise, . - - Boolean property is to enable .NET Framework 2.0 Service Pack 1 applications to interact with .NET Framework 2.0 applications. When you set this property to `true`, the object produces values that match the values produced by .NET Framework 2.0. You should set this property only once after you create your HMAC object. You will need to reset your key afterwards, as shown in the following example. - -```csharp -public static void Test() -{ - var hmac = new HMACSHA512(); - hmac.ProduceLegacyHmacValues = true; - hmac.Key = // ...Get the HMAC key. - // ... - // Use the HMAC algorithm. - // ... -} -``` - - ]]> - + To be added. Cryptographic Services diff --git a/xml/System.Security.Cryptography/HashAlgorithm.xml b/xml/System.Security.Cryptography/HashAlgorithm.xml index 9ae1fae0480..5cdc44dbec7 100644 --- a/xml/System.Security.Cryptography/HashAlgorithm.xml +++ b/xml/System.Security.Cryptography/HashAlgorithm.xml @@ -597,21 +597,9 @@ The following example calculates the Creates an instance of the default implementation of a hash algorithm. - A new instance, unless the default settings have been changed using the . - - implementation of a hash algorithm. If you want to specify a different implementation, use the overload, which lets you specify an algorithm name, instead. The cryptography configuration system defines the default implementation of . - - Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better. - - ]]> - - .NET Core 2.0 - 3.1 and .NET 5 and later: In all cases. + This method doesn't return a value. + To be added. + In all cases. diff --git a/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml b/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml index 4166dab208c..4ec16f6089a 100644 --- a/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml +++ b/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml @@ -309,20 +309,9 @@ Creates an instance of the specified implementation of a keyed hash algorithm. - A new instance of the specified keyed hash algorithm. - - - - .NET Core 2.0 - 3.1 and .NET 5 and later: In all cases. - Cryptographic Services + This method doesn't return a value. + To be added. + In all cases. diff --git a/xml/System.Security.Cryptography/Oid.xml b/xml/System.Security.Cryptography/Oid.xml index 96766965d67..c92463844f3 100644 --- a/xml/System.Security.Cryptography/Oid.xml +++ b/xml/System.Security.Cryptography/Oid.xml @@ -537,7 +537,7 @@ In .NET 5 and later versions, this property is *init only*, meaning that its val If one property is set to a known value, the value of the other property is updated automatically to a corresponding value. For example, if the property is set to "1.3.6.1.5.5.7.3.4", the property is set automatically to "Secure Email". In .NET 5 and later versions, this property is *init only*, meaning that its value can't be changed once it's been set. - + ## Examples The following code example shows how to use the class. diff --git a/xml/System.Security.Cryptography/ProtectedData.xml b/xml/System.Security.Cryptography/ProtectedData.xml index 3ea823cb233..cee44239950 100644 --- a/xml/System.Security.Cryptography/ProtectedData.xml +++ b/xml/System.Security.Cryptography/ProtectedData.xml @@ -48,7 +48,7 @@ This class provides access to the Data Protection API (DPAPI) available in Windows operating systems. This is a service that is provided by the operating system and does not require additional libraries. It provides protection using the user or machine credentials to encrypt or decrypt data. > [!IMPORTANT] -> Because it depends on DPAPI, the `ProtectedData` class is supported on the Windows platform only. Its use on .NET Core on platforms other than Windows throws a . +> Because it depends on DPAPI, the `ProtectedData` class is supported on the Windows platform only. Using this class on platforms other than Windows throws a . The class consists of two wrappers for the unmanaged DPAPI, and . These two methods can be used to encrypt and decrypt data such as passwords, keys, and connection strings. @@ -62,6 +62,7 @@ If you use these methods during impersonation, you may receive the following err ]]> + The operating system is not Windows. @@ -120,9 +121,7 @@ If you use these methods during impersonation, you may receive the following err This method can be used to encrypt data such as passwords, keys, or connection strings. The `optionalEntropy` parameter enables you to add data to increase the complexity of the encryption; specify `null` for no additional complexity. If provided, this information must also be used when decrypting the data using the method. > [!NOTE] -> If you use this method during impersonation, you may receive the following error: "Key not valid for use in specified state." To prevent this error, load the profile of the user you want to impersonate before calling the method. - - +> If you use this method during impersonation, you may receive the following error: "Key not valid for use in specified state." To prevent this error, load the profile of the user you want to impersonate before calling the method. ## Examples The following example shows how to use data protection. @@ -136,7 +135,7 @@ If you use these methods during impersonation, you may receive the following err The encryption failed. The operating system does not support this method. The system ran out of memory while encrypting the data. - .NET Core and .NET 5+ only: Calls to the Protect method are supported on Windows operating systems only. + The operating system is not Windows. @@ -392,7 +391,7 @@ If you use these methods during impersonation, you may receive the following err The decryption failed. The operating system does not support this method. Out of memory. - .NET Core and .NET 5+ only: Calls to the Unprotect method are supported on Windows operating systems only. + The operating system is not Windows. diff --git a/xml/System.Security.Cryptography/RSA.xml b/xml/System.Security.Cryptography/RSA.xml index 2ba0c0b661f..d1abc3684eb 100644 --- a/xml/System.Security.Cryptography/RSA.xml +++ b/xml/System.Security.Cryptography/RSA.xml @@ -619,15 +619,8 @@ The decryption operation failed. The cipher text to be decrypted. When overridden in a derived class, decrypts the input data using the private key. The resulting decryption of the parameter in plain text. - - , also threw a exception. - - ]]> - - This method call is not supported. This exception is thrown starting with the .NET Framework 4.6. + To be added. + This method call is not supported. Cryptographic Services @@ -883,15 +876,8 @@ The encryption operation failed. The plain text to be encrypted. When overridden in a derived class, encrypts the input data using the public key. The resulting encryption of the parameter as cipher text. - - , also threw a exception. - - ]]> - - This method call is not supported. This exception is thrown starting with the .NET Framework 4.6. + To be added. + This method call is not supported. Cryptographic Services @@ -1170,24 +1156,8 @@ The encryption operation failed. The XML string containing key information. Initializes an object from the key information from an XML string. - - initializes an RSA object using key information in an XML string that was generated using the method. The method accepts either an XML string containing a public key or an XML string containing a public and private key. - - Use the method to conveniently initialize key information. - -> [!CAUTION] -> Persisting an XML string containing a private key to an insecure location is a security threat. The security of your application can be compromised if a malicious third party can access your private key. To safely persist a private key, use a secure key container. For more information about persisting private keys in a key container, see [How to: Store Asymmetric Keys in a Key Container](/dotnet/standard/security/how-to-store-asymmetric-keys-in-a-key-container). - - ]]> - - The parameter is . - The format of the parameter is not valid. - .NET Core and .NET 5+ only: In all cases. - Cryptographic Services + To be added. + In all cases. @@ -2726,47 +2696,9 @@ An error occurred creating the signature. to include a public and private RSA key; to include only the public key. Creates and returns an XML string containing the key of the current object. - An XML string containing the key of the current object. - - method creates an XML string that contains either the public and private key of the current object or contains only the public key of the current object. - - Use the method whenever you need to conveniently persist RSA key information. To initialize an object with the key in an XML string, use the method. - -> [!CAUTION] -> Persisting an XML string containing a private key to an insecure location is a security threat. The security of your application can be compromised if a malicious third party can access your private key. To safely persist a private key, use a secure key container. For more information about persisting private keys in a key container, see [How to: Store Asymmetric Keys in a Key Container](/dotnet/standard/security/how-to-store-asymmetric-keys-in-a-key-container). - - When you pass `true` to the method, the resulting XML string takes the following form: - -```xml - - … - … -

…

- … - … - … - … - … - -``` - - When you pass `false` to the method, the resulting XML string takes the following form: - -```xml - - … - … - -``` - - ]]> - - .NET Core and .NET 5+ only: In all cases. - Cryptographic Services + This method doesn't return a value. + To be added. + In all cases. diff --git a/xml/System.Security.Cryptography/RSACng.xml b/xml/System.Security.Cryptography/RSACng.xml index e06fc175d12..58bce646730 100644 --- a/xml/System.Security.Cryptography/RSACng.xml +++ b/xml/System.Security.Cryptography/RSACng.xml @@ -1296,11 +1296,7 @@ any already open key is unaffected by this method. is . The value of the property of is or . - does not equal or . - - -or- - - The signature is badly formatted. (In the .NET Framework 4.6 and 4.6.1 only; starting with the .NET Framework 4.6.2, the method returns if a signature is badly formatted. + does not equal or . diff --git a/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml b/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml index a9d85a7dc1d..5032a8da58e 100644 --- a/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml @@ -2166,10 +2166,7 @@ The supported RSA key sizes depend on the available cryptographic service provid flag to a object. The property applies to all code in the current application domain, whereas the object applies only to classes that explicitly reference it. These settings are useful when impersonating or running under an account whose user profile is not loaded. Setting affects the key store location only if is initialized with no parameters. - - +Setting this property to `true` is equivalent to passing the flag to a object. The property applies to all code in the application domain, whereas the object applies only to classes that explicitly reference it. These settings are useful when impersonating or running under an account whose user profile is not loaded. Setting affects the key store location only if is initialized with no parameters. ## Examples The following code example creates an object and sets the static property to use the machine key store instead of the user profile key store. diff --git a/xml/System.Security.Cryptography/RijndaelManaged.xml b/xml/System.Security.Cryptography/RijndaelManaged.xml index 03f25de6f7e..bafa51b261d 100644 --- a/xml/System.Security.Cryptography/RijndaelManaged.xml +++ b/xml/System.Security.Cryptography/RijndaelManaged.xml @@ -75,7 +75,8 @@ -compatible). In .NET Core, it is the same as AES and supports only a 128-bit block size. + +The Rijndael algorithm supports key lengths of 128, 192, or 256 bits; defaulting to 256 bits. This implementation supports only a 128-bit block size. > [!IMPORTANT] > The class is the predecessor of the algorithm. You should use the algorithm instead of . For more information, see the entry [The Differences Between Rijndael and AES](https://learn.microsoft.com/archive/blogs/shawnfa/the-differences-between-rijndael-and-aes) in the .NET Security blog. @@ -182,7 +183,8 @@ for more information about block size. + +The block size for Rijndael must be 128 bits. For more information about block size, see the . ]]> diff --git a/xml/System.Security.Cryptography/SHA256.xml b/xml/System.Security.Cryptography/SHA256.xml index cdd98d3b872..58e9b994704 100644 --- a/xml/System.Security.Cryptography/SHA256.xml +++ b/xml/System.Security.Cryptography/SHA256.xml @@ -187,9 +187,8 @@ Creates an instance of the default implementation of . - A new instance of . On the .NET Framework, this method creates an instance of the class if FIPS mode is not active; if FIPS mode is active, it creates an instance of the class. On .NET Core, it returns an instance of a private class derived from . + A new instance of . This method returns an instance of a private class derived from . To be added. - On the .NET Framework 4.6.1 and earlier versions only: The algorithm was used with Federal Information Processing Standards (FIPS) mode enabled, but is not FIPS compatible. Cryptographic Services @@ -256,21 +255,7 @@ The name of the specific implementation of to be used. Creates an instance of a specified implementation of . A new instance of using the specified implementation. - - | SHA256
SHA-256
System.Security.Cryptography.SHA256 | -| | System.Security.Cryptography.SHA256Cng | -| | System.Security.Cryptography.SHA256CryptoServiceProvider | - - ]]> - - On the .NET Framework only: FIPS mode is enabled, but requests , which is not FIPS compatible. + To be added. Cryptographic Services diff --git a/xml/System.Security.Cryptography/SymmetricAlgorithm.xml b/xml/System.Security.Cryptography/SymmetricAlgorithm.xml index e4deed3318f..5365b41d8e6 100644 --- a/xml/System.Security.Cryptography/SymmetricAlgorithm.xml +++ b/xml/System.Security.Cryptography/SymmetricAlgorithm.xml @@ -68,9 +68,7 @@ Note that when using derived classes, it is not enough, from a security perspective, to simply force a garbage collection after you have finished using the object. You must explicitly call the method on the object to zero out any sensitive data within the object before it is released. Note that garbage collection does not zero out the contents of collected objects but simply marks the memory as available for reallocation. Thus the data contained within a garbage collected object may still be present in the memory heap in unallocated memory. In the case of cryptographic objects, this data could contain sensitive information such as key data or a block of plain text. - All cryptographic classes in the .NET Framework that hold sensitive data implement a `Clear` method. When called, the `Clear` method overwrites all sensitive data within the object with zeros and then releases the object so that it can be safely garbage collected. When the object has been zeroed and released, you should then call the `Dispose` method with the `disposing` parameter set to `True` to dispose of all managed and unmanaged resources associated with the object. - - + All cryptographic classes in .NET that hold sensitive data implement a `Clear` method. When called, the `Clear` method overwrites all sensitive data within the object with zeros and then releases the object so that it can be safely garbage collected. When the object has been zeroed and released, you should then call the `Dispose` method with the `disposing` parameter set to `True` to dispose of all managed and unmanaged resources associated with the object. ## Examples The following code example uses the class with the specified property and initialization vector () to encrypt a file specified by `inName`, and outputs the encrypted result to the file specified by `outName`. The `desKey` and `desIV` parameters to the method are 8-byte arrays. You must have the high encryption pack installed to run this example. @@ -295,7 +293,7 @@ ## Remarks Note that when using derived classes, it is not enough, from a security perspective, to simply force a garbage collection after you have finished using the object. You must explicitly call the method on the object to zero out any sensitive data within the object before it is released. Note that garbage collection does not zero out the contents of collected objects but simply marks the memory as available for reallocation. Thus the data contained within a garbage collected object may still be present in the memory heap in unallocated memory. In the case of cryptographic objects, this data could contain sensitive information such as key data or a block of plain text. - All cryptographic classes in the .NET Framework that hold sensitive data implement a `Clear` method. When called, the `Clear` method overwrites all sensitive data within the object with zeros and then releases the object so that it can be safely garbage collected. When the object has been zeroed and released, you should then call the `Dispose` method with the `disposing` parameter set to `True` to dispose of all managed and unmanaged resources associated with the object. + All cryptographic classes in .NET that hold sensitive data implement a `Clear` method. When called, the `Clear` method overwrites all sensitive data within the object with zeros and then releases the object so that it can be safely garbage collected. When the object has been zeroed and released, you should then call the `Dispose` method with the `disposing` parameter set to `True` to dispose of all managed and unmanaged resources associated with the object. ]]> @@ -364,20 +362,9 @@ Creates a default cryptographic object used to perform the symmetric algorithm. - A default cryptographic object used to perform the symmetric algorithm. - - overload of this method. - - ]]> - - .NET Core 2.0 - 3.1 and .NET 5 and later: In all cases. - Cryptographic Services + This method doesn't return a value. + To be added. + In all cases. From b19c52ff7f93e35416231cfc79e839295c29c182 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 1 Jun 2026 06:52:05 -0700 Subject: [PATCH 3/3] Remove .NET Framework remarks (System.Runtime) (#12678) --- .../IApplicationIdentifier.xml | 10 +-- .../IFileChangeNotificationSystem.xml | 2 +- xml/System.Runtime.Caching/ChangeMonitor.xml | 5 +- .../HostFileChangeMonitor.xml | 11 +-- xml/System.Runtime.Caching/MemoryCache.xml | 19 +---- xml/System.Runtime.Caching/ObjectCache.xml | 24 +++--- .../Cer.xml | 30 +------- .../Consistency.xml | 18 +---- .../CriticalFinalizerObject.xml | 31 +------- .../PrePrepareMethodAttribute.xml | 10 +-- .../ReliabilityContractAttribute.xml | 32 +------- .../ExceptionDispatchInfo.xml | 2 +- .../FirstChanceExceptionEventArgs.xml | 49 +++--------- ...ocessCorruptedStateExceptionsAttribute.xml | 17 +---- .../AssemblyDependencyResolver.xml | 4 +- .../AssemblyLoadContext.xml | 44 +++-------- .../BinaryFormatter.xml | 6 +- .../TypeFilterLevel.xml | 13 +--- .../DataMemberAttribute.xml | 4 +- .../ExportOptions.xml | 2 +- .../FormatterServices.xml | 76 ++----------------- .../ISafeSerializationData.xml | 11 +-- .../ImportOptions.xml | 2 +- .../KnownTypeAttribute.xml | 4 +- .../XsdDataContractImporter.xml | 6 +- .../ComponentGuaranteesOptions.xml | 16 ++-- .../FrameworkName.xml | 32 ++------ .../ResourceScope.xml | 10 +-- .../TargetFrameworkAttribute.xml | 10 +-- xml/System.Runtime/GCLatencyMode.xml | 4 +- xml/System.Runtime/ProfileOptimization.xml | 40 +++++----- 31 files changed, 117 insertions(+), 427 deletions(-) diff --git a/xml/System.Runtime.Caching.Hosting/IApplicationIdentifier.xml b/xml/System.Runtime.Caching.Hosting/IApplicationIdentifier.xml index 8335073e294..1eede510b2c 100644 --- a/xml/System.Runtime.Caching.Hosting/IApplicationIdentifier.xml +++ b/xml/System.Runtime.Caching.Hosting/IApplicationIdentifier.xml @@ -20,14 +20,14 @@ - Defines an identifier for application domains that a cache implementation can use to interact with a host environment. + Defines an identifier that a cache implementation can use to interact with a host environment. interface to define strings that identify individual application domains. The host environment implements the interface. This interface is then available to implementations through the property. + A .NET host environment such as ASP.NET can use the interface to define strings that identify individual application domains. The host environment implements the interface. This interface is then available to implementations through the property. - A cache implementation uses this reference to obtain an identifier for the application domain. In ASP.NET, cache implementations use the application identifier to construct identifiers for cache performance counters. This provides names for performance counter instances that can be distinguished between application domains when multiple application domains are running. + A cache implementation uses this reference to obtain an identifier. In ASP.NET, cache implementations use the application identifier to construct identifiers for cache performance counters. ]]> @@ -57,9 +57,7 @@ method is typically implemented by a .NET Framework host environment in order to construct an application identifier for an implementation. A implementation uses this information to identify the application domain that is currently running. - - For example, in ASP.NET, the cache uses an application identifier to construct identifiers for cache performance counters. The cache calls the method that is implemented by the host environment and the host returns the identifier. This provides names for performance counter instances that can be distinguished between application domains when multiple application domains are running. + The method is typically implemented by a .NET host environment in order to construct an application identifier for an implementation. ]]> diff --git a/xml/System.Runtime.Caching.Hosting/IFileChangeNotificationSystem.xml b/xml/System.Runtime.Caching.Hosting/IFileChangeNotificationSystem.xml index d22385cb5d1..c5576747f4c 100644 --- a/xml/System.Runtime.Caching.Hosting/IFileChangeNotificationSystem.xml +++ b/xml/System.Runtime.Caching.Hosting/IFileChangeNotificationSystem.xml @@ -29,7 +29,7 @@ The interface is used internally by the class. - When a cache implementation runs in an ASP.NET application domain, ASP.NET implements an interface through the property. The class detects this property and uses the ASP.NET file-change notification system to evict cache entries based on file-change notification. + When a cache implementation runs in an ASP.NET application, ASP.NET implements an interface through the property. The class detects this property and uses the ASP.NET file-change notification system to evict cache entries based on file-change notification. In non-ASP.NET applications, there is no host environment that implements a custom interface. As a result, the class uses the class of the CLR. diff --git a/xml/System.Runtime.Caching/ChangeMonitor.xml b/xml/System.Runtime.Caching/ChangeMonitor.xml index dd70c0dd1ee..634237cd932 100644 --- a/xml/System.Runtime.Caching/ChangeMonitor.xml +++ b/xml/System.Runtime.Caching/ChangeMonitor.xml @@ -38,14 +38,11 @@ Derived classes can be customized to monitor dependency changes for specific different data stores. For example, there are cache implementations for a file system, physical memory, or a database. The class examines changes that occur outside the cache, and then alerts the cache that changes have occurred. - The .NET Framework includes the following classes that derive from class: +.NET includes the following classes that derive from class: - - - - - - - Each of these classes works with different types of dependencies. For example, the derived class monitors changes to a cache for file system data (files and folders) that the cache item depends on. diff --git a/xml/System.Runtime.Caching/HostFileChangeMonitor.xml b/xml/System.Runtime.Caching/HostFileChangeMonitor.xml index 572d11f91bc..c96d0e3d1a3 100644 --- a/xml/System.Runtime.Caching/HostFileChangeMonitor.xml +++ b/xml/System.Runtime.Caching/HostFileChangeMonitor.xml @@ -33,15 +33,10 @@ For each specified file or directory path, the class triggers a change notification if any of the following changes occur: - The name of the monitored file or directory changes. - - The specified file or directory did not exist at the time the monitor was created, but was created later. In other words, a file or directory was created in the scope of the monitored items. - - The size of a monitored file changed. - - The contents of a monitored file changed, or the contents of a monitored directory changed. - - The access control list (ACL) of the file or directory was changed. - - The monitored file or directory was deleted. If too many changes occur for the monitored file or directory at the same time, the instance can lose track of specific changes. In this scenario, the class triggers a change notification. This scenario is more likely to occur when the instance monitors a directory, and many changes occur in the scope of the directory structure in a short period of time. @@ -53,17 +48,13 @@ When the class is used in an ASP.NET application, the Windows identity that is used for access to monitored items is the application identity for the ASP.NET application. In other words, the application identity will be one of the following: - The process identity. - - The configured application identity. - - The UNC credential if the application is running from a UNC share. When the class is used in a non-ASP.NET application, the class is used internally to monitor files. As a result, whatever access control list (ACL) applies to a monitored file or directory is applied to the Windows identity of the current thread. > [!NOTE] -> Callers must have the appropriate level of code access security (CAS) permissions and must have NTFS permissions to all monitored directories and paths. - - +> Callers must have NTFS permissions to all monitored directories and paths. ## Examples The following example creates a cache item that uses a object to monitor the state of the source data (which is a file) on the file system. The cache entry is defined using a object to provide eviction and expiration details for the cache entry. diff --git a/xml/System.Runtime.Caching/MemoryCache.xml b/xml/System.Runtime.Caching/MemoryCache.xml index 82d8cf612a3..23ddb54ac9e 100644 --- a/xml/System.Runtime.Caching/MemoryCache.xml +++ b/xml/System.Runtime.Caching/MemoryCache.xml @@ -38,14 +38,12 @@ The class is a concrete implementation of the abstract class. > [!NOTE] -> The class is similar to the ASP.NET class. The class has many properties and methods for accessing the cache that will be familiar to you if you have used the ASP.NET class. The main differences between the and classes are that the class has been changed to make it usable by .NET Framework applications that are not ASP.NET applications. For example, the class has no dependencies on the `System.Web` assembly. Another difference is that you can create multiple instances of the class for use in the same application and in the same instance. +> The class is similar to the ASP.NET class. The class has many properties and methods for accessing the cache that will be familiar to you if you have used the ASP.NET class. The main differences between the and classes are that the class has been changed to make it usable by .NET apps that aren't ASP.NET applications. For example, the class has no dependencies on the `System.Web` assembly. Another difference is that you can create multiple instances of the class for use in the same application. The class does not allow `null` as a value in the cache. Any attempt to add or change a cache entry with a value of `null` will fail. The type does not implement *cache regions*. Therefore, when you call methods that implement base methods that contain a parameter for regions, do not pass a value for the parameter. The methods that use the region parameter all supply a default `null` value. For example, the method overload has a `regionName` parameter whose default value is `null`. - - ## Examples The following example declares a reference to the default memory cache instance. The cache entry uses a object to provide eviction and expiration details for the cache entry. It also uses a object to monitor the state of the source data (which is a file) on the file system. @@ -102,7 +100,6 @@ private void btnGet_Click(object sender, EventArgs e) This type is thread safe. - Caching in .NET Framework Applications @@ -428,15 +425,10 @@ private void btnGet_Click(object sender, EventArgs e) ## Remarks > [!IMPORTANT] -> In .NET Core and .NET 5.0 and later, the property does not have any effect. The underlying implementation for enforcing this limit is not functional outside of .NET Framework. - -In .NET Framework (4.x), if the current instance of the cache exceeds the limit on memory set by the property, the cache implementation removes cache entries. Each cache instance in the application can use the amount of memory that is specified by the property. In .NET Core and later, this property returns the value from configuration or constructor parameters but is not enforced. - -You can specify the settings for the property in the application configuration file. Alternatively, they can be passed in the constructor or by a caller when the instance is initialized. +> The property does not have any effect in modern .NET. ]]> - <namedCaches> Element (Cache Settings) @@ -541,11 +533,10 @@ You can specify the settings for the is required. - Because the default cache instance is not created by the constructor, you must use configuration to explicitly set the memory and polling values for the default cache instance. For more information, see [<memoryCache> Element (Cache Settings)](/dotnet/framework/configure-apps/file-schema/runtime/memorycache-element-cache-settings). + Because the default cache instance is not created by the constructor, you must use configuration to explicitly set the memory and polling values for the default cache instance. ]]> - <memoryCache> Element (Cache Settings) @@ -925,7 +916,6 @@ You can specify the settings for the - <namedCaches> Element (Cache Settings) @@ -951,11 +941,10 @@ You can specify the settings for the property can be specified in the application configuration file. Alternatively they can be passed when the class is initialized. For more information about how to configure this property, see [<namedCaches> Element (Cache Settings)](/dotnet/framework/configure-apps/file-schema/runtime/namedcaches-element-cache-settings). For more information about how to configure the property when the class is being initialized, see the method. + The settings for the property can be specified when you call the constructor. ]]> - <namedCaches> Element (Cache Settings) diff --git a/xml/System.Runtime.Caching/ObjectCache.xml b/xml/System.Runtime.Caching/ObjectCache.xml index eba52c073fe..7f7f029a62d 100644 --- a/xml/System.Runtime.Caching/ObjectCache.xml +++ b/xml/System.Runtime.Caching/ObjectCache.xml @@ -37,10 +37,7 @@ ## Remarks The type is the primary type for the in-memory object cache. To develop a custom cache implementation, you derive from the class. -> [!NOTE] -> The class is new as of the .NET Framework 4. - - The built-in class derives from the class. The class is the only concrete object cache implementation in the .NET Framework 4 that derives from the class. + The built-in class derives from the class. ]]> @@ -152,10 +149,10 @@ Note: is not a singleton, bu A unique identifier for the cache entry. The object to insert. The fixed date and time at which the cache entry will expire. This parameter is required when the method is called. - Optional. A named region in the cache to which the cache entry can be added, if regions are implemented. Because regions are not implemented in .NET Framework 4, the default value is . + Optional. A named region in the cache to which the cache entry can be added, if regions are implemented. When overridden in a derived class, inserts a cache entry into the cache without overwriting any existing cache entry. - if insertion succeeded, or if there is an already an entry in the cache that has the same key as . + if insertion succeeded, or if there is already an entry in the cache that has the same key as . is not a singleton, bu Optional. A named region in the cache to which the cache entry can be added, if regions are implemented. The default value for the optional parameter is . When overridden in a derived class, inserts a cache entry into the cache, specifying information about how the entry will be evicted. - if the insertion try succeeds, or if there is an already an entry in the cache with the same key as . + if the insertion try succeeds, or if there is already an entry in the cache with the same key as . is not a singleton, bu A unique identifier for the cache entry to get. - Optional. A named region in the cache to which the cache was added, if regions are implemented. Because regions are not implemented in .NET Framework 4, the default is . + Optional. A named region in the cache to which the cache was added, if regions are implemented. When overridden in a derived class, gets the specified cache entry from the cache as a instance. The cache entry that is identified by . @@ -616,7 +613,7 @@ Note: is not a singleton, bu - Optional. A named region in the cache to which the cache entry or entries were added, if regions are implemented. Because regions are not implemented in .NET Framework 4, the default is . + Optional. A named region in the cache to which the cache entry or entries were added, if regions are implemented. A collection of unique identifiers for the cache entries to get. Gets a set of cache entries that correspond to the specified keys. A dictionary of key/value pairs that represent cache entries. @@ -655,19 +652,16 @@ Note: is not a singleton, bu property is intended for use by .NET Framework host environments and by cache implementations that implement behavior that depends on the .NET Framework host environment. + The property is intended for use by .NET host environments and by cache implementations that implement behavior that depends on the .NET host environment. The following table lists the set of host environment services that might be available from a managed hosting environment and that are available to implementations through the property: |Service|Description| |-------------|-----------------| -||Lets host environments provide application domain identifiers that might be needed by a cache implementation for features such as identifying performance counters.| -||Lets host environments provide a custom file-change notification system, instead of using the one provided in the .NET Framework.| +||Lets host environments provide identifiers that might be needed by a cache implementation for features such as identifying performance counters.| +||Lets host environments provide a custom file-change notification system, instead of using the one provided in .NET.| ||Lets cache implementations report cache memory consumption to the host environment. This enables host environments to centrally manage memory consumption across multiple cache implementations.| -> [!NOTE] -> Callers of this property value require unrestricted code access security permissions. - ]]> The value being assigned to the property is . diff --git a/xml/System.Runtime.ConstrainedExecution/Cer.xml b/xml/System.Runtime.ConstrainedExecution/Cer.xml index b4bd67ac642..7850338d9d5 100644 --- a/xml/System.Runtime.ConstrainedExecution/Cer.xml +++ b/xml/System.Runtime.ConstrainedExecution/Cer.xml @@ -49,37 +49,9 @@ Specifies a method's behavior when called within a constrained execution region. - - enumeration specifies the behavior of a method, type, or assembly within a constrained execution region (CER). Use one of the three available values to indicate that the entity will succeed, has no knowledge of a CER, or might (deterministically) be able to report success or failure. - -A CER provides guarantees that the region of code will execute uninterrupted even if an asynchronous exception such as an aborted thread out-of-memory exception, or stack overflow is raised. - -However, the `Cer.None` enumeration value indicates that the method, type, or assembly has no concept of a CER. It does not take advantage of CER guarantees. This implies the following: - -- In the face of exceptional conditions the method might fail. - -- The method might or might not report that it failed (it is non-deterministic). - -- The method is not written with CERs in mind (which is the most likely scenario). - -If a method, type, or assembly is not explicitly marked to succeed, it is implicitly marked as `Cer.None`. - -## Examples - -The following code example demonstrates the use of the enumeration when specifying a constrained execution region for a method. This code example is part of a larger example provided for the constructor. - -:::code language="csharp" source="~/snippets/csharp/System.Runtime.ConstrainedExecution/Cer/Overview/program.cs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/System.Runtime.ConstrainedExecution/Cer/Overview/program.vb" id="Snippet3"::: - - ]]> - + To be added. - Constrained Execution Regions Reliability Best Practices diff --git a/xml/System.Runtime.ConstrainedExecution/Consistency.xml b/xml/System.Runtime.ConstrainedExecution/Consistency.xml index a73b4ac9d8b..77736d54225 100644 --- a/xml/System.Runtime.ConstrainedExecution/Consistency.xml +++ b/xml/System.Runtime.ConstrainedExecution/Consistency.xml @@ -49,24 +49,8 @@ Specifies a reliability contract. - - enumeration is used as a parameter to the attribute to specify the reliability guarantee on a given method. - - - -## Examples - The following code example demonstrates the use of the enumeration when specifying a constrained execution region for a method. This code example is part of a larger example provided for the constructor. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.ConstrainedExecution/Cer/Overview/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.ConstrainedExecution/Cer/Overview/program.vb" id="Snippet3"::: - - ]]> - + To be added. - Constrained Execution Regions Reliability Best Practices diff --git a/xml/System.Runtime.ConstrainedExecution/CriticalFinalizerObject.xml b/xml/System.Runtime.ConstrainedExecution/CriticalFinalizerObject.xml index b581301c04d..bcb930aa879 100644 --- a/xml/System.Runtime.ConstrainedExecution/CriticalFinalizerObject.xml +++ b/xml/System.Runtime.ConstrainedExecution/CriticalFinalizerObject.xml @@ -44,30 +44,10 @@ Ensures that all finalization code in derived classes is marked as critical. - - class are implicitly treated as a constrained execution region (CER). This requires code in the finalizer to only call code with a strong reliability contract. For more information about CERs, see the namespace. - - In classes derived from the class, the common language runtime (CLR) guarantees that all critical finalization code will be given the opportunity to execute, provided the finalizer follows the rules for a CER, even in situations where the CLR forcibly unloads an application domain or aborts a thread. If a finalizer violates the rules for a CER, it might not successfully execute. In addition, the CLR establishes a weak ordering among normal and critical finalizers: for objects reclaimed by garbage collection at the same time, all the noncritical finalizers are called before any of the critical finalizers. For example, a class such as , which holds data in the class that is derived from , can run a standard finalizer to flush out existing buffered data. - - In most cases, you do not need to write classes that derive from the class. The .NET Framework class library provides two classes, and , that provide critical finalization functionality for handle resources. Furthermore, the .NET Framework provides a set of prewritten classes derived from the class, and this set is located in the namespace. These classes are designed to provide common functionality for supporting file and operating system handles. - - - -## Examples - The following code example shows the use of the class to provide critical finalization for the standard input and output streams. The , derived from the class, is passed to the file stream in the constructor. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.ConstrainedExecution/CriticalFinalizerObject/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.ConstrainedExecution/CriticalFinalizerObject/Overview/program.vb" id="Snippet1"::: - - ]]> - + To be added. - Constrained Execution Regions Reliability Best Practices @@ -152,14 +132,7 @@ Releases all the resources used by the class. - - is given the opportunity to execute and will not be aborted, assuming the finalizer correctly follows the rules for a constrained execution region (CER). - - ]]> - + To be added. diff --git a/xml/System.Runtime.ConstrainedExecution/PrePrepareMethodAttribute.xml b/xml/System.Runtime.ConstrainedExecution/PrePrepareMethodAttribute.xml index b35e16a3f95..20a532fea3a 100644 --- a/xml/System.Runtime.ConstrainedExecution/PrePrepareMethodAttribute.xml +++ b/xml/System.Runtime.ConstrainedExecution/PrePrepareMethodAttribute.xml @@ -54,16 +54,8 @@ Instructs the native image generation service to prepare a method for inclusion in a constrained execution region (CER). - - attribute to a method or constructor to tell the native image generation service that the method (and its statically determinable call graph) is to be prepared for use in a CER. This attribute is useful if the method to which it is applied will be prepared explicitly at run time, and the author of the method knows this and wants to avoid the overhead of run-time preparation. - - ]]> - + To be added. - Constrained Execution Regions Reliability Best Practices diff --git a/xml/System.Runtime.ConstrainedExecution/ReliabilityContractAttribute.xml b/xml/System.Runtime.ConstrainedExecution/ReliabilityContractAttribute.xml index ff08f89f062..4890570b7e6 100644 --- a/xml/System.Runtime.ConstrainedExecution/ReliabilityContractAttribute.xml +++ b/xml/System.Runtime.ConstrainedExecution/ReliabilityContractAttribute.xml @@ -54,27 +54,9 @@ Defines a contract for reliability between the author of some code, and the developers who have a dependency on that code. - - attribute provides a mechanism for you to document your code, and to indicate what type of reliability guarantees you can make in the face of exceptional conditions that could potentially lead to an inconsistent state. In this context, exceptional conditions are defined as asynchronous exceptions that can be generated at run time by the common language runtime, such as aborted threads, out-of-memory situations, and stack overflows. You can apply the attribute to assemblies, types, and methods. - - Use this attribute with the enumeration to define a reliability contract by documenting the level of reliability in a particular piece of code. - - - -## Examples - The following code example demonstrates the use of the attribute to document the level of reliability of an assembly. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.ConstrainedExecution/ReliabilityContractAttribute/ReliabilityContract.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.ConstrainedExecution/ReliabilityContractAttribute/Overview/FxCop.Reliability.ReliabilityContract.vb" id="Snippet1"::: - - ]]> - + To be added. - Constrained Execution Regions Reliability Best Practices @@ -118,17 +100,7 @@ One of the values. One of the values. Initializes a new instance of the class with the specified guarantee and value. - - constructor to create a constrained execution region and a `finally` block that is guaranteed to execute. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.ConstrainedExecution/Cer/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.ConstrainedExecution/Cer/Overview/program.vb" id="Snippet1"::: - - ]]> - + To be added. diff --git a/xml/System.Runtime.ExceptionServices/ExceptionDispatchInfo.xml b/xml/System.Runtime.ExceptionServices/ExceptionDispatchInfo.xml index 9c980f982ad..92f69b7b471 100644 --- a/xml/System.Runtime.ExceptionServices/ExceptionDispatchInfo.xml +++ b/xml/System.Runtime.ExceptionServices/ExceptionDispatchInfo.xml @@ -62,7 +62,7 @@ An object stores t For an example, see [Capture exceptions to rethrow later](/dotnet/standard/exceptions/best-practices-for-exceptions#capture-exceptions-to-rethrow-later). - cannot be serialized and is not intended to cross application domain boundaries. + cannot be serialized. ]]> diff --git a/xml/System.Runtime.ExceptionServices/FirstChanceExceptionEventArgs.xml b/xml/System.Runtime.ExceptionServices/FirstChanceExceptionEventArgs.xml index ae24918b8e6..830805f23d5 100644 --- a/xml/System.Runtime.ExceptionServices/FirstChanceExceptionEventArgs.xml +++ b/xml/System.Runtime.ExceptionServices/FirstChanceExceptionEventArgs.xml @@ -49,32 +49,7 @@ Provides data for the notification event that is raised when a managed exception first occurs, before the common language runtime begins searching for event handlers. - - event with access to the exception. - - - -## Examples - The following example creates a series of application domains named `Child_0` through `Child_3`, with a `Worker` object in each application domain. Each `Worker` object has a reference to the `Worker` object in the next application domain, except for the `Worker` in the last application domain. The event is handled in all application domains except `Child_1`. - - When the application domains have been created, the default application domain calls the `TestException` method for the first child application domain. Each `Worker` object calls the `TestException` method for the next, until the last `Worker` throws an exception that is either handled or unhandled. Thus, the current thread passes through all the application domains, and `TestException` is added to the stack in each application domain. - - When the last `Worker` object handles the exception, the event is raised only in the last application domain. The other application domains never get a chance to handle the exception, so the event is not raised. - - When the last `Worker` object does not handle the exception, the event is raised in each application domain that has an event handler. After each event handler has finished, the stack continues to unwind until the exception is caught by the default application domain. - -> [!NOTE] -> To see how the stack display grows as the event is raised closer and closer to the default application domain, change `e.Exception.Message` to `e.Exception` in the `FirstChanceHandler` event handlers. Notice that when `TestException` is called across application domain boundaries, it appears twice: once for the proxy and once for the stub. - - :::code language="csharp" source="~/snippets/csharp/System/AppDomain/FirstChanceException/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/AppDomain/FirstChanceException/example.vb" id="Snippet1"::: - - ]]> - - + To be added. @@ -115,11 +90,11 @@ The exception that was just thrown by managed code, and that will be examined by the event. Initializes a new instance of the class with a specified exception. - @@ -162,13 +137,11 @@ The managed exception object that corresponds to the exception thrown in managed code. The newly thrown exception. - event can examine the exception and perform appropriate logging or other notification services. - - For example code, see . - + event can examine the exception and perform appropriate logging or other notification services. + ]]> diff --git a/xml/System.Runtime.ExceptionServices/HandleProcessCorruptedStateExceptionsAttribute.xml b/xml/System.Runtime.ExceptionServices/HandleProcessCorruptedStateExceptionsAttribute.xml index 95dbd0947fe..c8af4cd8fca 100644 --- a/xml/System.Runtime.ExceptionServices/HandleProcessCorruptedStateExceptionsAttribute.xml +++ b/xml/System.Runtime.ExceptionServices/HandleProcessCorruptedStateExceptionsAttribute.xml @@ -53,22 +53,7 @@ Enables managed code to handle exceptions that indicate a corrupted process state. - - attribute to the method whose exception-handling clauses you want to execute. The CLR delivers the corrupted process state exception to applicable exception clauses only in methods that have both the and attributes. - - You can also add the [\](/dotnet/framework/configure-apps/file-schema/runtime/legacycorruptedstateexceptionspolicy-element) element to your application's configuration file. This will ensure that corrupted state exceptions are delivered to your exception handlers without the or attribute. This configuration element has no effect on applications that were compiled in versions previous to the .NET Framework 4 but are running in the .NET Framework 4 or later; corrupted state exceptions will continue to be delivered for those applications. The attribute is ignored when it is encountered in partially trusted or transparent code, because a trusted host should not allow an untrusted add-in to catch and ignore these serious exceptions. - - For more information about corrupted process state exceptions, see the entry [Handling Corrupted State Exceptions](https://learn.microsoft.com/archive/msdn-magazine/2009/february/clr-inside-out-handling-corrupted-state-exceptions) in the CLR Inside Out blog. - - **.NET Core only:** Even though this attribute exists in .NET Core, since the recovery from corrupted process state exceptions is not supported, this attribute is ignored. The CLR doesn't deliver corrupted process state exceptions to the managed code. - - ]]> - + To be added. diff --git a/xml/System.Runtime.Loader/AssemblyDependencyResolver.xml b/xml/System.Runtime.Loader/AssemblyDependencyResolver.xml index ae22dc22686..e46ad0a4d75 100644 --- a/xml/System.Runtime.Loader/AssemblyDependencyResolver.xml +++ b/xml/System.Runtime.Loader/AssemblyDependencyResolver.xml @@ -51,8 +51,8 @@ ## Remarks The `AssemblyDependencyResolver` class enables application developers to more easily develop a plugin architecture in conjunction with custom instances to isolate plugins and also enable plugins to load dependencies. - The [tutorial on creating a .NET Core application with plugins](https://learn.microsoft.com/dotnet/core/tutorials/creating-app-with-plugin-support) describes how to create a custom that uses an `AssemblyDependencyResolver` to resolve the dependencies of the plugin and correctly isolate the plugin's dependencies from the hosting application. - + The [tutorial on creating a .NET application with plugins](https://learn.microsoft.com/dotnet/core/tutorials/creating-app-with-plugin-support) describes how to create a custom that uses an `AssemblyDependencyResolver` to resolve the dependencies of the plugin and correctly isolate the plugin's dependencies from the hosting application. + ]]> diff --git a/xml/System.Runtime.Loader/AssemblyLoadContext.xml b/xml/System.Runtime.Loader/AssemblyLoadContext.xml index 9223dd5f032..d0e0e9a716a 100644 --- a/xml/System.Runtime.Loader/AssemblyLoadContext.xml +++ b/xml/System.Runtime.Loader/AssemblyLoadContext.xml @@ -42,7 +42,7 @@ Represents the runtime's concept of a scope for assembly loading. For more information about this API, see Supplemental API remarks for AssemblyLoadContext. About AssemblyLoadContext - How to use and debug assembly unloadability in .NET Core + How to use and debug assembly unloadability AssemblyLoadContext CoreCLR design document AssemblyLoadContext unloadability design document @@ -246,14 +246,8 @@ This constructor is protected. It can only be called from the Gets the set by the most recent call to . The set by the most recent call to . This value can be . The value is stored in an , so the value is unique per asynchronous context. - - - + To be added. + AssemblyLoadContext.CurrentContextualReflectionContext design doc @@ -319,14 +313,8 @@ For more information, see [AssemblyLoadContext.CurrentContextualReflectionContex Sets to . An object to restore the previous value of . It is intended to be used as an in a block. - - - + To be added. + AssemblyLoadContext.CurrentContextualReflectionContext design doc @@ -359,14 +347,8 @@ For more information, see [AssemblyLoadContext.CurrentContextualReflectionContex The assembly that is used to determine the requested instance. Sets to the that loaded the assembly. An object to restore the previous value of . It is intended to be used as an in a block. - - - + To be added. + AssemblyLoadContext.CurrentContextualReflectionContext design doc @@ -518,14 +500,8 @@ For more information, see [AssemblyLoadContext.CurrentContextualReflectionContex Gets a value that indicates whether this is collectible. if this is collectible; otherwise, . If a value is not specified in the constructor, the value is . - - - + To be added. + How to use and debug assembly unloadability @@ -592,7 +568,7 @@ Implementations of this method can return an assembly loaded into any Managed assembly loading algorithm - Create a .NET Core application with plugins + Create a .NET application with plugins diff --git a/xml/System.Runtime.Serialization.Formatters.Binary/BinaryFormatter.xml b/xml/System.Runtime.Serialization.Formatters.Binary/BinaryFormatter.xml index 0b6ba57f2a9..6d7c7e3bfbb 100644 --- a/xml/System.Runtime.Serialization.Formatters.Binary/BinaryFormatter.xml +++ b/xml/System.Runtime.Serialization.Formatters.Binary/BinaryFormatter.xml @@ -418,8 +418,6 @@ Initializes a new `BinaryFormatter` for serialization or deserialization of obje [!INCLUDE[binaryformatter](~/includes/binaryformatter.md)] -For successful deserialization, the current position in the stream must be at the beginning of the object graph. - [!INCLUDE [untrusted-data-method-note](~/includes/untrusted-data-method-note.md)] ]]> @@ -437,7 +435,7 @@ An error occurred while deserializing an object from the input stream. The property may contain more information about the root cause. The caller does not have the required permission. - ASP.NET Core 5-8: Always thrown unless functionality is re-enabled in the project file. For more information, see Resolving BinaryFormatter obsoletion and disablement errors. + ASP.NET Core 5-8: In all cases unless functionality is re-enabled in the project file. For more information, see Resolving BinaryFormatter obsoletion and disablement errors. .NET 9 and later versions: In all cases. For more information, see BinaryFormatter migration guide. @@ -574,7 +572,7 @@ The property may contain more information abou The is null. An error has occurred during serialization, such as if an object in the parameter is not marked as serializable. The caller does not have the required permission. - ASP.NET Core 5-8: Always thrown unless functionality is re-enabled in the project file. For more information, see Resolving BinaryFormatter obsoletion and disablement errors. + ASP.NET Core 5-8: In all cases unless functionality is re-enabled in the project file. For more information, see Resolving BinaryFormatter obsoletion and disablement errors. .NET 9 and later versions: In all cases. For more information, see BinaryFormatter migration guide. diff --git a/xml/System.Runtime.Serialization.Formatters/TypeFilterLevel.xml b/xml/System.Runtime.Serialization.Formatters/TypeFilterLevel.xml index fe6520b670c..42d399afee8 100644 --- a/xml/System.Runtime.Serialization.Formatters/TypeFilterLevel.xml +++ b/xml/System.Runtime.Serialization.Formatters/TypeFilterLevel.xml @@ -48,7 +48,7 @@ - Specifies the level of automatic deserialization for .NET Framework remoting. + Specifies the level of automatic deserialization for .NET remoting. [!CAUTION] -> Do not assume that controlling deserialization is the only security your application requires. In distributed applications, even a high degree of control over serialization might not prevent malicious clients from intercepting the communication and using it in some way, even if that is merely showing data to others. - ]]> @@ -105,7 +98,7 @@ 3 - The full deserialization level for .NET Framework remoting. It supports all types that remoting supports in all situations. + The full deserialization level for .NET remoting. It supports all types that remoting supports in all situations. @@ -145,7 +138,7 @@ 2 - The low deserialization level for .NET Framework remoting. It supports types associated with basic remoting functionality. + The low deserialization level for .NET remoting. It supports types associated with basic remoting functionality. diff --git a/xml/System.Runtime.Serialization/DataMemberAttribute.xml b/xml/System.Runtime.Serialization/DataMemberAttribute.xml index 53056fbf597..49d2022dacc 100644 --- a/xml/System.Runtime.Serialization/DataMemberAttribute.xml +++ b/xml/System.Runtime.Serialization/DataMemberAttribute.xml @@ -173,13 +173,11 @@ property to `false` (it is `true` by default). + In .NET, types have a concept of default values. For example, for any reference type the default value is `null`, and for an integer type it is 0. It is occasionally desirable to omit a data member from the serialized data when it is set to its default value. To do this, set the property to `false` (it is `true` by default). > [!NOTE] > Setting the property to `false` is not a recommended practice. It should only be done if there is a specific need to do so (such as for interoperability or to reduce data size). - - ## Examples The following example shows the property set to `false` on various fields. diff --git a/xml/System.Runtime.Serialization/ExportOptions.xml b/xml/System.Runtime.Serialization/ExportOptions.xml index b99e079249d..a6593e37759 100644 --- a/xml/System.Runtime.Serialization/ExportOptions.xml +++ b/xml/System.Runtime.Serialization/ExportOptions.xml @@ -54,7 +54,7 @@ is used to generate XSD schemas from a type or assembly. You can also use the to generate .NET Framework code from a schema document. + The is used to generate XSD schemas from a type or assembly. You can also use the to generate .NET code from a schema document. For more information about importing and exporting schemas, see [Schema Import and Export](/dotnet/framework/wcf/feature-details/schema-import-and-export) and [Exporting Schemas from Classes](/dotnet/framework/wcf/feature-details/exporting-schemas-from-classes). diff --git a/xml/System.Runtime.Serialization/FormatterServices.xml b/xml/System.Runtime.Serialization/FormatterServices.xml index f3adde99585..173e2347805 100644 --- a/xml/System.Runtime.Serialization/FormatterServices.xml +++ b/xml/System.Runtime.Serialization/FormatterServices.xml @@ -102,16 +102,7 @@ The to check for the ability to deserialize. The property value. Determines whether the specified can be deserialized with the property set to . - - property is set to `Low`. - - .NET Framework remoting provides two levels of automatic deserialization, and . helps protect against deserialization attacks by deserializing only the types associated with the most basic remoting functionality. The deserialization level supports automatic deserialization of all types that remoting supports in all situations. - - ]]> - + To be added. The parameter is an advanced type and cannot be deserialized when the property is set to . @@ -166,14 +157,7 @@ The members to extract from the object. Extracts the data from the specified object and returns it as an array of objects. An array of that contains data stored in and associated with . - - method extracts the value associated with the `obj` object, and returns it. The length of the returned array is the same as the length of the `members` array. - - ]]> - + To be added. The or parameter is . An element of is . @@ -229,16 +213,7 @@ The type of object to create. Creates a new instance of the specified object type. A zeroed object of the specified type. - - should only be used for deserialization when the user intends to immediately populate all fields. It does not create an uninitialized string, since creating an empty instance of an immutable type serves no purpose. - - converts all class level Link Demands to Demands to ensure that all direct and indirect callers have the permissions that the demand specifies. Use to increase the level of security when deserializing from a partially trusted source. For better performance in full trust scenarios, use . - - ]]> - + To be added. The parameter is . The parameter is not a valid common language runtime type. The caller does not have the required permission. @@ -303,16 +278,7 @@ The type being serialized. Gets all the serializable members for a class of the specified . An array of type of the non-transient, non-static members. - - interface or has a serialization surrogate does not have to serialize all these members, or can serialize additional members. - -Because the `GetSerializableMembers` method calls the method, it does not return fields in a particular order, such as alphabetical or declaration order. Your code must not depend on the order in which fields are returned. - - ]]> - + To be added. The parameter is . The caller does not have the required permission. @@ -371,18 +337,7 @@ Because the `GetSerializableMembers` method calls the The context where the serialization occurs. Gets all the serializable members for a class of the specified and in the provided . An array of type of the non-transient, non-static members. - - or has a serialization surrogate does not have to serialize all these members, or can serialize additional members. - -If `context` includes the enumeration value, transient fields are also included in the array returned by this method. - -Because the `GetSerializableMembers` method calls the method, it does not return fields in a particular order, such as alphabetical or declaration order. Your code must not depend on the order in which fields are returned. - - ]]> - + To be added. The parameter is . The caller does not have the required permission. @@ -546,17 +501,7 @@ Because the `GetSerializableMembers` method calls the The type of object to create. Creates a new instance of the specified object type. A zeroed object of the specified type. - - [!NOTE] -> You cannot use the method to create instances of types that derive from the class. - - ]]> - + To be added. The parameter is . The caller does not have the required permission. @@ -615,14 +560,7 @@ Because the `GetSerializableMembers` method calls the An array of that specifies the values for each field and property to populate. Populates the specified object with values for each field drawn from the data array of objects. The newly populated object. - - does not write anything to that field. - - ]]> - + To be added. The , , or parameter is . An element of is . diff --git a/xml/System.Runtime.Serialization/ISafeSerializationData.xml b/xml/System.Runtime.Serialization/ISafeSerializationData.xml index 025dfca763e..16cca7777d3 100644 --- a/xml/System.Runtime.Serialization/ISafeSerializationData.xml +++ b/xml/System.Runtime.Serialization/ISafeSerializationData.xml @@ -47,16 +47,7 @@ Enables serialization of custom exception data in security-transparent code. - - method. Starting with .NET Framework 4.0, that method is marked with the attribute, which prevents execution in security-transparent code. To work around this condition, implement the interface and add custom data as shown in the example below. - - The method is called after serialization, and uses the to restore the custom data. - - ]]> - + To be added. diff --git a/xml/System.Runtime.Serialization/ImportOptions.xml b/xml/System.Runtime.Serialization/ImportOptions.xml index 7575575cbae..aa22d42f366 100644 --- a/xml/System.Runtime.Serialization/ImportOptions.xml +++ b/xml/System.Runtime.Serialization/ImportOptions.xml @@ -175,7 +175,7 @@ diff --git a/xml/System.Runtime.Serialization/KnownTypeAttribute.xml b/xml/System.Runtime.Serialization/KnownTypeAttribute.xml index fb94da93b7a..45f3405222a 100644 --- a/xml/System.Runtime.Serialization/KnownTypeAttribute.xml +++ b/xml/System.Runtime.Serialization/KnownTypeAttribute.xml @@ -248,9 +248,7 @@ ## Remarks The method must exist on the class or structure that the is applied to, must be static, must accept no parameters, and must return an instance of any type that implements the generic interface, such as the class, or an array of objects. - The method is called once per application domain when the data contract is loaded for the type. - - + The method is called once when the data contract is loaded for the type. ## Examples The following example uses the `methodName` parameter to identify a method in the type that contains an array of objects. diff --git a/xml/System.Runtime.Serialization/XsdDataContractImporter.xml b/xml/System.Runtime.Serialization/XsdDataContractImporter.xml index 62929c86d81..e3e8f67b1f5 100644 --- a/xml/System.Runtime.Serialization/XsdDataContractImporter.xml +++ b/xml/System.Runtime.Serialization/XsdDataContractImporter.xml @@ -38,12 +38,12 @@ Use the if you are creating a Web service that must interoperate with an existing Web service, or to create data contract types from XML schemas. will transform a - set of XML schemas and create the .NET Framework types that represent the data contract in a selected programming language. + set of XML schemas and create the .NET types that represent the data contract in a selected programming language. To create the code, use the classes in the namespace. - + Conversely, use the class when you have created a Web service that incorporates data represented by CLR types and when you need to export XML schemas for each data type to be consumed by other Web - services.That is, transforms a set of CLR types into a set of XML schemas. + services. That is, transforms a set of CLR types into a set of XML schemas. Using Data Contracts diff --git a/xml/System.Runtime.Versioning/ComponentGuaranteesOptions.xml b/xml/System.Runtime.Versioning/ComponentGuaranteesOptions.xml index 51db4e4316f..668743da270 100644 --- a/xml/System.Runtime.Versioning/ComponentGuaranteesOptions.xml +++ b/xml/System.Runtime.Versioning/ComponentGuaranteesOptions.xml @@ -59,13 +59,13 @@ Describes the compatibility guarantee of a component, type, or type member that may span multiple versions. - enumeration is used by the class to indicate the level of compatibility that is guaranteed for a component or class library that spans multiple versions. Exchange provides the strongest compatibility guarantee, followed by Stable and SideBySide. None does not promise compatibility across versions. - - For a detailed discussion of the meaning of each guarantee, see the topic. - + enumeration is used by the class to indicate the level of compatibility that is guaranteed for a component or class library that spans multiple versions. Exchange provides the strongest compatibility guarantee, followed by Stable and SideBySide. None does not promise compatibility across versions. + + For a detailed discussion of the meaning of each guarantee, see the topic. + ]]> @@ -194,7 +194,7 @@ 4 - The component has been tested to work when more than one version of the assembly is loaded into the same application domain. Future versions can break compatibility. However, when such breaking changes are made, the old version is not modified but continues to exist alongside the new version. + The component has been tested to work when more than one version of the assembly is loaded. Future versions can break compatibility. However, when such breaking changes are made, the old version is not modified but continues to exist alongside the new version. diff --git a/xml/System.Runtime.Versioning/FrameworkName.xml b/xml/System.Runtime.Versioning/FrameworkName.xml index 5990111c8a0..4170ae726b5 100644 --- a/xml/System.Runtime.Versioning/FrameworkName.xml +++ b/xml/System.Runtime.Versioning/FrameworkName.xml @@ -119,13 +119,13 @@ - A string that contains .NET Framework version information. + A string that contains .NET version information. Initializes a new instance of the class from a string that contains information about a version of .NET. constructor parses a string in the following format. + The constructor parses a string in the following format: `*identifier*,Version=*versionNumber*[,Profile=*profileName*]` @@ -135,30 +135,16 @@ |---------------|-----------------| |*identifier*|An arbitrary string that identifies this instance.| |*versionNumber*|A string that represents the version of .NET, in the form [v]*major*.*minor*[.*build*.*revision*], where "v" can be either uppercase or lowercase, and the brackets denote optional elements of a version number.| -|*profileName*|An arbitrary string that represents the profile of the .NET version. Typically, it is used to denote some subset of the .NET Framework, such as the .NET Compact Framework or Silverlight.| +|*profileName*|An arbitrary string that represents the profile of the .NET version. Typically, it is used to denote some subset of the .NET platform.| If both *versionNumber* and *profileName* are present, they can appear in any order after *identifier*. These strings are defined by the "Version" and "Profile" keywords, which are not case-sensitive. The values of the *identifier*, *versionNumber*, and *profileName* components define the values of this object's properties as follows: - Any leading or trailing white space in the *identifier* component is removed and the resulting string is assigned to the property. - - Any leading or trailing white space and the initial "v" or "V", if present, are removed from the `versionNumber`. The returned string is then passed to the constructor, and the resulting object is assigned to the property. - - Any leading or trailing white space in the `profileName` component is removed and the resulting string is assigned to the property. - The following are examples of valid strings that can be passed to the constructor: - -- .NET Framework, Version=4.0 - -- .NETFramework, Version=4.0 - -- .NET Framework, Version=2.0, Profile=Compact - -- .NET Framework, Version=v4.0, Profile=Compact - -- .NET Framework, Profile=Full, Version=2.0.0 - ]]> @@ -220,8 +206,8 @@ - A string that identifies a .NET Framework version. - An object that contains .NET Framework version information. + A string that identifies a .NET version. + An object that contains .NET version information. Initializes a new instance of the class from a string and a object that identify a .NET version. - A string that identifies a .NET Framework version. - An object that contains .NET Framework version information. + A string that identifies a .NET version. + An object that contains .NET version information. A profile name. Initializes a new instance of the class from a string, a object that identifies a .NET version, and a profile name. @@ -668,7 +654,7 @@ The second object to compare. Returns a value that indicates whether two objects represent the same .NET version. - if the and parameters represent the same .NET Framework version; otherwise, . + if the and parameters represent the same .NET version; otherwise, . method instead. - - ## Examples The following example uses the equality operator to determine whether a object that represents the running version of .NET is equal to a supported version of .NET. Note that the two versions are not equal because they do not have identical version numbers. diff --git a/xml/System.Runtime.Versioning/ResourceScope.xml b/xml/System.Runtime.Versioning/ResourceScope.xml index 95dc6bce58a..6e5436b9951 100644 --- a/xml/System.Runtime.Versioning/ResourceScope.xml +++ b/xml/System.Runtime.Versioning/ResourceScope.xml @@ -60,11 +60,11 @@ Identifies the scope of a sharable resource. - . Knowing an object is a resource does not indicate its appropriate use; the important property of a resource is the scope of the resource. The scope includes both the type and the visibility of the resource. The resource type specifies whether the resource is a machine-level resource, such as a file on disk, a process-wide resource, such as a block of non-shared memory, or an application domain-level resource, such as a lock on an instance of a non-marshal by reference object. The visibility scopes are Assembly and Private, the default is `Public`, which is implicit if Private or Assembly are not indicated. There is no enumeration value for `Public`. - + . Knowing an object is a resource does not indicate its appropriate use; the important property of a resource is the scope of the resource. The scope includes both the type and the visibility of the resource. The resource type specifies whether the resource is a machine-level resource, such as a file on disk, a process-wide resource, such as a block of non-shared memory, or an application domain-level resource, such as a lock on an instance of a non-marshal by reference object. The visibility scopes are Assembly and Private, the default is `Public`, which is implicit if Private or Assembly are not indicated. There is no enumeration value for `Public`. + ]]> diff --git a/xml/System.Runtime.Versioning/TargetFrameworkAttribute.xml b/xml/System.Runtime.Versioning/TargetFrameworkAttribute.xml index e72e86d495d..285fb4b25c5 100644 --- a/xml/System.Runtime.Versioning/TargetFrameworkAttribute.xml +++ b/xml/System.Runtime.Versioning/TargetFrameworkAttribute.xml @@ -61,15 +61,9 @@ class provides an attribute that you can apply to an assembly to indicate the version of the .NET runtime against which the assembly was built. For example, the following example applies the `TargetFrameworkAttribute` to an assembly to indicate that it was built using .NET Framework 4. + The class provides an attribute that you can apply to an assembly to indicate the version of the .NET runtime against which the assembly was built. - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Versioning/TargetFrameworkAttribute/Overview/declare1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Versioning/TargetFrameworkAttribute/Overview/declare1.vb" id="Snippet1"::: - - The class constructor has a single parameter, `frameworkName`, that specifies the .NET version against which the assembly was built. This parameter maps to the property. In addition, the attribute can specify a property to provide a more descriptive .NET version string that is suitable for displaying to clients of the assembly. The following example applies the `TargetFrameworkAttribute` to an assembly and assigns both property values to indicate that the assembly was built using .NET Framework 4. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Versioning/TargetFrameworkAttribute/Overview/declare2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Versioning/TargetFrameworkAttribute/Overview/declare2.vb" id="Snippet2"::: +The class constructor has a single parameter, `frameworkName`, that specifies the .NET version against which the assembly was built. This parameter maps to the property. In addition, the attribute can specify a property to provide a more descriptive .NET version string that's suitable for displaying to clients of the assembly. ]]> diff --git a/xml/System.Runtime/GCLatencyMode.xml b/xml/System.Runtime/GCLatencyMode.xml index e9452c06616..e42b4df75ad 100644 --- a/xml/System.Runtime/GCLatencyMode.xml +++ b/xml/System.Runtime/GCLatencyMode.xml @@ -53,9 +53,9 @@ ## Remarks You can adjust the intrusiveness of garbage collection in your application by setting the property to any enumeration value except `GCLatencyMode.NoGCRegion`. You can also determine the garbage collector's current latency mode by retrieving the property value. - See [Latency Modes](/dotnet/standard/garbage-collection/latency) for a discussion of how the runtime configuration settings for garbage collection affect the default value for this enumeration. +For a discussion of how the runtime configuration settings for garbage collection affect the default value for this enumeration, see [Latency modes](/dotnet/standard/garbage-collection/latency). -The mode overrides the [\](/dotnet/framework/configure-apps/file-schema/runtime/gcconcurrent-element) runtime configuration setting. If concurrent garbage collection is enabled by the [\](/dotnet/framework/configure-apps/file-schema/runtime/gcconcurrent-element) element, switching to Batch mode prevents any further concurrent collections. +The mode overrides the [Background GC](https://learn.microsoft.com/dotnet/core/runtime-config/garbage-collector#background-gc) runtime configuration setting. If background, or concurrent, garbage collection is enabled, switching to Batch mode prevents any further concurrent collections. ]]> diff --git a/xml/System.Runtime/ProfileOptimization.xml b/xml/System.Runtime/ProfileOptimization.xml index f2618d746a1..aeb0116b1a0 100644 --- a/xml/System.Runtime/ProfileOptimization.xml +++ b/xml/System.Runtime/ProfileOptimization.xml @@ -38,27 +38,27 @@ - Improves the startup performance of application domains in applications that require the just-in-time (JIT) compiler by performing background compilation of methods that are likely to be executed, based on profiles created during previous compilations. + Improves the startup performance of applications that require the just-in-time (JIT) compiler by performing background compilation of methods that are likely to be executed, based on profiles created during previous compilations. - [!NOTE] > > - Profile optimization requires a multicore computer. The methods are ignored on other computers. > - This API reduces startup time. These improvements are complementary to [dynamic profile-guided optimization (Dynamic PGO)](/dotnet/core/whats-new/dotnet-6#profile-guided-optimization), which improves runtime optimization based on observed execution patterns. - - Each time you initiate profile optimization in an application domain, the profile that was created during the previous use is read. The information in the profile is used to guide background compilation by identifying the methods that are most likely to be executed during startup. On multicore computers, this increases the chances that a method is already compiled by the time it is needed so that the main application thread does not have to call the JIT compiler. - - The profile file is overwritten on each use, so it always contains the most recent information about which methods are used during startup. - - Optimization profiles are not restricted to application domain startup. They can be used for any activity that requires heavy use of the JIT compiler. You can maintain multiple profiles for an application domain so that each such activity has its own profile. - - To use optimization profiles in an application domain, you must call the method and specify the folder where profiles are stored. The folder must already exist. To begin using a profile, call the method and specify the file name of the profile. If the file was not recorded previously, it's created on first use. There is no performance benefit the first time a profile is created. - - Profile optimization does not change the order in which methods are executed. Methods are not executed on the background thread; if a method is compiled but never called, it is simply not used. If a profile file is corrupt or cannot be written to the specified folder (for example, because the folder does not exist), program execution continues without optimization profiling. - + + Each time you initiate profile optimization, the profile that was created during the previous use is read. The information in the profile is used to guide background compilation by identifying the methods that are most likely to be executed during startup. On multicore computers, this increases the chances that a method is already compiled by the time it is needed so that the main application thread does not have to call the JIT compiler. + + The profile file is overwritten on each use, so it always contains the most recent information about which methods are used during startup. + + Optimization profiles are not restricted to application startup. They can be used for any activity that requires heavy use of the JIT compiler. You can maintain multiple profiles so that each such activity has its own profile. + + To use optimization profiles, you must call the method and specify the folder where profiles are stored. The folder must already exist. To begin using a profile, call the method and specify the file name of the profile. If the file was not recorded previously, it's created on first use. There is no performance benefit the first time a profile is created. + + Profile optimization does not change the order in which methods are executed. Methods are not executed on the background thread; if a method is compiled but never called, it is simply not used. If a profile file is corrupt or cannot be written to the specified folder (for example, because the folder does not exist), program execution continues without optimization profiling. + ]]> @@ -97,13 +97,13 @@ - The full path to the folder where profile files are stored for the current application domain. - Enables optimization profiling for the current application domain, and sets the folder where the optimization profile files are stored. On a single-core computer, the method is ignored. + The full path to the folder where profile files are stored. + Enables optimization profiling and sets the folder where the optimization profile files are stored. On a single-core computer, the method is ignored. method for the first time in the current application domain. If you call more than once in the same application domain, all calls after the first are ignored. + You must call this method before you call the method for the first time. If you call more than once, all calls after the first are ignored. The specified folder must already exist. If it does not exist, calling this method does not create it, and no profiling occurs. @@ -162,7 +162,7 @@ Calling this method stops any previous recording in progress. Calling this method with a null profile file name stops any recording in progress and does not start a new recording. - If the method has not been called for the current application domain, or if the computer does not have multiple cores, the method has no effect. + If the method has not been called, or if the computer does not have multiple cores, the method has no effect. ]]>