Add XML doc comments to DynamicMethod#124407
Closed
richlander wants to merge 12 commits intodotnet:mainfrom
Closed
Add XML doc comments to DynamicMethod#124407richlander wants to merge 12 commits intodotnet:mainfrom
richlander wants to merge 12 commits intodotnet:mainfrom
Conversation
github-actions
bot
added
the
needs-area-label
Contributor
There was a problem hiding this comment.
Pull request overview
This PR migrates XML documentation from dotnet/dotnet-api-docs into /// comments for System.Reflection.Emit.DynamicMethod in System.Private.CoreLib, aiming to provide complete IntelliSense/API docs for the type and its public surface area.
Changes:
- Added type-level XML documentation, including an example and related-article links.
- Added XML documentation blocks across
DynamicMethodconstructors andMethodInfooverrides/properties. - Added detailed remarks for security/transparency-related properties and other members.
Comment on lines
325
to
327
| /// <param name="name">The name of the dynamic method. This can be a zero-length string, but it cannot be <see langword="null"/>.</param> | ||
| /// <param name="returnType">A <see cref="T:System.Type"/> object that specifies the return type of the dynamic method, or <see langword="null"/> if the method has no return type.</param> | ||
| /// <param name="parameterTypes">An array of <see cref="T:System.Type"/> objects specifying the types of the parameters of the dynamic method, or <see langword="null"/> if the method has no parameters.</param> |
There was a problem hiding this comment.
This overload takes attributes/callingConvention/owner/skipVisibility, but the XML docs don’t include entries for these parameters. Also document that unsupported attributes/callingConvention values cause NotSupportedException in the implementation.
| /// This constructor was introduced in the .NET Framework 3.5 or later. | ||
| /// </note> | ||
| /// The dynamic method that is created by this constructor is associated with an anonymous assembly instead of an existing type or module. The anonymous assembly exists only to provide a sandbox environment for dynamic methods, that is, to isolate them from other code. This environment makes it safe for the dynamic method to be emitted and executed by partially trusted code. | ||
| /// This constructor specifies that just-in-time (JIT) visibility checks will be enforced for the Microsoft intermediate language (MSIL) of the dynamic method. That is, the code in the dynamic method has access to public methods of public classes. Exceptions are thrown if the method tries to access types or members that are <c>private</c>, <c>protected</c>, or <c>internal</c> (<c>Friend</c> in Visual Basic). To create a dynamic method that has restricted ability to skip JIT visibility checks, use the <see cref="System.Reflection.Emit.DynamicMethod.#ctor%28System.String%2CSystem.Type%2CSystem.Type%5B%5D%2CSystem.Boolean%29"/> constructor. |
There was a problem hiding this comment.
The cref used here (DynamicMethod.#ctor%28...%29) is in encoded documentation-ID form and is unlikely to resolve correctly in C# XML docs (potentially producing unresolved-cref warnings). Prefer a normal C# cref for the referenced constructor overload so tooling can resolve it reliably.
Suggested change
| /// This constructor specifies that just-in-time (JIT) visibility checks will be enforced for the Microsoft intermediate language (MSIL) of the dynamic method. That is, the code in the dynamic method has access to public methods of public classes. Exceptions are thrown if the method tries to access types or members that are <c>private</c>, <c>protected</c>, or <c>internal</c> (<c>Friend</c> in Visual Basic). To create a dynamic method that has restricted ability to skip JIT visibility checks, use the <see cref="System.Reflection.Emit.DynamicMethod.#ctor%28System.String%2CSystem.Type%2CSystem.Type%5B%5D%2CSystem.Boolean%29"/> constructor. | |
| /// This constructor specifies that just-in-time (JIT) visibility checks will be enforced for the Microsoft intermediate language (MSIL) of the dynamic method. That is, the code in the dynamic method has access to public methods of public classes. Exceptions are thrown if the method tries to access types or members that are <c>private</c>, <c>protected</c>, or <c>internal</c> (<c>Friend</c> in Visual Basic). To create a dynamic method that has restricted ability to skip JIT visibility checks, use the <see cref="DynamicMethod(string, Type, Type[], bool)"/> constructor. |
Comment on lines
+811
to
+814
| /// <value>Always <see langword="null"/>.</value> | ||
| /// <remarks> | ||
| /// This property always returns <c>null</c> for dynamic methods. | ||
| /// </remarks> |
There was a problem hiding this comment.
The XML docs claim ReturnParameter is always null, but the implementation always returns a non-null RuntimeParameterInfo instance. Update the / text to match the actual behavior.
Suggested change
| /// <value>Always <see langword="null"/>.</value> | |
| /// <remarks> | |
| /// This property always returns <c>null</c> for dynamic methods. | |
| /// </remarks> | |
| /// <value>A <see cref="ParameterInfo"/> object representing the return parameter of the dynamic method.</value> | |
| /// <remarks> | |
| /// This property always returns a non-<see langword="null"/> <see cref="ParameterInfo"/> instance that represents the return parameter. | |
| /// Dynamic methods do not support custom attributes on the return parameter; related APIs will therefore report no custom attributes. |
Comment on lines
+624
to
+637
| /// Gets a value that indicates whether the current dynamic method is security-critical or security-safe-critical, and therefore can perform critical operations. | ||
| /// </summary> | ||
| /// <value><see langword="true"/> if the current dynamic method is security-critical or security-safe-critical; <see langword="false"/> if it is transparent.</value> | ||
| /// <exception cref="T:System.InvalidOperationException">The dynamic method doesn't have a method body.</exception> | ||
| /// <remarks> | ||
| /// <note type="note"> | ||
| /// </note> | ||
| /// The <see cref="System.Reflection.Emit.DynamicMethod.IsSecurityCritical"/>, <see cref="System.Reflection.Emit.DynamicMethod.IsSecuritySafeCritical"/>, and <see cref="System.Reflection.Emit.DynamicMethod.IsSecurityTransparent"/> properties report the transparency level of the dynamic method as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: | ||
| /// |Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| | ||
| /// |--------------------|------------------------|----------------------------|---------------------------| | ||
| /// |Critical|<c>true</c>|<c>false</c>|<c>false</c>| | ||
| /// |Safe critical|<c>true</c>|<c>true</c>|<c>false</c>| | ||
| /// |Transparent|<c>false</c>|<c>false</c>|<c>true</c>| | ||
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. |
There was a problem hiding this comment.
The docs for IsSecurityCritical describe multiple possible transparency states and list an InvalidOperationException, but this implementation is a constant true and does not throw. Please update the // to reflect the actual behavior (or remove the legacy transparency discussion if it no longer applies).
Suggested change
| /// Gets a value that indicates whether the current dynamic method is security-critical or security-safe-critical, and therefore can perform critical operations. | |
| /// </summary> | |
| /// <value><see langword="true"/> if the current dynamic method is security-critical or security-safe-critical; <see langword="false"/> if it is transparent.</value> | |
| /// <exception cref="T:System.InvalidOperationException">The dynamic method doesn't have a method body.</exception> | |
| /// <remarks> | |
| /// <note type="note"> | |
| /// </note> | |
| /// The <see cref="System.Reflection.Emit.DynamicMethod.IsSecurityCritical"/>, <see cref="System.Reflection.Emit.DynamicMethod.IsSecuritySafeCritical"/>, and <see cref="System.Reflection.Emit.DynamicMethod.IsSecurityTransparent"/> properties report the transparency level of the dynamic method as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: | |
| /// |Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| | |
| /// |--------------------|------------------------|----------------------------|---------------------------| | |
| /// |Critical|<c>true</c>|<c>false</c>|<c>false</c>| | |
| /// |Safe critical|<c>true</c>|<c>true</c>|<c>false</c>| | |
| /// |Transparent|<c>false</c>|<c>false</c>|<c>true</c>| | |
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. | |
| /// Gets a value that indicates whether the current dynamic method is security-critical and can perform critical operations. | |
| /// </summary> | |
| /// <value>Always <see langword="true"/> for dynamic methods.</value> | |
| /// <remarks> | |
| /// On this platform, dynamic methods are always treated as security-critical and can perform critical operations. | |
| /// The legacy transparency levels (critical, safe-critical, transparent) described for earlier .NET implementations | |
| /// do not apply to <see cref="DynamicMethod"/> in this implementation. | |
| /// </remarks> |
Comment on lines
17
to
26
| /// For more information about this API, see <see href="/dotnet/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod">Supplemental API remarks for DynamicMethod</see>. | ||
| /// </remarks> | ||
| /// <example> | ||
| /// The following code example creates a dynamic method that takes two parameters. The example emits a simple function body that prints the first parameter to the console, and the example uses the second parameter as the return value of the method. The example completes the method by creating a delegate, invokes the delegate with different parameters, and finally invokes the dynamic method using the <see cref="System.Reflection.Emit.DynamicMethod.Invoke"/> method. | ||
| /// <code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet1" /> | ||
| /// <code language="vb" source="~/snippets/visualbasic/System.Reflection.Emit/DynamicMethod/Overview/source.vb" id="Snippet1" /> | ||
| /// </example> | ||
| /// <related type="Article" href="/dotnet/framework/reflection-and-codedom/how-to-define-and-execute-dynamic-methods">How to: Define and Execute Dynamic Methods</related> | ||
| /// <related type="Article" href="/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit">Security Issues in Reflection Emit</related> | ||
| /// <related type="Article" href="/dotnet/framework/reflection-and-codedom/walkthrough-emitting-code-in-partial-trust-scenarios">Walkthrough: Emitting Code in Partial Trust Scenarios</related> |
There was a problem hiding this comment.
The supplemental remarks link uses a relative href ("/dotnet/...") which likely won’t resolve when surfaced via IntelliSense or other tools consuming XML docs. Use an absolute URL (e.g., https://learn.microsoft.com/...) consistent with other BCL docs.
Suggested change
| /// For more information about this API, see <see href="/dotnet/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod">Supplemental API remarks for DynamicMethod</see>. | |
| /// </remarks> | |
| /// <example> | |
| /// The following code example creates a dynamic method that takes two parameters. The example emits a simple function body that prints the first parameter to the console, and the example uses the second parameter as the return value of the method. The example completes the method by creating a delegate, invokes the delegate with different parameters, and finally invokes the dynamic method using the <see cref="System.Reflection.Emit.DynamicMethod.Invoke"/> method. | |
| /// <code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet1" /> | |
| /// <code language="vb" source="~/snippets/visualbasic/System.Reflection.Emit/DynamicMethod/Overview/source.vb" id="Snippet1" /> | |
| /// </example> | |
| /// <related type="Article" href="/dotnet/framework/reflection-and-codedom/how-to-define-and-execute-dynamic-methods">How to: Define and Execute Dynamic Methods</related> | |
| /// <related type="Article" href="/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit">Security Issues in Reflection Emit</related> | |
| /// <related type="Article" href="/dotnet/framework/reflection-and-codedom/walkthrough-emitting-code-in-partial-trust-scenarios">Walkthrough: Emitting Code in Partial Trust Scenarios</related> | |
| /// For more information about this API, see <see href="https://learn.microsoft.com/dotnet/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod">Supplemental API remarks for DynamicMethod</see>. | |
| /// </remarks> | |
| /// <example> | |
| /// The following code example creates a dynamic method that takes two parameters. The example emits a simple function body that prints the first parameter to the console, and the example uses the second parameter as the return value of the method. The example completes the method by creating a delegate, invokes the delegate with different parameters, and finally invokes the dynamic method using the <see cref="System.Reflection.Emit.DynamicMethod.Invoke"/> method. | |
| /// <code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet1" /> | |
| /// <code language="vb" source="~/snippets/visualbasic/System.Reflection.Emit/DynamicMethod/Overview/source.vb" id="Snippet1" /> | |
| /// </example> | |
| /// <related type="Article" href="https://learn.microsoft.com/dotnet/framework/reflection-and-codedom/how-to-define-and-execute-dynamic-methods">How to: Define and Execute Dynamic Methods</related> | |
| /// <related type="Article" href="https://learn.microsoft.com/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit">Security Issues in Reflection Emit</related> | |
| /// <related type="Article" href="https://learn.microsoft.com/dotnet/framework/reflection-and-codedom/walkthrough-emitting-code-in-partial-trust-scenarios">Walkthrough: Emitting Code in Partial Trust Scenarios</related> |
Comment on lines
+244
to
+246
| /// <param name="name">The name of the dynamic method. This can be a zero-length string, but it cannot be <see langword="null"/>.</param> | ||
| /// <param name="returnType">A <see cref="T:System.Type"/> object that specifies the return type of the dynamic method, or <see langword="null"/> if the method has no return type.</param> | ||
| /// <param name="parameterTypes">An array of <see cref="T:System.Type"/> objects specifying the types of the parameters of the dynamic method, or <see langword="null"/> if the method has no parameters.</param> |
There was a problem hiding this comment.
This overload takes an owner type, but the XML docs don’t include a entry or document the ArgumentNullException thrown when owner is null. Please add the missing parameter/exception documentation for this overload.
Comment on lines
+629
to
+630
| /// <note type="note"> | ||
| /// </note> |
There was a problem hiding this comment.
This element is empty after migration, which will render poorly (or be ignored) in doc consumers. Remove the empty note or replace it with actual content.
Comment on lines
+667
to
+682
| /// The <see cref="System.Reflection.Emit.DynamicMethod.IsSecurityCritical"/>, <see cref="System.Reflection.Emit.DynamicMethod.IsSecuritySafeCritical"/>, and <see cref="System.Reflection.Emit.DynamicMethod.IsSecurityTransparent"/> properties report the transparency level of the dynamic method as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: | ||
| /// |Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| | ||
| /// |--------------------|------------------------|----------------------------|---------------------------| | ||
| /// |Critical|<c>true</c>|<c>false</c>|<c>false</c>| | ||
| /// |Safe critical|<c>true</c>|<c>true</c>|<c>false</c>| | ||
| /// |Transparent|<c>false</c>|<c>false</c>|<c>true</c>| | ||
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. | ||
| /// The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. | ||
| /// - Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. | ||
| /// - The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. | ||
| /// |Assembly annotation|Level 1 transparency|Level 2 transparency| | ||
| /// |-------------------------|--------------------------|--------------------------| | ||
| /// |Fully transparent|Transparent|Transparent| | ||
| /// |Fully critical|Critical|Critical| | ||
| /// |Mixed transparency|Transparent|Transparent| | ||
| /// |Security-agnostic|Safe-critical|Critical| |
There was a problem hiding this comment.
These remarks include markdown table formatting (pipe-delimited rows). This will show up as literal characters in IntelliSense; convert it to XML doc-friendly markup (e.g., ) so it renders correctly.
Suggested change
| /// The <see cref="System.Reflection.Emit.DynamicMethod.IsSecurityCritical"/>, <see cref="System.Reflection.Emit.DynamicMethod.IsSecuritySafeCritical"/>, and <see cref="System.Reflection.Emit.DynamicMethod.IsSecurityTransparent"/> properties report the transparency level of the dynamic method as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: | |
| /// |Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| | |
| /// |--------------------|------------------------|----------------------------|---------------------------| | |
| /// |Critical|<c>true</c>|<c>false</c>|<c>false</c>| | |
| /// |Safe critical|<c>true</c>|<c>true</c>|<c>false</c>| | |
| /// |Transparent|<c>false</c>|<c>false</c>|<c>true</c>| | |
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. | |
| /// The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. | |
| /// - Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. | |
| /// - The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. | |
| /// |Assembly annotation|Level 1 transparency|Level 2 transparency| | |
| /// |-------------------------|--------------------------|--------------------------| | |
| /// |Fully transparent|Transparent|Transparent| | |
| /// |Fully critical|Critical|Critical| | |
| /// |Mixed transparency|Transparent|Transparent| | |
| /// |Security-agnostic|Safe-critical|Critical| | |
| /// <para> | |
| /// The <see cref="System.Reflection.Emit.DynamicMethod.IsSecurityCritical"/>, <see cref="System.Reflection.Emit.DynamicMethod.IsSecuritySafeCritical"/>, and <see cref="System.Reflection.Emit.DynamicMethod.IsSecurityTransparent"/> properties report the transparency level of the dynamic method as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: | |
| /// </para> | |
| /// <list type="table"> | |
| /// <listheader> | |
| /// <term>Security level</term> | |
| /// <description>IsSecurityCritical</description> | |
| /// <description>IsSecuritySafeCritical</description> | |
| /// <description>IsSecurityTransparent</description> | |
| /// </listheader> | |
| /// <item> | |
| /// <term>Critical</term> | |
| /// <description><c>true</c></description> | |
| /// <description><c>false</c></description> | |
| /// <description><c>false</c></description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Safe critical</term> | |
| /// <description><c>true</c></description> | |
| /// <description><c>true</c></description> | |
| /// <description><c>false</c></description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Transparent</term> | |
| /// <description><c>false</c></description> | |
| /// <description><c>false</c></description> | |
| /// <description><c>true</c></description> | |
| /// </item> | |
| /// </list> | |
| /// <para> | |
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. | |
| /// </para> | |
| /// <para> | |
| /// The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. | |
| /// </para> | |
| /// <list type="bullet"> | |
| /// <item> | |
| /// <description>Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent.</description> | |
| /// </item> | |
| /// <item> | |
| /// <description>The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table.</description> | |
| /// </item> | |
| /// </list> | |
| /// <list type="table"> | |
| /// <listheader> | |
| /// <term>Assembly annotation</term> | |
| /// <description>Level 1 transparency</description> | |
| /// <description>Level 2 transparency</description> | |
| /// </listheader> | |
| /// <item> | |
| /// <term>Fully transparent</term> | |
| /// <description>Transparent</description> | |
| /// <description>Transparent</description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Fully critical</term> | |
| /// <description>Critical</description> | |
| /// <description>Critical</description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Mixed transparency</term> | |
| /// <description>Transparent</description> | |
| /// <description>Transparent</description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Security-agnostic</term> | |
| /// <description>Safe-critical</description> | |
| /// <description>Critical</description> | |
| /// </item> | |
| /// </list> |
Comment on lines
+702
to
+718
| /// </note> | ||
| /// The <see cref="System.Reflection.Emit.DynamicMethod.IsSecurityCritical"/>, <see cref="System.Reflection.Emit.DynamicMethod.IsSecuritySafeCritical"/>, and <see cref="System.Reflection.Emit.DynamicMethod.IsSecurityTransparent"/> properties report the transparency level of the dynamic method as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: | ||
| /// |Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| | ||
| /// |--------------------|------------------------|----------------------------|---------------------------| | ||
| /// |Critical|<c>true</c>|<c>false</c>|<c>false</c>| | ||
| /// |Safe critical|<c>true</c>|<c>true</c>|<c>false</c>| | ||
| /// |Transparent|<c>false</c>|<c>false</c>|<c>true</c>| | ||
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. | ||
| /// The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. | ||
| /// - Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. | ||
| /// - The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. | ||
| /// |Assembly annotation|Level 1 transparency|Level 2 transparency| | ||
| /// |-------------------------|--------------------------|--------------------------| | ||
| /// |Fully transparent|Transparent|Transparent| | ||
| /// |Fully critical|Critical|Critical| | ||
| /// |Mixed transparency|Transparent|Transparent| | ||
| /// |Security-agnostic|Safe-critical|Critical| |
There was a problem hiding this comment.
These remarks include markdown table formatting (pipe-delimited rows). This will show up as literal characters in IntelliSense; convert it to XML doc-friendly markup (e.g., ) so it renders correctly.
Suggested change
| /// </note> | |
| /// The <see cref="System.Reflection.Emit.DynamicMethod.IsSecurityCritical"/>, <see cref="System.Reflection.Emit.DynamicMethod.IsSecuritySafeCritical"/>, and <see cref="System.Reflection.Emit.DynamicMethod.IsSecurityTransparent"/> properties report the transparency level of the dynamic method as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: | |
| /// |Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| | |
| /// |--------------------|------------------------|----------------------------|---------------------------| | |
| /// |Critical|<c>true</c>|<c>false</c>|<c>false</c>| | |
| /// |Safe critical|<c>true</c>|<c>true</c>|<c>false</c>| | |
| /// |Transparent|<c>false</c>|<c>false</c>|<c>true</c>| | |
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. | |
| /// The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. | |
| /// - Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. | |
| /// - The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. | |
| /// |Assembly annotation|Level 1 transparency|Level 2 transparency| | |
| /// |-------------------------|--------------------------|--------------------------| | |
| /// |Fully transparent|Transparent|Transparent| | |
| /// |Fully critical|Critical|Critical| | |
| /// |Mixed transparency|Transparent|Transparent| | |
| /// |Security-agnostic|Safe-critical|Critical| | |
| /// The <see cref="System.Reflection.Emit.DynamicMethod.IsSecurityCritical"/>, <see cref="System.Reflection.Emit.DynamicMethod.IsSecuritySafeCritical"/>, and <see cref="System.Reflection.Emit.DynamicMethod.IsSecurityTransparent"/> properties report the transparency level of the dynamic method as determined by the common language runtime (CLR). | |
| /// </note> | |
| /// The combinations of these properties are shown in the following table: | |
| /// <list type="table"> | |
| /// <listheader> | |
| /// <term>Security level</term> | |
| /// <description>IsSecurityCritical</description> | |
| /// <description>IsSecuritySafeCritical</description> | |
| /// <description>IsSecurityTransparent</description> | |
| /// </listheader> | |
| /// <item> | |
| /// <term>Critical</term> | |
| /// <description><c>true</c></description> | |
| /// <description><c>false</c></description> | |
| /// <description><c>false</c></description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Safe critical</term> | |
| /// <description><c>true</c></description> | |
| /// <description><c>true</c></description> | |
| /// <description><c>false</c></description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Transparent</term> | |
| /// <description><c>false</c></description> | |
| /// <description><c>false</c></description> | |
| /// <description><c>true</c></description> | |
| /// </item> | |
| /// </list> | |
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. | |
| /// The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. | |
| /// <list type="bullet"> | |
| /// <item> | |
| /// <description>Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent.</description> | |
| /// </item> | |
| /// <item> | |
| /// <description>The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table.</description> | |
| /// </item> | |
| /// </list> | |
| /// <list type="table"> | |
| /// <listheader> | |
| /// <term>Assembly annotation</term> | |
| /// <description>Level 1 transparency</description> | |
| /// <description>Level 2 transparency</description> | |
| /// </listheader> | |
| /// <item> | |
| /// <term>Fully transparent</term> | |
| /// <description>Transparent</description> | |
| /// <description>Transparent</description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Fully critical</term> | |
| /// <description>Critical</description> | |
| /// <description>Critical</description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Mixed transparency</term> | |
| /// <description>Transparent</description> | |
| /// <description>Transparent</description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Security-agnostic</term> | |
| /// <description>Safe-critical</description> | |
| /// <description>Critical</description> | |
| /// </item> | |
| /// </list> |
Comment on lines
+639
to
+650
| /// - Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. | ||
| /// - The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. | ||
| /// |Assembly annotation|Level 1 transparency|Level 2 transparency| | ||
| /// |-------------------------|--------------------------|--------------------------| | ||
| /// |Fully transparent|Transparent|Transparent| | ||
| /// |Fully critical|Critical|Critical| | ||
| /// |Mixed transparency|Transparent|Transparent| | ||
| /// |Security-agnostic|Safe-critical|Critical| | ||
| /// For example, if you associate a dynamic method with a type that is in mscorlib.dll, which has level 2 mixed transparency, the dynamic method is transparent and cannot execute critical code. For information about transparency levels, see [Security-Transparent Code, Level 1](/dotnet/framework/misc/security-transparent-code-level-1) and [Security-Transparent Code, Level 2](/dotnet/framework/misc/security-transparent-code-level-2). | ||
| /// > Associating a dynamic method with a module in a trusted level 1 assembly that is security-agnostic, such as System.dll, does not permit elevation of trust. If the grant set of the code that calls the dynamic method does not include the grant set of System.dll (that is, full trust), <see cref="System.Security.SecurityException"/> is thrown when the dynamic method is called. | ||
| /// - The transparency of a dynamic method that is associated with a partially trusted assembly depends on how the assembly is loaded. If the assembly is loaded with partial trust (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types and members, including dynamic methods, are treated as transparent. The runtime pays attention to security annotations only if the partial-trust assembly is loaded with full trust (for example, into the default application domain of a desktop application). In that case, the runtime assigns the dynamic method the default transparency for methods according to the assembly's annotations. | ||
| /// For more information about reflection emit and transparency, see [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). |
There was a problem hiding this comment.
The remarks use raw markdown link / blockquote syntax (e.g., text and leading '>'). XML docs consumers typically won’t render this as intended; prefer links and / markup.
Suggested change
| /// - Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. | |
| /// - The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. | |
| /// |Assembly annotation|Level 1 transparency|Level 2 transparency| | |
| /// |-------------------------|--------------------------|--------------------------| | |
| /// |Fully transparent|Transparent|Transparent| | |
| /// |Fully critical|Critical|Critical| | |
| /// |Mixed transparency|Transparent|Transparent| | |
| /// |Security-agnostic|Safe-critical|Critical| | |
| /// For example, if you associate a dynamic method with a type that is in mscorlib.dll, which has level 2 mixed transparency, the dynamic method is transparent and cannot execute critical code. For information about transparency levels, see [Security-Transparent Code, Level 1](/dotnet/framework/misc/security-transparent-code-level-1) and [Security-Transparent Code, Level 2](/dotnet/framework/misc/security-transparent-code-level-2). | |
| /// > Associating a dynamic method with a module in a trusted level 1 assembly that is security-agnostic, such as System.dll, does not permit elevation of trust. If the grant set of the code that calls the dynamic method does not include the grant set of System.dll (that is, full trust), <see cref="System.Security.SecurityException"/> is thrown when the dynamic method is called. | |
| /// - The transparency of a dynamic method that is associated with a partially trusted assembly depends on how the assembly is loaded. If the assembly is loaded with partial trust (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types and members, including dynamic methods, are treated as transparent. The runtime pays attention to security annotations only if the partial-trust assembly is loaded with full trust (for example, into the default application domain of a desktop application). In that case, the runtime assigns the dynamic method the default transparency for methods according to the assembly's annotations. | |
| /// For more information about reflection emit and transparency, see [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). | |
| /// <list type="bullet"> | |
| /// <item> | |
| /// <description>Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent.</description> | |
| /// </item> | |
| /// <item> | |
| /// <description> | |
| /// The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described as follows. | |
| /// Assembly annotation / Level 1 transparency / Level 2 transparency: | |
| /// Fully transparent: Transparent / Transparent. | |
| /// Fully critical: Critical / Critical. | |
| /// Mixed transparency: Transparent / Transparent. | |
| /// Security-agnostic: Safe-critical / Critical. | |
| /// </description> | |
| /// </item> | |
| /// <item> | |
| /// <description> | |
| /// The transparency of a dynamic method that is associated with a partially trusted assembly depends on how the assembly is loaded. If the assembly is loaded with partial trust (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types and members, including dynamic methods, are treated as transparent. The runtime pays attention to security annotations only if the partial-trust assembly is loaded with full trust (for example, into the default application domain of a desktop application). In that case, the runtime assigns the dynamic method the default transparency for methods according to the assembly's annotations. | |
| /// </description> | |
| /// </item> | |
| /// </list> | |
| /// <para> | |
| /// For example, if you associate a dynamic method with a type that is in mscorlib.dll, which has level 2 mixed transparency, the dynamic method is transparent and cannot execute critical code. For information about transparency levels, see | |
| /// <see href="/dotnet/framework/misc/security-transparent-code-level-1">Security-Transparent Code, Level 1</see> and | |
| /// <see href="/dotnet/framework/misc/security-transparent-code-level-2">Security-Transparent Code, Level 2</see>. | |
| /// </para> | |
| /// <para> | |
| /// Associating a dynamic method with a module in a trusted level 1 assembly that is security-agnostic, such as System.dll, does not permit elevation of trust. If the grant set of the code that calls the dynamic method does not include the grant set of System.dll (that is, full trust), <see cref="System.Security.SecurityException"/> is thrown when the dynamic method is called. | |
| /// </para> | |
| /// <para> | |
| /// For more information about reflection emit and transparency, see | |
| /// <see href="/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit">Security Issues in Reflection Emit</see>. | |
| /// For information about transparency, see | |
| /// <see href="/dotnet/framework/security/security-changes">Security Changes</see>. | |
| /// </para> |
Migrate documentation from dotnet/dotnet-api-docs XML into /// comments for System.Reflection.Emit.DynamicMethod using the slash migration tool. All 48 public members now have doc comments including summary, remarks, param, returns, value, and exception tags as applicable. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
richlander
force-pushed
the
dev/richlander/dynamicmethod-xmldocs
branch
from
49e5e1b to
9c7e7db
Compare
Create DynamicMethod.Examples.cs with #region blocks for per-member code examples. Replace ~/snippets/ paths from dotnet-api-docs with relative paths to the local samples file. Drop VB sample references. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Each #region is a testable example with assertions. The app creates a DynamicMethod, exercises each documented property/method, and returns nonzero on failure. Run with: dotnet run DynamicMethod.Examples.cs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Create two additional file-based app samples for the full-program examples that were missing code references: - DynamicMethod.Overview.cs: ctor + emit + delegate + Invoke - DynamicMethod.CtorOwnerType.cs: ctor with owner type, private field access, bound delegate Restore <code> references in DynamicMethod.cs for the type-level example, constructor with Module, constructor with owner Type, and GetILGenerator — all now pointing to local sample files. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Place samples.json at the samples directory root as the stable
contract between sample authoring and the migration tool. The tool
reads this to generate <code> tags — no manual editing of source
file references needed.
Keys are DocId strings (T:, M:, P:), values are {file, region}.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
All 16 sample references now injected by the slash merge --samples pipeline, with titles and correct relative paths. Paths changed from samples/System/Reflection/Emit/DynamicMethod.*.cs to samples/DynamicMethod.*.cs to match samples.json file entries. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Snippet1 -> CreateAndInvoke (Overview), OwnerTypeAccess (CtorOwnerType) - Fix file paths to include System/Reflection/Emit/ subdirectory - Regenerate DynamicMethod.cs code tags via merge tool Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated 9 comments.
Comments suppressed due to low confidence (1)
src/libraries/System.Private.CoreLib/src/System/Reflection/Emit/DynamicMethod.cs:31
- The PR description says all 48 public members are now documented, but several key public members of
DynamicMethod(e.g.,CreateDelegate,Invoke,GetDynamicILInfo,GetILGenerator(int)) are declared in runtime-specific partials (CoreCLR/Mono) rather than this shared file. Please confirm those declarations also have XML doc comments, or adjust the PR description to reflect the actual scope.
/// <summary>
/// Defines and represents a dynamic method that can be compiled, executed, and discarded. Discarded methods are available for garbage collection.
/// </summary>
/// <remarks>
/// For more information about this API, see <see href="/dotnet/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod">Supplemental API remarks for DynamicMethod</see>.
/// </remarks>
/// <example>
/// The following example creates a dynamic method, emits a method body, and executes it via a delegate and via <see cref="System.Reflection.Emit.DynamicMethod.Invoke"/>.
/// <code lang="cs" source="../../../../samples/System/Reflection/Emit/DynamicMethod.Overview.cs" region="CreateAndInvoke" title="Creating and invoking a DynamicMethod" />
/// </example>
/// <related type="Article" href="/dotnet/framework/reflection-and-codedom/how-to-define-and-execute-dynamic-methods">How to: Define and Execute Dynamic Methods</related>
/// <related type="Article" href="/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit">Security Issues in Reflection Emit</related>
/// <related type="Article" href="/dotnet/framework/reflection-and-codedom/walkthrough-emitting-code-in-partial-trust-scenarios">Walkthrough: Emitting Code in Partial Trust Scenarios</related>
public sealed partial class DynamicMethod : MethodInfo
{
// The context when the method was created. We use this to do the RestrictedMemberAccess checks.
// These checks are done when the method is compiled. This can happen at an arbitrary time,
// when CreateDelegate or Invoke is called, or when another DynamicMethod executes OpCodes.Call.
// We capture the creation context so that we can do the checks against the same context,
Comment on lines
+548
to
+549
| /// <value>Always <see langword="null"/>.</value> | ||
| /// <remarks> |
There was a problem hiding this comment.
There’s a double space in “provided for the DynamicMethod class”, which will show up in IntelliSense output. Please fix the spacing.
Comment on lines
19
to
26
| /// <example> | ||
| /// The following example creates a dynamic method, emits a method body, and executes it via a delegate and via <see cref="System.Reflection.Emit.DynamicMethod.Invoke"/>. | ||
| /// <code lang="cs" source="../../../../samples/System/Reflection/Emit/DynamicMethod.Overview.cs" region="CreateAndInvoke" title="Creating and invoking a DynamicMethod" /> | ||
| /// </example> | ||
| /// <related type="Article" href="/dotnet/framework/reflection-and-codedom/how-to-define-and-execute-dynamic-methods">How to: Define and Execute Dynamic Methods</related> | ||
| /// <related type="Article" href="/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit">Security Issues in Reflection Emit</related> | ||
| /// <related type="Article" href="/dotnet/framework/reflection-and-codedom/walkthrough-emitting-code-in-partial-trust-scenarios">Walkthrough: Emitting Code in Partial Trust Scenarios</related> | ||
| public sealed partial class DynamicMethod : MethodInfo |
There was a problem hiding this comment.
The type-level XML docs contain an empty <example> block (and multiple adjacent <example> elements). Empty example elements render poorly in IntelliSense and add noise to generated docs. Consider removing empty <example> tags and consolidating the description + <code ... /> into a single <example> element.
Comment on lines
+100
to
+104
| /// For example, a dynamic method that is created with <c>restrictedSkipVisibility</c> set to <c>true</c> can access a private member of any assembly on the call stack if the call stack has been granted restricted member access. If the dynamic method is created with partially trusted code on the call stack, it cannot access a private member of a type in a .NET Framework assembly, because such assemblies are fully trusted. | ||
| /// If <c>restrictedSkipVisibility</c> is <c>false</c>, JIT visibility checks are enforced. The code in the dynamic method has access to public methods of public classes, and exceptions are thrown if it tries to access types or members that are <c>private</c>, <c>protected</c>, or <c>internal</c>. | ||
| /// When an anonymously hosted dynamic method is constructed, the call stack of the emitting assembly is included. When the method is invoked, the permissions of the emitting call stack are used instead of the permissions of the actual caller. Thus, the dynamic method cannot execute at a higher level of privilege than that of the assembly that emitted it, even if it is passed to and executed by an assembly that has a higher trust level. | ||
| /// This constructor specifies the method attributes <see cref="System.Reflection.MethodAttributes.Public">Public</see> and <see cref="System.Reflection.MethodAttributes.Static">Static</see>, and the calling convention <see cref="System.Reflection.CallingConventions.Standard">Standard</see>. | ||
| /// </remarks> |
There was a problem hiding this comment.
The remarks here use DocFX/Markdown syntax (bullet lines starting with - and a blockquote line starting with >). In C# XML doc comments this will render as literal text in IntelliSense. Consider converting these to XML-doc-friendly constructs (e.g., <list type="bullet"> for bullets and a <para> / <note> for the quoted paragraph).
Comment on lines
+698
to
+712
| /// |Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| | ||
| /// |--------------------|------------------------|----------------------------|---------------------------| | ||
| /// |Critical|<c>true</c>|<c>false</c>|<c>false</c>| | ||
| /// |Safe critical|<c>true</c>|<c>true</c>|<c>false</c>| | ||
| /// |Transparent|<c>false</c>|<c>false</c>|<c>true</c>| | ||
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. | ||
| /// The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. | ||
| /// - Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. | ||
| /// - The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. | ||
| /// |Assembly annotation|Level 1 transparency|Level 2 transparency| | ||
| /// |-------------------------|--------------------------|--------------------------| | ||
| /// |Fully transparent|Transparent|Transparent| | ||
| /// |Fully critical|Critical|Critical| | ||
| /// |Mixed transparency|Transparent|Transparent| | ||
| /// |Security-agnostic|Safe-critical|Critical| |
There was a problem hiding this comment.
The remarks here include a pipe-table (|...|) and Markdown links ([text](url)). XML doc comments shown in IntelliSense don’t render Markdown tables/links, so this will display as raw punctuation. Consider converting the tables to <list type="table"> and replacing Markdown links with <see href="..."> (or plain text URLs).
Suggested change
| /// |Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| | |
| /// |--------------------|------------------------|----------------------------|---------------------------| | |
| /// |Critical|<c>true</c>|<c>false</c>|<c>false</c>| | |
| /// |Safe critical|<c>true</c>|<c>true</c>|<c>false</c>| | |
| /// |Transparent|<c>false</c>|<c>false</c>|<c>true</c>| | |
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. | |
| /// The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. | |
| /// - Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. | |
| /// - The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. | |
| /// |Assembly annotation|Level 1 transparency|Level 2 transparency| | |
| /// |-------------------------|--------------------------|--------------------------| | |
| /// |Fully transparent|Transparent|Transparent| | |
| /// |Fully critical|Critical|Critical| | |
| /// |Mixed transparency|Transparent|Transparent| | |
| /// |Security-agnostic|Safe-critical|Critical| | |
| /// <list type="table"> | |
| /// <listheader> | |
| /// <term>Security level</term> | |
| /// <description>IsSecurityCritical</description> | |
| /// <description>IsSecuritySafeCritical</description> | |
| /// <description>IsSecurityTransparent</description> | |
| /// </listheader> | |
| /// <item> | |
| /// <term>Critical</term> | |
| /// <description><c>true</c></description> | |
| /// <description><c>false</c></description> | |
| /// <description><c>false</c></description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Safe critical</term> | |
| /// <description><c>true</c></description> | |
| /// <description><c>true</c></description> | |
| /// <description><c>false</c></description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Transparent</term> | |
| /// <description><c>false</c></description> | |
| /// <description><c>false</c></description> | |
| /// <description><c>true</c></description> | |
| /// </item> | |
| /// </list> | |
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. | |
| /// The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. | |
| /// - Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. | |
| /// - The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. | |
| /// <list type="table"> | |
| /// <listheader> | |
| /// <term>Assembly annotation</term> | |
| /// <description>Level 1 transparency</description> | |
| /// <description>Level 2 transparency</description> | |
| /// </listheader> | |
| /// <item> | |
| /// <term>Fully transparent</term> | |
| /// <description>Transparent</description> | |
| /// <description>Transparent</description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Fully critical</term> | |
| /// <description>Critical</description> | |
| /// <description>Critical</description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Mixed transparency</term> | |
| /// <description>Transparent</description> | |
| /// <description>Transparent</description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Security-agnostic</term> | |
| /// <description>Safe-critical</description> | |
| /// <description>Critical</description> | |
| /// </item> | |
| /// </list> |
Comment on lines
+865
to
+872
| /// <summary> | ||
| /// Defines a parameter of the dynamic method. | ||
| /// </summary> | ||
| /// <param name="position">The position of the parameter in the parameter list. Parameters are indexed beginning with the number 1 for the first parameter.</param> | ||
| /// <param name="attributes">A bitwise combination of <see cref="T:System.Reflection.ParameterAttributes"/> values that specifies the attributes of the parameter.</param> | ||
| /// <param name="parameterName">The name of the parameter. The name can be a zero-length string.</param> | ||
| /// <returns>Always returns <see langword="null"/>.</returns> | ||
| /// <exception cref="T:System.ArgumentOutOfRangeException">The method has no parameters. -or- <paramref name="position"/> is less than 0. -or- <paramref name="position"/> is greater than the number of the method's parameters.</exception> |
There was a problem hiding this comment.
ReturnParameter is documented as always returning null, but the implementation always returns a RuntimeParameterInfo instance. Update the <value>/<remarks> to reflect that it returns a ParameterInfo representing the return parameter (and not null).
Comment on lines
+56
to
+58
| public class Example(int id) | ||
| { | ||
| private int id = id; |
There was a problem hiding this comment.
This field initializer uses the same identifier on both sides (private int id = id;) inside a primary-constructor type. This is very likely to either fail to compile (self-referential field initializer / name collision) or to not do what’s intended. Consider renaming the field (e.g., _id) or assigning the primary-constructor parameter to a differently-named backing field/property to make initialization unambiguous and compilable.
Suggested change
| public class Example(int id) | |
| { | |
| private int id = id; | |
| public class Example(int initialId) | |
| { | |
| private int id = initialId; |
Comment on lines
+92
to
+97
| /// This constructor was introduced in the .NET Framework 3.5 or later. | ||
| /// </note> | ||
| /// The dynamic method that is created by this constructor is associated with an anonymous assembly instead of an existing type or module. The anonymous assembly exists only to provide a sandbox environment for dynamic methods, that is, to isolate them from other code. This environment makes it safe for the dynamic method to be emitted and executed by partially trusted code. | ||
| /// Anonymously hosted dynamic methods do not have automatic access to any types or members that are <c>private</c>, <c>protected</c>, or <c>internal</c> (<c>Friend</c> in Visual Basic). This is different from dynamic methods that are associated with an existing type or module, which have access to hidden members in their associated scope. | ||
| /// Specify <c>true</c> for <c>restrictedSkipVisibility</c> if your dynamic method has to access types or members that are <c>private</c>, <c>protected</c>, or <c>internal</c>. This gives the dynamic method restricted access to these members. That is, the members can be accessed only if the following conditions are met: | ||
| /// - The target members belong to an assembly that has a level of trust equal to or lower than the call stack that emits the dynamic method. |
There was a problem hiding this comment.
This constructor’s remarks include an empty <note type="important"> block. Empty note elements show up as blank callouts (or get dropped inconsistently) in docs tooling. Remove the empty <note> wrapper or restore meaningful note content.
Comment on lines
+101
to
+103
| /// If <c>restrictedSkipVisibility</c> is <c>false</c>, JIT visibility checks are enforced. The code in the dynamic method has access to public methods of public classes, and exceptions are thrown if it tries to access types or members that are <c>private</c>, <c>protected</c>, or <c>internal</c>. | ||
| /// When an anonymously hosted dynamic method is constructed, the call stack of the emitting assembly is included. When the method is invoked, the permissions of the emitting call stack are used instead of the permissions of the actual caller. Thus, the dynamic method cannot execute at a higher level of privilege than that of the assembly that emitted it, even if it is passed to and executed by an assembly that has a higher trust level. | ||
| /// This constructor specifies the method attributes <see cref="System.Reflection.MethodAttributes.Public">Public</see> and <see cref="System.Reflection.MethodAttributes.Static">Static</see>, and the calling convention <see cref="System.Reflection.CallingConventions.Standard">Standard</see>. |
There was a problem hiding this comment.
These <see cref="System.Security.Permissions.*"/> references appear to target Code Access Security permission types/flags. Please verify they resolve during the System.Private.CoreLib build (unresolved cref produces CS1574/CS1584, and this repo treats warnings as errors). If they don’t resolve for CoreLib, replace them with plain text or with references to types that are actually available to this compilation.
Comment on lines
+139
to
+142
| /// The dynamic method created with this constructor has access to public and <c>internal</c> (<c>Friend</c> in Visual Basic) members of all the types contained in module <c>m</c>. | ||
| /// > For backward compatibility, this constructor demands <see cref="System.Security.Permissions.SecurityPermission"/> with the <see cref="System.Security.Permissions.SecurityPermissionFlag.ControlEvidence">ControlEvidence</see> flag if the following conditions are both true: <c>m</c> is a module other than the calling module, and the demand for <see cref="System.Security.Permissions.ReflectionPermission"/> with the <see cref="System.Security.Permissions.ReflectionPermissionFlag.MemberAccess">MemberAccess</see> flag has failed. If the demand for <see cref="System.Security.Permissions.SecurityPermission"/> succeeds, the operation is allowed. | ||
| /// The following code example creates a dynamic method that takes two parameters. The example emits a simple function body that prints the first parameter to the console, and the example uses the second parameter as the return value of the method. The example completes the method by creating a delegate, invokes the delegate with different parameters, and finally invokes the dynamic method using the <see cref="System.Reflection.Emit.DynamicMethod.Invoke%28System.Object%2CSystem.Reflection.BindingFlags%2CSystem.Reflection.Binder%2CSystem.Object%5B%5D%2CSystem.Globalization.CultureInfo%29"/> method. | ||
| /// </remarks> |
There was a problem hiding this comment.
This constructor’s <remarks> contains an empty <note type="note"> block. Empty notes degrade IntelliSense/doc output and should be removed or populated with content.
This was referenced Feb 14, 2026
Blocks inheritance of repo-wide settings (IsAotCompatible, TreatWarningsAsErrors, resource targets) that prevent file-based app samples from building and running. Sets TargetFramework to net11.0 to match the SDK and PublishAot=false since DynamicMethod requires JIT. Removes per-file #:property PublishAot=false directives. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add dedicated #region blocks for GetILGenerator, CreateDelegate, and Invoke in DynamicMethod.Examples.cs. Add samples.json entries for CreateDelegate(Type), CreateDelegate(Type,Object), Invoke, GetILGenerator, and GetILGenerator(int). The CreateDelegate/Invoke/ GetILGenerator(int) entries target the CoreCLR partial file. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Comment on lines
+89
to
+90
| /// <note type="important"> | ||
| /// </note> |
There was a problem hiding this comment.
This note block is empty and should be removed. Empty note elements provide no value to the documentation and may cause rendering issues in documentation tools.
Suggested change
| /// <note type="important"> | |
| /// </note> |
Comment on lines
+695
to
+696
| /// <note type="note"> | ||
| /// </note> |
There was a problem hiding this comment.
This note block is empty and should be removed. Empty note elements provide no value to the documentation and may cause rendering issues in documentation tools.
Suggested change
| /// <note type="note"> | |
| /// </note> |
Comment on lines
+731
to
+732
| /// <note type="note"> | ||
| /// </note> |
There was a problem hiding this comment.
This note block is empty and should be removed. Empty note elements provide no value to the documentation and may cause rendering issues in documentation tools.
Suggested change
| /// <note type="note"> | |
| /// </note> |
Comment on lines
+662
to
+676
| /// |Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| | ||
| /// |--------------------|------------------------|----------------------------|---------------------------| | ||
| /// |Critical|<c>true</c>|<c>false</c>|<c>false</c>| | ||
| /// |Safe critical|<c>true</c>|<c>true</c>|<c>false</c>| | ||
| /// |Transparent|<c>false</c>|<c>false</c>|<c>true</c>| | ||
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. | ||
| /// The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. | ||
| /// - Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. | ||
| /// - The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. | ||
| /// |Assembly annotation|Level 1 transparency|Level 2 transparency| | ||
| /// |-------------------------|--------------------------|--------------------------| | ||
| /// |Fully transparent|Transparent|Transparent| | ||
| /// |Fully critical|Critical|Critical| | ||
| /// |Mixed transparency|Transparent|Transparent| | ||
| /// |Security-agnostic|Safe-critical|Critical| |
There was a problem hiding this comment.
Raw markdown table syntax detected (pipe-delimited format). These lines will render as literal text in IntelliSense rather than as a formatted table. For XML documentation, consider converting to HTML table format using 'list' elements, or reformatting as plain text with clear formatting.
Suggested change
| /// |Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| | |
| /// |--------------------|------------------------|----------------------------|---------------------------| | |
| /// |Critical|<c>true</c>|<c>false</c>|<c>false</c>| | |
| /// |Safe critical|<c>true</c>|<c>true</c>|<c>false</c>| | |
| /// |Transparent|<c>false</c>|<c>false</c>|<c>true</c>| | |
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. | |
| /// The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. | |
| /// - Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. | |
| /// - The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. | |
| /// |Assembly annotation|Level 1 transparency|Level 2 transparency| | |
| /// |-------------------------|--------------------------|--------------------------| | |
| /// |Fully transparent|Transparent|Transparent| | |
| /// |Fully critical|Critical|Critical| | |
| /// |Mixed transparency|Transparent|Transparent| | |
| /// |Security-agnostic|Safe-critical|Critical| | |
| /// <list type="table"> | |
| /// <listheader> | |
| /// <term>Security level</term> | |
| /// <description>IsSecurityCritical</description> | |
| /// <description>IsSecuritySafeCritical</description> | |
| /// <description>IsSecurityTransparent</description> | |
| /// </listheader> | |
| /// <item> | |
| /// <term>Critical</term> | |
| /// <description><c>true</c></description> | |
| /// <description><c>false</c></description> | |
| /// <description><c>false</c></description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Safe critical</term> | |
| /// <description><c>true</c></description> | |
| /// <description><c>true</c></description> | |
| /// <description><c>false</c></description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Transparent</term> | |
| /// <description><c>false</c></description> | |
| /// <description><c>false</c></description> | |
| /// <description><c>true</c></description> | |
| /// </item> | |
| /// </list> | |
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. | |
| /// The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. | |
| /// - Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. | |
| /// - The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. | |
| /// <list type="table"> | |
| /// <listheader> | |
| /// <term>Assembly annotation</term> | |
| /// <description>Level 1 transparency</description> | |
| /// <description>Level 2 transparency</description> | |
| /// </listheader> | |
| /// <item> | |
| /// <term>Fully transparent</term> | |
| /// <description>Transparent</description> | |
| /// <description>Transparent</description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Fully critical</term> | |
| /// <description>Critical</description> | |
| /// <description>Critical</description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Mixed transparency</term> | |
| /// <description>Transparent</description> | |
| /// <description>Transparent</description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Security-agnostic</term> | |
| /// <description>Safe-critical</description> | |
| /// <description>Critical</description> | |
| /// </item> | |
| /// </list> |
Comment on lines
+136
to
+137
| /// <note type="note"> | ||
| /// </note> |
There was a problem hiding this comment.
This note block is empty and should be removed. Empty note elements provide no value to the documentation and may cause rendering issues in documentation tools.
Comment on lines
+734
to
+748
| /// |Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| | ||
| /// |--------------------|------------------------|----------------------------|---------------------------| | ||
| /// |Critical|<c>true</c>|<c>false</c>|<c>false</c>| | ||
| /// |Safe critical|<c>true</c>|<c>true</c>|<c>false</c>| | ||
| /// |Transparent|<c>false</c>|<c>false</c>|<c>true</c>| | ||
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. | ||
| /// The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. | ||
| /// - Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. | ||
| /// - The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. | ||
| /// |Assembly annotation|Level 1 transparency|Level 2 transparency| | ||
| /// |-------------------------|--------------------------|--------------------------| | ||
| /// |Fully transparent|Transparent|Transparent| | ||
| /// |Fully critical|Critical|Critical| | ||
| /// |Mixed transparency|Transparent|Transparent| | ||
| /// |Security-agnostic|Safe-critical|Critical| |
There was a problem hiding this comment.
Raw markdown table syntax detected (pipe-delimited format). These lines will render as literal text in IntelliSense rather than as a formatted table. For XML documentation, consider converting to HTML table format using 'list' elements, or reformatting as plain text with clear formatting.
Suggested change
| /// |Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| | |
| /// |--------------------|------------------------|----------------------------|---------------------------| | |
| /// |Critical|<c>true</c>|<c>false</c>|<c>false</c>| | |
| /// |Safe critical|<c>true</c>|<c>true</c>|<c>false</c>| | |
| /// |Transparent|<c>false</c>|<c>false</c>|<c>true</c>| | |
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. | |
| /// The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. | |
| /// - Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. | |
| /// - The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. | |
| /// |Assembly annotation|Level 1 transparency|Level 2 transparency| | |
| /// |-------------------------|--------------------------|--------------------------| | |
| /// |Fully transparent|Transparent|Transparent| | |
| /// |Fully critical|Critical|Critical| | |
| /// |Mixed transparency|Transparent|Transparent| | |
| /// |Security-agnostic|Safe-critical|Critical| | |
| /// <list type="table"> | |
| /// <listheader> | |
| /// <term>Security level</term> | |
| /// <term>IsSecurityCritical</term> | |
| /// <term>IsSecuritySafeCritical</term> | |
| /// <term>IsSecurityTransparent</term> | |
| /// </listheader> | |
| /// <item> | |
| /// <term>Critical</term> | |
| /// <term><c>true</c></term> | |
| /// <term><c>false</c></term> | |
| /// <term><c>false</c></term> | |
| /// </item> | |
| /// <item> | |
| /// <term>Safe critical</term> | |
| /// <term><c>true</c></term> | |
| /// <term><c>true</c></term> | |
| /// <term><c>false</c></term> | |
| /// </item> | |
| /// <item> | |
| /// <term>Transparent</term> | |
| /// <term><c>false</c></term> | |
| /// <term><c>false</c></term> | |
| /// <term><c>true</c></term> | |
| /// </item> | |
| /// </list> | |
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. | |
| /// The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. | |
| /// - Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. | |
| /// - The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. | |
| /// <list type="table"> | |
| /// <listheader> | |
| /// <term>Assembly annotation</term> | |
| /// <term>Level 1 transparency</term> | |
| /// <term>Level 2 transparency</term> | |
| /// </listheader> | |
| /// <item> | |
| /// <term>Fully transparent</term> | |
| /// <term>Transparent</term> | |
| /// <term>Transparent</term> | |
| /// </item> | |
| /// <item> | |
| /// <term>Fully critical</term> | |
| /// <term>Critical</term> | |
| /// <term>Critical</term> | |
| /// </item> | |
| /// <item> | |
| /// <term>Mixed transparency</term> | |
| /// <term>Transparent</term> | |
| /// <term>Transparent</term> | |
| /// </item> | |
| /// <item> | |
| /// <term>Security-agnostic</term> | |
| /// <term>Safe-critical</term> | |
| /// <term>Critical</term> | |
| /// </item> | |
| /// </list> |
Comment on lines
+738
to
+748
| /// |Transparent|<c>false</c>|<c>false</c>|<c>true</c>| | ||
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. | ||
| /// The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. | ||
| /// - Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. | ||
| /// - The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. | ||
| /// |Assembly annotation|Level 1 transparency|Level 2 transparency| | ||
| /// |-------------------------|--------------------------|--------------------------| | ||
| /// |Fully transparent|Transparent|Transparent| | ||
| /// |Fully critical|Critical|Critical| | ||
| /// |Mixed transparency|Transparent|Transparent| | ||
| /// |Security-agnostic|Safe-critical|Critical| |
There was a problem hiding this comment.
Raw markdown table syntax detected (pipe-delimited format). These lines will render as literal text in IntelliSense rather than as a formatted table. For XML documentation, consider converting to HTML table format using 'list' elements, or reformatting as plain text with clear formatting.
Suggested change
| /// |Transparent|<c>false</c>|<c>false</c>|<c>true</c>| | |
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. | |
| /// The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. | |
| /// - Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. | |
| /// - The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. | |
| /// |Assembly annotation|Level 1 transparency|Level 2 transparency| | |
| /// |-------------------------|--------------------------|--------------------------| | |
| /// |Fully transparent|Transparent|Transparent| | |
| /// |Fully critical|Critical|Critical| | |
| /// |Mixed transparency|Transparent|Transparent| | |
| /// |Security-agnostic|Safe-critical|Critical| | |
| /// For example, when the associated code is transparent, the relevant properties have the values <c>false</c>, <c>false</c>, and <c>true</c>. | |
| /// Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. | |
| /// The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. | |
| /// - Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. | |
| /// - The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. | |
| /// <list type="table"> | |
| /// <listheader> | |
| /// <term>Assembly annotation</term> | |
| /// <term>Transparency by level</term> | |
| /// </listheader> | |
| /// <item> | |
| /// <term>Fully transparent</term> | |
| /// <description>Level 1 transparency: Transparent; Level 2 transparency: Transparent.</description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Fully critical</term> | |
| /// <description>Level 1 transparency: Critical; Level 2 transparency: Critical.</description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Mixed transparency</term> | |
| /// <description>Level 1 transparency: Transparent; Level 2 transparency: Transparent.</description> | |
| /// </item> | |
| /// <item> | |
| /// <term>Security-agnostic</term> | |
| /// <description>Level 1 transparency: Safe-critical; Level 2 transparency: Critical.</description> | |
| /// </item> | |
| /// </list> |
Comment on lines
+137
to
+140
| /// </note> | ||
| /// This constructor specifies method attributes <see cref="System.Reflection.MethodAttributes.Public">Public</see> and <see cref="System.Reflection.MethodAttributes.Static">Static</see>, calling convention <see cref="System.Reflection.CallingConventions.Standard">Standard</see>, and does not skip just-in-time (JIT) visibility checks. | ||
| /// The dynamic method created with this constructor has access to public and <c>internal</c> (<c>Friend</c> in Visual Basic) members of all the types contained in module <c>m</c>. | ||
| /// > For backward compatibility, this constructor demands <see cref="System.Security.Permissions.SecurityPermission"/> with the <see cref="System.Security.Permissions.SecurityPermissionFlag.ControlEvidence">ControlEvidence</see> flag if the following conditions are both true: <c>m</c> is a module other than the calling module, and the demand for <see cref="System.Security.Permissions.ReflectionPermission"/> with the <see cref="System.Security.Permissions.ReflectionPermissionFlag.MemberAccess">MemberAccess</see> flag has failed. If the demand for <see cref="System.Security.Permissions.SecurityPermission"/> succeeds, the operation is allowed. |
There was a problem hiding this comment.
Raw markdown blockquote prefix detected. The '> ' prefix should be removed or converted to proper XML documentation format. This markdown syntax will render as literal text in IntelliSense and may confuse developers. Consider using a note element or reformatting as plain text.
Suggested change
| /// </note> | |
| /// This constructor specifies method attributes <see cref="System.Reflection.MethodAttributes.Public">Public</see> and <see cref="System.Reflection.MethodAttributes.Static">Static</see>, calling convention <see cref="System.Reflection.CallingConventions.Standard">Standard</see>, and does not skip just-in-time (JIT) visibility checks. | |
| /// The dynamic method created with this constructor has access to public and <c>internal</c> (<c>Friend</c> in Visual Basic) members of all the types contained in module <c>m</c>. | |
| /// > For backward compatibility, this constructor demands <see cref="System.Security.Permissions.SecurityPermission"/> with the <see cref="System.Security.Permissions.SecurityPermissionFlag.ControlEvidence">ControlEvidence</see> flag if the following conditions are both true: <c>m</c> is a module other than the calling module, and the demand for <see cref="System.Security.Permissions.ReflectionPermission"/> with the <see cref="System.Security.Permissions.ReflectionPermissionFlag.MemberAccess">MemberAccess</see> flag has failed. If the demand for <see cref="System.Security.Permissions.SecurityPermission"/> succeeds, the operation is allowed. | |
| /// For backward compatibility, this constructor demands <see cref="System.Security.Permissions.SecurityPermission"/> with the <see cref="System.Security.Permissions.SecurityPermissionFlag.ControlEvidence">ControlEvidence</see> flag if the following conditions are both true: <c>m</c> is a module other than the calling module, and the demand for <see cref="System.Security.Permissions.ReflectionPermission"/> with the <see cref="System.Security.Permissions.ReflectionPermissionFlag.MemberAccess">MemberAccess</see> flag has failed. If the demand for <see cref="System.Security.Permissions.SecurityPermission"/> succeeds, the operation is allowed. | |
| /// </note> | |
| /// This constructor specifies method attributes <see cref="System.Reflection.MethodAttributes.Public">Public</see> and <see cref="System.Reflection.MethodAttributes.Static">Static</see>, calling convention <see cref="System.Reflection.CallingConventions.Standard">Standard</see>, and does not skip just-in-time (JIT) visibility checks. | |
| /// The dynamic method created with this constructor has access to public and <c>internal</c> (<c>Friend</c> in Visual Basic) members of all the types contained in module <c>m</c>. |
| /// |Mixed transparency|Transparent|Transparent| | ||
| /// |Security-agnostic|Safe-critical|Critical| | ||
| /// For example, if you associate a dynamic method with a type that is in mscorlib.dll, which has level 2 mixed transparency, the dynamic method is transparent and cannot execute critical code. For information about transparency levels, see [Security-Transparent Code, Level 1](/dotnet/framework/misc/security-transparent-code-level-1) and [Security-Transparent Code, Level 2](/dotnet/framework/misc/security-transparent-code-level-2). | ||
| /// > Associating a dynamic method with a module in a trusted level 1 assembly that is security-agnostic, such as System.dll, does not permit elevation of trust. If the grant set of the code that calls the dynamic method does not include the grant set of System.dll (that is, full trust), <see cref="System.Security.SecurityException"/> is thrown when the dynamic method is called. |
There was a problem hiding this comment.
Raw markdown blockquote prefix detected. The '> ' prefix should be removed or converted to proper XML documentation format. This markdown syntax will render as literal text in IntelliSense and may confuse developers. Consider using a note element or reformatting as plain text.
Suggested change
| /// > Associating a dynamic method with a module in a trusted level 1 assembly that is security-agnostic, such as System.dll, does not permit elevation of trust. If the grant set of the code that calls the dynamic method does not include the grant set of System.dll (that is, full trust), <see cref="System.Security.SecurityException"/> is thrown when the dynamic method is called. | |
| /// <note> | |
| /// Associating a dynamic method with a module in a trusted level 1 assembly that is security-agnostic, such as System.dll, does not permit elevation of trust. If the grant set of the code that calls the dynamic method does not include the grant set of System.dll (that is, full trust), <see cref="System.Security.SecurityException"/> is thrown when the dynamic method is called. | |
| /// </note> |
| /// |Mixed transparency|Transparent|Transparent| | ||
| /// |Security-agnostic|Safe-critical|Critical| | ||
| /// For example, if you associate a dynamic method with a type that is in mscorlib.dll, which has level 2 mixed transparency, the dynamic method is transparent and cannot execute critical code. For information about transparency levels, see [Security-Transparent Code, Level 1](/dotnet/framework/misc/security-transparent-code-level-1) and [Security-Transparent Code, Level 2](/dotnet/framework/misc/security-transparent-code-level-2). | ||
| /// > Associating a dynamic method with a module in a trusted level 1 assembly that is security-agnostic, such as System.dll, does not permit elevation of trust. If the grant set of the code that calls the dynamic method does not include the grant set of System.dll (that is, full trust), <see cref="System.Security.SecurityException"/> is thrown when the dynamic method is called. |
There was a problem hiding this comment.
Raw markdown blockquote prefix detected. The '> ' prefix should be removed or converted to proper XML documentation format. This markdown syntax will render as literal text in IntelliSense and may confuse developers. Consider using a note element or reformatting as plain text.
Suggested change
| /// > Associating a dynamic method with a module in a trusted level 1 assembly that is security-agnostic, such as System.dll, does not permit elevation of trust. If the grant set of the code that calls the dynamic method does not include the grant set of System.dll (that is, full trust), <see cref="System.Security.SecurityException"/> is thrown when the dynamic method is called. | |
| /// Associating a dynamic method with a module in a trusted level 1 assembly that is security-agnostic, such as System.dll, does not permit elevation of trust. If the grant set of the code that calls the dynamic method does not include the grant set of System.dll (that is, full trust), <see cref="System.Security.SecurityException"/> is thrown when the dynamic method is called. |
jkotas
reviewed
Feb 14, 2026
| failures++; | ||
| } | ||
|
|
||
| #region Name |
Member
There was a problem hiding this comment.
The #region / #endregion directives every few lines are an eyesore. They make the sample code very unpleasant to read.
Member
Author
There was a problem hiding this comment.
I was copying this scheme:
We can certainly do something different. This scheme is quite effective. The regions are a key aspect. We could switch to method boundary. That would work equally well. Less flexible, but good enough. Fair?
This is what it looks like for the tool I'm working on:
$dotnet-inspect samples Newtonsoft.Json JObject --list
# Samples: Newtonsoft.Json (Newtonsoft.Json)
- Newtonsoft.Json.Linq.JObject - Parsing a JSON Object from Text: https://github.com/JamesNK/Newtonsoft.Json/raw/4e13299d4b0ec96bd4df9954ef646bd2d1b5bf2a/Src/Newtonsoft.Json.Tests/Documentation/LinqToJsonTests.cs
$ dotnet-inspect samples Newtonsoft.Json JObject
# Samples: Newtonsoft.Json (Newtonsoft.Json)
## 1. Newtonsoft.Json.Linq.JObject - Parsing a JSON Object from Text
```csharp
string json = @"{
CPU: 'Intel',
Drives: [
'DVD read/writer',
'500 gigabyte hard drive'
]
}";
JObject o = JObject.Parse(json);
```
Member
Author
There was a problem hiding this comment.
As a side note, I was intended on pushing this to upstream. That was an accident. I was intending on pushing to a fork until I got a bit further.
Member
Author
There was a problem hiding this comment.
I'll switch to method boundary and see how that works. It will likely be fine.
Member
There was a problem hiding this comment.
Good samples are self-contained. You can copy&paste them into your app, and they will compile. The Json samples are like that. The samples enclosed in the region blocks in the PR are not like that - the code outside the region block is needed to make something that compiles.
Member
Author
There was a problem hiding this comment.
The JSON samples have regions inside the methods. As I said, I'm happy to change. But that's not an accurate description of the JSON samples. I was just copying their approach.
Member
Author
There was a problem hiding this comment.
Here's a new take:
richlander
added a commit
to richlander/runtime
that referenced
this pull request
Feb 14, 2026
Restructure DynamicMethod.Examples.cs to use self-contained static methods instead of #region/#endregion directives. Each method creates its own DynamicMethod and is independently runnable — addressing feedback that samples should be copy-paste compilable. Three methods replace the many small regions: - MetadataAndProperties: Name, DeclaringType, Module, Attributes, etc. - DefineParameterAndGetParameters: parameter metadata - GetILGeneratorAndInvoke: IL emission, delegates, and Invoke Update <code> tags in DynamicMethod.cs and samples.json to use method= instead of region= for Examples.cs entries. Overview.cs and CtorOwnerType.cs retain their existing region-based approach (single self-contained regions). Addresses feedback from jkotas on PR dotnet#124407. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
richlander
added a commit
to richlander/runtime
that referenced
this pull request
Feb 14, 2026
Restructure DynamicMethod.Examples.cs to use self-contained static methods instead of #region/#endregion directives. Each method creates its own DynamicMethod and is independently runnable — addressing feedback that samples should be copy-paste compilable. Three methods replace the many small regions: - MetadataAndProperties: Name, DeclaringType, Module, Attributes, etc. - DefineParameterAndGetParameters: parameter metadata - GetILGeneratorAndInvoke: IL emission, delegates, and Invoke Update <code> tags in DynamicMethod.cs and samples.json to use method= instead of region= for Examples.cs entries. Overview.cs and CtorOwnerType.cs retain their existing region-based approach (single self-contained regions). Addresses feedback from jkotas on PR dotnet#124407. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
richlander
force-pushed
the
dev/richlander/dynamicmethod-xmldocs
branch
from
bae73d6 to
80aada7
Compare
Restructure DynamicMethod.Examples.cs to use self-contained static methods instead of #region/#endregion directives. Each method creates its own DynamicMethod and is independently runnable — addressing feedback that samples should be copy-paste compilable. Three methods replace the many small regions: - MetadataAndProperties: Name, DeclaringType, Module, Attributes, etc. - DefineParameterAndGetParameters: parameter metadata - GetILGeneratorAndInvoke: IL emission, delegates, and Invoke Update <code> tags in DynamicMethod.cs and samples.json to use method= instead of region= for Examples.cs entries. Overview.cs and CtorOwnerType.cs retain their existing region-based approach (single self-contained regions). Addresses feedback from jkotas on PR dotnet#124407. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
richlander
force-pushed
the
dev/richlander/dynamicmethod-xmldocs
branch
from
80aada7 to
22a88a6
Compare
Comment on lines
+743
to
+748
| /// |Assembly annotation|Level 1 transparency|Level 2 transparency| | ||
| /// |-------------------------|--------------------------|--------------------------| | ||
| /// |Fully transparent|Transparent|Transparent| | ||
| /// |Fully critical|Critical|Critical| | ||
| /// |Mixed transparency|Transparent|Transparent| | ||
| /// |Security-agnostic|Safe-critical|Critical| |
There was a problem hiding this comment.
Raw markdown table syntax in XML documentation. The pipe characters will render as literal text in IntelliSense.
Comment on lines
+671
to
+676
| /// |Assembly annotation|Level 1 transparency|Level 2 transparency| | ||
| /// |-------------------------|--------------------------|--------------------------| | ||
| /// |Fully transparent|Transparent|Transparent| | ||
| /// |Fully critical|Critical|Critical| | ||
| /// |Mixed transparency|Transparent|Transparent| | ||
| /// |Security-agnostic|Safe-critical|Critical| |
There was a problem hiding this comment.
Raw markdown table syntax in XML documentation. The pipe characters will render as literal text in IntelliSense. Consider converting to a format that renders properly in XML doc comments.
Comment on lines
+662
to
+666
| /// |Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| | ||
| /// |--------------------|------------------------|----------------------------|---------------------------| | ||
| /// |Critical|<c>true</c>|<c>false</c>|<c>false</c>| | ||
| /// |Safe critical|<c>true</c>|<c>true</c>|<c>false</c>| | ||
| /// |Transparent|<c>false</c>|<c>false</c>|<c>true</c>| |
There was a problem hiding this comment.
Raw markdown table syntax in XML documentation. The pipe characters and table format will render as literal text in IntelliSense rather than as a formatted table. Consider removing the table formatting or converting to a different format that renders properly in XML doc comments.
This was referenced Feb 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Migrate XML documentation from
dotnet/dotnet-api-docsinto///comments forSystem.Reflection.Emit.DynamicMethod. This is a companion to #124227 (DynamicILInfo), covering the other major type in this namespace.All 48 public members now have doc comments including
<summary>,<remarks>,<param>,<returns>,<value>, and<exception>tags as applicable. The type-level docs include examples with code sample references.Process
This change was produced using the slash XML doc migration tool, orchestrated by a Copilot agent. The tool performs a mechanical, reliable operation:
xml/System.Reflection.Emit/DynamicMethod.xml) into a unified doc modelfill-gapsmode (only adds docs where none exist, preserves any existing///comments)"To be added.") automatically///comment blocks, placed on the correct declarations via Roslyn syntax tree manipulationThe tool can operate at any scope — whole corpus, library, namespace, or individual type. In this case, we chose
DynamicMethodspecifically to match the scope of #124227.Quality metrics (post-migration)
Agent review of the result
After the mechanical migration, the agent reviewed the full output and identified these issues in the source XML data (not tool bugs):
Constructor summaries are identical across all 8 overloads. Each says "Initializes an anonymously hosted dynamic method" regardless of whether the overload takes
Module,Type owner,skipVisibility, orattributes/callingConvention. The XML source does not differentiate.Constructor remarks are duplicated verbatim across all 8 overloads — the same long block about anonymous hosting, JIT visibility, and trust. Each overload should have remarks specific to its unique parameters.
Missing
<param>tags for several constructor parameters (m,owner,skipVisibility,attributes,callingConvention,restrictedSkipVisibility). Onlyname,returnType, andparameterTypesare documented. This is a gap in the XML source.Empty
<note>blocks onIsSecurityCritical,IsSecuritySafeCritical,IsSecurityTransparent— the note content was "To be added." in the XML source, which the tool stripped, leaving an empty<note type="note"></note>wrapper.Raw markdown in remarks — blockquote prefix (
>) and pipe-table format (|col1|col2|) from DocFX markdown that passed through to///comments. These render as literal text in IntelliSense.Items 1-3 are source data quality issues that exist in
dotnet-api-docstoday. Items 4-5 are format conversion gaps that we will address in the tool for subsequent migrations.