Skip to content

Commit 72da3aa

Browse files
eNeRGy164buyaa-n
authored andcommitted
Provide System.Composition.AttributedModel package readme (dotnet#106781)
* Provide System.Composition.AttributedModel package readme * Improve after feedback * Set correct PackageDescription
1 parent d64eace commit 72da3aa

File tree

2 files changed

+141
-8
lines changed

2 files changed

+141
-8
lines changed
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)