Reinstate supplemental API remarks (System.Runtime)#12699
Open
gewarren wants to merge 5 commits into
Open
Conversation
gewarren
requested review from
a team,
AaronRobinsonMSFT,
StephenMolloy and
jkoritzinsky
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
This PR reinstates “supplemental API remarks” directly into this repo’s ECMA XML files for several System.Runtime-related APIs (per #12613), replacing the previous pattern of linking out to conceptual documentation. It also adds/relocates snippet assets to support the restored remarks.
Changes:
- Replaces “Supplemental API remarks…” external links with inlined markdown remarks in multiple
xml/type docs. - Updates
InternalsVisibleToAttributedocs to point at new snippet paths and adds new snippet projects/files. - Adds new snippet project files (C#/VB) to support compilation/validation of the referenced code samples.
Reviewed changes
Copilot reviewed 34 out of 38 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| xml/System.Runtime.Versioning/ComponentGuaranteesAttribute.xml | Inlines previously external supplemental remarks and references snippet files. |
| xml/System.Runtime.Serialization/XsdDataContractExporter.xml | Inlines supplemental remarks content for the exporter. |
| xml/System.Runtime.Serialization/IExtensibleDataObject.xml | Inlines supplemental remarks content for version-tolerant serialization. |
| xml/System.Runtime.Serialization/DataContractSerializer.xml | Inlines supplemental remarks content (includes a .NET Framework partial-trust section that needs adjustment). |
| xml/System.Runtime.Serialization/DataContractAttribute.xml | Inlines supplemental remarks content and guidance for data contracts. |
| xml/System.Runtime.Loader/AssemblyLoadContext.xml | Inlines supplemental remarks content for load contexts. |
| xml/System.Runtime.InteropServices/SafeHandle.xml | Inlines supplemental remarks content for SafeHandle usage and motivation. |
| xml/System.Runtime.InteropServices/ICustomMarshaler.xml | Inlines supplemental remarks content and adds snippet references (includes .NET Framework wording to neutralize). |
| xml/System.Runtime.InteropServices/ComWrappers.xml | Inlines supplemental remarks content describing ComWrappers concepts. |
| xml/System.Runtime.InteropServices/COMException.xml | Inlines supplemental remarks content for COMException handling guidance. |
| xml/System.Runtime.CompilerServices/RuntimeHelpers.xml | Inlines supplemental remarks for RuntimeHelpers.GetHashCode and adds snippet references. |
| xml/System.Runtime.CompilerServices/InternalsVisibleToAttribute.xml | Inlines supplemental remarks and repoints snippet references; includes a minor punctuation fix needed. |
| snippets/visualbasic/System.Runtime.Versioning/ComponentGuaranteesAttribute/Overview/Project.vbproj | Adds a VB snippet project for ComponentGuaranteesAttribute examples. |
| snippets/visualbasic/System.Runtime.Versioning/ComponentGuaranteesAttribute/Overview/apply1.vb | Adds VB snippet source for the ComponentGuaranteesAttribute examples. |
| snippets/visualbasic/System.Runtime.InteropServices/ICustomMarshaler/Overview/source.vb | Adds VB snippet source for ICustomMarshaler remarks. |
| snippets/visualbasic/System.Runtime.InteropServices/ICustomMarshaler/Overview/Project.vbproj | Adds a VB snippet project for ICustomMarshaler examples. |
| snippets/visualbasic/System.Runtime.CompilerServices/RuntimeHelpers/GetHashCode/Project.vbproj | Adds a VB snippet project for RuntimeHelpers.GetHashCode examples. |
| snippets/visualbasic/System.Runtime.CompilerServices/RuntimeHelpers/GetHashCode/gethashcodeex1.vb | Adds VB snippet source for RuntimeHelpers.GetHashCode examples. |
| snippets/visualbasic/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/UtilityLib/utilitylib.vb | Adds VB UtilityLib snippet source (missing a corresponding Project.vbproj). |
| snippets/visualbasic/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/friend2.vb | Removes the old VB Friend2 snippet location (relocated under Overview/Friend/). |
| snippets/visualbasic/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/multiple2.vb | Adds VB snippet showing multiple friend assemblies via one assembly block. |
| snippets/visualbasic/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/multiple1.vb | Adds VB snippet showing multiple friend assemblies via multiple attributes. |
| snippets/visualbasic/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/Friend2.vbproj | Adds a VB snippet project for friend-assembly examples. |
| snippets/visualbasic/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/friend2.vb | Adds relocated VB Friend2 snippet (currently has the key call commented out). |
| snippets/visualbasic/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/friend1.vb | Updates/relocates VB Friend1 snippet content. |
| snippets/visualbasic/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/assembly1.vb | Adds relocated VB Assembly1 snippet content for signed-assembly example. |
| snippets/csharp/System.Runtime.InteropServices/ICustomMarshaler/Overview/source.cs | Adds C# snippet source referenced by the restored ICustomMarshaler remarks. |
| snippets/csharp/System.Runtime.InteropServices/ICustomMarshaler/Overview/Project.csproj | Adds a C# snippet project for ICustomMarshaler examples. |
| snippets/csharp/System.Runtime.CompilerServices/RuntimeHelpers/GetHashCode/gethashcodeex1.cs | Adds C# snippet source referenced by the restored RuntimeHelpers remarks. |
| snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/UtilityLib/UtilityLib.csproj | Adds a C# UtilityLib snippet project for InternalsVisibleTo examples. |
| snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/UtilityLib/utilitylib.cs | Adds C# UtilityLib snippet source for InternalsVisibleTo examples. |
| snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/friend2.cs | Removes the old C# Friend2 snippet location (relocated under Overview/Friend/). |
| snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/multiple2.cs | Adds C# snippet showing multiple friend assemblies in one attribute list. |
| snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/multiple1.cs | Adds C# snippet showing multiple friend assemblies via multiple attributes. |
| snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/Friend2.csproj | Adds a C# snippet project for friend-assembly examples (needs a ProjectReference). |
| snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/friend2.cs | Adds relocated C# Friend2 snippet (needs compile + example correctness fixes). |
| snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/friend1.cs | Updates/relocates C# Friend1 snippet content (had a compile break due to renaming). |
| snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/assembly1.cs | Adds relocated C# Assembly1 snippet content for signed-assembly example. |
Comments suppressed due to low confidence (1)
snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/friend1.cs:29
- The snippet renames the helper type to
FileUtilities1, butMainstill callsFileUtilities.AppendDirectorySeparator, which will fail to compile. Update the call site to use the new type name (or keep the original type name consistent across the snippet).
Comment on lines
+92
to
+97
| ## Run under partial trust | ||
|
|
||
| When instantiating the target object during deserialization, the <xref:System.Runtime.Serialization.DataContractSerializer> does not call the constructor of the target object. If you author a *[DataContract]* type that is accessible from partial trust (that is, it is public and in an assembly that has the `AllowPartiallyTrustedCallers` attribute applied) and that performs some security-related actions, you must be aware that the constructor is not called. In particular, the following techniques do not work: | ||
|
|
||
| - If you try to restrict partial trust access by making the constructor internal or private, or by adding a `LinkDemand` to the constructor -- neither of these have any effect during deserialization under partial trust. | ||
| - If you code the class that assumes the constructor has run, the class may get into an invalid internal state that is exploitable. |
| - It enables client applications that were designed to work with an old interface to also work with servers that implement a new interface. | ||
| - It enables client applications built to work with a new interface to work with servers that implement an old interface. | ||
|
|
||
| If you have an interface that introduces different marshaling behavior or that is exposed to the Component Object Model (COM) in a different way, you can design a custom marshaller instead of using the interop marshaller. By using a custom marshaller, you can minimize the distinction between new .NET Framework components and existing COM components. |
|
|
||
| The <xref:System.Runtime.CompilerServices.InternalsVisibleToAttribute> attribute specifies that types that are ordinarily visible only within the current assembly are visible to a specified assembly. | ||
|
|
||
| Ordinarily, types and members with [`internal` scope in C#](/dotnet/csharp/language-reference/keywords/internal) or [`Friend` scope in Visual Basic](/dotnet/visual-basic/language-reference/modifiers/friend) are visible only in the assembly in which they are defined. Types and members with [`protected internal`](/dotnet/csharp/language-reference/keywords/protected-internal) scope ([`Protected Friend`](/dotnet/visual-basic/language-reference/modifiers/protected-friend) scope in Visual Basic) are visible only in their own assembly or to types that derive from their containing class. Types and members with [`private protected`](/dotnet/csharp/language-reference/keywords/private-protected) scope ([`Private Protected`](/dotnet/visual-basic/language-reference/modifiers/private-protected) scope in Visual Basic) are visible in the containing class or in types that derive from their containing class within the current assembly |
Comment on lines
+1
to
+5
| <Project Sdk="Microsoft.NET.Sdk"> | ||
|
|
||
| <PropertyGroup> | ||
| <OutputType>Library</OutputType> | ||
| <TargetFramework>net10.0</TargetFramework> |
Comment on lines
+1
to
+11
| // <Snippet6> | ||
|
|
||
| public class Example1 | ||
| { | ||
| public static void Main() | ||
| { | ||
| String s = "The Sign of the Four"; | ||
| //Console.WriteLine(Utilities.StringUtilities.StringLib.IsFirstLetterUpperCase(s)); | ||
| } | ||
| } | ||
| // </Snippet6> |
Comment on lines
+5
to
+9
| Module Example1 | ||
| Public Sub Main() | ||
| Dim s As String = "The Sign of the Four" | ||
| ' Console.WriteLine(Utilities.StringUtilities.StringLib.IsFirstLetterUpperCase(s)) | ||
| End Sub |
BillWagner
approved these changes
Jun 4, 2026
Member
BillWagner
left a comment
BillWagner
left a comment
There was a problem hiding this comment.
This LGTM @gewarren
I had a couple code suggestions, and then it's ready.
| internal string ToTitleCase(string value) | ||
| { | ||
| string retval = null; | ||
| for (int ctr = 0; ctr <= value.Length - 1; ctr++) |
Member
There was a problem hiding this comment.
Why not simplify:
Suggested change
| for (int ctr = 0; ctr <= value.Length - 1; ctr++) | |
| for (int ctr = 0; ctr < value.Length; ctr++) |
| internal static string ToTitleCase(string value) | ||
| { | ||
| string retval = null; | ||
| for (int ctr = 0; ctr <= value.Length - 1; ctr++) |
Member
There was a problem hiding this comment.
Same:
Suggested change
| for (int ctr = 0; ctr <= value.Length - 1; ctr++) | |
| for (int ctr = 0; ctr < value.Length; ctr++) |
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
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.
Contributes to #12613.
Also removes .NET Framework remarks.