Skip to content

Commit bef9c4a

Browse files
buyaa-neNeRGy164
buyaa-n
and
eNeRGy164
authored
[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]>
1 parent a1f25d8 commit bef9c4a

File tree

14 files changed

+703
-58
lines changed

14 files changed

+703
-58
lines changed

‎src/libraries/System.CodeDom/src/PACKAGE.md

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
## About
2+
3+
<!-- A description of the package and where one can find more documentation -->
4+
5+
Provides functionality for dynamically generating and compiling source code using the Code Document Object Model (CodeDOM).
6+
7+
It allows developers to represent code in a language-agnostic format and then generate code in multiple languages, such as C# and VB.NET.
8+
The primary use cases include creating dynamic code generation tools, runtime code generation, and facilitating code analysis or transformation.
9+
10+
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).
11+
12+
## Key Features
13+
14+
<!-- The key features of this package -->
15+
16+
* Write code using a common object model that can be translated into multiple programming languages.
17+
* Generate and compile code at runtime based on the CodeDOM.
18+
19+
## How to Use
20+
21+
<!-- A compelling example on how to use this package with code, as well as any specific guidelines for when to use the package -->
22+
23+
Generating and compiling C# code:
24+
25+
```csharp
26+
using System.CodeDom;
27+
using System.CodeDom.Compiler;
28+
using Microsoft.CSharp;
29+
30+
// Create a new CodeCompileUnit to hold the code
31+
var compileUnit = new CodeCompileUnit();
32+
33+
// Create a namespace
34+
var codeNamespace = new CodeNamespace("MyNamespace");
35+
compileUnit.Namespaces.Add(codeNamespace);
36+
37+
// Create a class
38+
var classDeclaration = new CodeTypeDeclaration("MyClass")
39+
{
40+
IsClass = true
41+
};
42+
codeNamespace.Types.Add(classDeclaration);
43+
44+
// Add a simple method to the class
45+
var method = new CodeMemberMethod
46+
{
47+
Name = "HelloWorld",
48+
ReturnType = new CodeTypeReference(typeof(void)),
49+
};
50+
classDeclaration.Members.Add(method);
51+
52+
var methodInvocation = new CodeMethodInvokeExpression(new CodeTypeReferenceExpression("Console"),
53+
"WriteLine",
54+
new CodePrimitiveExpression("Hello, World!"));
55+
method.Statements.Add(methodInvocation);
56+
57+
// Generate C# code from the CodeDOM structure
58+
CodeDomProvider provider = new CSharpCodeProvider();
59+
60+
using (var writer = new StringWriter())
61+
{
62+
var codeGenereationOptions = new CodeGeneratorOptions()
63+
{
64+
BlankLinesBetweenMembers = false,
65+
IndentString = " ",
66+
};
67+
68+
provider.GenerateCodeFromCompileUnit(compileUnit, writer, codeGenereationOptions);
69+
Console.WriteLine(writer.GetStringBuilder().ToString());
70+
}
71+
```
72+
73+
This example generates:
74+
75+
```csharp
76+
//------------------------------------------------------------------------------
77+
// <auto-generated>
78+
// This code was generated by a tool.
79+
//
80+
// Changes to this file may cause incorrect behavior and will be lost if
81+
// the code is regenerated.
82+
// </auto-generated>
83+
//------------------------------------------------------------------------------
84+
85+
namespace MyNamespace {
86+
87+
public class MyClass {
88+
private void HelloWorld() {
89+
Console.WriteLine("Hello, World!");
90+
}
91+
}
92+
}
93+
```
94+
95+
## Main Types
96+
97+
<!-- The main types provided in this library -->
98+
99+
The main types provided by this library are:
100+
101+
* `System.CodeDom.CodeObject`
102+
* `System.CodeDom.CodeCompileUnit`
103+
* `System.CodeDom.CodeNamespace`
104+
* `System.CodeDom.CodeTypeDeclaration`
105+
* `System.CodeDom.CodeMemberMethod`
106+
* `System.CodeDom.CodeTypeReference`
107+
* `System.CodeDom.CodeMethodInvokeExpression`
108+
* `System.CodeDom.CodeTypeReferenceExpression`
109+
* `System.CodeDom.CodePrimitiveExpression`
110+
* `System.CodeDom.Compiler.CodeDomProvider`
111+
* `System.CodeDom.Compiler.CodeGeneratorOptions`
112+
* `Microsoft.CSharp.CSharpCodeProvider`
113+
* `Microsoft.VisualBasic.VBCodeProvider`
114+
115+
## Additional Documentation
116+
117+
<!-- Links to further documentation. Remove conceptual documentation if not available for the library. -->
118+
119+
* [API documentation](https://learn.microsoft.com/dotnet/api/system.codedom)
120+
* [Compile and generate dynamic source code](https://learn.microsoft.com/dotnet/framework/reflection-and-codedom/dynamic-source-code-generation-and-compilation)
121+
122+
## Feedback & Contributing
123+
124+
<!-- How to provide feedback on this package and contribute to it -->
125+
126+
System.CodeDom is released as open source under the [MIT license](https://licenses.nuget.org/MIT).
127+
Bug reports and contributions are welcome at [the GitHub repository](https://github.com/dotnet/runtime).

‎src/libraries/System.CodeDom/src/System.CodeDom.csproj

Lines changed: 1 addition & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,19 +6,11 @@
66
<IsTrimmable>false</IsTrimmable>
77
<UseCompilerGeneratedDocXmlFile>false</UseCompilerGeneratedDocXmlFile>
88
<IsPackable>true</IsPackable>
9-
<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.
10-
11-
Commonly Used Types:
12-
System.CodeDom.CodeObject
13-
System.CodeDom.Compiler.CodeDomProvider
14-
Microsoft.CSharp.CSharpCodeProvider
15-
Microsoft.VisualBasic.VBCodeProvider</PackageDescription>
9+
<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>
1610

1711
<!-- TODO https://github.com/dotnet/runtime/issues/90400: Annotate for nullable reference types -->
1812
<Nullable>disable</Nullable>
1913
<NoWarn>$(NoWarn);nullable</NoWarn>
20-
<!-- TODO: Add package README file: https://github.com/dotnet/runtime/issues/99358 -->
21-
<EnableDefaultPackageReadmeFile>false</EnableDefaultPackageReadmeFile>
2214
</PropertyGroup>
2315

2416
<!-- DesignTimeBuild requires all the TargetFramework Derived Properties to not be present in the first property group. -->

‎src/libraries/System.Composition.AttributedModel/src/PACKAGE.md

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
## About
2+
3+
<!-- A description of the package and where one can find more documentation -->
4+
5+
`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.
6+
7+
This package provides the foundational attributes that allow you to declare parts for composition, such as imports, exports, and metadata.
8+
It is used to mark classes, properties, methods, and constructors for MEF's discovery and composition process.
9+
10+
## Key Features
11+
12+
<!-- The key features of this package -->
13+
14+
* Provides attributes for declaring composable parts, importing dependencies, metadata, and creating shared or non-shared parts
15+
16+
## How to Use
17+
18+
<!-- A compelling example on how to use this package with code, as well as any specific guidelines for when to use the package -->
19+
20+
Mark classes for export and import using attributes.
21+
22+
```csharp
23+
using System.Composition;
24+
using System.Composition.Hosting;
25+
26+
var configuration = new ContainerConfiguration()
27+
.WithPart<Service>()
28+
.WithPart<Application>();
29+
30+
using CompositionHost container = configuration.CreateContainer();
31+
32+
Application app = container.GetExport<Application>();
33+
app.Service.Execute();
34+
// Service is running!
35+
36+
[Export]
37+
public class Application
38+
{
39+
[Import]
40+
public Service Service { get; set; }
41+
}
42+
43+
[Export]
44+
public class Service
45+
{
46+
public void Execute() => Console.WriteLine("Service is running!");
47+
}
48+
```
49+
50+
Metadata can be used to differentiate between multiple exports of the same contract.
51+
52+
```csharp
53+
using System.Composition;
54+
using System.Composition.Hosting;
55+
56+
ContainerConfiguration configuration = new ContainerConfiguration()
57+
.WithPart<FileLogger>()
58+
.WithPart<ConsoleLogger>()
59+
.WithPart<Application>();
60+
61+
using CompositionHost container = configuration.CreateContainer();
62+
63+
Application app = container.GetExport<Application>();
64+
app.Run();
65+
// Using FileLogger to log.
66+
// FileLogger: Hello, World!
67+
// Using ConsoleLogger to log.
68+
// ConsoleLogger: Hello, World!
69+
70+
public interface ILogger
71+
{
72+
void Log(string message);
73+
}
74+
75+
[Export(typeof(ILogger))]
76+
[ExportMetadata("Name", "FileLogger")]
77+
public class FileLogger : ILogger
78+
{
79+
public void Log(string message) => Console.WriteLine($"FileLogger: {message}");
80+
}
81+
82+
[Export(typeof(ILogger))]
83+
[ExportMetadata("Name", "ConsoleLogger")]
84+
public class ConsoleLogger : ILogger
85+
{
86+
public void Log(string message) => Console.WriteLine($"ConsoleLogger: {message}");
87+
}
88+
89+
[Export]
90+
public class Application
91+
{
92+
[ImportMany]
93+
public required IEnumerable<Lazy<ILogger, IDictionary<string, object>>> Loggers { get; set; }
94+
95+
public void Run()
96+
{
97+
foreach (var logger in Loggers)
98+
{
99+
var name = logger.Metadata["Name"];
100+
101+
Console.WriteLine($"Using {name} to log.");
102+
logger.Value.Log("Hello, World!");
103+
}
104+
}
105+
}
106+
```
107+
108+
## Main Types
109+
110+
<!-- The main types provided in this library -->
111+
112+
The main types provided by this library are:
113+
114+
* `System.Composition.ExportAttribute`
115+
* `System.Composition.ImportAttribute`
116+
* `System.Composition.ExportMetadataAttribute`
117+
118+
## Additional Documentation
119+
120+
<!-- Links to further documentation. Remove conceptual documentation if not available for the library. -->
121+
122+
* [API documentation](https://learn.microsoft.com/dotnet/api/system.composition)
123+
* [Managed Extensibility Framework (MEF)](https://learn.microsoft.com/dotnet/framework/mef/)
124+
125+
## Related Packages
126+
127+
<!-- The related packages associated with this package -->
128+
129+
* [System.Composition](https://www.nuget.org/packages/System.Composition)
130+
* [System.Composition.Convention](https://www.nuget.org/packages/System.Composition.Convention)
131+
* [System.Composition.Hosting](https://www.nuget.org/packages/System.Composition.Hosting)
132+
* [System.Composition.Runtime](https://www.nuget.org/packages/System.Composition.Runtime)
133+
* [System.Composition.TypedParts](https://www.nuget.org/packages/System.Composition.TypedParts)
134+
135+
## Feedback & Contributing
136+
137+
<!-- How to provide feedback on this package and contribute to it -->
138+
139+
System.Composition.AttributedModel is released as open source under the [MIT license](https://licenses.nuget.org/MIT).
140+
Bug reports and contributions are welcome at [the GitHub repository](https://github.com/dotnet/runtime).

‎src/libraries/System.Composition.AttributedModel/src/System.Composition.AttributedModel.csproj

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,10 @@
55
<StrongNameKeyId>Microsoft</StrongNameKeyId>
66
<UseCompilerGeneratedDocXmlFile>false</UseCompilerGeneratedDocXmlFile>
77
<IsPackable>true</IsPackable>
8-
<PackageDescription>Provides common attributes used by System.Composition types.
9-
10-
Commonly Used Types:
11-
System.Composition.ExportAttribute
12-
System.Composition.ImportAttribute
13-
System.Composition.Convention.AttributedModelProvider</PackageDescription>
8+
<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>
149
<!-- TODO https://github.com/dotnet/runtime/issues/90400: Annotate for nullable reference types -->
1510
<Nullable>disable</Nullable>
1611
<NoWarn>$(NoWarn);nullable</NoWarn>
17-
<!-- TODO: Add package README file: https://github.com/dotnet/runtime/issues/99358 -->
18-
<EnableDefaultPackageReadmeFile>false</EnableDefaultPackageReadmeFile>
1912
</PropertyGroup>
2013

2114
<ItemGroup>

0 commit comments

Comments
 (0)