This feature is supported by version 26.11 or greater.
Warning
Since version 26.11, external resources whose references come from data are not loaded by default: for example, <<image [item.PhotoUrl]>> where PhotoUrl is an http or https URI gives an empty image. Add the hosts to LoadSaveOptions.WhitelistedResources, or set LoadSaveOptions.SkipExternalResources to false to keep the previous behavior. Resources referenced by the template itself are loaded as before.
An <<image>> or <<doc>> tag can evaluate to a URI taken from data. When a server assembles documents from data supplied by others, such a URI could make the server request internal addresses. Template documents can reference network resources too: an image of an HTML template, a linked image or an INCLUDEPICTURE field of a Word document, an external link of a workbook.
GroupDocs.Assembly tells where each reference to an external resource comes from (ExternalResourceOrigin):
Template: the template document references the resource itself, including a literal URI of a tag such as <<image ["https://example.com/logo.png"]>>;
Data: the reference comes from data, such as a URI a tag expression evaluates to, or a resource of a document inserted by <<doc>> from data.
By default, resources referenced by the template are loaded, and resources whose references come from data are skipped.
Options
Four LoadSaveOptions properties control loading of external resources:
Property
Default
Description
SkipExternalResources
true
External resources are not loaded.
TrustTemplateResources
true
Resources referenced by the template are loaded even when skipping is on. Set it to false when templates come from untrusted sources.
WhitelistedResources
empty
Host names (a host and its subdomains) or absolute URI prefixes allowed even when skipping is on.
ExternalResourceHandler
null
Called for every external resource before it is requested, with its Uri, Origin and pre-set Skipped decision, to allow it, skip it, or provide its content.
External resources are resources reaching the network: http, https and ftp URIs, UNC paths (\\host\share) and file URIs with a remote host. Local file paths are not affected, so templates and <<image>> tags using local files keep working.
A skipped image of a document is replaced with a transparent image; a skipped <<image>> or <<doc>> value is treated as an empty value.
Allowing, Skipping and Providing Resources
In the example, the template inserts an image with <<image [expression]>>, and the image URI comes from data. With default options, the image is skipped. With the host added to WhitelistedResources, the image is allowed, and a handler derived from ExternalResourceHandler reports every decision and provides the content from a local file instead of requesting it.
usingSystem;usingSystem.IO;usingGroupDocs.Assembly;conststringphotoUri="https://images.example.com/photos/no-photo.jpg";DocumentAssemblerassembler=newDocumentAssembler();// Default options: the URI comes from data, so the image is skipped and left empty.assembler.AssembleDocument("Inserting image.docx","Skipped.docx",newDataSourceInfo(photoUri,"expression"));// Allow a trusted host and see every decision. The handler can also provide the content itself.LoadSaveOptionsoptions=newLoadSaveOptions();options.WhitelistedResources.Add("images.example.com");options.ExternalResourceHandler=newLocalImageHandler("no-photo.jpg");assembler.AssembleDocument("Inserting image.docx","Provided.docx",options,newDataSourceInfo(photoUri,"expression"));publicclassLocalImageHandler:ExternalResourceHandler{privatereadonlystringmImagePath;publicLocalImageHandler(stringimagePath){mImagePath=imagePath;}publicoverridevoidOnLoading(ExternalResourceLoadingArgsargs){Console.WriteLine($"{args.Origin} resource {args.Uri}: {(args.Skipped ? "skipped" : "allowed")}");// Provide the content instead of requesting it.if(!args.Skipped&&args.Uri.StartsWith("https://images.example.com/",StringComparison.OrdinalIgnoreCase))args.Data=File.ReadAllBytes(mImagePath);}}
Output:
Data resource https://images.example.com/photos/no-photo.jpg: allowed
In the handler, set args.Skipped to true to skip a resource or to false to allow it, and set args.Data to provide the content of the resource yourself.