You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/Features.md
+26-22Lines changed: 26 additions & 22 deletions
Original file line number
Diff line number
Diff line change
@@ -2,11 +2,33 @@
2
2
3
3
Features are a new concept in v2.14 and later that allows for behavior and state to be contained within the document or part. This is accessed via `Features` property on packages, parts, and elements. Elements inherit part features, and parts inherit package features.
4
4
5
-
This is inspired by the pattern ASP.NET Core uses to modify behavior of HttpContext: https://learn.microsoft.com/aspnet/core/fundamentals/request-features
5
+
This is inspired by the pattern ASP.NET Core uses to modify behavior of HttpContext: https://learn.microsoft.com/aspnet/core/fundamentals/request-features. This is an implementation of the [strategy pattern](https://refactoring.guru/design-patterns/strategy) that makes it easy to replace behavior on the fly.
6
+
7
+
As of v3.0, the `IFeatureCollection` includes the ability to enumerate registered features.
8
+
9
+
## Visualizing Registered Features
10
+
11
+
The in-box implementations of the `IFeatureCollection` provide a helpful debug view so you can see what features are available and what their properties/fields are:
12
+
13
+
6
14
7
15
## Current Features
8
16
9
-
The features that are currently available are described below and at what scope they are available. This is important, because and element by itself will not have any features available, while an element in one part may have different features than another part.
17
+
The features that are currently available are described below and at what scope they are available:
18
+
19
+
### IDisposableFeature
20
+
21
+
This feature allows for registering actions that need to run when a package or a part is destroyed or disposed:
22
+
23
+
```csharp
24
+
OpenXmlPackagepackage=GetSomePackage();
25
+
package.Features.Get<IDisposableFeature>().Register(() =>/* Some action that is called when the package is disposed */);
26
+
27
+
OpenXmlPartpart=GetSomePart();
28
+
part.Features.Get<IDisposableFeature>().Register(() =>/* Some action that is called when the part is removed or closed */);
29
+
```
30
+
31
+
Packages and parts will have their own implementations of this feature. Elements will retrieve the feature for their containing part if available.
10
32
11
33
### IPackageEventsFeature
12
34
@@ -51,28 +73,10 @@ Generally, assume that there may be a singleton implementation for the events an
51
73
52
74
> Note: There may be times when the part root is changed but an event is not fired. Not all areas have been identified where it would make sense to raise an event. Please file an issue if you find one.
53
75
54
-
## DocumentFormat.OpenXml.Features - unreleased
76
+
## DocumentFormat.OpenXml.Features
55
77
56
78
This library contains additional (non-core) features that build on top of built-in features and functionality.
57
79
58
-
### IDisposableFeature
59
-
60
-
This feature allows for registering features that need to be disposed at the same time as the feature goes out of scope. This allows a feature to be created, but its lifetime managed concurrently with the collection it is added to. The recommended way to use it is simply to call the following method:
61
-
62
-
```csharp
63
-
OpenXmlPackagepackage=GetSomePackage();
64
-
package.TryAddDisposableFeature();
65
-
66
-
OpenXmlPartpart=GetSomePart();
67
-
part.SetDisposable(newExampleFeature());
68
-
69
-
publicclassExampleFeature : IDisposable
70
-
{
71
-
}
72
-
```
73
-
74
-
This will add `ExampleFeature` to the part feature, and register it to be disposed when the part is disposed.
75
-
76
80
### IRandomNumberGeneratorFeature
77
81
This feature allows for a shared service to generate random numbers and fill an array.
0 commit comments