Settings
PdfFormatProvider provides the ability to import/export PDF documents. Additionally, you can take advantage of the import/export settings that give you modification options and further fine-tuning.
Import Settings
The PdfFormatProvider class offers the ImportSettings property which allows you to modify how the content is being imported. The available import settings are listed below:
Currently, the OnDemand mode should be applied when using with viewers only.| Property | Description |
|---|---|
| ReadingMode | Gets or sets the mode for loading the document pages content on import. Introduced in R2 2020.
|
| CopyStream | Gets or sets whether to copy the document stream on import. When false and ReadingMode is OnDemand, the original stream must be kept open while the document is in use. When true, the original stream can be disposed after import, regardless of the reading mode. |
| Event | Description |
|---|---|
| UserPasswordNeeded | The event is fired when a user password is needed to open the document. The password can be specified in the PasswordNeededEventArgs.Password property. |
| OwnerPasswordNeeded | The event is fired when an owner password is needed to open the document. The password can be specified in the PasswordNeededEventArgs.Password property. |
| DuplicatedEmbeddedFileNameResolving | The event is fired when trying to resolve conflicts between the embedded file names with the same names. |
The example shows how you can create a PdfImportSettings object with the desired settings and handle the offered events:
PdfFormatProvider provider = new PdfFormatProvider();
PdfImportSettings settings = new PdfImportSettings();
settings.UserPasswordNeeded += (s, a) =>
{
a.Password = "Us3rP4ssw0rd";
};
settings.OwnerPasswordNeeded += (s, a) =>
{
a.Password = "Own3erP4ssw0rd";
};
settings.DuplicatedEmbeddedFileNameResolving += (s, a) =>
{
string myNewName = "2_" + a.Name;
if (!a.UsedNames.Contains(myNewName))
{
a.NewName = myNewName;
}
};
provider.ImportSettings = settings;Export Settings
The PdfFormatProvider class offers the ExportSettings property which allows you to modify how the content is being exported. These are the modification options you can use:
The subset export option is currently implemented only for TrueType fonts (.ttf). The default value is None. For more information on PDF/A compliance, check the PDF/A Compliance article.| Property | Description |
|---|---|
| StripJavaScriptActions | Specifies if the PDF document should strip JavaScript actions on export. Introduced in Q4 2024. The default value is false. |
| ShouldEmbedFonts (obsolete) | Specifies whether the font files should be embedded in the PDF document. The default value is true because the fonts should be embedded in the file by the PDF Standard. This means that by default the fonts are added which allows proper viewing on any device. If the fonts are not embedded and the file is viewed on a device that does not have the used fonts the font might be substituted. If the font is embedded in the PDF file, it ensures the most predictable and dependable results. As of Q2 2024 the ShouldEmbedFonts property is obsolete. Use the FontEmbeddingType property instead. |
| FontEmbeddingType | The property controls what part of the fonts will be embedded in the file offering the following options:
|
| IsEncrypted | This property specifies if the document should be encrypted. The default value is false. You can specify the encryption algorithm by setting the EncryptionType property. The supported values are AES256 and RC4. All passwords for revision 6 (AES-256) shall be based on Unicode. Preprocessing of a user-provided password consists first of normalizing its representation by applying the "SASLPrep" profile (Internet RFC 4013) of the "stringprep" algorithm (Internet RFC 3454) to the supplied password using the Normalize and BiDi options. This setting is ignored when ComplianceLevel differs from None as PDF/A compliant documents do not allow encryption. |
| UserPassword | The password to be used if the document is encrypted. The default password is an empty string. |
| OwnerPassword | The password that governs permissions for operations such as printing, copying, and modifying the document. The default password is an empty string. |
| UserAccessPermissions | Gets or sets the user access permissions. These permissions specify which access permissions should be granted when the document is opened with user access. In order to be applied, the IsEncrypted property should be set to true. This property specifies three types of user access permissions: Available UserAccessPermissions |
| ImageQuality | Specifies the quality with which images are exported to PDF. More information about how it works is available in this article. .NET Standard specification does not define APIs for converting images or scaling their quality. That is why to allow the library to export images different than Jpeg and Jpeg2000 or ImageQuality different than High, you will need to provide an implementation of the JpegImageConverterBase abstract class. This implementation should be passed to the JpegImageConverter property of the FixedExtensibilityManager. For more information check the Cross-Platform Support help article. |
| ImageCompression | Sets the desired compression for the images when exporting. You can set one of the following values of the ImageFilterTypes:
|
| StreamCompression | Gets or sets the content stream compression type. Possible Values are:
|
| ComplianceLevel | Specifies the PDF/A compliance level. It can have one of the following values:
|
| PdfA3U | Specify PDF/A-3u compliance level. |
| ShouldExportXfa | Specifies whether the PDF document should export XFA content (if any). Default value: false. Introduced in Q1 2025. |
Available UserAccessPermissions
| UserAccessPermission Type | Description |
|---|---|
| PrintingPermissionType | Sets the permissions for document printing. Possible values:
|
| ChangingPermissionType | Sets the permissions for making changes to the document. Possible values:
|
| CopyingPermissionType | Sets the permissions for document copying. Possible values:
|
The receiver of a PDF document must have the same fonts that were originally used to create it. If a different font is substituted, its character set, glyph shapes, and metrics may differ from those in the original font. This substitution can produce unexpected and unwanted results, such as lines of text extending into margins or overlapping with graphics. A PDF file can refer by name to fonts that are not embedded in the PDF file. In this case, a PDF consumer can use those fonts if they are available in its environment. This approach suffers from the uncertainties noted above.
As of Q1 2025 the PdfExportSettings offers the DocumentUnhandledException event which allows you to handle exceptions while exporting a document.
The example shows how you can create a PdfExportSettings object with the desired settings and handle unexpected errors while exporting the PDF document:
PdfFormatProvider provider = new PdfFormatProvider();
PdfExportSettings settings = new PdfExportSettings();
provider.ExportSettings = settings;
settings.StripJavaScriptActions = true;
settings.FontEmbeddingType = FontEmbeddingType.Full;
settings.ComplianceLevel = PdfComplianceLevel.PdfA2B;
settings.ImageCompression = new ImageFilterTypes[] { ImageFilterTypes.FlateDecode };
settings.ImageQuality = ImageQuality.Medium;
settings.IsEncrypted = true;
settings.UserPassword = "TelerikUser";
settings.OwnerPassword = "0wn3rP4ssw0rd";
UserAccessPermissions permissions = new UserAccessPermissions
{
Printing = PrintingPermissionType.HighResolution,
Changing = ChangingPermissionType.AnyExceptExtractingPages,
Copying = CopyingPermissionType.TextAccess,
};
settings.UserAccessPermissions = permissions;
settings.DocumentUnhandledException += (s, e) =>
{
Debug.WriteLine("The document is corrupted and cannot be exported: " + e.Exception.Message);
e.Handled = true;
};