Sdk10 version

apiCount.include.md

@@ -1 +1 @@
-**API count: 594**
+**API count: 617**

consuming.md

@@ -2,6 +2,11 @@
 
 The default type visibility for all polyfills is `internal`. This means it can be consumed in multiple projects and types will not conflict.
 
+## Recommended consuming pattern
+
+The recommended general way to consume polyfill is to use the source package (`Polyfill`, not `PolyfillLib`), with all types being `internal` (default). As many projects use `InternalsVisibleTo`, this can result in conflicts. To resolve this, specify `<PolyUseEmbeddedAttribute>true</PolyUseEmbeddedAttribute>` under a `PropertyGroup`. That way, every project will have its "embedded" version of the types of Polyfill. Simply put, "embedded" means that even if `InternalsVisibleTo` is used, the "embedded" types are still not visible to the other assemblies.
+
+Alternatively, and depending on your specific scenario, below states other ways to consume Polyfill.
 
 ## Consuming in an app
 
@@ -27,4 +32,3 @@ If, however, `InternalsVisibleTo` is being used to expose APIs (for example to t
 
  * [PolyfillLib](polyfill-lib.md)
  * [Polyfill and TargetFrameworks](target-frameworks.md)
-

contributing.md

@@ -149,6 +149,9 @@ using System.Diagnostics.CodeAnalysis;
 [AttributeUsage(
     validOn: AttributeTargets.Method,
     Inherited = false)]
+#if PolyUseEmbeddedAttribute
+[global::Microsoft.CodeAnalysis.EmbeddedAttribute]
+#endif
 #if PolyPublic
 public
 #endif
@@ -159,7 +162,7 @@ using System.Runtime.CompilerServices;
 [assembly: TypeForwardedTo(typeof(ModuleInitializerAttribute))]
 #endif
 ```
-<sup><a href='/src/Polyfill/ModuleInitializerAttribute.cs#L1-L29' title='Snippet source file'>snippet source</a> | <a href='#snippet-ModuleInitializerAttribute.cs' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/src/Polyfill/ModuleInitializerAttribute.cs#L1-L32' title='Snippet source file'>snippet source</a> | <a href='#snippet-ModuleInitializerAttribute.cs' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 

src/.gitattributes

@@ -7,4 +7,5 @@
 *.verified.json text eol=lf working-tree-encoding=UTF-8
 
 .editorconfig text eol=lf working-tree-encoding=UTF-8
-Shared.sln.DotSettings text eol=lf working-tree-encoding=UTF-8
+*.sln.DotSettings text eol=lf working-tree-encoding=UTF-8
+*.slnx.DotSettings text eol=lf working-tree-encoding=UTF-8

src/ApiBuilderTests/BuildApiTest.cs

@@ -13,40 +13,19 @@ static BuildApiTest()
     [Test]
     public void RunWithRoslyn()
     {
-        var types = ReadFiles();
-
         var md = Path.Combine(solutionDirectory, "..", "api_list.include.md");
         File.Delete(md);
         using var writer = File.CreateText(md);
         var count = 0;
+        count = WriteExtensions(writer, count);
 
-        var extensions = types["Polyfill"];
-        writer.WriteLine("### Extension methods");
-        writer.WriteLine();
-        foreach (var grouping in PublicMethods(extensions)
-                     .GroupBy(_ => _.ParameterList.Parameters[0].Type!.ToString())
-                     .OrderBy(_ => _.Key))
-        {
-            WriteTypeMethods(grouping.Key, writer, ref count, grouping);
-        }
-
-        writer.WriteLine("### Static helpers");
-        writer.WriteLine();
-        foreach (var (key, value) in types
-                     .OrderBy(_ => _.Key)
-                     .Where(_ => _.Key.EndsWith("Polyfill") &&
-                                 _.Key != "Polyfill"))
-        {
-            WriteTypeMethods(key, writer, ref count, value);
-        }
-
-        WriteHelper(types, "Guard", writer, ref count);
-        WriteHelper(types, "Lock", writer, ref count);
-        WriteHelper(types, nameof(KeyValuePair), writer, ref count);
+        WriteHelper("Ensure*", writer, ref count);
+        WriteHelper("Lock", writer, ref count);
+        WriteHelper(nameof(KeyValuePair), writer, ref count);
         WriteType(nameof(TaskCompletionSource), writer, ref count);
         WriteType(nameof(UnreachableException), writer, ref count);
 
-        count += types.Count(_ => _.Key.EndsWith("Attribute"));
+        count += Directory.EnumerateFiles(polyfillDir, "*Attribute.cs", SearchOption.AllDirectories).Count();
         // Index and Range
         count++;
         //Nullability*
@@ -57,37 +36,152 @@ public void RunWithRoslyn()
         File.WriteAllText(countMd, $"**API count: {count}**");
     }
 
-    static IEnumerable<Method> PublicMethods(HashSet<Method> type) =>
-        type.Where(_ => _.IsPublic() &&
-                        !_.IsConstructor())
-            .OrderBy(_ => _.Identifier.ToString());
-
-    static Dictionary<string, HashSet<Method>> ReadFiles()
+    static int WriteExtensions(StreamWriter writer, int count)
     {
-        var types = new Dictionary<string, HashSet<Method>>();
-        var methodComparer = EqualityComparer<Method>
-            .Create(
-                (x, y) => Key(x!) == Key(y!),
-                _ => Key(_).GetHashCode());
-        foreach (var file in Directory.EnumerateFiles(polyfillDir, "*.cs", SearchOption.AllDirectories))
+        var files = Directory.EnumerateFiles(polyfillDir, "*Polyfill*.cs", SearchOption.AllDirectories).ToList();
+
+        var instanceFiles = files
+            .Where(_ => Path.GetFileNameWithoutExtension(_).StartsWith("Polyfill_"))
+            .ToList();
+
+        var staticFiles = files
+            .Where(_ =>
+            {
+                var name = Path.GetFileNameWithoutExtension(_);
+                return name.EndsWith("Polyfill") &&
+                       name != "Polyfill";
+            })
+            .ToList();
+
+        var instanceMethods = ReadMethodsForFiles(instanceFiles);
+
+        var instanceTypeNames = instanceMethods
+            .Select(FirstParameterType);
+
+        var staticTypeNames = staticFiles
+            .Select(Path.GetFileNameWithoutExtension)
+            .Select(_ => _![..^8].ToString());
+
+        var typeNames = instanceTypeNames.Concat(staticTypeNames)
+            .Distinct()
+            .ToList();
+
+        writer.WriteLine("### Extension methods");
+        writer.WriteLine();
+
+        foreach (var name in typeNames.Order())
         {
-            foreach (var type in Identifiers.ReadTypesForFile(file))
+            var instanceMethodsForType = instanceMethods
+                .Where(_ => FirstParameterType(_) == name)
+                .ToList();
+            writer.WriteLine($"#### {name}");
+            writer.WriteLine();
+            if (instanceMethodsForType.Count != 0)
+            {
+                foreach (var method in instanceMethodsForType.OrderBy(Key))
+                {
+                    count++;
+                    WriteSignature(method, writer);
+                }
+            }
+
+            var staticExtension = staticFiles
+                .SingleOrDefault(_ => Path.GetFileNameWithoutExtension(_)[..^8].ToString() == name);
+            if (staticExtension != null)
             {
-                var identifier = type.Identifier.Text;
-                if (!types.TryGetValue(identifier, out var methods))
+                foreach (var method in ReadMethodsForFiles([staticExtension]).OrderBy(Key))
                 {
-                    methods = new(methodComparer);
-                    types.Add(identifier, methods);
+                    count++;
+                    WriteSignature(method, writer);
                 }
 
-                foreach (var method in type.PublicMethods())
+                foreach (var property in ReadPropertiesForFiles([staticExtension]))
                 {
-                    methods.Add(method);
+                    count++;
+                    WriteSignature(property, writer);
                 }
             }
+
+            writer.WriteLine();
+            writer.WriteLine();
+        }
+
+        return count;
+    }
+
+    static Dictionary<string, string> langwordToType = new()
+    {
+        ["bool"] = "Boolean",
+        ["byte"] = "Byte",
+        ["sbyte"] = "SByte",
+        ["char"] = "Char",
+        ["decimal"] = "Decimal",
+        ["double"] = "Double",
+        ["float"] = "Single",
+        ["int"] = "Int32",
+        ["uint"] = "UInt32",
+        ["long"] = "Int64",
+        ["ulong"] = "UInt64",
+        ["object"] = "Object",
+        ["short"] = "Int16",
+        ["ushort"] = "UInt16",
+        ["string"] = "String"
+    };
+
+    static string FirstParameterType(Method method)
+    {
+        var type = method.ParameterList.Parameters[0].Type!.ToString();
+        return langwordToType.GetValueOrDefault(type, type);
+    }
+
+    static List<Method> ReadMethodsForFiles(string pattern)
+    {
+        var files = Directory.EnumerateFiles(polyfillDir, $"{pattern}.cs", SearchOption.AllDirectories);
+        return ReadMethodsForFiles(files);
+    }
+
+    private static List<Method> ReadMethodsForFiles(IEnumerable<string> files)
+    {
+        var types = files
+            .SelectMany(Identifiers.ReadTypesForFile)
+            .ToList();
+
+        var distinctTypes = types.Select(_ => _.Identifier.Text).Distinct().ToList();
+        if (distinctTypes.Count > 1)
+        {
+            throw new(string.Join(", ", distinctTypes));
+        }
+
+        return types
+            .SelectMany(_ => _.PublicMethods())
+            .DistinctBy(Key)
+            .OrderBy(Key)
+            .ToList();
+    }
+
+    static List<Property> ReadPropertiesForFiles(string pattern)
+    {
+        var files = Directory.EnumerateFiles(polyfillDir, $"{pattern}.cs", SearchOption.AllDirectories);
+        return ReadPropertiesForFiles(files);
+    }
+
+    static List<Property> ReadPropertiesForFiles(IEnumerable<string> files)
+    {
+        var types = files
+            .SelectMany(Identifiers.ReadTypesForFile)
+            .ToList();
+
+        var distinctTypes = types.DistinctBy(_ => _.Identifier.Text).ToList();
+        if (distinctTypes.Count > 1)
+        {
+            throw new(string.Join(", ", distinctTypes));
         }
 
-        return types;
+        return types
+            .SelectMany(_ => _.PublicProperties())
+            .DistinctBy(_ => _.Identifier.Text)
+            .OrderBy(_ => _.Identifier.Text)
+            .ToList();
     }
 
     static void WriteType(string name, StreamWriter writer, ref int count)
@@ -100,12 +194,8 @@ static void WriteType(string name, StreamWriter writer, ref int count)
         count++;
     }
 
-    static void WriteHelper(Dictionary<string, HashSet<Method>> types, string name, StreamWriter writer, ref int count)
-    {
-        var methods = types[name];
-
-        WriteTypeMethods(name, writer, ref count, methods.OrderBy(Key));
-    }
+    static void WriteHelper(string name, StreamWriter writer, ref int count) =>
+        WriteTypeMethods(name.Trim('*'), writer, ref count, ReadMethodsForFiles(name));
 
     static void WriteTypeMethods(string name, StreamWriter writer, ref int count, IEnumerable<Method> methods)
     {
@@ -144,6 +234,20 @@ static void WriteSignature(Method method, StreamWriter writer)
         }
     }
 
+    static void WriteSignature(Property method, StreamWriter writer)
+    {
+        var signature = new StringBuilder(method.Identifier.Text);
+
+        if (method.TryGetReference(out var reference))
+        {
+            writer.WriteLine($" * `{signature}` [reference]({reference})");
+        }
+        else
+        {
+            writer.WriteLine($" * `{signature}`");
+        }
+    }
+
     static string Key(Method method) =>
         $"{method.Identifier.Text}{BuildTypeArgs(method)}({BuildParameters(method, false)})";
 
@@ -160,17 +264,16 @@ static string BuildTypeArgs(Method method)
 
     static string BuildParameters(Method method, bool skipThisModified)
     {
-        List<Parameter> parameters;
+        var parameters = method
+            .ParameterList
+            .Parameters
+            .ToList();
+
         if (skipThisModified)
         {
-            parameters = method.ParameterList
-                .Parameters
-                .Where(_ => !_.IsThis()).ToList();
-        }
-        else
-        {
-            parameters = method.ParameterList
-                .Parameters.ToList();
+            parameters = parameters
+                .Where(_ => !_.IsThis())
+                .ToList();
         }
 
         if (parameters.Count > 0)

src/ApiBuilderTests/Identifiers.cs

@@ -27,7 +27,7 @@ public static IEnumerable<Type> ReadTypesForFile(string file)
     [
         "FeatureMemory",
         "FeatureRuntimeInformation",
-        "PolyGuard",
+        "PolyEnsure",
         "PolyPublic",
         "FeatureHttp",
         "PolyNullability",

src/ApiBuilderTests/LinkReader.cs

@@ -1,8 +1,8 @@
 public static class LinkReader
 {
-    public static bool TryGetReference(this Method method, [NotNullWhen(true)] out string? reference)
+    public static bool TryGetReference(this Member member, [NotNullWhen(true)] out string? reference)
     {
-        var syntaxTrivia = method.GetLeadingTrivia();
+        var syntaxTrivia = member.GetLeadingTrivia();
         foreach (var trivia in syntaxTrivia)
         {
             if (!trivia.IsKind(SyntaxKind.SingleLineCommentTrivia))

src/ApiBuilderTests/RoslynExtensions.cs

@@ -20,6 +20,13 @@ public static IEnumerable<Method> PublicMethods(this Type type) =>
                         _.IsPublic() &&
                         !_.IsConstructor());
 
+    public static IEnumerable<Property> PublicProperties(this Type type) =>
+        type
+            .DescendantNodes()
+            .OfType<Property>()
+            .Where(_ => _.Parent == type &&
+                        _.IsPublic());
+
     public static bool IsConstructor(this Method method)
     {
         if (method.Parent is Type type)