Add doc/example for ref assemblies, PDB and resources

docs/core/porting/net-framework-tech-unavailable.md

@@ -59,9 +59,9 @@ Windows Workflow Foundation (WF) is not supported in .NET 6+. For an alternative
 - <xref:System.Reflection.Emit.AssemblyBuilderAccess.RunAndSave>
 - <xref:System.Reflection.Emit.AssemblyBuilderAccess.Save>
 
-In .NET 9, a `PersistedAssemblyBuilder` was implemented and the <xref:System.Reflection.Emit.AssemblyBuilder.Save%2A?displayProperty=nameWithType> method was added back to the reflection emit library. To learn more about how to use this API, see [System.Reflection.Emit.AssemblyBuilder class](../../fundamentals/runtime-libraries/system-reflection-emit-assemblybuilder.md#persisted-dynamic-assemblies-in-net).
+In .NET 9, a `PersistedAssemblyBuilder` was implemented and the <xref:System.Reflection.Emit.AssemblyBuilder.Save%2A?displayProperty=nameWithType> method was added back to the reflection emit library. To learn more about how to use this API, see [System.Reflection.Emit.PersistedAssemblyBuilder class](../../fundamentals/runtime-libraries/system-reflection-emit-persistedassemblybuilder.md).
 
-For more information, see [dotnet/runtime issue 15704](https://github.com/dotnet/runtime/issues/15704).
+For more information about the different AssemblyBuilder implementations in .NET, see [System.Reflection.Emit.AssemblyBuilder class](../../fundamentals/runtime-libraries/system-reflection-emit-assemblybuilder.md)
 
 ## Loading multi-module assemblies
 

docs/fundamentals/runtime-libraries/snippets/System.Reflection.Emit/PersistedAssemblyBuilder/Overview/csharp/CreateAndRunAssembly.cs

@@ -0,0 +1,51 @@
+using System;
+using System.IO;
+using System.Reflection;
+using System.Reflection.Emit;
+using System.Runtime.Loader;
+using System.Runtime.InteropServices;
+
+public class CreatePersistedAssemblyExample
+{
+    public static void Main()
+    {
+        CreateSaveAndRunAssembly();
+        CreatePersistedAssemblyBuilderCoreAssemblyWithMetadataLoadContext(RuntimeEnvironment.GetRuntimeDirectory());
+    }
+    // <Snippet1>
+    public static void CreateSaveAndRunAssembly()
+    {
+        PersistedAssemblyBuilder ab = new PersistedAssemblyBuilder(new AssemblyName("MyAssembly"), typeof(object).Assembly);
+        ModuleBuilder mob = ab.DefineDynamicModule("MyModule");
+        TypeBuilder tb = mob.DefineType("MyType", TypeAttributes.Public | TypeAttributes.Class);
+        MethodBuilder meb = tb.DefineMethod("SumMethod", MethodAttributes.Public | MethodAttributes.Static,
+                                                             typeof(int), new Type[] { typeof(int), typeof(int) });
+        ILGenerator il = meb.GetILGenerator();
+        il.Emit(OpCodes.Ldarg_0);
+        il.Emit(OpCodes.Ldarg_1);
+        il.Emit(OpCodes.Add);
+        il.Emit(OpCodes.Ret);
+
+        tb.CreateType();
+
+        using var stream = new MemoryStream();
+        ab.Save(stream);  // or pass filename to save into a file
+        stream.Seek(0, SeekOrigin.Begin);
+        Assembly assembly = AssemblyLoadContext.Default.LoadFromStream(stream);
+        MethodInfo method = assembly.GetType("MyType").GetMethod("SumMethod");
+        Console.WriteLine(method.Invoke(null, new object[] { 5, 10 }));
+    }
+    // </Snippet1>
+    // <Snippet2>
+    public static void CreatePersistedAssemblyBuilderCoreAssemblyWithMetadataLoadContext(string refAssembliesPath)
+    {
+        PathAssemblyResolver resolver = new PathAssemblyResolver(Directory.GetFiles(refAssembliesPath, "*.dll"));
+        using MetadataLoadContext context = new MetadataLoadContext(resolver);
+        Assembly coreAssembly = context.CoreAssembly;
+        PersistedAssemblyBuilder ab = new PersistedAssemblyBuilder(new AssemblyName("MyDynamicAssembly"), coreAssembly);
+        TypeBuilder typeBuilder = ab.DefineDynamicModule("MyModule").DefineType("Test", TypeAttributes.Public);
+        MethodBuilder methodBuilder = typeBuilder.DefineMethod("Method", MethodAttributes.Public, coreAssembly.GetType(typeof(int).FullName), Type.EmptyTypes);
+        // .. add members and save the assembly
+    }
+    // </Snippet2>
+}

docs/fundamentals/runtime-libraries/snippets/System.Reflection.Emit/PersistedAssemblyBuilder/Overview/csharp/GenerateMetadataSnippets.cs

@@ -0,0 +1,76 @@
+using System;
+using System.IO;
+using System.Reflection;
+using System.Reflection.Emit;
+using System.Reflection.Metadata.Ecma335;
+using System.Reflection.Metadata;
+using System.Reflection.PortableExecutable;
+using System.Resources;
+
+public class SnippetExamples
+{
+   public static void Main()
+   {
+        SetEntryPoint();
+        SetResource();
+   }
+    // <Snippet1>
+    public static void SetEntryPoint()
+    {
+        PersistedAssemblyBuilder ab = new PersistedAssemblyBuilder(new AssemblyName("MyAssembly"), typeof(object).Assembly);
+        TypeBuilder tb = ab.DefineDynamicModule("MyModule").DefineType("MyType", TypeAttributes.Public | TypeAttributes.Class);
+        // ...
+        MethodBuilder entryPoint = tb.DefineMethod("Main", MethodAttributes.HideBySig | MethodAttributes.Public | MethodAttributes.Static);
+        ILGenerator il2 = entryPoint.GetILGenerator();
+        // ...
+        il2.Emit(OpCodes.Ret);
+        tb.CreateType();
+
+        MetadataBuilder metadataBuilder = ab.GenerateMetadata(out BlobBuilder ilStream, out BlobBuilder fieldData);
+        PEHeaderBuilder peHeaderBuilder = new PEHeaderBuilder(imageCharacteristics: Characteristics.ExecutableImage);
+
+        ManagedPEBuilder peBuilder = new ManagedPEBuilder(
+                        header: peHeaderBuilder,
+                        metadataRootBuilder: new MetadataRootBuilder(metadataBuilder),
+                        ilStream: ilStream,
+                        mappedFieldData: fieldData,
+                        entryPoint: MetadataTokens.MethodDefinitionHandle(entryPoint.MetadataToken));
+
+        BlobBuilder peBlob = new BlobBuilder();
+        peBuilder.Serialize(peBlob);
+
+        // in case saving to a file:
+        using var fileStream = new FileStream("MyAssembly.exe", FileMode.Create, FileAccess.Write);
+        peBlob.WriteContentTo(fileStream);
+    }
+    // </Snippet1>
+    // <Snippet2>
+    public static void SetResource()
+    {
+        PersistedAssemblyBuilder ab = new PersistedAssemblyBuilder(new AssemblyName("MyAssembly"), typeof(object).Assembly);
+        ab.DefineDynamicModule("MyModule");
+        MetadataBuilder metadata = ab.GenerateMetadata(out BlobBuilder ilStream, out _);
+
+        using MemoryStream stream = new MemoryStream();
+        ResourceWriter myResourceWriter = new ResourceWriter(stream);
+        myResourceWriter.AddResource("AddResource 1", "First added resource");
+        myResourceWriter.AddResource("AddResource 2", "Second added resource");
+        myResourceWriter.AddResource("AddResource 3", "Third added resource");
+        myResourceWriter.Close();
+        BlobBuilder resourceBlob = new BlobBuilder();
+        resourceBlob.WriteBytes(stream.ToArray());
+        metadata.AddManifestResource(ManifestResourceAttributes.Public, metadata.GetOrAddString("MyResource"), default, (uint)resourceBlob.Count);
+
+        ManagedPEBuilder peBuilder = new ManagedPEBuilder(
+                        header: new PEHeaderBuilder(imageCharacteristics: Characteristics.ExecutableImage | Characteristics.Dll),
+                        metadataRootBuilder: new MetadataRootBuilder(metadata),
+                        ilStream: ilStream,
+                        managedResources: resourceBlob);
+
+        BlobBuilder blob = new BlobBuilder();
+        peBuilder.Serialize(blob);
+        using var fileStream = new FileStream("MyAssemblyWithResource.dll", FileMode.Create, FileAccess.Write);
+        blob.WriteContentTo(fileStream);
+    }
+    // </Snippet2>
+}

docs/fundamentals/runtime-libraries/snippets/System.Reflection.Emit/PersistedAssemblyBuilder/Overview/csharp/Project.csproj

@@ -0,0 +1,11 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Library</OutputType>
+    <TargetFrameworks>net9</TargetFrameworks>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="System.Reflection.MetadataLoadContext" Version="8.0.0" />
+  </ItemGroup>
+ </Project>

docs/fundamentals/runtime-libraries/system-reflection-emit-assemblybuilder.md

@@ -7,7 +7,7 @@ ms.date: 12/31/2023
 
 [!INCLUDE [context](includes/context.md)]
 
-A dynamic assembly is an assembly that is created using the Reflection Emit APIs. A dynamic assembly can reference types defined in another dynamic or static assembly. You can use <xref:System.Reflection.Emit.AssemblyBuilder> to generate dynamic assemblies in memory and execute their code during the same application run. In .NET 9 we added a new `PersistedAssemblyBuilder` with fully managed implementation of reflection emit that allows you save the assembly into a file. In .NET Framework, you can do both&mdash;run the dynamic assembly and save it to a file. The dynamic assembly created for saving is called a *persisted* assembly, while the regular memory-only assembly is called *transient* or *runnable*. In .NET Framework, a dynamic assembly can consist of one or more dynamic modules. In .NET Core and .NET 5+, a dynamic assembly can only consist of one dynamic module.
+A dynamic assembly is an assembly that is created using the Reflection Emit APIs. A dynamic assembly can reference types defined in another dynamic or static assembly. You can use <xref:System.Reflection.Emit.AssemblyBuilder> to generate dynamic assemblies in memory and execute their code during the same application run. In .NET 9 we added a new [PersistedAssemblyBuilder](system-reflection-emit-persistedassemblybuilder.md)  with fully managed implementation of reflection emit that allows you save the assembly into a file. In .NET Framework, you can do both&mdash;run the dynamic assembly and save it to a file. The dynamic assembly created for saving is called a *persisted* assembly, while the regular memory-only assembly is called *transient* or *runnable*. In .NET Framework, a dynamic assembly can consist of one or more dynamic modules. In .NET Core and .NET 5+, a dynamic assembly can only consist of one dynamic module.
 
 The way you create an <xref:System.Reflection.Emit.AssemblyBuilder> instance differs for each implementation, but further steps for defining a module, type, method, or enum, and for writing IL, are quite similar.
 
@@ -51,80 +51,7 @@ public void CreateAndRunAssembly(string assemblyPath)
 
 ## Persisted dynamic assemblies in .NET
 
-The <xref:System.Reflection.Emit.AssemblyBuilder.Save%2A?displayProperty=nameWithType> API wasn't originally ported to .NET (Core) because the implementation depended heavily on Windows-specific native code that also wasn't ported. In .NET 9 we added a fully managed `Reflection.Emit` implementation that supports saving. This implementation has no dependency on the pre-existing, runtime-specific `Reflection.Emit` implementation. That is, now there are two different implementations in .NET, runnable and persisted. To run the persisted assembly, first save it into a memory stream or a file, then load it back. Before `PersistedAssemblyBuilder`, because you could only run a generated assembly and not save it, it was difficult to debug these in-memory assemblies. Advantages of saving a dynamic assembly to a file are:
-
-- You can verify the generated assembly with tools such as ILVerify, or decompile and manually examine it with tools such as ILSpy.
-- The saved assembly can be loaded directly, no need to compile again, which can decrease application startup time.
-
-To create a `PersistedAssemblyBuilder` instance, use the `public PersistedAssemblyBuilder(AssemblyName name, Assembly coreAssembly, IEnumerable<CustomAttributeBuilder>? assemblyAttributes = null)` constructor. The `coreAssembly` parameter is used to resolve base runtime types and can be used for resolving reference assembly versioning:
-
-- If `Reflection.Emit` is used to generate an assembly that targets a specific TFM, open the reference assemblies for the given TFM using `MetadataLoadContext` and use the value of the [MetadataLoadContext.CoreAssembly](xref:System.Reflection.MetadataLoadContext.CoreAssembly) property for `coreAssembly`. This value allows the generator to run on one .NET runtime version and target a different .NET runtime version.
-
-- If `Reflection.Emit` is used to generate an assembly that's only going to be executed on the same runtime version as the runtime version that the compiler is running on (typically in-proc), the core assembly can be `typeof(object).Assembly`. The reference assemblies aren't necessary in this case.
-
-The following example demonstrates how to create and save an assembly to a stream and run it:
-
-```csharp
-public void CreateSaveAndRunAssembly(string assemblyPath)
-{
-    PersistedAssemblyBuilder ab = new PersistedAssemblyBuilder(new AssemblyName("MyAssembly"), typeof(object).Assembly);
-    ModuleBuilder mob = ab.DefineDynamicModule("MyModule");
-    TypeBuilder tb = mob.DefineType("MyType", TypeAttributes.Public | TypeAttributes.Class);
-    MethodBuilder meb = tb.DefineMethod("SumMethod", MethodAttributes.Public | MethodAttributes.Static,
-                                                                   typeof(int), new Type[] {typeof(int), typeof(int)});
-    ILGenerator il = meb.GetILGenerator();
-    il.Emit(OpCodes.Ldarg_0);
-    il.Emit(OpCodes.Ldarg_1);
-    il.Emit(OpCodes.Add);
-    il.Emit(OpCodes.Ret);
-
-    tb.CreateType();
-
-    using var stream = new MemoryStream();
-    ab.Save(stream);  // or pass filename to save into a file
-    stream.Seek(0, SeekOrigin.Begin);
-    Assembly assembly = AssemblyLoadContext.Default.LoadFromStream(stream);
-    MethodInfo method = assembly.GetType("MyType").GetMethod("SumMethod");
-    Console.WriteLine(method.Invoke(null, new object[] { 5, 10 }));
-}
-```
-
-In order to set entry point for an executable and/or set other options for the assembly file you could to call the `public MetadataBuilder GenerateMetadata(out BlobBuilder ilStream, out BlobBuilder mappedFieldData)` method and use the populated metadata for generating the assembly with desired the options, for example:
-
-```csharp
-PersistedAssemblyBuilder ab = new PersistedAssemblyBuilder(new AssemblyName("MyAssembly"), typeof(object).Assembly);
-TypeBuilder tb = ab.DefineDynamicModule("MyModule").DefineType("MyType", TypeAttributes.Public | TypeAttributes.Class);
-// ...
-MethodBuilder entryPoint = tb.DefineMethod("Main", MethodAttributes.HideBySig | MethodAttributes.Public | MethodAttributes.Static);
-ILGenerator il2 = entryPoint.GetILGenerator();
-// ...
-il2.Emit(OpCodes.Ret);
-tb.CreateType();
-
-MetadataBuilder metadataBuilder = ab.GenerateMetadata(out BlobBuilder ilStream, out BlobBuilder fieldData);
-PEHeaderBuilder peHeaderBuilder = new PEHeaderBuilder(imageCharacteristics: Characteristics.ExecutableImage);
-
-ManagedPEBuilder peBuilder = new ManagedPEBuilder(
-                header: peHeaderBuilder,
-                metadataRootBuilder: new MetadataRootBuilder(metadataBuilder),
-                ilStream: ilStream,
-                mappedFieldData: fieldData,
-                entryPoint: MetadataTokens.MethodDefinitionHandle(entryPoint.MetadataToken));
-
-BlobBuilder peBlob = new BlobBuilder();
-peBuilder.Serialize(peBlob);
-
-// in case saving to a file:
-using var fileStream = new FileStream("MyAssembly.exe", FileMode.Create, FileAccess.Write);
-peBlob.WriteContentTo(fileStream); 
-```
-
-> [!NOTE]
-> The metadata tokens for all members are populated on the <xref:System.Reflection.Emit.AssemblyBuilder.Save%2A> operation. Don't use the tokens of a generated type and its members before saving, as they'll have default values or throw exceptions. It's safe to use tokens for types that are referenced, not generated.
->
-> Some APIs that aren't important for emitting an assembly aren't implemented; for example, `GetCustomAttributes()` is not implemented. With the runtime implementation, you were able to use those APIs after creating the type. For the persisted `AssemblyBuilder`, they throw `NotSupportedException` or `NotImplementedException`. If you have a scenario that requires those APIs, file an issue in the [dotnet/runtime repo](https://github.com/dotnet/runtime).
-
-For an alternative way to generate assembly files, see <xref:System.Reflection.Metadata.Ecma335.MetadataBuilder>.
+The new <xref:System.Reflection.Emit.PersistedAssemblyBuilder> type derived from the <xref:System.Reflection.Emit.AssemblyBuilder> and allows save the dynamic assemblies in .NET Core, check the usage scenarios and examples from [PersistedAssemblyBuilder](system-reflection-emit-persistedassemblybuilder.md) page.
 
 ## Persisted dynamic assemblies in .NET Framework