[API Proposal] Add persist able AssemblyBuilder implementation

[buyaa-n]

Contributes to Support equivalent of AssemblyBuilder.Save to save in-memory IL to an assembly

As per #62956 we plan to a add managed implementation of AssemblyBuilder that could save in-memory IL to an assembly file/stream.

Proposed design 1

Initial version would only support Save, no Run, therefore the factory method not accepting AssemblyBuilderAccess that defines the access mode for the assembly. It is the current prototype design.

namespace System.Reflection.Emit
{
+    public sealed class AssemblyFileBuilder : AssemblyBuilder
+    {
+        internal AssemblyFileBuilder(AssemblyName name, IEnumerable<CustomAttributeBuilder>? assemblyAttributes) { }

         // New static methods without AssemblyBuilderAccess, because initial version will only support Save
+        public static AssemblyFileBuilder DefineDynamicAssembly(AssemblyName name) { throw null; }
+        public static AssemblyFileBuilder DefineDynamicAssembly(AssemblyName name, Enumerable<CustomAttributeBuilder>? assemblyAttributes) { throw null; }
	
        // New instance methods
+        public void Save(Stream stream) { }
+        public void Save(string assemblyFileName) { } // same as in .NET Framework
+    }
}

Usage example

using System.Reflection.Emit;

public class MyType
{
    public void MyMethod(AssemblyName assemblyName, string fileName)
    {
	AssemblyFileBuilder builder = AssemblyFileBuilder.DefineDynamicAssembly(assemblyName);
	// ... Add module and other members 
	builder.Save(fileName);
    }
}

Alternative design 2:

The new persisted AssemblyBuilder type implementation will not exposed, instead we add Save into the abstract class AssemblyBuilder and protected abstract SaveCore method for implementation. Use the same factory method for creating AssemblyBuilder. This need for using reflection in order to create persisted AssemblyBuilder.

namespace System.Reflection.Emit
{
    public abstract class AssemblyBuilder : Assembly
    {
+        public void Save(Stream stream) { }
+        public void Save(string assemblyFileName) { }
+        protected abstract void SaveCore(Stream stream);
    }

    [Flags]
    public enum AssemblyBuilderAccess
    {
        Run = 1,
+	Save = 2,
        RunAndCollect = 8 | Run,
    }
}

Usage example

using System.Reflection.Emit;

public class MyType
{
    public void MyMethod(AssemblyName assemblyName, string fileName)
    {
	AssemblyBuilder builder = AssemblyBuilder.DefineDynamicAssembly(assemblyName, AssemblyBuilderAccess.Save);
	// ... Add module and other members 
	builder.Save(fileName);
    }
}

Alternative design 3:

Comment by @jkotas for above Alternative design 2:

• Supporting both the runtime and persisted assemblies through the same API creates a choke-point for trimming and AOT. Save mode that somebody may want to use to build a compiler is compatible with trimming and AOT. The dynamic time mode is not compatible with AOT, and brings in additional runtime support. We should have two distinct APIs for the dynamic and persistent modes.
• The core assembly should be passed in as Assembly to avoid ambiguity about what kind of name it is.

With these two points incorporated, the design would be:

 class AssemblyBuilder
 {
     // Existing APIs
     [RequiresDynamicCode("Defining a dynamic assembly requires dynamic code.")]
     public static AssemblyBuilder DefineDynamicAssembly(AssemblyName name, AssemblyBuilderAccess access);
     [RequiresDynamicCode("Defining a dynamic assembly requires dynamic code.")]
     public static AssemblyBuilder DefineDynamicAssembly(AssemblyName name, AssemblyBuilderAccess access, System.Collections.Generic.IEnumerable<CustomAttributeBuilder>? assemblyAttributes);

+    // New API - note that it does not have RequiresDynamicCode annotation
+    public static AssemblyBuilder DefinePersistedAssembly(AssemblyName name, Assembly coreAssembly, IEnumerable<CustomAttributeBuilder>? assemblyAttributes = null);

+    public void Save(Stream stream) { }
+    public void Save(string assemblyFileName) { } // same as in .NET Framework
+    protected abstract void SaveCore(Stream stream);
 }

AssemblyBuilderAccess is not used in this design because it will only support "Save" initially and eventually we allow Run without requiring to specify Save/Run explicitly.

Usage example

using System.Reflection.Emit;

public class MyType
{
    public void MyMethod(AssemblyName assemblyName, string fileName)
    {
	AssemblyBuilder builder = AssemblyBuilder.DefinePersistedAssembly(assemblyName, AssemblyBuilderAccess.Save);
	// ... Add module and other members 
	builder.Save(fileName);
    }
}

Tagging subscribers to this area: @dotnet/area-system-reflection
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Contributes to Support equivalent of AssemblyBuilder.Save to save in-memory IL to an assembly

As per #62956 we plan to a add managed implementation of AssemblyBuilder that could save in-memory IL to an assembly file/stream.

Initial version would only support Save, no Run, therefore the factory method not accepting AssemblyBuilderAccess that defines the access mode for the assembly.

namespace System.Reflection.Emit
{
+    public sealed class PersistableAssemblyBuilder : AssemblyBuilder
+    {
+        internal PersistableAssemblyBuilder (AssemblyName name, IEnumerable<CustomAttributeBuilder>? assemblyAttributes) { }

         // New static methods without AssemblyBuilderAccess, because initial version will only support Save
+        public static PersistableAssemblyBuilder DefineDynamicAssembly(AssemblyName name) { throw null; }
+        public static PersistableAssemblyBuilder DefineDynamicAssembly(AssemblyName name, Enumerable<CustomAttributeBuilder>? assemblyAttributes) { throw null; }
	
        // New instance methods
+        public void Save(Stream stream) { }
+        public void Save(string assemblyFileName) { } // same as in .NET Framework
+    }
}

Usage example

using System.Reflection.Emit;

public class MyType
{
    public void MyMethod(AssemblyName assemblyName, string fileName)
    {
	PersistableAssemblyBuilder builder = PersistableAssemblyBuilder.DefineDynamicAssembly(assemblyName);
	// ... Add module and other members 
	builder.Save(fileName);
    }
}

Alternative design

Support for AssemblyBuilderAccess.Run will be added to this type in the future. Therefore we might want to AssemblyBuilderAccess.Save option and use it for existing factory methods.

namespace System.Reflection.Emit
{
+    public sealed class PersistableAssemblyBuilder : AssemblyBuilder
+    {
+        internal PersistableAssemblyBuilder (AssemblyName name, IEnumerable<CustomAttributeBuilder>? assemblyAttributes) { }

+        public static new PersistableAssemblyBuilder DefineDynamicAssembly(AssemblyName name, AssemblyBuilderAccess access) { throw null; }
+        public static new PersistableAssemblyBuilder DefineDynamicAssembly(AssemblyName name, AssemblyBuilderAccess access, Enumerable<CustomAttributeBuilder>? assemblyAttributes) { throw null; }
	
        // New instance methods
+        public void Save(Stream stream) { }
+        public void Save(string assemblyFileName) { } // same as in .NET Framework
+    }

    [Flags]
    public enum AssemblyBuilderAccess
    {
        Run = 1,
+	Save = 2,
        RunAndCollect = 8 | Run,
    }
}

Usage example

using System.Reflection.Emit;

public class MyType
{
    public void MyMethod(AssemblyName assemblyName, string fileName)
    {
	PersistableAssemblyBuilder builder = PersistableAssemblyBuilder.DefineDynamicAssembly(assemblyName, AssemblyBuilderAccess.Save);
	// ... Add module and other members 
	builder.Save(fileName);
    }
}

Author:	buyaa-n
Assignees:	-
Labels:	api-suggestion, area-System.Reflection, untriaged, needs-area-label
Milestone:	-

Tagging subscribers to this area: @dotnet/area-system-reflection-emit
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Contributes to Support equivalent of AssemblyBuilder.Save to save in-memory IL to an assembly

As per #62956 we plan to a add managed implementation of AssemblyBuilder that could save in-memory IL to an assembly file/stream.

Initial version would only support Save, no Run, therefore the factory method not accepting AssemblyBuilderAccess that defines the access mode for the assembly.

namespace System.Reflection.Emit
{
+    public sealed class PersistableAssemblyBuilder : AssemblyBuilder
+    {
+        internal PersistableAssemblyBuilder (AssemblyName name, IEnumerable<CustomAttributeBuilder>? assemblyAttributes) { }

         // New static methods without AssemblyBuilderAccess, because initial version will only support Save
+        public static PersistableAssemblyBuilder DefineDynamicAssembly(AssemblyName name) { throw null; }
+        public static PersistableAssemblyBuilder DefineDynamicAssembly(AssemblyName name, Enumerable<CustomAttributeBuilder>? assemblyAttributes) { throw null; }
	
        // New instance methods
+        public void Save(Stream stream) { }
+        public void Save(string assemblyFileName) { } // same as in .NET Framework
+    }
}

Usage example

using System.Reflection.Emit;

public class MyType
{
    public void MyMethod(AssemblyName assemblyName, string fileName)
    {
	PersistableAssemblyBuilder builder = PersistableAssemblyBuilder.DefineDynamicAssembly(assemblyName);
	// ... Add module and other members 
	builder.Save(fileName);
    }
}

Alternative design

Support for AssemblyBuilderAccess.Run will be added to this type in the future. Therefore we might want to AssemblyBuilderAccess.Save option and use it for existing factory methods.

namespace System.Reflection.Emit
{
+    public sealed class PersistableAssemblyBuilder : AssemblyBuilder
+    {
+        internal PersistableAssemblyBuilder (AssemblyName name, IEnumerable<CustomAttributeBuilder>? assemblyAttributes) { }

+        public static new PersistableAssemblyBuilder DefineDynamicAssembly(AssemblyName name, AssemblyBuilderAccess access) { throw null; }
+        public static new PersistableAssemblyBuilder DefineDynamicAssembly(AssemblyName name, AssemblyBuilderAccess access, Enumerable<CustomAttributeBuilder>? assemblyAttributes) { throw null; }
	
        // New instance methods
+        public void Save(Stream stream) { }
+        public void Save(string assemblyFileName) { } // same as in .NET Framework
+    }

    [Flags]
    public enum AssemblyBuilderAccess
    {
        Run = 1,
+	Save = 2,
        RunAndCollect = 8 | Run,
    }
}

Usage example

using System.Reflection.Emit;

public class MyType
{
    public void MyMethod(AssemblyName assemblyName, string fileName)
    {
	PersistableAssemblyBuilder builder = PersistableAssemblyBuilder.DefineDynamicAssembly(assemblyName, AssemblyBuilderAccess.Save);
	// ... Add module and other members 
	builder.Save(fileName);
    }
}

Author:	buyaa-n
Assignees:	-
Labels:	api-suggestion, area-System.Reflection, area-System.Reflection.Emit, untriaged
Milestone:	-

[jkotas]

Alternative design

Another alternative is add Save methods and abstract SaveCore method on the AssemblyBuilder.

[buyaa-n]

Another alternative is add Save methods and abstract SaveCore method on the AssemblyBuilder.

Are you suggesting adding AssemblyBuilderAccess.Save option and creating appropriate instance of AssemblyBuilder implementation with AssemblyBuilder.DefineDynamicAssembly(assemblyName, AssemblyBuilderAccess.Save);:

namespace System.Reflection.Emit
{
    public abstract class AssemblyBuilder : Assembly
    {
+        public void Save(Stream stream) { }
+        public void Save(string assemblyFileName) { } // same as in .NET Framework
+        protected abstract void SaveCore(Stream stream);
    }

    [Flags]
    public enum AssemblyBuilderAccess
    {
        Run = 1,
+	Save = 2,
        RunAndCollect = 8 | Run,
    }
}

Usage example

using System.Reflection.Emit;

public class MyType
{
    public void MyMethod(AssemblyName assemblyName, string fileName)
    {
	AssemblyBuilder builder = AssemblyBuilder.DefineDynamicAssembly(assemblyName, AssemblyBuilderAccess.Save);
	// ... Add module and other members 
	builder.Save(fileName);
    }
}

The problem with that design is it would need reflection in order to create persist able AssemblyBuilder instance as it will not be added in CoreLib. What you think about this @jkotas?