Add design usage notes to TypeMapAttribute and TypeMapAssociationAttribute documentation

[Copilot]

Summary

Adds detailed Remarks sections to TypeMapAttribute<TTypeMapGroup> and TypeMapAssociationAttribute<TTypeMapGroup> documenting the trimming behavior from the runtime design doc.

TypeMapAttribute

• Usage for unmanaged-to-managed interop type mapping
• Complete list of IL instructions that trigger External Type Map entry inclusion (ldtoken, unbox, isinst, castclass, box, newarr, newobj, etc.)
• Notes on generic parameter handling

TypeMapAssociationAttribute

• Usage for managed-to-unmanaged interop source/proxy type associations
• IL instructions triggering Proxy Type Map inclusion
• Special handling for interface types with IDynamicInterfaceCastable

Also fixes pre-existing typo ("kthe" → "the") in TypeMapAttribute constructor parameter description.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>TypeMapAttribute/TypeMapAssociationAttribute Add design usage notes to documentation</issue_title>
<issue_description>Design details and usage requirements should be pushed into the "Remarks" section of the two APIs.

https://learn.microsoft.com/dotnet/api/system.runtime.interopservices.typemapassociationattribute-1
https://learn.microsoft.com/dotnet/api/system.runtime.interopservices.typemapattribute-1

The design details can be found at https://github.com/dotnet/runtime/blob/main/docs/design/features/typemap.md.</issue_description>

<agent_instructions>The primary data in the design doc are the bulleted list for how the attributes influence trimming logic.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@AaronRobinsonMSFT /cc @Sergio0694 @AaronRobinsonMSFT /cc @jkoritzinsky @jtschuster @sbomer @agocke @MichalStrehovsky

• Fixes TypeMapAttribute/TypeMapAssociationAttribute Add design usage notes to documentation #12102

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Sergio0694]

All of this below is incorrect, it only applies to the type map, not the proxy map.

[AaronRobinsonMSFT]

@Sergio0694 This is directly from the design document. What is incorrect about it?

See https://github.com/dotnet/runtime/blob/main/docs/design/features/typemap.md#proxy-type-map

[jkoritzinsky]

Suggested change

	If the type is an interface type and the user could possibly see a `RuntimeTypeHandle` for the type as part of a casting or virtual method resolution operation (such as with <xref:System.Runtime.InteropServices.IDynamicInterfaceCastable>), then the following cases also apply:
	If the type is an interface type and the user could possibly see a <xref:System.RuntimeTypeHandle> for the type as part of a casting or virtual method resolution operation (such as with <xref:System.Runtime.InteropServices.IDynamicInterfaceCastable>), then the following cases also apply:

[jkoritzinsky]

Suggested change

> The underlying format of the produced maps is implementation-defined. Different .NET form factors might use different formats. Additionally, it's not guaranteed that the `TypeMapAttribute`, `TypeMapAssociationAttribute`, and `TypeMapAssemblyTargetAttribute` attributes are present in the final image after a trimming tool has been run.

> The underlying format of the produced maps is implementation-defined. Different .NET form factors might use different formats. Additionally, it's not guaranteed that the <xref:System.Runtime.InteropServices.TypeMapAttribute%60%601>, <xref:System.Runtime.InteropServices.TypeMapAssociationAttribute%60%601>, and <xref:System.Runtime.InteropServices.TypeMapAssemblyTarget%60%601> attributes are present in the final image after a trimming tool has been run.

[jkoritzinsky]

Suggested change

> The underlying format of the produced maps is implementation-defined. Different .NET form factors might use different formats. Additionally, it's not guaranteed that the `TypeMapAttribute`, `TypeMapAssociationAttribute`, and `TypeMapAssemblyTargetAttribute` attributes are present in the final image after a trimming tool has been run.

> The underlying format of the produced maps is implementation-defined. Different .NET form factors might use different formats. Additionally, it's not guaranteed that the <xref:System.Runtime.InteropServices.TypeMapAttribute%60%601>, <xref:System.Runtime.InteropServices.TypeMapAssociationAttribute%60%601>, and <xref:System.Runtime.InteropServices.TypeMapAssemblyTarget%60%601> attributes are present in the final image after a trimming tool has been run.

[jkoritzinsky]

Suggested change

	Types used in a managed-to-unmanaged interop operation can use `TypeMapAssociationAttribute` to define a conditional link between the source and proxy type. If the source is kept, so is the proxy type. If trimming observes an explicit allocation of the source type, the entry is inserted into the map.
	Types used in a managed-to-unmanaged interop operation can use <xref:System.Runtime.InteropServices.TypeMapAssociationAttribute%60%601> to define a conditional link between the source and proxy type. If the source is kept, so is the proxy type. If trimming observes an explicit allocation of the source type, the entry is inserted into the map.

[jkoritzinsky]

Suggested change

Types involved in unmanaged-to-managed interop operations can be referenced in a `TypeMapAttribute` assembly attribute that declares the external type system name, a target type, and optionally a "trim target" to determine if the target type should be included in the map. If the constructor that doesn't take a trim target is used, the entry is always emitted into the type map.

Types involved in unmanaged-to-managed interop operations can be referenced in a <xref:System.Runtime.InteropServices.TypeMapAttribute%60%601> assembly attribute that declares the external type system name, a target type, and optionally a "trim target" to determine if the target type should be included in the map. If the constructor that doesn't take a trim target is used, the entry is always emitted into the type map.