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
description: "Subscribe to conversion lifecycle events (completed, failed, by-page-failed) through the typed ConversionEvents aggregator in GroupDocs.Conversion for .NET."
description: "Subscribe to pipeline lifecycle and per-result conversion events through the typed ConversionEvents aggregator in GroupDocs.Conversion for .NET."
Starting with **GroupDocs.Conversion for .NET v26.6**, conversion lifecycle event handlers are aggregated into a single typed object — [ConversionEvents](https://reference.groupdocs.com/conversion/net/groupdocs.conversion/conversionevents/). This replaces the previous practice of setting individual handlers on [ConverterSettings](https://reference.groupdocs.com/conversion/net/groupdocs.conversion/convertersettings/) or chaining `.OnConversionCompleted(...).OnConversionFailed(...)` after `WithOptions(...)` in the fluent API.
14
+
Starting with **GroupDocs.Conversion for .NET v26.6**, conversion event handlers are aggregated into a single typed object — [ConversionEvents](https://reference.groupdocs.com/conversion/net/groupdocs.conversion/conversionevents/). This replaces three previously separate registration paths:
15
15
16
-
The aggregator exposes the following handlers:
16
+
* The [IConverterListener](https://reference.groupdocs.com/conversion/net/groupdocs.conversion.reporting/iconverterlistener/) interface assigned to [ConverterSettings.Listener](https://reference.groupdocs.com/conversion/net/groupdocs.conversion/convertersettings/listener/) — for pipeline lifecycle callbacks.
17
+
* Per-result handler properties on `ConverterSettings` (`OnConversionFailed`, `OnConversionByPageFailed`, `OnCompressionCompleted`).
18
+
* The fluent chain methods placed after `WithOptions(...)` or `Compress(...)` (`.OnConversionCompleted(...)`, `.OnConversionFailed(...)`, `.OnCompressionCompleted(...)`).
19
+
20
+
The aggregator is registered with the [Converter](https://reference.groupdocs.com/conversion/net/groupdocs.conversion/converter/) constructor via a new `events:` factory parameter, or with the fluent API via the entry-stage `FluentConverter.WithEvents(...)` method.
21
+
22
+
## Event groups
23
+
24
+
`ConversionEvents` exposes two distinct groups of handlers.
25
+
26
+
### Pipeline lifecycle
27
+
28
+
Fire **once per conversion run**, regardless of how many documents or pages the run produces. These replace the `Started` / `Progress` / `Completed` callbacks of `IConverterListener`.
17
29
18
30
| Handler | Signature | When it fires |
19
31
|---------|-----------|---------------|
20
-
|`OnConversionCompleted`|`Action<ConvertedContext>`| After the entire conversion completes successfully |
21
-
|`OnConversionFailed`|`Action<ConvertContext, Exception>`| When a conversion run throws |
22
-
|`OnConversionByPageFailed`|`Action<ConvertContext, Exception>`| When a single page fails during page-by-page conversion |
32
+
|`OnConversionStarted`|`Action`| Once, when the conversion pipeline starts |
33
+
|`OnConversionProgress`|`Action<byte>`| While the pipeline is running, with the current progress percentage (0–100) |
34
+
|`OnConversionCompleted`|`Action`| Once at the end of the pipeline, regardless of success or failure |
35
+
36
+
{{< hint style="warning" title="Name reuse — read before upgrading" >}}
37
+
The `OnConversionCompleted` name is **reused with new semantics** in v26.6. The pre-v26.6 fluent chain method `.OnConversionCompleted(Action<ConvertedContext>)` (per-document) is now `OnDocumentConverted` on the aggregator. The new `ConversionEvents.OnConversionCompleted` is a lifecycle handler — its signature is `Action` (no parameters) and it fires once at pipeline end. If you copy a v26.5-and-earlier example expecting per-document context, switch to `OnDocumentConverted`.
38
+
{{< /hint >}}
39
+
40
+
### Per-result
41
+
42
+
Fire **once per produced item** — each converted document, each converted page, each compressed archive — including failures.
43
+
44
+
| Handler | Signature | When it fires |
45
+
|---------|-----------|---------------|
46
+
|`OnDocumentConverted`|`Action<ConvertedContext>`| After each document conversion completes successfully |
47
+
|`OnDocumentFailed`|`Action<ConvertContext, Exception>`| When a document conversion throws |
48
+
|`OnPageConverted`|`Action<ConvertedPageContext>`| After each page is converted in page-by-page conversions |
49
+
|`OnPageFailed`|`Action<ConvertContext, Exception>`| When a single page fails during page-by-page conversion |
23
50
|`OnCompressionCompleted`|`Action<Stream>`| After contents have been converted and packaged into a compressed archive (see [Extract and Convert Archive Contents]({{< ref "conversion/net/developer-guide/advanced-usage/converting/conversion-options-by-document-family/convert-contents-of-rar-or-zip-document-to-different-formats-and-compress.md" >}})) |
24
51
52
+
See [Context Objects — Complete Guide]({{< ref "conversion/net/developer-guide/basic-usage/context-objects-complete-guide.md" >}}) for the properties exposed by `ConvertedContext`, `ConvertContext`, and `ConvertedPageContext`.
53
+
25
54
## Registering events with the classic API
26
55
27
-
Pass a `ConversionEvents` factory as the third argument to the [Converter](https://reference.groupdocs.com/conversion/net/groupdocs.conversion/converter/) constructor:
56
+
Pass a `ConversionEvents` factory as the third argument to the `Converter` constructor:
28
57
29
58
```csharp
30
59
usingGroupDocs.Conversion;
@@ -33,9 +62,15 @@ using GroupDocs.Conversion.Options.Convert;
converter.Convert("page2.tiff", newTiffConvertOptions()); // same global handler fires again
81
120
}
82
121
```
83
122
84
-
`Convert(...)` overloads that accept an `Action<ConvertedContext>` register a **per-call** result handler that wins over the global `OnConversionCompleted` for that single call:
123
+
`Convert(...)` overloads that accept an `Action<ConvertedContext>` register a **per-call** result handler that wins over the global `OnDocumentConverted` for that single call:
85
124
86
125
```csharp
87
126
using (varconverter=newConverter("source.docx", () =>newConverterSettings(), () =>events))
88
127
{
89
-
// Per-call handler — overrides events.OnConversionCompleted for THIS call only
128
+
// Per-call handler — overrides events.OnDocumentConverted for THIS call only
90
129
converter.Convert(
91
130
newPdfConvertOptions(),
92
131
(ConvertedContextctx) =>
@@ -97,12 +136,12 @@ using (var converter = new Converter("source.docx", () => new ConverterSettings(
97
136
}
98
137
});
99
138
100
-
// No per-call handler — events.OnConversionCompleted fires
139
+
// No per-call handler — events.OnDocumentConverted fires
The precedence rule is `(perCall ?? global)?.Invoke(...)`: if a per-call handler is supplied, the global `OnConversionCompleted` does not fire for that call. `OnConversionFailed` and `OnConversionByPageFailed` are always global — there is no per-call override.
144
+
The precedence rule is `(perCall ?? global)?.Invoke(...)`: if a per-call handler is supplied, the global `OnDocumentConverted` does not fire for that call. The other per-result handlers (`OnDocumentFailed`, `OnPageConverted`, `OnPageFailed`, `OnCompressionCompleted`) and all lifecycle handlers are always global — there is no per-call override.
106
145
107
146
Between consecutive `Convert(...)` calls on the same `Converter`, only the per-call slot is reset. The global `ConversionEvents` bag is preserved across runs.
108
147
@@ -137,13 +176,14 @@ The previous registration mechanisms continue to work, but are obsolete and plan
When values are set on both the obsolete locations and on `ConversionEvents`, the aggregator wins. Handlers set on `ConverterSettings` are merged into the internal events bag at converter construction.
187
+
When values are set on both the obsolete locations and on `ConversionEvents`, the aggregator wins. Handlers set on `ConverterSettings`(including a `Listener` instance) are forwarded into the internal events bag at converter construction.
148
188
149
189
See the [migration notes]({{< ref "conversion/net/developer-guide/migration-notes.md" >}}) for a step-by-step upgrade guide.
Copy file name to clipboardExpand all lines: net/developer-guide/advanced-usage/listening.md
+6Lines changed: 6 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,6 +9,12 @@ keywords: Track conversion process, Subscribe to conversion process events, trac
9
9
productName: GroupDocs.Conversion for .NET
10
10
hideChildren: False
11
11
---
12
+
{{< hint style="important" title="Obsolete since v26.6 — use ConversionEvents instead" >}}
13
+
The `IConverterListener` interface and the `ConverterSettings.Listener` property are marked obsolete in v26.6 and are planned for removal in v26.9. New code should subscribe to `OnConversionStarted` / `OnConversionProgress` / `OnConversionCompleted` on the [ConversionEvents]({{< ref "conversion/net/developer-guide/advanced-usage/conversion-events.md" >}}) aggregator instead.
14
+
15
+
Existing code that assigns a listener continues to work in v26.6 — the `Started` / `Progress` / `Completed` callbacks are forwarded to the corresponding `ConversionEvents` handlers at converter construction.
16
+
{{< /hint >}}
17
+
12
18
In some cases, there is a need to monitor the conversion process and to receive updates upon a start, progress and completion of a conversion. For such situations, [**GroupDocs.Conversion**](https://products.groupdocs.com/conversion/net) exposes an extension point where the client application may hook up and receive updates.
0 commit comments