Update to Roslyn 5.3.0

Author: AndriySvyryd

ThreatDragonModels/New Threat Model/New Threat Model.json

@@ -8,8 +8,15 @@
 
 namespace CSharpScriptSerialization
 {
+    /// <summary>
+    ///     Serializes arrays (including multi-dimensional and jagged arrays) as C# array creation expressions.
+    /// </summary>
     public class ArrayCSScriptSerializer : CSScriptSerializer
     {
+        /// <summary>
+        ///     Creates a new instance of <see cref="ArrayCSScriptSerializer"/> for the given array type.
+        /// </summary>
+        /// <param name="type">The array <see cref="System.Type"/> to serialize.</param>
         public ArrayCSScriptSerializer(Type type)
             : base(type)
         {

src/CSharpScriptSerializer/ArrayCSScriptSerializer.cs

@@ -17,11 +17,24 @@
 
 namespace CSharpScriptSerialization
 {
+    /// <summary>
+    ///     Abstract base class for all C# script serializers. Provides static factory methods to
+    ///     <see cref="Serialize">serialize</see> .NET objects to C# script strings and
+    ///     <see cref="DeserializeAsync{T}(string)">deserialize</see> them back by evaluating the script.
+    /// </summary>
     public abstract class CSScriptSerializer : ICSScriptSerializer
     {
+        /// <summary>
+        ///     A list of <see cref="ICSScriptSerializerFactory"/> instances consulted in order when no serializer
+        ///     is found in <see cref="Serializers"/> for a given type. Add factories here to support additional types.
+        /// </summary>
         public static readonly List<ICSScriptSerializerFactory> SerializerFactories =
             new List<ICSScriptSerializerFactory>();
 
+        /// <summary>
+        ///     A cache of <see cref="ICSScriptSerializer"/> instances keyed by <see cref="System.Type"/>.
+        ///     Pre-populate entries here to override the default serializer for specific types.
+        /// </summary>
         public static readonly ConcurrentDictionary<Type, ICSScriptSerializer> Serializers =
             new ConcurrentDictionary<Type, ICSScriptSerializer>();
 
@@ -30,19 +43,49 @@ public abstract class CSScriptSerializer : ICSScriptSerializer
 
         protected CSScriptSerializer(Type type) => Type = type;
 
+        /// <summary>
+        ///     Gets the CLR <see cref="System.Type"/> this serializer handles.
+        /// </summary>
         public Type Type { get; }
 
+        /// <inheritdoc/>
         public abstract ExpressionSyntax GetCreation(object obj);
 
+        /// <summary>
+        ///     Evaluates a C# script string and returns the result as <typeparamref name="T"/>.
+        /// </summary>
+        /// <typeparam name="T">The expected type of the evaluated result.</typeparam>
+        /// <param name="script">The C# script to evaluate.</param>
         public static T Deserialize<T>(string script) => DeserializeAsync<T>(script).GetAwaiter().GetResult();
 
+        /// <summary>
+        ///     Asynchronously evaluates a C# script string and returns the result as <typeparamref name="T"/>.
+        /// </summary>
+        /// <typeparam name="T">The expected type of the evaluated result.</typeparam>
+        /// <param name="script">The C# script to evaluate.</param>
         public static Task<T> DeserializeAsync<T>(string script)
             => DeserializeAsync<T>(script, Enumerable.Empty<Assembly>(), Enumerable.Empty<string>());
 
+        /// <summary>
+        ///     Evaluates a C# script string with additional assembly references and namespace imports,
+        ///     and returns the result as <typeparamref name="T"/>.
+        /// </summary>
+        /// <typeparam name="T">The expected type of the evaluated result.</typeparam>
+        /// <param name="script">The C# script to evaluate.</param>
+        /// <param name="referencedAssemblies">Additional assemblies to reference during evaluation.</param>
+        /// <param name="imports">Additional namespaces to import during evaluation.</param>
         public static T Deserialize<T>(string script, IEnumerable<Assembly> referencedAssemblies,
             IEnumerable<string> imports)
             => DeserializeAsync<T>(script, referencedAssemblies, imports).GetAwaiter().GetResult();
 
+        /// <summary>
+        ///     Asynchronously evaluates a C# script string with additional assembly references and namespace imports,
+        ///     and returns the result as <typeparamref name="T"/>.
+        /// </summary>
+        /// <typeparam name="T">The expected type of the evaluated result.</typeparam>
+        /// <param name="script">The C# script to evaluate.</param>
+        /// <param name="referencedAssemblies">Additional assemblies to reference during evaluation.</param>
+        /// <param name="imports">Additional namespaces to import during evaluation.</param>
         public static Task<T> DeserializeAsync<T>(
             string script, IEnumerable<Assembly> referencedAssemblies, IEnumerable<string> imports)
             => CSharpScript.EvaluateAsync<T>(script,
@@ -60,6 +103,15 @@ public static Task<T> DeserializeAsync<T>(
                         typeof(List<>).GetTypeInfo().Namespace)
                     .AddImports(imports));
 
+        /// <summary>
+        ///     Serializes <paramref name="obj"/> to a formatted C# script string.
+        /// </summary>
+        /// <param name="obj">The object to serialize.</param>
+        /// <param name="applyFormattingOptions">
+        ///     An optional delegate to customize the Roslyn formatting options applied to the output.
+        ///     When <see langword="null"/>, a sensible default set of options is used.
+        /// </param>
+        /// <returns>A C# script string that, when evaluated, recreates <paramref name="obj"/>.</returns>
         public static string Serialize(object obj, Func<OptionSet, OptionSet> applyFormattingOptions = null)
         {
             using (var workspace = new AdhocWorkspace())
@@ -79,13 +131,22 @@ public static string Serialize(object obj, Func<OptionSet, OptionSet> applyForma
             }
         }
 
+        /// <summary>
+        ///     Returns the full Roslyn <see cref="CompilationUnitSyntax"/> that wraps the creation expression for
+        ///     <paramref name="obj"/> as a top-level global statement.
+        /// </summary>
+        /// <param name="obj">The object to serialize.</param>
         public static CompilationUnitSyntax GetCompilationUnitExpression(object obj) => CompilationUnit()
             .WithMembers(
                 SingletonList<MemberDeclarationSyntax>(
                     GlobalStatement(
                         ExpressionStatement(GetCreationExpression(obj))
                             .WithSemicolonToken(MissingToken(SyntaxKind.SemicolonToken)))));
 
+        /// <summary>
+        ///     Returns the Roslyn <see cref="ExpressionSyntax"/> that represents the creation of <paramref name="obj"/>.
+        /// </summary>
+        /// <param name="obj">The object to serialize.</param>
         public static ExpressionSyntax GetCreationExpression(object obj) => GetSerializer(obj).GetCreation(obj);
 
         private static ICSScriptSerializer GetSerializer(object obj)

src/CSharpScriptSerializer/CSScriptSerializer.cs

@@ -5,16 +5,17 @@
     <PackageId>CSharpScriptSerializer</PackageId>
     <AssemblyTitle>CSharpScriptSerializer</AssemblyTitle>
     <Title>CSharpScriptSerializer</Title>
-    <VersionPrefix>3.0.4</VersionPrefix>
+    <VersionPrefix>4.0.0</VersionPrefix>
     <TargetFrameworks>netstandard2.1</TargetFrameworks>
-    <NetStandardImplicitPackageVersion>2.0.3</NetStandardImplicitPackageVersion>
     <TreatWarningsAsErrors>True</TreatWarningsAsErrors>
     <GenerateAssemblyProductAttribute>false</GenerateAssemblyProductAttribute>
     <Description>Serialize objects to C# scripts</Description>
     <Authors>Andriy Svyryd</Authors>
     <PackageTags>Roslyn;CSharp;C#;CSX;Script;Serialization</PackageTags>
     <PackageReleaseNotes>
       <![CDATA[
+Version 4.0.0
+* Update to Roslyn V5.3.0
 Version 3.0.4
 * Simplify empty object initializers
 Version 3.0.3
@@ -46,8 +47,8 @@ Version 1.4.0
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Scripting" Version="4.2.0" />
-    <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.2.0" />
+    <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Scripting" Version="5.3.0" />
+    <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="5.3.0" />
   </ItemGroup>
 
 </Project>

src/CSharpScriptSerializer/CSharpScriptSerializer.csproj

@@ -7,35 +7,78 @@
 
 namespace CSharpScriptSerialization
 {
+    /// <summary>
+    ///     Serializes a collection of type <typeparamref name="T"/> as a constructor invocation with
+    ///     a collection initializer expression.
+    /// </summary>
+    /// <typeparam name="T">The collection type to serialize.</typeparam>
     public class CollectionCSScriptSerializer<T> : ConstructorCSScriptSerializer<T>
     {
         private readonly IReadOnlyCollection<Func<object, object>> _elementDecomposers;
         private readonly Func<T, IEnumerable<object>> _getEnumerable;
 
+        /// <summary>
+        ///     Creates a new instance of <see cref="CollectionCSScriptSerializer{T}"/> that serializes each element
+        ///     directly, with no constructor arguments and using <see cref="System.Collections.IEnumerable"/> to enumerate.
+        /// </summary>
         public CollectionCSScriptSerializer()
             : this(elementDecomposers: null, constructorParameterGetters: null)
         {
         }
 
+        /// <summary>
+        ///     Creates a new instance of <see cref="CollectionCSScriptSerializer{T}"/> with custom element decomposers.
+        /// </summary>
+        /// <param name="elementDecomposers">
+        ///     Functions that decompose each element into sub-values for a complex collection initializer entry
+        ///     (e.g., key and value for a dictionary). Pass <see langword="null"/> or empty to serialize each element directly.
+        /// </param>
         public CollectionCSScriptSerializer(
             IReadOnlyCollection<Func<object, object>> elementDecomposers)
             : this(elementDecomposers, constructorParameterGetters: null)
         {
         }
 
+        /// <summary>
+        ///     Creates a new instance of <see cref="CollectionCSScriptSerializer{T}"/> with strongly-typed constructor
+        ///     parameter getters.
+        /// </summary>
+        /// <param name="constructorParameterGetters">
+        ///     Getters for values passed as positional constructor arguments when creating <typeparamref name="T"/>.
+        /// </param>
         public CollectionCSScriptSerializer(
             IReadOnlyCollection<Func<T, object>> constructorParameterGetters)
             : this(elementDecomposers: null, constructorParameterGetters: constructorParameterGetters)
         {
         }
 
+        /// <summary>
+        ///     Creates a new instance of <see cref="CollectionCSScriptSerializer{T}"/> with element decomposers
+        ///     and a non-generic enumerable getter.
+        /// </summary>
+        /// <param name="elementDecomposers">
+        ///     Functions that decompose each element into sub-values for a complex collection initializer entry.
+        /// </param>
+        /// <param name="getEnumerable">
+        ///     A function that extracts the sequence of elements from an instance of <typeparamref name="T"/>.
+        /// </param>
         public CollectionCSScriptSerializer(
             IReadOnlyCollection<Func<object, object>> elementDecomposers,
             Func<object, IEnumerable<object>> getEnumerable)
             : this(elementDecomposers, nonGenericParameterGetters: null, nonGenericGetEnumerable: getEnumerable)
         {
         }
 
+        /// <summary>
+        ///     Creates a new instance of <see cref="CollectionCSScriptSerializer{T}"/> with strongly-typed constructor
+        ///     parameter getters and an enumerable getter.
+        /// </summary>
+        /// <param name="constructorParameterGetters">
+        ///     Getters for values passed as positional constructor arguments when creating <typeparamref name="T"/>.
+        /// </param>
+        /// <param name="getEnumerable">
+        ///     A function that extracts the sequence of elements from an instance of <typeparamref name="T"/>.
+        /// </param>
         public CollectionCSScriptSerializer(
             IReadOnlyCollection<Func<T, object>> constructorParameterGetters,
             Func<T, IEnumerable<object>> getEnumerable)
@@ -46,13 +89,33 @@ public CollectionCSScriptSerializer(
         {
         }
 
+        /// <summary>
+        ///     Creates a new instance of <see cref="CollectionCSScriptSerializer{T}"/> with element decomposers
+        ///     and non-generic constructor parameter getters.
+        /// </summary>
+        /// <param name="elementDecomposers">
+        ///     Functions that decompose each element into sub-values for a complex collection initializer entry.
+        /// </param>
+        /// <param name="nonGenericParameterGetters">
+        ///     Non-generic getters for values passed as positional constructor arguments.
+        /// </param>
         public CollectionCSScriptSerializer(
             IReadOnlyCollection<Func<object, object>> elementDecomposers,
             IReadOnlyCollection<Func<object, object>> nonGenericParameterGetters)
             : this(elementDecomposers, nonGenericParameterGetters, nonGenericGetEnumerable: null)
         {
         }
 
+        /// <summary>
+        ///     Creates a new instance of <see cref="CollectionCSScriptSerializer{T}"/> with element decomposers
+        ///     and strongly-typed constructor parameter getters.
+        /// </summary>
+        /// <param name="elementDecomposers">
+        ///     Functions that decompose each element into sub-values for a complex collection initializer entry.
+        /// </param>
+        /// <param name="constructorParameterGetters">
+        ///     Getters for values passed as positional constructor arguments when creating <typeparamref name="T"/>.
+        /// </param>
         public CollectionCSScriptSerializer(
             IReadOnlyCollection<Func<object, object>> elementDecomposers,
             IReadOnlyCollection<Func<T, object>> constructorParameterGetters)

src/CSharpScriptSerializer/CollectionCSScriptSerializer.cs

@@ -6,27 +6,57 @@
 
 namespace CSharpScriptSerialization
 {
+    /// <summary>
+    ///     Serializes objects of type <typeparamref name="T"/> as a constructor invocation expression,
+    ///     passing values derived from the object as positional arguments.
+    /// </summary>
+    /// <typeparam name="T">The type of object to serialize.</typeparam>
     public class ConstructorCSScriptSerializer<T> : CSScriptSerializer
     {
         private readonly IReadOnlyCollection<Func<T, object>> _constructorParameterGetters;
         private ObjectCreationExpressionSyntax _objectCreationExpression;
 
+        /// <summary>
+        ///     Creates a new instance of <see cref="ConstructorCSScriptSerializer{T}"/> that emits a
+        ///     no-argument constructor call.
+        /// </summary>
         public ConstructorCSScriptSerializer()
             : this(constructorParameterGetters: null)
         {
         }
 
+        /// <summary>
+        ///     Creates a new instance of <see cref="ConstructorCSScriptSerializer{T}"/> using non-generic
+        ///     parameter getters.
+        /// </summary>
+        /// <param name="nonGenericParameterGetters">
+        ///     Functions that accept the object as <see cref="object"/> and return the value for each
+        ///     positional constructor argument.
+        /// </param>
         public ConstructorCSScriptSerializer(IReadOnlyCollection<Func<object, object>> nonGenericParameterGetters)
             : this(nonGenericParameterGetters
                 .Select<Func<object, object>, Func<T, object>>(g => o => g(o)).ToArray())
         {
         }
 
+        /// <summary>
+        ///     Creates a new instance of <see cref="ConstructorCSScriptSerializer{T}"/> using strongly-typed
+        ///     parameter getters.
+        /// </summary>
+        /// <param name="constructorParameterGetters">
+        ///     Getters for values passed as positional constructor arguments when creating <typeparamref name="T"/>.
+        ///     Pass <see langword="null"/> or an empty collection to emit a no-argument constructor call.
+        /// </param>
         public ConstructorCSScriptSerializer(IReadOnlyCollection<Func<T, object>> constructorParameterGetters)
             : base(typeof(T)) => _constructorParameterGetters = constructorParameterGetters;
 
+        /// <summary>
+        ///     Gets a value indicating whether to emit an empty argument list <c>()</c> when no constructor
+        ///     parameters are provided. Defaults to <see langword="true"/>.
+        /// </summary>
         protected virtual bool GenerateEmptyArgumentList => true;
 
+        /// <inheritdoc/>
         public override ExpressionSyntax GetCreation(object obj) => GetObjectCreationExpression((T)obj);
 
         protected virtual ObjectCreationExpressionSyntax GetObjectCreationExpression(T obj)

src/CSharpScriptSerializer/ConstructorCSScriptSerializer.cs

@@ -6,8 +6,16 @@
 
 namespace CSharpScriptSerialization
 {
+    /// <summary>
+    ///     Serializes enum values as member-access expressions (e.g., <c>MyEnum.Value</c>).
+    ///     Composite flag values are represented as bitwise-OR combinations of their constituent members.
+    /// </summary>
     public class EnumCSScriptSerializer : CSScriptSerializer
     {
+        /// <summary>
+        ///     Creates a new instance of <see cref="EnumCSScriptSerializer"/> for the given enum type.
+        /// </summary>
+        /// <param name="type">The enum <see cref="System.Type"/> to serialize.</param>
         public EnumCSScriptSerializer(Type type)
             : base(type)
         {

src/CSharpScriptSerializer/EnumCSScriptSerializer.cs

@@ -3,8 +3,14 @@
 
 namespace CSharpScriptSerialization
 {
+    /// <summary>
+    ///     Serializes <see langword="false"/> as the <c>false</c> literal expression.
+    /// </summary>
     public class FalseCSScriptSerializer : CSScriptSerializer
     {
+        /// <summary>
+        ///     The singleton instance of <see cref="FalseCSScriptSerializer"/>.
+        /// </summary>
         public static readonly FalseCSScriptSerializer Instance = new FalseCSScriptSerializer();
 
         private FalseCSScriptSerializer()

src/CSharpScriptSerializer/FalseCSScriptSerializer.cs

@@ -1,7 +1,14 @@
 namespace CSharpScriptSerialization
 {
+    /// <summary>
+    ///     Allows a type to supply its own <see cref="ICSScriptSerializer"/> instead of relying on
+    ///     the default serializer discovery logic in <see cref="CSScriptSerializer"/>.
+    /// </summary>
     public interface ICSScriptSerializable
     {
+        /// <summary>
+        ///     Returns the <see cref="ICSScriptSerializer"/> to use when serializing this object.
+        /// </summary>
         ICSScriptSerializer GetSerializer();
     }
 }