Interface IRendersZptDocument

An entry-point object for use by consuming logic. Renders ZPT documents from a stream and returns the rendered document as a stream.

Namespace: ZptSharp

Assembly: ZptSharp.Abstractions.dll

Syntax

public interface IRendersZptDocument

Remarks

Use this interface in your own application if you want to render a ZPT document from a Stream source but that stream did not originate as a file in a file system. The method RenderAsync(Stream, Object, RenderingConfig, CancellationToken, IDocumentSourceInfo) in this interface will not be able to use a filename/extension to detect an appropriate document provider.

This means that you must explicitly select a document provider: an implementation of IReadsAndWritesDocument and pass it to this document renderer service. There are two ways to achieve that; the first way is to pass a RenderingConfig which has the selected document provider implementation in its DocumentProviderType property. The other way is to have manually-registered the document provider with the IServiceProvider from which this document-renderer instance was resolved.

If you do neither of the above then RenderAsync(Stream, Object, RenderingConfig, CancellationToken, IDocumentSourceInfo) will fail with an exception, stating that it cannot resolve an instance of IReadsAndWritesDocument.

Methods

RenderAsync(Stream, Object, RenderingConfig, CancellationToken, IDocumentSourceInfo)

Renders a specified ZPT document from a stream using the specified model.

Declaration

Task<Stream> RenderAsync(Stream stream, object model, RenderingConfig config = null, CancellationToken token = default(CancellationToken), IDocumentSourceInfo sourceInfo = null)

Parameters

Type	Name	Description
System.IO.Stream	stream	A stream containing the document to render.
System.Object	model	The model/data to be rendered by the document.
RenderingConfig	config	An optional rendering configuration.
System.Threading.CancellationToken	token	An optional token used to cancel/abort the operation whilst it is in-progress.
IDocumentSourceInfo	sourceInfo	An optional source information object describing the source of the stream.

Returns

Type	Description
System.Threading.Tasks.Task<System.IO.Stream>	A stream containing the rendered document.

Remarks

The stream parameter is a Stream containing the content of the source ZPT document to be rendered.

The model parameter is the model which will be rendered-by/bound-to the document template. It will be available as the pre-defined TALES variable here during the rendering process. This model may be any arbitrary object, as appropriate to your application/use-case.

Passing a RenderingConfig in the config parameter is optional but recommended. Because this service cannot rely upon a filename/extension to automatically select an appropriate document provider, using a configuration object with the DocumentProviderType property set is the easiest way to explicitly select the provider. The alternative is to have registered an implementation of IReadsAndWritesDocument with the same IServiceProvider as was used to resolve this document renderer instance.

If the configuration is omitted or null then Default will be used, which has mostly sane defaults, except does not specify a document provider (see above).

The cancellation token parameter token may be used during asynchronous operations in order to abort/cancel the operation before completion. For more information about task cancellation see https://docs.microsoft.com/en-us/dotnet/api/system.threading.cancellationtokensource.

The sourceInfo parameter is optional information about the source of the stream parameter. It may be any implementation of IDocumentSourceInfo. The source info is useful for providing diagnostic/debugging information, particularly if IncludeSourceAnnotation is true. If omitted or null then a default UnknownSourceInfo will be used, indicating that the source of the document is unknown/unspecified.

The return of this method is a Task which exposes a Stream. That stream is the rendered document. If you wish to copy this to a TextWriter, for example to save it to a file, or to write it to another output, then consider using IWritesStreamToTextWriter.