The CS-Script action allows you to implement a custom script in C# to process the print job. You have the possibility to work with the entire print job data (you are accessing the actual job object) right before and immediately after the conversion. All with the full functionality available in C#.
Note
This feature is available in our PDFCreator Business Editions
The used technology is CS-Script. A CLR (Common Language Runtime) based scripting system which uses ECMA-compliant C# as a programming language. By this, we provide an interface with pre- and postconversion functions for your own implementation.
For more info on CS-Script, please see the official CS-Script documentation.
PDFCreator uses CodeDOM hosting. Please be aware of the CodeDOM compatibility when reading the documentation. In general, you can use .net 4.5 with C#5.
Attention
You can enable the CS-Script action in the advanced section of the queue settings. The setting will always enable the pre- and postconversion functions. If you wish to disable one of the functions, simply implement an empty function with a successful ScriptResult (see PDFCreatorScript Interface below).
The script file must be a .cs or .csx file and must be located in the CS-Scripts Folder.
All the available script files are listed in the dropdown. If the file is not listed please click on Refresh. With the Open CS-Scripts Folder button you can check the script file location in the Windows explorer.
If a script is selected it will be automatically checked and compiled. Potential errors are listed beneath the dropdown. Click on Check Script to repeat the check.
PDFCreator is delivered with a sample script file named SetFilenameInPreConversionCreateBackUpInPostConversionScript.cs. It can be found in the CS-Scripts folder in the PDFCreator program directory.
The script sets a new output file template before the conversion and creates a backup file afterwards. The backup folder gets created in the target folder and is named after the filename with an appended “_backup”. The script will succeed if the backup is created and will abort if it fails or the backup file already exists.
The custom script needs to provide a class that implements the PDFCreatorScript interface.
public interface IPDFCreatorScript
{
ScriptResult PreConversion(Job job, Logger logger);
ScriptResult PostConversion(Job job, Logger logger);
}
The PreConversion function is called immediately before the conversion of a document, PostConversion directly afterwards.
Ensure the following using directives in your script:
using NLog;
using pdfforge.CustomScriptAction;
using pdfforge.PDFCreator.Conversion.Jobs.Jobs;
using pdfforge.PDFCreator.Conversion.Settings;
using pdfforge.PDFCreator.Utilities.Tokens;
You can use the NLogg.dll, CustomScriptAction.dll, PDFCreator.Jobs.dll, PDFCreator.Settings.dll and the PDFCreator.Utilities.dll files from the PDFCreator program directory to embed them in your IDE. The script compiler will automatically consider all the DLLs in the PDFCreator program directory and the CS-Scripts Folder.
Note
If you are referencing external libraries the required DLL files must be located in the PDFCreator program directory or in the CS-Scripts Folder.
The return value can be either ScriptResult.Success for an successful execution (or at least to continue the current job) or ScriptResult.Abort to cancel the current job.
You can enable and configure actions inside the PreConversion method. This code block shows how to enable and configure the AttachmentPage and CoverPage actions and change their order:
public ScriptResult PreConversion(Job job, Logger logger)
{
job.Profile.AttachmentPage.Enabled = true;
job.Profile.AttachmentPage.Files.Add(@"C:\attachment.pdf");
job.Profile.CoverPage.Enabled = true;
job.Profile.CoverPage.Files.Add(@"C:\cover.pdf");
job.Profile.ActionOrder.Remove("CoverPage"); // it's optional to modify the order
job.Profile.ActionOrder.Insert(0, "CoverPage");
}
When enabled, the action will be added to the end of the action list (or its category, i.e. ‘Modify’ or ‘Send’). When you add multiple actions, the actions will be executed in the order they were added. By modifying the list job.Profile.ActionOrder, you can change the order (e.g. if other actions were configured in the UI, that should be executed after the new action).
The given logger is the current logger from the PDFCreator, so the logs entries from the custom script are included in the general PDFCreator log according to the current log level (see Debug).
The logger is a NLog.Logger. The common functions to log on a certain log level are:
logger.Debug(messagestring)
logger.Warn(messagestring)
logger.Warn(exception, messagestring)
logger.Error(messagestring)
logger.Error(exception, messagestring)
The job class contains all the data of the current job including the current profile (see below).
Note
The job class works with a copy of the current profile and all the job data is monetary. Changed data (including passwords) will be not be saved and will be discarded when the job is finished.
At execution time of the script some data from the profile is already processed. All the listed properties will be used instead of the related data in the profile:
This is the template to the full path of the future output file. Used tokens are already replaced. If applicable, the output filename will be extended automatically by a page number (for multi file formats) or a counter to ensure a unique filename.
List of output files generated during conversion
The JobPasswords class contains properties for passwords of each action.
For example:
job.Passwords.PdfUserPassword = "1234";
job.Passwords.PdfOwnerPassword = "Swordfish";
Note
For missing passwords the profile check will fail. Please disable the concerned action in the settings and enable it in the PreConversion function of the script.
The Accounts class contains functions to access the accounts for each action - pass the current profile to get the current account.
For example:
job.Accounts.GetFtpAccount(job.Profile);
Note
For incomplete accounts the profile check will fail. Please disable the concerned action in the settings and enable it in the PreConversion function of the script.
The required password must be set in the job.Passwords property
If you want to create a new Account, you have to give it an AccountId, add the new account to job.Accounts and set the AccountId in the profile.
Contains the Metadata from the print job, the time of printing (PrintDateTime) and a function to determine the total number of pages: job.JobInfo.CalculateTotalPages()
Use the TokenReplacer to extract the values from your UserTokens.
var userTokenValue = job.TokenReplacer.GetToken("User").GetValueWithFormat("YourUserTokenKey");
//GetToken is always called with "User"
//Just change your requested UserToken key
The job class contains the profile with the following settings:
Setting |
Type |
Description |
---|---|---|
ActionOrder |
Order in which actions are processed by an executing job |
|
AuthorTemplate |
Template for the Author field. This may contain tokens. |
|
FileNameTemplate |
Template of which the filename will be created. This may contain Tokens. |
|
Guid |
GUID of the profile |
|
KeywordTemplate |
Template for the Keyword field. This may contain tokens. |
|
Name |
Name of the profile |
|
OutputFormat |
Default format for this print job. Valid values: Pdf, PdfA1B, PdfA2B, PdfA3B, PdfX, Jpeg, Png, Tif, Txt |
|
SaveFileTemporary |
Enable to save files only in a temp directory |
|
ShowAllNotifications |
Show a notification after converting the document |
|
ShowOnlyErrorNotifications |
Only show notification for error |
|
ShowProgress |
If true, a progress window will be shown during conversion |
|
ShowQuickActions |
Show quick actions page after converting the document |
|
SkipSendFailures |
Allow to proceed with further send actions if a single send action fails |
|
SubjectTemplate |
Template for the Subject field. This may contain tokens. |
|
TargetDirectory |
Directory in which the files will be saved (in interactive mode, this is the default location that is presented to the user) |
|
TitleTemplate |
Template for the Title field. This may contain tokens. |
|
UseGsNewPDF |
Use the new Ghostscript PDF Interpreter introduced with gs 9.55.0 |
|
WarnSendFailures |
Show a warning for failing send actions (only if SkipSendFailures is active) |
|
AttachmentPage |
||
Appends one or more pages at the end of the converted document |
||
AttachmentPage.Enabled |
Enables the AttachmentPage action |
|
AttachmentPage.Files |
Filename of the PDF that will be appended |
|
BackgroundPage |
||
Adds a page background to the resulting document |
||
BackgroundPage.Enabled |
Enables the BackgroundPage action |
|
BackgroundPage.File |
Filename of the PDF that will be used as background |
|
BackgroundPage.FitToPage |
Enable to resize the background to fit the document page |
|
BackgroundPage.Opacity |
Opacity for background in percent |
|
BackgroundPage.Repetition |
Defines the way the background document is repeated. Valid values: NoRepetition, RepeatAllPages, RepeatLastPage |
|
CoverPage |
||
Inserts one or more pages at the beginning of the converted document |
||
CoverPage.Enabled |
Enables the CoverPage action |
|
CoverPage.Files |
Filename of the PDF that will be inserted |
|
CustomScript |
||
Pre- and post-conversion actions calling functions from a custom script |
||
CustomScript.Enabled |
Enables the custom script pre- and post-conversion action |
|
CustomScript.ScriptFilename |
Filename of the custom script in application directory ‘Cs-Scripts’ folder |
|
DropboxSettings |
||
Dropbox settings for currently logged user |
||
DropboxSettings.AccountId |
ID of the linked account |
|
DropboxSettings.CreateShareLink |
||
DropboxSettings.Enabled |
||
DropboxSettings.EnsureUniqueFilenames |
If true, files with the same name will not be overwritten on the server. A counter will be appended instead (i.e. document_2.pdf) |
|
DropboxSettings.SharedFolder |
||
EmailClientSettings |
||
Opens the default e-mail client with the converted document as attachment |
||
EmailClientSettings.AddSignature |
Add the PDFCreator signature to the mail |
|
EmailClientSettings.AdditionalAttachments |
The list of additional attachments for the e-mail |
|
EmailClientSettings.Content |
Body text of the e-mail |
|
EmailClientSettings.Enabled |
Enables the EmailClient action |
|
EmailClientSettings.Format |
Set the e-mail body format Valid values: Auto, Html, Text |
|
EmailClientSettings.Recipients |
The list of recipients of the e-mail, i.e. info@someone.com; me@mywebsite.org |
|
EmailClientSettings.RecipientsBcc |
The list of recipients of the e-mail in the ‘BCC’ field, i.e. info@someone.com; me@mywebsite.org |
|
EmailClientSettings.RecipientsCc |
The list of recipients of the e-mail in the ‘CC’ field, i.e. info@someone.com; me@mywebsite.org |
|
EmailClientSettings.Subject |
Subject line of the e-mail |
|
EmailSmtpSettings |
||
Sends a mail without user interaction through SMTP |
||
EmailSmtpSettings.AccountId |
ID of linked account |
|
EmailSmtpSettings.AddSignature |
Add the PDFCreator signature to the mail |
|
EmailSmtpSettings.AdditionalAttachments |
The list of additional attachments for the e-mail |
|
EmailSmtpSettings.Content |
Body text of the mail |
|
EmailSmtpSettings.DisplayName |
Display name for e-mail sender |
|
EmailSmtpSettings.Enabled |
If true, this action will be executed |
|
EmailSmtpSettings.Format |
Set the e-mail body format Valid values: Auto, Html, Text |
|
EmailSmtpSettings.OnBehalfOf |
If set it will be used as From and the address from the account will be set as Sender |
|
EmailSmtpSettings.Recipients |
The list of recipients of the e-mail, i.e. info@someone.com; me@mywebsite.org |
|
EmailSmtpSettings.RecipientsBcc |
The list of recipients of the e-mail in the ‘BCC’ field, i.e. info@someone.com; me@mywebsite.org |
|
EmailSmtpSettings.RecipientsCc |
The list of recipients of the e-mail in the ‘CC’ field, i.e. info@someone.com; me@mywebsite.org |
|
EmailSmtpSettings.ReplyTo |
Specifies an address that should be used to reply to the e-mail |
|
EmailSmtpSettings.Subject |
Subject line of the e-mail |
|
ForwardToFurtherProfile |
||
ForwardToFurtherProfile.Enabled |
||
ForwardToFurtherProfile.ProfileGuid |
||
Ftp |
||
Upload the converted documents with FTP |
||
Ftp.AccountId |
ID of the linked account |
|
Ftp.Directory |
Target directory on the server |
|
Ftp.Enabled |
If true, this action will be executed |
|
Ftp.EnsureUniqueFilenames |
If true, files with the same name will not be overwritten on the server. A counter will be appended instead (i.e. document_2.pdf) |
|
Ghostscript |
||
Ghostscript settings |
||
Ghostscript.AdditionalGsParameters |
These parameters will be provided to Ghostscript in addition to the PDFCreator parameters |
|
HttpSettings |
||
Action to upload files to a HTTP server |
||
HttpSettings.AccountId |
||
HttpSettings.Enabled |
If true, this action will be executed |
|
JpegSettings |
||
Settings for the JPEG output format |
||
JpegSettings.Color |
Number of colors. Valid values: Color24Bit, Gray8Bit |
|
JpegSettings.Dpi |
Resolution of the JPEG files |
|
JpegSettings.Quality |
Quality factor of the resulting JPEG (100 is best, 0 is worst) |
|
PageNumbers |
||
Settings for page numbers. |
||
PageNumbers.AlternateCorner |
Whether to switch left/right corner every page. |
|
PageNumbers.BeginOn |
The page to begin numbering on. |
|
PageNumbers.BeginWith |
The number to start counting at. |
|
PageNumbers.Enabled |
If true, this action will be executed |
|
PageNumbers.FontColor |
The color of the page numbers. |
|
PageNumbers.FontFile |
The font of the page numbers. |
|
PageNumbers.FontName |
The name of the font of the page numbers. |
|
PageNumbers.FontSize |
The size of the page numbers. |
|
PageNumbers.Format |
Format of the page numbers. |
|
PageNumbers.HorizontalOffset |
The horizontalOffset offset from the page border of the page numbers in points. |
|
PageNumbers.Position |
Where to put the page numbers. Valid values: BottomRight, BottomLeft, BottomCenter, TopRight, TopLeft, TopCenter, |
|
PageNumbers.UnitOfMeasurement |
Defines the unit of measurement for the page number position. Valid values: Centimeter, Inch |
|
PageNumbers.UseRomanNumerals |
Print the numbers as roman numerals. |
|
PageNumbers.VerticalOffset |
The vertical offset from the page border of the page numbers in points. |
|
PdfSettings |
||
Settings for the PDF output format |
||
PdfSettings.ColorModel |
Color model of the PDF (does not apply to images). Valid values: Rgb, Cmyk, Gray |
|
PdfSettings.DocumentView |
Defines which controls will be opened in the reader. Valid values: NoOutLineNoThumbnailImages, Outline, ThumbnailImages, FullScreen, ContentGroupPanel, AttachmentsPanel |
|
PdfSettings.EnablePdfAValidation |
Enable PDF/A validation |
|
PdfSettings.NoFonts |
If enabled, no fonts will be embedded into the output. |
|
PdfSettings.PageOrientation |
Define how pages are automatically rotated. Valid values: Automatic, Portrait, Landscape |
|
PdfSettings.PageView |
Defines how the document will be opened in the reader. Valid values: OnePage, OneColumn, TwoColumnsOddLeft, TwoColumnsOddRight, TwoPagesOddLeft, TwoPagesOddRight |
|
PdfSettings.ViewerStartsOnPage |
Defines the page number the viewer will start on when opening the document |
|
CompressColorAndGray |
||
Compression settings for color and greyscale images |
||
PdfSettings.CompressColorAndGray.Compression |
Settings for the compression method. Valid values: Automatic, JpegMaximum, JpegHigh, JpegMedium, JpegLow, JpegMinimum, JpegManual, Zip |
|
PdfSettings.CompressColorAndGray.Dpi |
Images will be resampled to this maximum resolution of the images, if resampling is enabled |
|
PdfSettings.CompressColorAndGray.Enabled |
If true, color and grayscale images will be processed according to the algorithm. If false, they will remain uncompressed |
|
PdfSettings.CompressColorAndGray.JpegCompressionFactor |
Define a custom compression factor (requires JpegManual as method) |
|
PdfSettings.CompressColorAndGray.Resampling |
If true, the images will be resampled to a maximum resolution |
|
CompressMonochrome |
||
Compression settings for monochrome images |
||
PdfSettings.CompressMonochrome.Compression |
Settings for the compression method. Valid values: CcittFaxEncoding, Zip, RunLengthEncoding |
|
PdfSettings.CompressMonochrome.Dpi |
Images will be resampled to this maximum resolution of the images, if resampling is enabled |
|
PdfSettings.CompressMonochrome.Enabled |
If true, monochrome images will be processed according to the algorithm. If false, they will remain uncompressed |
|
PdfSettings.CompressMonochrome.Resampling |
If true, the images will be resampled to a maximum resolution |
|
Security |
||
PDF Security options |
||
PdfSettings.Security.AllowPrinting |
Allow to user to print the document |
|
PdfSettings.Security.AllowScreenReader |
Allow to user to use a screen reader |
|
PdfSettings.Security.AllowToCopyContent |
Allow to user to copy content from the PDF |
|
PdfSettings.Security.AllowToEditAssembly |
Allow to user to make changes to the assembly |
|
PdfSettings.Security.AllowToEditComments |
Allow to user to edit comments |
|
PdfSettings.Security.AllowToEditTheDocument |
Allow to user to edit the document |
|
PdfSettings.Security.AllowToFillForms |
Allow to user to fill in forms |
|
PdfSettings.Security.Enabled |
If true, the PDF file will be password protected |
|
PdfSettings.Security.EncryptionLevel |
Defines the encryption level. Valid values: Rc40Bit, Rc128Bit, Aes128Bit, Aes256Bit |
|
PdfSettings.Security.OwnerPassword |
Password that can be used to modify the document |
|
PdfSettings.Security.RequireUserPassword |
If true, a password is required to open the document. |
|
PdfSettings.Security.RestrictPrintingToLowQuality |
If true, only printing in low resolution will be supported |
|
PdfSettings.Security.UserPassword |
Password that must be used to open the document (if set) |
|
Signature |
||
Digitally sign the PDF document |
||
PdfSettings.Signature.AllowMultiSigning |
If true, the PDF file may be signed by additional persons |
|
PdfSettings.Signature.BackgroundImageFile |
The Path of the background image to use. |
|
PdfSettings.Signature.CertificateFile |
Path to the certificate |
|
PdfSettings.Signature.DisplaySignature |
Defines the display level of the signature in the document. Valid values: NoDisplay, TextOnly, ImageOnly, ImageAndText |
|
PdfSettings.Signature.Enabled |
If true, the signature will be displayed in the PDF document |
|
PdfSettings.Signature.FitTextToSignatureSize |
Resize signature text to fit into displayed signature |
|
PdfSettings.Signature.FontColor |
Font color of the signature text |
|
PdfSettings.Signature.FontFile |
PostScript name of the signature font |
|
PdfSettings.Signature.FontName |
Font name of the signature text (this is only used as a hint, FontFile contains the real name) |
|
PdfSettings.Signature.FontSize |
Size of the signature font |
|
PdfSettings.Signature.LeftX |
Signature location: Top left corner (X part) |
|
PdfSettings.Signature.LeftY |
Signature location: Top left corner (Y part) |
|
PdfSettings.Signature.RightX |
Signature location: Bottom right corner (X part) |
|
PdfSettings.Signature.RightY |
Signature location: Bottom right corner (Y part) |
|
PdfSettings.Signature.SignContact |
Contact name of the signature |
|
PdfSettings.Signature.SignLocation |
Signature location |
|
PdfSettings.Signature.SignReason |
Reason for the signature |
|
PdfSettings.Signature.SignatureCustomPage |
If the signature page is set to custom, this property defines the page where the signature will be displayed |
|
PdfSettings.Signature.SignaturePage |
Defines the page on which the signature will be displayed. Valid values: FirstPage, LastPage, CustomPage |
|
PdfSettings.Signature.SignaturePassword |
Password for the certificate file |
|
PdfSettings.Signature.TimeServerAccountId |
ID of the linked account for the timeserver |
|
PngSettings |
||
Settings for the PNG output format |
||
PngSettings.Color |
Number of colors. Valid values: Color32BitTransp, Color24Bit, Color8Bit, Color4Bit, Gray8Bit, BlackWhite |
|
PngSettings.Dpi |
Resolution of the PNG files |
|
Printing |
||
Print the document to a physical printer |
||
Printing.Duplex |
Defines the duplex printing mode. Valid values: Disable, LongEdge, ShortEdge |
|
Printing.Enabled |
If enabled, the document will be printed to a physical printer |
|
Printing.FitToPage |
If set, the pages of the document will be adjusted to the paper size of the printer. |
|
Printing.PrinterName |
Name of the printer that will be used, if SelectedPrinter is set. |
|
Printing.SelectPrinter |
Method to select the printer. Valid values: DefaultPrinter, ShowDialog, SelectedPrinter |
|
Scripting |
||
The scripting action allows to run a script after the conversion |
||
Scripting.Enabled |
If true, the given script or application will be executed |
|
Scripting.ParameterString |
Parameters that will be passed to the script in addition to the output files |
|
Scripting.ScriptFile |
Path to the script or application |
|
Scripting.Visible |
If false, the given script or application will be executed in a hidden window |
|
Scripting.WaitForScript |
Wait until the script execution has ended |
|
Stamping |
||
Place a stamp text on all pages of the document |
||
Stamping.Color |
Color of the text |
|
Stamping.Enabled |
If true, the document all pages will be stamped with a text |
|
Stamping.FontAsOutline |
If true, the text will be rendered as outline. If false, it will be filled. |
|
Stamping.FontFile |
PostScript name of the stamp font. |
|
Stamping.FontName |
Name of the font. (this is only used as a hint, the PostScriptFontName contains the real name) |
|
Stamping.FontOutlineWidth |
Width of the outline |
|
Stamping.FontSize |
Size of the font |
|
Stamping.StampText |
Text that will be stamped |
|
TextSettings |
||
TextSettings.Format |
Text Format (0 outputs XML-escaped Unicode along with information regarding the format of the text | 1 same XML output format, but attempts similar processing to MuPDF, and will output blocks of text | 2 outputs Unicode (UCS2) text (with a Byte Order Mark) which approximates the original text layout | 3 same as 2 encoded in UTF-8) |
|
TiffSettings |
||
Settings for the TIFF output format |
||
TiffSettings.Color |
Number of colors. Valid values: Color24Bit, Color12Bit, Gray8Bit, BlackWhiteG3Fax, BlackWhiteG4Fax, BlackWhiteLzw |
|
TiffSettings.Dpi |
Resolution of the TIFF files |
|
UserTokens |
||
Parse ps files for user defined tokens |
||
UserTokens.Enabled |
Activate parsing ps files for user tokens (Only available in the PDFCreator business editions) |
|
UserTokens.Separator |
UserToken separator in the document Valid values: SquareBrackets, AngleBrackets, |
|
Watermark |
||
Adds a watermark to the resulting document |
||
Watermark.Enabled |
Enables the WatermarkAction |
|
Watermark.File |
Filename of the PDF that will be used as watermark |
|
Watermark.FitToPage |
Enable to resize the watermark to fit the document page |
|
Watermark.Opacity |
Opacity for watermark in percent |
|
Watermark.Repetition |
Defines the way the watermark document is repeated Valid values: NoRepetition, RepeatAllPages, RepeatLastPage |