.NET Report Engine app.exe.config Settings

This article describes the optional properties that can be placed in your .NET Report Engine application's app.exe.config file.

Place these properties into the "WindwardReports" section of the app.exe.config file, e.g.:

<configuration>
<configSections>
<section name="WindwardReports" type="System.Configuration.NameValueSectionHandler" />
</configSections>
<WindwardReports>
<add key="license" value="EnterKeyHere" />
</WindwardReports>
</configuration>

Properties Categories#

The below property settings fall into three general categories:

  1. Read in and set when the Report Engine starts. You need to restart the Report Engine for new values to be read and used. These properties are categorized as Global.
  2. Read in and used every time a output is generated from a Report Template. When these are changed, the next report will use the new settings. These properties are categorized as Local.
  3. Default values for properties you can set in a (Process)Report object. When you change these the next instantiation of the report object will use those new values as the defaults. You can then explicitly set these properties in the object. These properties are categorized as Report.
  4. Other properties that don't fall into the above categories are categorized as Miscellaneous.

Global Properties#

NameAllowed ValuesDefaultDescription
asian.supporttrue, falsetrueIf set to false, the server assumes the files needed for output of Asian text is not available and will fall-back to latin text only.
default.chart.dpiany number300When charts are rendered to a bitmap (for printers), they are rendered at this resolution.
default.image.dpiany number96If a bitmap does not have it's DPI set, this is the value used.
expand.out.textignore, newline, paragraphparagraphWhat to do if an Out Tag has a <CR> and/or <TAB> in the text. Choices are ignore, newline, or paragraph. <TAB> is handled for both newline and paragraph. newline is a line break (like <br/> in html) and paragraph is a paragraph break.
font.filesfontname; fontname;…noneExample: C:/windows/fonts/.ttf;c:/windows/fonts/.ttc;
A series of pathnames, separated by semicolons, of true type fonts installed on the system. The only wildcard recognized is the "*" (i.e. no regular expressions). The Report Engine will look in the usual directories on Windows & Linux; this setting is just to include non-standard locations.
font.mapfont_replace1=font_substitute1;…noneExample: Arial=Courier New;Times New Roman=Verdana
Map a font onto another. In the example above any use of Arial in the generated output will instead use Courier New. Any use of Times New Roman will instead use Verdana. Very useful when a template uses fonts that do not exist on the system the engine is running on.
force.bitmap.formatbmp, gif, jpeg, png, & tiffnoneThis will force all bitmaps in the Report Template output to be converted to the requested format. The default is no conversion.
ignore.tag.colorstrue, falsefalseSet to false to remove foreground colors from Tags if the color of the Tag in the template matches the Tag's assigned color.
layout.documenton, offonIf set to off, then page layout for output of type DOCX, XLSX, PPTX and HTML in non-pages mode, will not be performed. The advantage of turning this off is that document production will be faster. This setting is ignored for other output types.
licensea valid Windward licensenoneThis is required for the .NET Report Engine – it is your license to run the program. It is a uuencoded string and can be in a single line or in multiple lines. If multiple lines, do not put spaces at the beginning/end of the lines.
logging.filenameoff, a log4j properties filenamenoneThe location of your log4j properties file. If you use log4j for your application, put the properties file location here. The value of off means you are not using log4j. There is no need to set this if log4j is initialized before Windward Reports is called.
odata.max-message-sizeAny number10000000Set the maximum message size in the OData provider.
pdf.font_mappingauto, postscriptFont1=displayFont1;…noneCan be set to auto or ArialMT=Arial;Arial-BoldMT=Arial,Bold; auto will set the font names to the names specified in the Report Template, overwriting the true postscript name. The series of "postscriptFont=displayFont;" is an explicit mapping and you can have as many as you wish.
pdf.makeLineToFittrue, falsetrueSet to true to force PDF text to fit within the Report Engine-calculated width. Set to false to fit the text within the width Acrobat calculates.
pdf.rgbTransparencyBlendingSpacetrue, falsefalseSet to false to turn off using the RGB space for image color blending in PDF output.
system.localeany locale such as de or de_CHthe system localeSet the locale for system messages.

Local Properties#

NameAllowed ValuesDefaultDescription
check.for.glyphson, offonChecks the font specified for text and changes the font if it does not have glyphs for some of the text. If a font has normal glyphs, but not bold/italic and those are needed, it will use the normal font and widen/skew the rendered glyphs.
check.for.glyphs.fontnamesfont name 1;font name 2;…MS Mincho;Arial Unicode MSThe list of fonts to consider when the specified font does not have the glyphs needed. The font with the largest number of needed glyphs is used. If more than one font has the largest number, the earliest font in the list is used.
check.for.ole.imagestrue, falsetrueIf true, the Report Engine will check all images brought in via an Out Tag for an OLE header (used in Northwind & Access databases), and will strip it off. Non-OLE images are not affected.
html.embed_imagestrue, falsefalseIf set to true, embeds images in HTML output. If set to false, separate image files are output.
html.split_pagestrue, falsefalseSet to true to output multiple files, one HTML file per document page. Set to f__alse to create one continuous HTML page.
keep.blank.sheetstrue, falsefalseIn XLSX output, keep blank sheets that were created upon generation.
line.breakinternal, externalinternalSet to internal to use the Windward Reports internal line breaker. Set to external to use the Java or .NET runtime line breaker.
The Windows default is external; the default for other operating systems is internal. Use internal for hyphenation, small caps, font scaling and font spacing for PDF and printer output.
report.hyphenate0, 1, or 21Use to hyphenate generated output. 0: do not hyphenate; 1: hyphenate if auto-hyphenate is set in the Report Template; 2: hyphenate.
report.remove-unused-formatstrue, falsefalseSet to true to remove unused formats (Word only).
report.timeoutany number (in seconds) greater than 0noneIf a report takes longer than this time (+/- 15 seconds) to generate, it will throw an exception.
report.trimnone, end.whitespace, and end.blanknoneUse this to trim whitespace at the end of a report. end.whitespace will remove empty paragraphs and section breaks. end.blank will also remove blank text.
report.write-fields-as-fieldstrue, falsetrueIf true, DOCX form fields and content controls are written to PDF and HTML output as form fields. If false, they are written as text.
sql.smart-quotetrue, falsefalseIf set to true, a '${var}' will be changed to ? instead of the regular substitution of '?'.
sql.timeoutany number 0 or greaterWhatever the underlying data connector (ADO.NET) has as a default.Set the timeout on SQL selects in the underlying SQL connector. A value of 0 is infinite and is NOT recommended.
trim.tablesaggressivelyaggressivelyFor Excel only - it will remove empty rows at the bottom of the table and empty columns on the right side of rows. It will remove formatted cells, but it will not remove cells with content or that are merged with other cells.
txt.font_nameany valid font nameCourier (Courier New on Windows)Use this font instead of Courier to calculate text placement in Report Template output.
txt.font_size6 - 25612Use this font size instead of 12pt to calculate text placement in Report Template output.
use.decimaltrue, falsefalseSet to true to use BigDecimal instead of Double in the Windward functions. Useful in cases when String to Double rounding errors occur.
word.version2007, 2010, 2013, 20162016The Report Template will be parsed using the default values for this version of Word.
write.tags0, 1, 22When generating output with Tags without a data source applied, it will output the Tags in the following format: 0: text; 1: field (Word), Report Designer macro (Excel), text (PPT); 2: field, bitmap/chart for Tags that produce a bitmap or chart (Word only).

Report Properties#

NameAllowed ValuesDefaultDescription
csv.cell_separatorany string,In CSV reports, this changes the separator between cells from "," to the specified string.
csv.quote_charany string"In CSV reports, changes the quote delimiter from " to this string.
csv.newlineany string\r\nIn CSV reports, changes the new line string from \r\n (carriage return, line feed) to this string.
csv.trim_whitespacetrue, falsefalseIn CSV reports, if set to true, this will trim all whitespace at the end of cell contents in all cells.
date.format.modedefault, legacydefaultDetermines the date format parsing style. Legacy is the date formatting used prior to version 21.*. Default is the new date formatting introduced version 21.
html.full_filetrue, falsetrueThe default value for ProcessOpenXmlAPI.getFullFile(). This can be overridden with a programatic call to Report.setFullFile().
html.html_typesee setSpec() <!--- NEEDS LINK to .net api reference doco --->see setSpec() <!--- NEEDS LINK to .net api reference doco --->The default value for ProcessOpenXmlAPI.getSpec().This can be overridden with a programatic call to Report.setSpec().
openxml.copy-drawingstrue, falsetrueThe default value for ProcessOpenXmlAPI.getCopyDrawings(). This can be overridden with a programatic call to Report. setCopyDrawings().
openxml.copy-embedded-objectstrue, falsetrueThe default value for ProcessOpenXmlAPI.getCopyEmbeddedObjects(). This can be overridden with a programmatic call to Report.setCopyEmbeddedObjects().
openxml.copy-metadatasee setCopyMetadata()<!--- NEEDS LINK to .net api reference doco --->2The default value for ProcessOpenXmlAPI.getCopyMetadata(). This can be overridden with a programmatic call to Report.setCopyMetadata().
openxml.copy-shapestrue, falsetrueThe default value for ProcessOpenXmlAPI.getCopyShapes(). This can be overridden with a programmatic call to Report.setCopyShapes().
openxml.recalculatetrue, falsetrue for XLSX; false for DOCX and PPTXThe default value for ProcessOpenXmlAPI.getRecalculateOnOpen(). This can be overridden with a programmatic call to Report.setRecalculateOnOpen().
openxml.write-chart-as-charttrue, falsetrueThe default value for ProcessOpenXmlAPI.getChartsAsCharts().This can be overridden with a programatic call to Report.setChartsAsCharts().
pdf.compression_level0, 1, or 21The default value for ReportPdf.getCompressionLevel().This can be overridden with a programmatic call to ReportPdf.setCompressionLevel().
pdf.font_level0, 1, or 22This is the default value for ProcessPdf.setFontLevel(). You must use the number of the static final int specified in ProcessPdf<!--- NEEDS LINK to .net api reference doco --->. This can still be overridden with a programmatic call to ProcessPdf.setFontLevel().
pdf.key_length40 or 12840The default value for ReportPdf.getKeyLength(). This can be overridden with a programmatic call to ReportPdf.setKeyLength().
pdf.owner_passwordany stringnoneThe default value for ReportPdf.getOwnerPassword().This can be overridden with a programmatic call to ReportPdf.setOwnerPassword().
pdf.PDF_Aon, offoffThe default value for ReportPdf.isPdfA(). This can be overridden with a programmatic call to ReportPdf.setPdfA().
pdf.securitysee getSecurity()<!--- NEEDS LINK to .net api reference doco --->0The default value for ReportPdf.getSecurity(). This can be overridden with a programmatic call to ReportPdf.setSecurity().
pdf.user_passwordany stringnoneThe default value for ReportPdf.getUserPassword().This can be overridden with a programmatic call to ReportPdf.setUserPassword().
pdf.includeHeaderFooterOnPdfImporttrue, falsetrueDetermines whether headers and footers from the parent docx being copied on top of imported pdf.().
report.hidden.modesee Report.setHiddenMode()<!--- NEEDS LINK to .net api reference doco --->0The default for Report.getHiddenMode(). This can be overridden with a programmatic call to Report.setHiddenMode().
report.localeany locale stringthe system localeThe default value for Report.setLocale(). You must use either a language (en) or language_country (en_US). This can be overridden with a programmatic call to Report.setLocale(). This is the locale used when generating output for things like the default formatting of a currency amount.
report.locale_asianany locale stringthe system locale for East Asian contentSimilar to report.locale except used when content for a Tag is marked as East Asian.
report.locale_bidiany locale stringthe system locale for bidi contentSimilar to report.locale except used when content for a Tag is marked as bi-directional, e.g. ar_SA.
txt.break_pagetrue, falsefalseThe default value for ProcessText.getBreakPage(). This can be overridden with a programmatic call to ReportPdf.setBreakPage().
txt.show_headerstrue, falsefalseThe default value for ProcessText.getShowHeaders(). This can be overridden with a programmatic call to ReportPdf.setShowHeaders().
txt.use_marginstrue, falsefalseThe default value for ProcessText.getUseMargins(). This can be overridden with a programmatic call to ReportPdf.setUseMargins().
txt.use_soft_eolntrue, falsefalseThe default value for ProcessText.getUseSoftEoln(). This can be overridden with a programatic call to ReportPdf.setUseSoftEoln().

Miscellaneous Properties#

NameAllowed ValuesDefaultDescription
import.use.child.stylestrue, falsetrue(Version 13.x only. For applying/importing parent styles in versions 14.x and later, see Import Tag Reference <!---NEEDS LINK to Import Tag Reference doco--->.) When an imported template's style settings don't match the master document this determines if default settings in the imported document will match the imported style (true) or the master style (false).
sql.parameterssubstitution, parameters or parameters.alwaysparametersSets the default value in DataSourceProvider.setParamMode().
use.parent.formattrue, falsefalse(Version 13.x only. For applying/importing parent styles in versions 14.x and later, see Import Tag Reference<!---NEEDS LINK to Import Tag Reference doco--->.) This sets the default value for the Import Tag use-parent-format property. The default is false and does nothing. If set to true, then imported templates will have their first paragraph and character formatting set to that of the paragraph in the parent template where the Import Tag is located.

ImportFileClass#

Use the ImportFileClass if you have a method for accessing files and/or security protocols that is not supported by Windward. See that attached file for a sample implementation

In the app.exe.config file you can set the property ImportFileClass. You set it to the classname of the class you implement. For example, you can set:

ImportFileClass=net.windward.env.StandardImportFile

If that class exists, it will be used instead of the default class (which is net.windward.env.StandardImportFile). This class must be available to the Report Engine so it must be loaded with your application. The class must implement ImportFile. It has a single method that is passed the information of the file you wish to import and it returns the imported file.