Update the TypeLib embedding and add comments on API use (#105416)

There is an undocumented semantic of Win32 Resource APIs.
The missing semantic is that all resource type/name
strings are transparently converted to uppercase
when calling any of the Win32 Resource APIs.

We don't want to apply this undocumented semantic to the reader/writer API
so we document it instead. We are avoiding applying the behavior
since ReadyToRun scenarios are designed to be a byte for byte copy
of the resource, including name as it was written by other tooling.

src/coreclr/tools/Common/Compiler/Win32Resources/ResourceData.UpdateResourceDataModel.cs

@@ -3,6 +3,7 @@
 
 using System;
 using System.Collections;
+using System.Diagnostics;
 
 #if HOST_MODEL
 namespace Microsoft.NET.HostModel.Win32Resources
@@ -26,6 +27,7 @@ private void AddResourceInternal(object name, object type, ushort language, byte
             }
             else
             {
+                Debug.Assert(type is string);
                 if (!_resTypeHeadName.TryGetValue((string)type, out resType))
                 {
                     resType = new ResType();
@@ -45,6 +47,7 @@ private void AddResourceInternal(object name, object type, ushort language, byte
             }
             else
             {
+                Debug.Assert(name is string);
                 if (!resType.NameHeadName.TryGetValue((string)name, out resName))
                 {
                     resName = new ResName();
@@ -57,28 +60,30 @@ private void AddResourceInternal(object name, object type, ushort language, byte
 
         private byte[] FindResourceInternal(object name, object type, ushort language)
         {
-            ResType resType = null;
+            ResType resType;
 
             if (type is ushort)
             {
                 _resTypeHeadID.TryGetValue((ushort)type, out resType);
             }
-            if (type is string)
+            else
             {
+                Debug.Assert(type is string);
                 _resTypeHeadName.TryGetValue((string)type, out resType);
             }
 
             if (resType == null)
                 return null;
 
-            ResName resName = null;
+            ResName resName;
 
             if (name is ushort)
             {
                 resType.NameHeadID.TryGetValue((ushort)name, out resName);
             }
-            if (name is string)
+            else
             {
+                Debug.Assert(name is string);
                 resType.NameHeadName.TryGetValue((string)name, out resName);
             }
 

src/coreclr/tools/Common/Compiler/Win32Resources/ResourceData.cs

@@ -60,6 +60,10 @@ public ResourceData(Internal.TypeSystem.Ecma.EcmaModule ecmaModule, Func<object,
         /// <summary>
         /// Find a resource in the resource data
         /// </summary>
+        /// <remarks>
+        /// The Win32 APIs typcially perform an uppercase transform on string arguments - during add and find.
+        /// If the resource will be read by Win32 APIs, it is recommended to make the resource name upper case.
+        /// </remarks>
         public byte[] FindResource(string name, string type, ushort language)
         {
             return FindResourceInternal(name, type, language);
@@ -68,6 +72,10 @@ public byte[] FindResource(string name, string type, ushort language)
         /// <summary>
         /// Find a resource in the resource data
         /// </summary>
+        /// <remarks>
+        /// The Win32 APIs typcially perform an uppercase transform on string arguments - during add and find.
+        /// If the resource will be read by Win32 APIs, it is recommended to make the resource name upper case.
+        /// </remarks>
         public byte[] FindResource(ushort name, string type, ushort language)
         {
             return FindResourceInternal(name, type, language);
@@ -76,6 +84,10 @@ public byte[] FindResource(ushort name, string type, ushort language)
         /// <summary>
         /// Find a resource in the resource data
         /// </summary>
+        /// <remarks>
+        /// The Win32 APIs typcially perform an uppercase transform on string arguments - during add and find.
+        /// If the resource will be read by Win32 APIs, it is recommended to make the resource name upper case.
+        /// </remarks>
         public byte[] FindResource(string name, ushort type, ushort language)
         {
             return FindResourceInternal(name, type, language);
@@ -92,16 +104,28 @@ public byte[] FindResource(ushort name, ushort type, ushort language)
         /// <summary>
         /// Add or update resource
         /// </summary>
+        /// <remarks>
+        /// The Win32 APIs typcially perform an uppercase transform on string arguments - during add and find.
+        /// If the resource will be read by Win32 APIs, it is recommended to make the resource name upper case.
+        /// </remarks>
         public void AddResource(string name, string type, ushort language, byte[] data) => AddResourceInternal(name, type, language, data);
 
         /// <summary>
         /// Add or update resource
         /// </summary>
+        /// <remarks>
+        /// The Win32 APIs typcially perform an uppercase transform on string arguments - during add and find.
+        /// If the resource will be read by Win32 APIs, it is recommended to make the resource name upper case.
+        /// </remarks>
         public void AddResource(string name, ushort type, ushort language, byte[] data) => AddResourceInternal(name, type, language, data);
 
         /// <summary>
         /// Add or update resource
         /// </summary>
+        /// <remarks>
+        /// The Win32 APIs typcially perform an uppercase transform on string arguments - during add and find.
+        /// If the resource will be read by Win32 APIs, it is recommended to make the resource name upper case.
+        /// </remarks>
         public void AddResource(ushort name, string type, ushort language, byte[] data) => AddResourceInternal(name, type, language, data);
 
         /// <summary>

src/installer/managed/Microsoft.NET.HostModel/ComHost/ComHost.cs

@@ -57,7 +57,7 @@ public static void Create(
                             if (tlbFileBytes.Length == 0)
                                 throw new InvalidTypeLibraryException(typeLibrary.Value);
 
-                            updater.AddResource(tlbFileBytes, "typelib", (IntPtr)typeLibrary.Key);
+                            updater.AddResource(tlbFileBytes, "TYPELIB", (IntPtr)typeLibrary.Key);
                         }
                         catch (FileNotFoundException ex)
                         {