Remove .NET Framework-specific remarks (System namespace) by gewarren · Pull Request #12514 · dotnet/dotnet-api-docs

gewarren · 2026-04-14T01:30:44Z

Contributes to #12513

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

These types only exist in .NET Framework (assembly: mscorlib), so their Framework-specific remarks should be preserved. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

gewarren · 2026-04-14T18:42:41Z

xml/System/AppContext.xml


- For applications running on .NET Framework, in addition to setting the value of a switch programmatically, it can also be set:
-
 - By adding the switch name and value to the [\<AppContextSwitchOverrides>](/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) element in the [\<runtime>](/dotnet/framework/configure-apps/file-schema/runtime/runtime-element) section of an application configuration file. For example, the following defines a switch named `Libraries.FPLibrary.UseExactFloatingPointComparison` whose value is `False`.


These two bullets need to be removed.

gewarren · 2026-04-14T18:44:50Z

xml/System/AppDomain.xml

 ## Examples
- The following example demonstrates the <xref:System.AppDomain.IsFullyTrusted> property and the <xref:System.Reflection.Assembly.IsFullyTrusted?displayProperty=nameWithType> property with fully trusted and partially trusted application domains. The fully trusted application domain is the default application domain for the application. The partially trusted application domain is created by using the <xref:System.AppDomain.CreateDomain(System.String,System.Security.Policy.Evidence,System.AppDomainSetup,System.Security.PermissionSet,System.Security.Policy.StrongName%5B%5D)?displayProperty=nameWithType> method overload.
-
 The example uses a `Worker` class that derives from <xref:System.MarshalByRefObject>, so it can be marshaled across application domain boundaries. The example creates a `Worker` object in the default application domain. It then calls the `TestIsFullyTrusted` method to display the property value for the application domain and for two assemblies that are loaded into the application domain: mscorlib, which is part of the .NET Framework, and the example assembly. The application domain is fully trusted, so both assemblies are fully trusted.


Remove entire example and intro text.

gewarren · 2026-04-14T18:46:56Z

xml/System/AppDomain.xml

 ## Remarks
- This property returns `true` for sandboxed application domains that were created by using the <xref:System.AppDomain.CreateDomain(System.String,System.Security.Policy.Evidence,System.AppDomainSetup,System.Security.PermissionSet,System.Security.Policy.StrongName%5B%5D)?displayProperty=nameWithType> method overload. Sandboxed application domains have a homogenous set of permissions; that is, the same set of permissions is granted to all partially trusted assemblies that are loaded into the application domain. A sandboxed application domain optionally has a list of strong-named assemblies that are exempt from this permission set, and instead run with full trust.
-
 Fully trusted code can use the <xref:System.AppDomain.PermissionSet> property to determine the homogenous grant set of a sandboxed application domain.


Remove next two paragraphs.

gewarren · 2026-04-14T18:48:01Z

xml/System/AppDomain.xml


- Beginning with the .NET Framework version 2.0, this event is raised in each application domain that registers an event handler.
-
 > [!NOTE]


Remove this note.

gewarren · 2026-04-14T18:55:29Z

xml/System/AppDomain.xml

@@ -7803,7 +7729,6 @@ The friendly name of the default application domain is the file name of the proc
        </remarks>
        <exception cref="T:System.AppDomainUnloadedException">The operation is attempted on an unloaded application domain.</exception>
        <altmember cref="P:System.AppDomainSetup.CachePath" />


We should also remove altmember/seealso links to APIs that are .NET Fx only.

gewarren · 2026-04-14T18:55:54Z

xml/System/AppDomainSetup.xml


- The following table provides examples of compatibility switches that can be set to restore the behavior of earlier versions of the .NET Framework.
-
 |Switch|Meaning|


Remove the table.

gewarren · 2026-04-14T18:56:41Z

xml/System/AppDomainUnloadedException.xml

 ## Remarks
- In the .NET Framework version 2.0, an <xref:System.AppDomainUnloadedException> that is not handled in user code has the following effect:
-
 - If a thread was started in managed code, it is terminated. The unhandled exception is not allowed to terminate the application.


Remove bullet points.

gewarren · 2026-04-14T18:57:57Z

xml/System/ApplicationId.xml

 ## Remarks
- An application identity consists of the publisher's public key, the application name, the target processor architecture, the application culture, and the application version. The application identity properties values correspond to information contained in the application manifest. For more information about the application manifest, see [ClickOnce Application Manifest](/visualstudio/deployment/clickonce-application-manifest).
-
 <xref:System.ApplicationId> is used by the <xref:System.Security.Policy.ApplicationSecurityInfo> class to identify a manifest-based application.


Remove. The ASI type is .NET Fx only.

gewarren · 2026-04-14T20:10:26Z

xml/System/Attribute.xml

 A match is determined in the same way described in the Return Value section of <xref:System.Type.IsAssignableFrom*?displayProperty=nameWithType>.

-> [!NOTE]
->  Starting with the .NET Framework version 2.0, this method returns security attributes on types, methods, and constructors if the attributes are stored in the new metadata format. Assemblies compiled with version 2.0 or later use the new format. Dynamic assemblies and assemblies compiled with earlier versions of the .NET Framework use the old XML format. See [Emitting Declarative Security Attributes](/previous-versions/dotnet/netframework-4.0/ms404249(v=vs.100)).


Remove all links to /previous-versions.

gewarren · 2026-04-14T20:12:01Z

xml/System/DateTime.xml


 The fractional part of `value` is the fractional part of a day. For example, 4.5 is equivalent to 4 days, 12 hours, 0 minutes, 0 seconds, 0 milliseconds, and 0 ticks.

- In .NET Framework, the `value` parameter is rounded to the nearest millisecond. In .NET 7 and later versions, the full <xref:System.Double> precision of the `value` parameter is used. However, due to the inherent imprecision of floating point math, the resulting precision will vary.


Most of this should be retained.

gewarren · 2026-04-14T20:12:09Z

xml/System/DateTime.xml


 The fractional part of `value` is the fractional part of an hour. For example, 4.5 is equivalent to 4 hours, 30 minutes, 0 seconds, 0 milliseconds, and 0 ticks.

- In .NET Framework, the `value` parameter is rounded to the nearest millisecond. In .NET 7 and later versions, the full <xref:System.Double> precision of the `value` parameter is used. However, due to the inherent imprecision of floating point math, the resulting precision will vary.


gewarren · 2026-04-14T20:12:20Z

xml/System/DateTime.xml


 The fractional part of `value` is the fractional part of a millisecond. For example, 4.5 is equivalent to 4 milliseconds and 5000 ticks, where one millisecond = 10000 ticks.

- In .NET Framework, the `value` parameter is rounded to the nearest millisecond. In .NET 7 and later versions, the full <xref:System.Double> precision of the `value` parameter is used. However, due to the inherent imprecision of floating point math, the resulting precision will vary.


gewarren · 2026-04-14T20:12:41Z

xml/System/DateTime.xml


 The fractional part of `value` is the fractional part of a minute. For example, 4.5 is equivalent to 4 minutes, 30 seconds, 0 milliseconds, and 0 ticks.

- In .NET Framework, the `value` parameter is rounded to the nearest millisecond. In .NET 7 and later versions, the full <xref:System.Double> precision of the `value` parameter is used. However, due to the inherent imprecision of floating point math, the resulting precision will vary.


gewarren · 2026-04-14T20:12:52Z

xml/System/DateTime.xml


 The fractional part of `value` is the fractional part of a second. For example, 4.5 is equivalent to 4 seconds, 500 milliseconds, and 0 ticks.

- In .NET Framework, the `value` parameter is rounded to the nearest millisecond. In .NET 7 and later versions, the full <xref:System.Double> precision of the `value` parameter is used. However, due to the inherent imprecision of floating point math, the resulting precision will vary.


gewarren · 2026-04-14T20:13:26Z

xml/System/DateTime.xml


 The `fileTime` parameter specifies a file time expressed in 100-nanosecond ticks.

- Starting with the .NET Framework version 2.0, the return value is a <xref:System.DateTime> whose <xref:System.DateTime.Kind> property is <xref:System.DateTimeKind.Local?displayProperty=nameWithType>.


Keep but revise

gewarren · 2026-04-14T20:13:36Z

xml/System/DateTime.xml


 The `fileTime` parameter specifies a file time expressed in 100-nanosecond ticks.

- Starting with the .NET Framework version 2.0, the return value is a <xref:System.DateTime> whose <xref:System.DateTime.Kind> property is <xref:System.DateTimeKind.Utc>.


Keep but revise

gewarren · 2026-04-14T20:13:54Z

xml/System/DateTime.xml


 The <xref:System.DateTime.Now> property is frequently used to measure performance. However, because of its low resolution, it is not suitable for use as a benchmarking tool. A better alternative is to use the <xref:System.Diagnostics.Stopwatch> class.

- Starting with the .NET Framework version 2.0, the return value is a <xref:System.DateTime> whose <xref:System.DateTime.Kind> property returns <xref:System.DateTimeKind.Local?displayProperty=nameWithType>.


Keep but revise

gewarren · 2026-04-14T20:14:11Z

xml/System/DateTime.xml

          <format type="text/markdown"><![CDATA[

 ## Remarks
- Starting with the .NET Framework version 2.0, the return value is a <xref:System.DateTime> whose <xref:System.DateTime.Kind> property returns <xref:System.DateTimeKind.Local>.


Keep but revise

gewarren · 2026-04-14T20:14:23Z

xml/System/DateTime.xml

 > [!IMPORTANT]
 >  On Windows XP systems, the <xref:System.DateTime.ToLocalTime*> method recognizes only the current adjustment rule when converting from UTC to local time. As a result, conversions for periods before the current adjustment rule came into effect may not accurately reflect the difference between UTC and local time.

- Starting with the .NET Framework version 2.0, the value returned by the <xref:System.DateTime.ToLocalTime*> method is determined by the <xref:System.DateTime.Kind> property of the current <xref:System.DateTime> object. The following table describes the possible results.


Keep but revise (and search rest of doc)

gewarren · 2026-04-14T20:15:07Z

xml/System/DateTimeOffset.xml


 The fractional part of the `days` parameter is the fractional part of a day. For example, 4.5 is equivalent to 4 days, 12 hours, 0 minutes, 0 seconds, 0 milliseconds.

-In .NET Framework, the `days` parameter is rounded to the nearest millisecond. In .NET 7 and later versions, the full <xref:System.Double> precision of the `days` parameter is used. However, due to the inherent imprecision of floating point math, the resulting precision will vary.


Keep but revise (throughout doc)

gewarren · 2026-04-14T20:16:47Z

xml/System/Environment.xml

-> [!WARNING]
-> For the .NET Framework 4.5 and later, we do not recommend using the <xref:System.Environment.Version> property to detect the version of the runtime; instead, you can determine the version of the common language runtime by querying the registry. For more information, see [How to: Determine Which .NET Framework Versions Are Installed](/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed).
-
 For more information about the version of the common language runtime that is installed with each version of the .NET Framework, see [Versions and Dependencies](/dotnet/framework/migration-guide/versions-and-dependencies).


Revise wording

gewarren · 2026-04-14T20:17:39Z

xml/System/GC.xml


 All objects, regardless of how long they have been in memory, are considered for collection; however, objects that are referenced in managed code are not collected. Use this method to force the system to try to reclaim the maximum amount of available memory.

- Starting with the .NET Framework 4.5.1, you can compact the large object heap (LOH) by setting the <xref:System.Runtime.GCSettings.LargeObjectHeapCompactionMode?displayProperty=nameWithType> property to <xref:System.Runtime.GCLargeObjectHeapCompactionMode.CompactOnce?displayProperty=nameWithType> before calling the <xref:System.GC.Collect*> method, as the following example illustrates.


Keep but revise

gewarren · 2026-04-14T20:18:11Z

xml/System/LoaderOptimization.xml

-> [!NOTE]
-> **.NET Framework only:** If custom code access security policy is set for the <xref:System.AppDomain>, by using the <xref:System.AppDomain.SetAppDomainPolicy(System.Security.Policy.PolicyLevel)> method, and the <xref:System.AppDomain> is created using the `MultiDomain` flag, the effect is the same as specifying the `MultiDomainHost` flag; that is, only assemblies in the GAC are shared. When this occurs, the loader does not throw an exception and the application does not experience the performance gains associated with the `MultiDomain` flag.
-
 For more information on assembly sharing and domain-neutral assembly loading, see [Application Domains and Assemblies](/dotnet/framework/app-domains/application-domains#application-domains-and-assemblies).


gewarren · 2026-04-14T20:31:43Z

xml/System/MTAThreadAttribute.xml


 COM threading models only apply to applications that use COM interop. The COM threading model can be set to single-threaded apartment or multithreaded apartment. The application thread is only initialized for COM interop if the thread actually makes a call to a COM component. If COM interop is not used, then the thread is not initialized, and the <xref:System.MTAThreadAttribute> attribute, if it is present, has no effect.

- Starting with the .NET Framework version 2.0, the default threading model for COM interop depends on the language in which you are developing your application, as the following table shows.


Keep but remove intro

gewarren · 2026-04-14T20:32:40Z

xml/System/Random.xml

 ## Remarks
-In .NET Framework, the default seed value is derived from the system clock, which has finite resolution. As a result, different <xref:System.Random> objects that are created in close succession by a call to the parameterless constructor have identical default seed values and, therefore, produce identical sets of random numbers. You can avoid this problem by using a single <xref:System.Random> object to generate all random numbers. You can also work around it by generating your own random seed value and passing it to the <xref:System.Random.%23ctor(System.Int32)> constructor. For more information, see the <xref:System.Random.%23ctor(System.Int32)> constructor.
-
 In .NET Core, the default seed value is produced by the thread-static, pseudo-random number generator, so the previously described limitation does not apply. Different <xref:System.Random> objects created in close succession produce different sets of random numbers in .NET Core.


Revise wording

gewarren · 2026-04-14T20:33:43Z

xml/System/ResolveEventHandler.xml

 If the runtime class loader cannot resolve a reference to an assembly, type, or resource, the corresponding events are raised to give the callback a chance to tell the runtime which assembly the referenced assembly, type, or resource is in. It is the responsibility of the <xref:System.ResolveEventHandler> to return the assembly that resolves the type, assembly, or resource, or to return null if the assembly is not recognized. For more information, see [Resolving Assembly Loads](/dotnet/standard/assembly/resolve-loads) and the <xref:System.AppDomain.ResourceResolve?displayProperty=nameWithType>, <xref:System.AppDomain.AssemblyResolve?displayProperty=nameWithType>, and <xref:System.AppDomain.ReflectionOnlyAssemblyResolve?displayProperty=nameWithType> events.

-> [!IMPORTANT]
-> Beginning with .NET Framework 4, the <xref:System.ResolveEventHandler?displayProperty=nameWithType> event is raised for all assemblies, including resource assemblies. In earlier versions, the event was not raised for resource assemblies. If the operating system is localized, the handler might be called multiple times: once for each culture in the fallback chain.


Keep but revise

gewarren · 2026-04-14T20:34:00Z

xml/System/STAThreadAttribute.xml


 COM threading models only apply to applications that use COM interop. The COM threading model can be set to single-threaded apartment or multithreaded apartment. The application thread is only initialized for COM interop if the thread actually makes a call to a COM component. If COM interop is not used, then the thread is not initialized, and the <xref:System.STAThreadAttribute> attribute, if it is present, has no effect.

- Starting with the .NET Framework version 2.0, the default threading model for COM interop depends on the language in which you are developing your application, as the following table shows.


Keep but revise

gewarren · 2026-04-14T20:40:28Z

xml/System/TimeZoneInfo.xml

 If `dateTime` corresponds to an ambiguous local time, this method assumes that it is standard local time. If `dateTime` corresponds to an invalid local time, the method throws an <xref:System.ArgumentException>.

-> [!NOTE]
->  If the current computer's local time zone includes multiple adjustment rules, this overload of the <xref:System.TimeZoneInfo.ConvertTimeToUtc*> method can return results that differ from the <xref:System.TimeZone.ToUniversalTime*?displayProperty=nameWithType> and <xref:System.DateTime.ToUniversalTime*?displayProperty=nameWithType> methods. <xref:System.TimeZone.ToUniversalTime*?displayProperty=nameWithType> always applies the current adjustment rule to time zone conversion, whether or not `dateTime` lies within its date range. And when executing on .NET Framework 3.5, <xref:System.DateTime.ToUniversalTime*?displayProperty=nameWithType> also applies the current adjustment rule to time zone conversion, whether or not `dateTime` lies within its date range.


Check for removal

gewarren · 2026-04-14T20:44:54Z

xml/System/Uri.xml

@@ -1593,8 +1590,6 @@ If you used an escaped string to construct this instance (for example, `"http://

 The <xref:System.Uri.DnsSafeHost> property was extended in .NET Framework v3.5, 3.0 SP1, and 2.0 SP1 to provide International Resource Identifier (IRI) support based on RFC 3987. However, to ensure application compatibility with prior versions, you must specifically enable it in .NET Framework apps. To enable support for IRI, the following two changes are required:


Remove more text from this region.

gewarren · 2026-04-14T20:45:15Z

xml/System/Uri.xml

@@ -5384,8 +5379,6 @@ The following examples show a URI and the results of calling <xref:System.Uri.Ge
          <format type="text/markdown"><![CDATA[

 ## Remarks


Remove heading

gewarren and others added 2 commits April 13, 2026 18:15

remove .net fx specific remarks

bc32c92

Replace empty remarks headings with 'To be added.'

f54b02e

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions bot added the area-Meta Concerns something that extends across runtime area boundaries, for example, IDisposable. label Apr 14, 2026

dotnet-policy-service bot assigned gewarren Apr 14, 2026

Restore remarks for Framework-only APIs

d5c3ad4

These types only exist in .NET Framework (assembly: mscorlib), so their Framework-specific remarks should be preserved. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

gewarren commented Apr 14, 2026

View reviewed changes


		For applications running on .NET Framework, in addition to setting the value of a switch programmatically, it can also be set:

		- By adding the switch name and value to the [\<AppContextSwitchOverrides>](/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) element in the [\<runtime>](/dotnet/framework/configure-apps/file-schema/runtime/runtime-element) section of an application configuration file. For example, the following defines a switch named `Libraries.FPLibrary.UseExactFloatingPointComparison` whose value is `False`.


		Beginning with the .NET Framework version 2.0, this event is raised in each application domain that registers an event handler.

		> [!NOTE]


		The following table provides examples of compatibility switches that can be set to restore the behavior of earlier versions of the .NET Framework.

		\|Switch\|Meaning\|


		The fractional part of `value` is the fractional part of a day. For example, 4.5 is equivalent to 4 days, 12 hours, 0 minutes, 0 seconds, 0 milliseconds, and 0 ticks.

		In .NET Framework, the `value` parameter is rounded to the nearest millisecond. In .NET 7 and later versions, the full <xref:System.Double> precision of the `value` parameter is used. However, due to the inherent imprecision of floating point math, the resulting precision will vary.


		The `fileTime` parameter specifies a file time expressed in 100-nanosecond ticks.

		Starting with the .NET Framework version 2.0, the return value is a <xref:System.DateTime> whose <xref:System.DateTime.Kind> property is <xref:System.DateTimeKind.Local?displayProperty=nameWithType>.


		The <xref:System.DateTime.Now> property is frequently used to measure performance. However, because of its low resolution, it is not suitable for use as a benchmarking tool. A better alternative is to use the <xref:System.Diagnostics.Stopwatch> class.

		Starting with the .NET Framework version 2.0, the return value is a <xref:System.DateTime> whose <xref:System.DateTime.Kind> property returns <xref:System.DateTimeKind.Local?displayProperty=nameWithType>.


		The fractional part of the `days` parameter is the fractional part of a day. For example, 4.5 is equivalent to 4 days, 12 hours, 0 minutes, 0 seconds, 0 milliseconds.

		In .NET Framework, the `days` parameter is rounded to the nearest millisecond. In .NET 7 and later versions, the full <xref:System.Double> precision of the `days` parameter is used. However, due to the inherent imprecision of floating point math, the resulting precision will vary.


		All objects, regardless of how long they have been in memory, are considered for collection; however, objects that are referenced in managed code are not collected. Use this method to force the system to try to reclaim the maximum amount of available memory.

		Starting with the .NET Framework 4.5.1, you can compact the large object heap (LOH) by setting the <xref:System.Runtime.GCSettings.LargeObjectHeapCompactionMode?displayProperty=nameWithType> property to <xref:System.Runtime.GCLargeObjectHeapCompactionMode.CompactOnce?displayProperty=nameWithType> before calling the <xref:System.GC.Collect*> method, as the following example illustrates.


		COM threading models only apply to applications that use COM interop. The COM threading model can be set to single-threaded apartment or multithreaded apartment. The application thread is only initialized for COM interop if the thread actually makes a call to a COM component. If COM interop is not used, then the thread is not initialized, and the <xref:System.MTAThreadAttribute> attribute, if it is present, has no effect.

		Starting with the .NET Framework version 2.0, the default threading model for COM interop depends on the language in which you are developing your application, as the following table shows.

		@@ -1593,8 +1590,6 @@ If you used an escaped string to construct this instance (for example, `"http://

		The <xref:System.Uri.DnsSafeHost> property was extended in .NET Framework v3.5, 3.0 SP1, and 2.0 SP1 to provide International Resource Identifier (IRI) support based on RFC 3987. However, to ensure application compatibility with prior versions, you must specifically enable it in .NET Framework apps. To enable support for IRI, the following two changes are required:

		@@ -5384,8 +5379,6 @@ The following examples show a URI and the results of calling <xref:System.Uri.Ge
		<format type="text/markdown"><![CDATA[

		## Remarks

Conversation

gewarren commented Apr 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gewarren Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

gewarren Apr 14, 2026 •

edited

Loading