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. ]]>