Static method.

Converts a file using the requested conversion settings.


PNConverter.ConvertFile(InputFile, OutputFolder, OutputName,

                       OverwriteExisting, RemoveFileExtension, CreateResultsLogFiles,

                       SettingsProfile, ExtensionsProfile, MIMEProfile, UserSettings,

                       RemoteComputerName, ConversionWorkingFolder,



PNConverter.ConvertFile(InputFile, OutputFolder, OutputName,

                        OverwriteExisting, RemoveFileExtension, CreateResultsLogFiles,

                        SettingsList, ExtensionsProfile, MIMEProfile, UserSettings,

                        RemoteComputerName, ConversionWorkingFolder,



Returns a PNConversionItem object that contains information about the original conversion request and an inner PNConversionResult object containing information about the conversion results.


String InputFile

The full path to the file to convert. 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 OutputFolder

Full path to the save file location, or String.Empty to create the new file in the same location as the source file. If the path doesn't exist, the conversion will fail. This folder must be created before the call to ConvertFolder is made.

If a file of the same name already exists in the save file 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 file being created will always be added to the name provided here.

Pass String.Empty to use the base name of the source file. When using the source name, the extension of the source file is always used as part of the new file name unless RemoveFileExtension is set to True.

Boolean 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.

Boolean RemoveFileExtension

This parameter is ignored if you have provided an file name in OutputName.

If OutputName is not specified, the name of the each output file is created using the base name and file extension of the original file. This is done to prevent name collision when you have two files in the folder with the same base name. Set this to True if you do not want the original file name extension as part of your output file name.

Boolean CreateResultsLogFile

Pass True to create a results log file containing a complete snapshot of the conversion information, This file is saved with the 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 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. 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. 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 in either 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 conversion process. 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.



If the conversion does not succeed, a folder named .failed is created in the same location as the source file. Inside the .failed folder is a timestamped folder that contains the conversion results log file that is always created with each failed file. The results log file named based on the source file's name and its conversion status. For example, if converting Document.doc failed the results log file would be named Document.doc.failed.dcsresults. See Controlling the Failed Results File Location to store these files in a different location or to disable the creation of these file.





An empty, or badly formatted profile was passed for SettingsProfile.

An empty list was passed for SettingsList.

An empty, or badly formatted profile was passed for ExtensionsProfile.

Null or empty string passed for InputFile.

A name for RemoteComputerName was passed but no corresponding ConversionWorkingFolder specified.


InputFile doesn't exist.


When a path to OutputFolder is specified but does not exist or is invalid.

When ConversionWorkingFolder is specified but does not exist or is invalid.

See Also:

ConvertFileList ConvertFolder CombineFiles CombineFolder IsConversionServiceRunning


Code Sample - C#

PNConversionItem resultItem = null;
resultItem = PNConverter.ConvertFile(@"C:\Test\File.pdf",
                                     true, // overwrite existing
                                     false, //  do not remove file ext
                                     false, // do not create log
                                     "TIFF 200dpi OptimizedColor",
                                     null,         // no custom user settings
                                     String.Empty, // not using DCOM
                                     String.Empty, // use default working folder
                                     String.Empty); // do not use custom log folder


Code Sample - VB.NET

Dim resultItem As PNConversionItem
resultItem = Nothing
resultItem = PNConverter.ConvertFile("C:\Test\File.pdf", _
                                     "C:\Test\Output", _
                                     "ConvertedFromPDF", _
                                     True, _
                                     False, _
                                     False, _
                                     "TIFF 200dpi OptimizedColor", _
                                     String.Empty, _
                                     String.Empty, _
                                     Nothing, _
                                     String.Empty, _
                                     String.Empty, _