Description

Static method.

Converts and combines all files in the folder, and optionally all subfolders, using the requested conversion settings.

The order of the files in the combined file cannot be guaranteed and is dependent on the file system. In most cases they are alphabetical but can also be by creation time. Files from the root of the input folder are listed first, then all files from the subfolders when enabled. Subfolders are listed in alphabetical or creation time order, again dependent on the file system.

A filter pattern can be used to only process files in the folder that match the provided pattern, such as *.doc to process all Word documents, or ABC* to process all files that start with the letters ABC. An exclude filter is also provided, to allow you to skip files that match the exclude pattern. The exclude filter is applied to the list of files returned by the include filter.

The conversion settings passed in determine how the files are combined. For instance, passing conversion settings to create a multipaged PDF file will combine all input files into a single, multipage PDF file, while passing in the conversion settings to create serialized TIFF images will result in a serialized sequence of TIFF images, one for each page of each file.

Syntax

PNConverter.CombineFolder(InputFolder, IncludeSubFolders,

                          FileFilter, ExcludeFileFilter,

                          OutputFolder, OutputName, OverwriteExisting,

                          CreateResultsLogFiles, SettingsProfile,

                          ExtensionsProfile, MIMEProfile, UserSettings,

                          RemoteComputerName, ConversionWorkingFolder,

                          CombineFilesProcessLoggingPath)

 

PNConverter.CombineFolder(InputFolder, IncludeSubFolders,

                          FileFilter, ExcludeFileFilter,

                          OutputFolder, OutputName, OverwriteExisting,

                          CreateResultsLogFiles, SettingsProfile,

                          ExtensionsProfile, MIMEProfile, UserSettings,

                          RemoteComputerName, ConversionWorkingFolder,

                          CombineFilesProcessLoggingPath,

                          SortMode, SortOrder)

 

PNConverter.CombineFolder(InputFolder, IncludeSubFolders,

                          FileFilter, ExcludeFileFilter,

                          OutputFolder, OutputName, OverwriteExisting,

                          CreateResultsLogFiles, SettingsList,

                          ExtensionsProfile, MIMEProfile, UserSettings,

                          RemoteComputerName, ConversionWorkingFolder,

                          CombineFilesProcessLoggingPath)

 

PNConverter.CombineFolder(InputFolder, IncludeSubFolders,

                          FileFilter, ExcludeFileFilter,

                          OutputFolder, OutputName, OverwriteExisting,

                          CreateResultsLogFiles, SettingsList,

                          ExtensionsProfile, MIMEProfile, UserSettings,

                          RemoteComputerName, ConversionWorkingFolder,

                          CombineFilesProcessLoggingPath,

                          SortMode, SortOrder)

 

Returns a PNCombineItem object which contains a collection of PNConversionResult objects, one for each file in the folder (and subfolders, if selected) that matched the filter pattern. The PNCombineItem object contains a list of files used in the combine process, and a list of the resulting combined files as well as other information about the original combine request. Each inner PNConversionResult object contains information about the conversion results for a file in the combine set passed.

Parameters

String InputFolder

The full path to the folder containing the files to convert and combine together. This can be on the local computer, on a shared location using a mapped drive letter or by passing a UNC formatted file path.

String IncludeSubFolders

Set to True to include the subfolders under the folder when building the list of files to be converted and combined.

String FileFilter

A filter to process only the files matching the filter pattern, such as using *.pdf to only process files ending with the .PDF or .pdf extension. Multiple filters can be combined using the pipe (|) character, such as *.doc|*.pdf to process only Word and PDF files.

Hidden and system files are ignored, and the search pattern filters files based on a regular expression match of the long name of a file. The filter defaults to all files in the folder (*.*) if String.Empty or null are passed for the filter.

String ExcludeFileFilter

After the Filter pattern is used to get the list of files to convert from the InputFolder, the exclude filter can then be applied to that list to remove files that match the exclude pattern. Multiple excluded filters are combined using the pipe (|) character, such as *.pdf|*.xml to process all files returned except PDF and XML files.

If String.Empty or null is passed then no files are excluded.

String OutputFolder

Full path to the save file location. This folder must be specified and it must be created before the call to CombineFolder is made. If the path doesn't exist or a file of the same name already exists in the output folder location, the conversion will fail. Pass True for OverwriteExisting to allow file overwriting.

String OutputName

The name to use for the output file, without extension. The default file extension for the type of multipaged file being created will always be added to the name provided here. This argument must be provided.

String OverwriteExisting

Set to True to overwrite existing files, or False to fail conversion when a file of the same name already exists in the save location.

String CreateResultsLogFile

Pass True to create a results log file containing a complete snapshot of the conversion information for each file. This file is saved with each output file. The name of the results log file is based on the name of the original file and also indicates the conversion status for that file. For example, when converting Sample.doc, a successful conversion will create Sample.doc.succeeded.dcsresults and if the conversion did not succeed, the file would be named Sample.doc.failed.dcsresults.

These log files can later be read from disk using the DeserializeFromXML method of the PNConversionItem class.

String SettingsProfile

The name of the profile to use, with or without the XML extension. Settings in the profile that do not apply to the type of output being created are ignored. Document Conversion Service includes several sample profiles for common types of output files for your use, or you can create your own and pass in a full path to your custom profile. See Creating and Customizing Profiles for a list of included profiles and how to create your own.

IDictionary<String, String> SettingsList

A dictionary of name\value pairs of settings that describes the conversion options. Used instead of SettingsProfile above. The name\value pairs that make up this dictionary are the same settings that are used to create the XML-formatted profiles included with Document Conversion Service. See Conversion Settings for a list of all of the settings that are available.

String ExtensionsProfile

Name of the file mapping profile XML file, with or without the XML extension. Providing this parameter is optional and an internal default mapping is provided. You would only need to provide this file if you wanted to override the default file extension to converter mappings provided.

String MimeProfile

Reserved for future use - pass String.Empty.

IDictionary<String, String> UserSettings

Optional. Pass a dictionary of additional conversion settings. These settings will override any matching settings passed in for SettingsProfile or SettingsList. Pass null if not using.

String RemoteComputerName

Optional. Pass String.Empty if you are converting locally or the name of the remote computer where Document Conversion Service is running. When converting remotely, a ConversionWorkingFolder must also be provided.

String ConversionWorkingFolder

Used to provide a shared path to be used when doing remote conversion or an alternate temporary working instead of our default of the Windows TEMP folder.

This setting is required when RemoteComputerName is provided for remote conversion (DCOM) as both the local and the remote computer need access to a shared path in which to do the conversion. Pass String.Empty if you are not using this setting.

When not doing remote conversion, this setting is not required in most cases but can be useful when dealing with folder and file names longer than 255 characters. When converting a file, the conversion tool copies the file and performs the conversion in temporary staging and working folders created on demand in the default Windows temp folder. These folders need to be less than 255 characters as required by the underlying programs used by Document Conversion Service to perform conversions. When dealing with these long path and file names the default folders created can occasionally cause path names that are too long for Document Conversion Service to process. When this happens this switch can be used to set the temporary folder to a shorter path to allow processing. Again, pass String.Empty if you are not using this setting.

String ConvertFileProcessLoggingPath

Optional. Specify a path to a folder in which to store the SmartInspect logs files of any failed conversions. These files are stored in the temp folder by default and can be viewed using the SmartInspect Redistributable Console. These log files are a tracing of the entire conversion process and are not the same as the conversion results log files created when a conversion fails. See Controlling the SmartInspect Logging Files to change where these files are stored, how they are named, or to disable creation of these files.

PNFileSortMode SortMode

Optional, controls the sort order of the list of files returned from the InputFolder. Files can be sorted by name, date created or date modified. Default is None when not specfied.

PNFileSortOrder SortOrder

Optional, returns the files in Ascending (0-9, A-Z) or Descending (Z-A, 9-0) order. Default is Ascending when not specified.

Remarks

In the case of a failed combine, the combine results log file is always created. When the combine does not succeed, a .failed folder is created in the save folder location specified by OutputFolder argument and the results log files are stored there.

The name of the results log when the combine does not succeed will be similar to the following:

PNCombineFolder_2013_05_31_2_50_05_PM_3.failed.dcsresults

The bold text in the name will change for each file and is based on the date and time of the run and an internal counter. See Controlling the Failed Results File Location to store these files in a different location, disable the use of the date and time in the name, or to disable the creation of these file.

Exceptions

See Also:

ConvertFile ConvertFileList ConvertFolder CombineFiles IsConversionServiceRunning