Message Handlers in C#

Use message handlers in Aspose.HTML for .NET to customize the network request and response pipeline. A handler can inspect, modify, block, authenticate, resolve, or measure requests before an HTMLDocument loads resources or a conversion workflow renders output.

Message handlers are useful when HTML processing depends on network behavior that must be controlled by your application. They can help load resources from a ZIP archive, implement a custom scheme, block unwanted external requests, set operation timeouts, log request duration, or add authentication credentials for protected resources.

Articles in This Section

• Creating a Custom Message Handler – learn the message handler concept and implement a custom handler with Aspose.HTML for .NET.
• Popular Use Cases for Message Handlers – choose practical workflows for ZIP resources, request filtering, timeouts, authentication, and execution-time logging.

What Are Message Handlers?

Message handlers are a sequence of classes that are part of a process of a Web request and response through a pipeline. The key concept of message handlers work is chaining them together. The first handler receives a Web request, does some processing, and passes the request on to the next handler. At some point, the response is created and returned along the chain. This pattern is called a delegating handler.

Looking at the Figure, the sequence begins with the Request, then continues through the chain of message handlers. Once the message reaches the server, the Response is sent back through the chain of handlers in reverse order.

The request message goes through each handler in turn, reaching the last handler. This handler is also the first to receive the response. At this point, this response goes back through the chain of handlers in reverse order, and each handler can check or use the response as needed.

Handler behavior is governed by a set of protocols that describe what action message handlers can take in a given situation. The handlers, their protocols and their place in the chain may be defined by a system or user. For example, a message handler might: change the processing sequence of a pipeline, check requests or responses for errors, log the duration of an operation or other diagnostic information, etc.

Message Handler Use Cases

• Custom Message Handler – derive from MessageHandler, override Invoke(), and add the handler to the network pipeline.
• Convert HTML from ZIP Archive to PDF – resolve HTML and related resources stored inside a ZIP archive and render the document to PDF.
• Convert HTML from ZIP Archive to JPG – load HTML and resources from a ZIP archive and render the document to a raster image.
• Network Timeouts – set operation timeouts for opening HTML documents or converting HTML when remote resources are slow.
• Check Network Requests – intercept requests, block unwanted external resources, or restrict allowed protocols.
• Web Request Execution Time – log how long an HTML loading request takes.
• Execution Time Logging – combine ZIP resource loading, conversion to PDF, and request duration logging.
• Authentication – add credentials for password-protected resources that use Basic, Digest, NTLM, or Kerberos authentication.

FAQ

When should I use a custom message handler?

Use a custom message handler when you need to control resource loading, authentication, request filtering, timeout behavior, custom schemes, or diagnostics during HTML loading and rendering.

Where is a message handler added in Aspose.HTML for .NET?

Create a Configuration, get INetworkService, and add or insert a custom MessageHandler into the MessageHandlers collection before loading the HTMLDocument.

Can message handlers affect conversion output?

Yes. Conversion output can change if a handler blocks resources, changes request URLs, resolves resources from ZIP archives, sets timeouts, or supplies authentication credentials.

Related Resources

• Aspose.Html.Net API Reference – classes and interfaces for network processing and message handlers.
• Aspose.HTML for .NET Examples on GitHub – complete C# examples and project files.