[release/9.0] Backport some PACKAGE.md files (#107724)

* Provide System.Composition package readme (#106443) * Provide System.Composition package readme * Fix empty lines * Provide System.Composition.AttributedModel package readme (#106781) * Provide System.Composition.AttributedModel package readme * Improve after feedback * Set correct PackageDescription * Provide System.Composition.Convention package readme (#106782) * Provide System.Composition.Convention package readme * Improve after feedback * Provide System.Composition.Hosting package readme (#106783) * Provide System.Composition.Hosting package readme * Improve after feedback * Provide System.Composition.Runtime package readme (#106784) * Provide System.Composition.Runtime package readme * Improve after feedback * Provide System.Composition.TypedParts package readme (#106785) * Provide System.Composition.TypedParts package readme * Improve after feedback * Provide System.CodeDom package readme (#107372) * Provide System.CodeDom package readme * Add remark about Roslyn/.NET Compiler SDK * Update src/libraries/System.CodeDom/src/PACKAGE.md --------- Co-authored-by: Buyaa Namnan <[email protected]> --------- Co-authored-by: Michaël Hompus <[email protected]>
dotnet · Sep 12, 2024 · bef9c4a · bef9c4a
1 parent a1f25d8
commit bef9c4a
Show file tree

Hide file tree

Showing 14 changed files with 703 additions and 58 deletions.
diff --git a/src/libraries/System.CodeDom/src/PACKAGE.md b/src/libraries/System.CodeDom/src/PACKAGE.md
@@ -0,0 +1,127 @@
+## About
+
+<!-- A description of the package and where one can find more documentation -->
+
+Provides functionality for dynamically generating and compiling source code using the Code Document Object Model (CodeDOM).
+
+It allows developers to represent code in a language-agnostic format and then generate code in multiple languages, such as C# and VB.NET.
+The primary use cases include creating dynamic code generation tools, runtime code generation, and facilitating code analysis or transformation.
+
+For a new modern development consider using the [.NET Compiler Platform SDK](https://learn.microsoft.com/dotnet/csharp/roslyn-sdk/), in particular [Roslyn source generators](https://learn.microsoft.com/dotnet/csharp/roslyn-sdk/source-generators-overview#get-started-with-source-generators).
+
+## Key Features
+
+<!-- The key features of this package -->
+
+* Write code using a common object model that can be translated into multiple programming languages.
+* Generate and compile code at runtime based on the CodeDOM.
+
+## How to Use
+
+<!-- A compelling example on how to use this package with code, as well as any specific guidelines for when to use the package -->
+
+Generating and compiling C# code:
+
+```csharp
+using System.CodeDom;
+using System.CodeDom.Compiler;
+using Microsoft.CSharp;
+
+// Create a new CodeCompileUnit to hold the code
+var compileUnit = new CodeCompileUnit();
+
+// Create a namespace
+var codeNamespace = new CodeNamespace("MyNamespace");
+compileUnit.Namespaces.Add(codeNamespace);
+
+// Create a class
+var classDeclaration = new CodeTypeDeclaration("MyClass")
+{
+    IsClass = true
+};
+codeNamespace.Types.Add(classDeclaration);
+
+// Add a simple method to the class
+var method = new CodeMemberMethod
+{
+    Name = "HelloWorld",
+    ReturnType = new CodeTypeReference(typeof(void)),
+};
+classDeclaration.Members.Add(method);
+
+var methodInvocation = new CodeMethodInvokeExpression(new CodeTypeReferenceExpression("Console"),
+                                                      "WriteLine",
+                                                      new CodePrimitiveExpression("Hello, World!"));
+method.Statements.Add(methodInvocation);
+
+// Generate C# code from the CodeDOM structure
+CodeDomProvider provider = new CSharpCodeProvider();
+
+using (var writer = new StringWriter())
+{
+    var codeGenereationOptions = new CodeGeneratorOptions()
+    {
+        BlankLinesBetweenMembers = false,
+        IndentString = "  ",
+    };
+
+    provider.GenerateCodeFromCompileUnit(compileUnit, writer, codeGenereationOptions);
+    Console.WriteLine(writer.GetStringBuilder().ToString());
+}
+```
+
+This example generates:
+
+```csharp
+//------------------------------------------------------------------------------
+// <auto-generated>
+//     This code was generated by a tool.
+//
+//     Changes to this file may cause incorrect behavior and will be lost if
+//     the code is regenerated.
+// </auto-generated>
+//------------------------------------------------------------------------------
+
+namespace MyNamespace {
+
+  public class MyClass {
+    private void HelloWorld() {
+      Console.WriteLine("Hello, World!");
+    }
+  }
+}
+```
+
+## Main Types
+
+<!-- The main types provided in this library -->
+
+The main types provided by this library are:
+
+* `System.CodeDom.CodeObject`
+* `System.CodeDom.CodeCompileUnit`
+* `System.CodeDom.CodeNamespace`
+* `System.CodeDom.CodeTypeDeclaration`
+* `System.CodeDom.CodeMemberMethod`
+* `System.CodeDom.CodeTypeReference`
+* `System.CodeDom.CodeMethodInvokeExpression`
+* `System.CodeDom.CodeTypeReferenceExpression`
+* `System.CodeDom.CodePrimitiveExpression`
+* `System.CodeDom.Compiler.CodeDomProvider`
+* `System.CodeDom.Compiler.CodeGeneratorOptions`
+* `Microsoft.CSharp.CSharpCodeProvider`
+* `Microsoft.VisualBasic.VBCodeProvider`
+
+## Additional Documentation
+
+<!-- Links to further documentation. Remove conceptual documentation if not available for the library. -->
+
+* [API documentation](https://learn.microsoft.com/dotnet/api/system.codedom)
+* [Compile and generate dynamic source code](https://learn.microsoft.com/dotnet/framework/reflection-and-codedom/dynamic-source-code-generation-and-compilation)
+
+## Feedback & Contributing
+
+<!-- How to provide feedback on this package and contribute to it -->
+
+System.CodeDom is released as open source under the [MIT license](https://licenses.nuget.org/MIT).
+Bug reports and contributions are welcome at [the GitHub repository](https://github.com/dotnet/runtime).
diff --git a/src/libraries/System.CodeDom/src/System.CodeDom.csproj b/src/libraries/System.CodeDom/src/System.CodeDom.csproj
@@ -6,19 +6,11 @@
     <IsTrimmable>false</IsTrimmable>
     <UseCompilerGeneratedDocXmlFile>false</UseCompilerGeneratedDocXmlFile>
     <IsPackable>true</IsPackable>
-    <PackageDescription>Provides types that can be used to model the structure of a source code document and to output source code for that model in a supported language.
-
-Commonly Used Types:
-System.CodeDom.CodeObject
-System.CodeDom.Compiler.CodeDomProvider
-Microsoft.CSharp.CSharpCodeProvider
-Microsoft.VisualBasic.VBCodeProvider</PackageDescription>
+    <PackageDescription>Provides types that can be used to model the structure of a source code document and to output source code for that model in C# or Visual Basic.</PackageDescription>
 
     <!-- TODO https://github.com/dotnet/runtime/issues/90400: Annotate for nullable reference types -->
     <Nullable>disable</Nullable>
     <NoWarn>$(NoWarn);nullable</NoWarn>
-    <!-- TODO: Add package README file: https://github.com/dotnet/runtime/issues/99358 -->
-    <EnableDefaultPackageReadmeFile>false</EnableDefaultPackageReadmeFile>
   </PropertyGroup>
 
   <!-- DesignTimeBuild requires all the TargetFramework Derived Properties to not be present in the first property group. -->

diff --git a/src/libraries/System.Composition.AttributedModel/src/PACKAGE.md b/src/libraries/System.Composition.AttributedModel/src/PACKAGE.md
@@ -0,0 +1,140 @@
+## About
+
+<!-- A description of the package and where one can find more documentation -->
+
+`System.Composition.AttributedModel` is part of the Managed Extensibility Framework (MEF) 2.0, a composition library for .NET that enables dependency injection through attributes or conventions.
+
+This package provides the foundational attributes that allow you to declare parts for composition, such as imports, exports, and metadata.
+It is used to mark classes, properties, methods, and constructors for MEF's discovery and composition process.
+
+## Key Features
+
+<!-- The key features of this package -->
+
+* Provides attributes for declaring composable parts, importing dependencies, metadata, and creating shared or non-shared parts
+
+## How to Use
+
+<!-- A compelling example on how to use this package with code, as well as any specific guidelines for when to use the package -->
+
+Mark classes for export and import using attributes.
+
+```csharp
+using System.Composition;
+using System.Composition.Hosting;
+
+var configuration = new ContainerConfiguration()
+    .WithPart<Service>()
+    .WithPart<Application>();
+
+using CompositionHost container = configuration.CreateContainer();
+
+Application app = container.GetExport<Application>();
+app.Service.Execute();
+// Service is running!
+
+[Export]
+public class Application
+{
+    [Import]
+    public Service Service { get; set; }
+}
+
+[Export]
+public class Service
+{
+    public void Execute() => Console.WriteLine("Service is running!");
+}
+```
+
+Metadata can be used to differentiate between multiple exports of the same contract.
+
+```csharp
+using System.Composition;
+using System.Composition.Hosting;
+
+ContainerConfiguration configuration = new ContainerConfiguration()
+    .WithPart<FileLogger>()
+    .WithPart<ConsoleLogger>()
+    .WithPart<Application>();
+
+using CompositionHost container = configuration.CreateContainer();
+
+Application app = container.GetExport<Application>();
+app.Run();
+// Using FileLogger to log.
+// FileLogger: Hello, World!
+// Using ConsoleLogger to log.
+// ConsoleLogger: Hello, World!
+
+public interface ILogger
+{
+    void Log(string message);
+}
+
+[Export(typeof(ILogger))]
+[ExportMetadata("Name", "FileLogger")]
+public class FileLogger : ILogger
+{
+    public void Log(string message) => Console.WriteLine($"FileLogger: {message}");
+}
+
+[Export(typeof(ILogger))]
+[ExportMetadata("Name", "ConsoleLogger")]
+public class ConsoleLogger : ILogger
+{
+    public void Log(string message) => Console.WriteLine($"ConsoleLogger: {message}");
+}
+
+[Export]
+public class Application
+{
+    [ImportMany]
+    public required IEnumerable<Lazy<ILogger, IDictionary<string, object>>> Loggers { get; set; }
+
+    public void Run()
+    {
+        foreach (var logger in Loggers)
+        {
+            var name = logger.Metadata["Name"];
+
+            Console.WriteLine($"Using {name} to log.");
+            logger.Value.Log("Hello, World!");
+        }
+    }
+}
+```
+
+## Main Types
+
+<!-- The main types provided in this library -->
+
+The main types provided by this library are:
+
+* `System.Composition.ExportAttribute`
+* `System.Composition.ImportAttribute`
+* `System.Composition.ExportMetadataAttribute`
+
+## Additional Documentation
+
+<!-- Links to further documentation. Remove conceptual documentation if not available for the library. -->
+
+* [API documentation](https://learn.microsoft.com/dotnet/api/system.composition)
+* [Managed Extensibility Framework (MEF)](https://learn.microsoft.com/dotnet/framework/mef/)
+
+## Related Packages
+
+<!-- The related packages associated with this package -->
+
+* [System.Composition](https://www.nuget.org/packages/System.Composition)
+* [System.Composition.Convention](https://www.nuget.org/packages/System.Composition.Convention)
+* [System.Composition.Hosting](https://www.nuget.org/packages/System.Composition.Hosting)
+* [System.Composition.Runtime](https://www.nuget.org/packages/System.Composition.Runtime)
+* [System.Composition.TypedParts](https://www.nuget.org/packages/System.Composition.TypedParts)
+
+## Feedback & Contributing
+
+<!-- How to provide feedback on this package and contribute to it -->
+
+System.Composition.AttributedModel is released as open source under the [MIT license](https://licenses.nuget.org/MIT).
+Bug reports and contributions are welcome at [the GitHub repository](https://github.com/dotnet/runtime).
diff --git a/...ibraries/System.Composition.AttributedModel/src/System.Composition.AttributedModel.csproj b/...ibraries/System.Composition.AttributedModel/src/System.Composition.AttributedModel.csproj
@@ -5,17 +5,10 @@
     <StrongNameKeyId>Microsoft</StrongNameKeyId>
     <UseCompilerGeneratedDocXmlFile>false</UseCompilerGeneratedDocXmlFile>
     <IsPackable>true</IsPackable>
-    <PackageDescription>Provides common attributes used by System.Composition types.
-
-Commonly Used Types:
-System.Composition.ExportAttribute
-System.Composition.ImportAttribute
-System.Composition.Convention.AttributedModelProvider</PackageDescription>
+    <PackageDescription>Provides the foundational attributes that allow you to declare parts for composition, such as imports, exports, and metadata with the Managed Extensibility Framework (MEF).</PackageDescription>
     <!-- TODO https://github.com/dotnet/runtime/issues/90400: Annotate for nullable reference types -->
     <Nullable>disable</Nullable>
     <NoWarn>$(NoWarn);nullable</NoWarn>
-    <!-- TODO: Add package README file: https://github.com/dotnet/runtime/issues/99358 -->
-    <EnableDefaultPackageReadmeFile>false</EnableDefaultPackageReadmeFile>
   </PropertyGroup>
 
   <ItemGroup>