39
PDF Converter - Installation & Administration Guide
PDF Converter - Installation & Administration Guide - Version 8.0 - 15/10/15
© Copyright 2015, Muhimbi Ltd
Page 65 of 84
In the
PDF Converter’s Central Administration page
enable the new Word
Automation Service
and click ‘Validate Settings’.
The XML in the configuration file should now look something like this:
<!--<add key="WordProcessing"
description="Word Processing (e.g. MS-Word, RTF, TXT)"
fidelity="Full"
supportedExtensions="doc,docx,docm,rtf,txt,wps,xml,eml,odt,ott,mht,html,htm"
supportedOutputFormats="xps,pdf,doc,docx,rtf,txt,html,mht,xml,odt"
type="Muhimbi.DocumentConverter.WebService.WordProcessorConverterFullFidelity,
Muhimbi.DocumentConverter.WebService, Version=1.0.1.1, Culture=neutral,
PublicKeyToken=c9db4759c9eaad12" /> -->
<add key="WordAutomationServiceConverter"
description="Word Automation Service (e.g. MS-Word, RTF, MHT)"
fidelity="Full"
supportedExtensions="docx,docm,dotx,dotm,doc,dot,rtf,htm,html,mht,mhtml,xml"
supportedOutputFormats="docx,docm,doc,mht,pdf,rtf,xml,xps"
type="Muhimbi.DocumentConverter.WebService.WordAutomationServiceConverter,
Muhimbi.DocumentConverter.WebService, Version=1.0.1.1, Culture=neutral,
PublicKeyToken=c9db4759c9eaad12"
parameter="Service Name=;TempDocLibPath=http://your site/sites/your web
app/Temp"/>
Once the service has restarted try converting an MS-Word file. If you are
encountering any errors then please look in the Windows Application Event
Log and / or SharePoint’s
ULS logs. We have tried to make the errors as
descriptive as possible.
A common problem when using WAS is that it takes a long time to spin-up,
making it appear to our software that it is hanging, resulting in a not
responding error. If this is the case in your environment then we recommend
changing the value of the MAX_HUNG_COUNT
value in the PDF Converter’s
configuration file from 15 (seconds) to 45.
C# Word - Paragraph Processing in C#.NET Add references: C# users can set paragraph properties and create content such as run, footnote, endnote and picture in a paragraph.
add png to pdf preview; add image to pdf form
53
PDF Converter - Installation & Administration Guide
PDF Converter - Installation & Administration Guide - Version 8.0 - 15/10/15
© Copyright 2015, Muhimbi Ltd
Page 66 of 84
Appendix - STSADM Commands
Wherever possible the PDF Converter for SharePoint provides a User
Interface for specifying settings. However, some settings are so infrequently
used that creating special screens for them just leads to confusion.
Instead a number of ‘
stsadm
’ commands
are provided to tweak these settings.
This section lists all available settings, t
hey all use the standard ‘
STSADM -o
setproperty
’ syntax. Please note that the value can be deleted by specifying
nothing after the ‘
-
pv’ switch.
Please note that all these settings are global and apply to all Web Applications
and Site Collections.
Alternative Check-in Behaviour (version 6.1.0.66+)
The default behaviour of the PDF Converter’s SharePoint front end is to
always check-
in files on document libraries that don’t explicitly require a
check-out to be performed first, even when mandatory data is missing. If this
is not desirable and you wish files with missing meta-data to remain checked
out then issue the following command on one of your farm’s SharePoint
servers:
stsadm.exe -o setproperty -pn Muhimbi.SharePoint.DocumentConverter.PDF
.CheckOutWhenRequiredFieldsEmpty -pv true
For more details on the topic of check-in behaviour see this KB Article
.
Skip certain fields when copying meta-data (version 6.1.0.66+)
The PDF Converter for SharePoint provides a number of facilities to copy
meta-data between files. Although we automatically skip certain fields,
including calculated fields, some custom fields you may never want to copy.
This very much depends on your own requirements, but suffice to say that you
can specify a list of fields to ignore when copying meta-data. For example the
following command will make sure that the Title and User fields are never
copied (unless explicitly listed in the Copy Meta-Data workflow activity).
stsadm.exe -o setproperty -pn Muhimbi.SharePoint.DocumentConverter.PDF
.SkipMetaDataFieldNames -pv Title;User
Always send PDF files to the Conversion Service (version 6.0.0.62+)
By default Muhimbi’s SharePoint front end sof
tware does not send any files
that are already in PDF format to the conversion server. If you have written
a custom converter (See Appendix - Creating Custom Converters) that
requires PDF files to be sent to the conversion server then execute the
following command:
stsadm.exe -o setproperty -pn Muhimbi.SharePoint.DocumentConverter.PDF
.SkipPDFFiles -pv false
52
PDF Converter - Installation & Administration Guide
PDF Converter - Installation & Administration Guide - Version 8.0 - 15/10/15
© Copyright 2015, Muhimbi Ltd
Page 67 of 84
Appendix - Creating Custom Converters
The Muhimbi PDF Conversion Service allows custom converters to be added with
relative ease. This is useful for converting file types specific to your organisation or
for file types that have not (yet) been implemented by Muhimbi in the main product.
The following example describes how to replace the existing MS-Word converter,
which relies on MS-Word being present, with a simple third party converter that
works well enough for simple documents. Some programming knowledge is required.
It is also possible to use 3
rd
party executables as custom converters without any
programming, see Appendix - Invoke 3rd party Converters.
The steps are as follows:
1.
Create a new Visual Studio project, select Class Library (C#, .net 3.0) as the
template and give the project an appropriate name, e.g. CustomConverters.
2.
Add references to the following DLLs. They are located in the folder the Muhimbi
Document Conversion Service has been installed in, usually c:\Program
Files\
Muhimbi….
Muhimbi.dll
Muhimbi.DocumentConverter.WebService.dll
Muhimbi.DocumentConverter.WebService.Data.dll
System.Runtime.Serialization (Add reference from the .NET tab)
3.
Change your project’s Assembly name and default namespace to something
sensible, e.g. Muhimbi.DocumentConverter.WebService.CustomConverters. This
can be done by right-clicking on your project and selecting Properties. The
Application tab allows these settings to be changed.
4.
Delete the automatically generated class1.cs file and add a new class named
WordConverter.cs. Make sure the class definition is public.
5.
Inherit Muhimbi.DocumentConverter.WebService.AbstractDocumentConverter in
the WordConverter class and implement the members (right-click on the base
class name and select Implement Abstract Class).
6.
Add the following 2 constructors and make sure they call the base constructors.
public WordConverter() : base()
{}
public WordConverter(Stream sourceFile, OpenOptions openOptions,
ConversionSettings conversionSettings)
: base(sourceFile, openOptions, conversionSettings)
{}
49
PDF Converter - Installation & Administration Guide
PDF Converter - Installation & Administration Guide - Version 8.0 - 15/10/15
© Copyright 2015, Muhimbi Ltd
Page 68 of 84
7.
Next up, we need to implement the RunDiagnostics method. This method is
normally used to carry out an internal end-to-end conversion to verify that the
converter and all prerequisites have been installed correctly. In this test we simply
return a new DiagnosticResultItem with the Valid property set to true .
public override DiagnosticResultItem RunDiagnostics()
{
DiagnosticResultItem dri = new DiagnosticResultItem();
dri.Valid = true;
return dri;
}
8.
If we need to look further than just the file extension to determine the file type
then we can optionally override the CanConvert method and look inside the
stream (available in the _sourceFile member variable). This is not necessary for
this sample converter, but an example is provided below.
public override bool CanConvert(string[] fileExtensions)
{
// ** Do we know anything about this extension
if (base.CanConvert(fileExtensions) == false)
return false;
// ** Investigate in more detail
...implement your own...
}
9.
The next and final method to implement is the actual Convert method, which is
where all the magic happens. As it is not feasible to develop an MS-Word to PDF
converter from scratch, the sensible approach to take is to use a third party library
such as SyncFusion DocIO
or Aspose.Words
(download the archive that contains
just the DLLs). In this example we are going to use Aspose's library for
processing MS-Word files. It is not perfect, but for some documents such as
forms and simple text documents it works very well.
Copy Aspose.Words.dll into the project directory and add a reference to it. Copy
the following code into the WordConverter class.
public override Stream Convert()
{
try
{
// ** Validate as certain options are not supported by this converter
if (_openOptions.AllowMacros != MacroSecurityOption.None)
Logger.Warn("Macros are not supported by this converter.");
// ** Set the licences for Aspose.Words.
Aspose.Words.License wordLicence = new Aspose.Words.License();
61
PDF Converter - Installation & Administration Guide
PDF Converter - Installation & Administration Guide - Version 8.0 - 15/10/15
© Copyright 2015, Muhimbi Ltd
Page 69 of 84
//wordLicence.SetLicense("Enter your license in here.");
Document asposeDocument = new Document(_sourceFile, null,
LoadFormat.Auto, _openOptions.Password);
// ** Do we need to refresh the fields etc?
if (_openOptions.RefreshContent == true)
asposeDocument.Range.UpdateFields();
// ** Convert the Document to PDF and save it as a memory stream.
if (_conversionSettings.Format == OutputFormat.PDF)
{
MemoryStream convertedStream = new MemoryStream();
PdfOptions options = new PdfOptions();
// ** Specify the PDF Profile
if (_conversionSettings.PDFProfile == PDFProfile.PDF_1_5)
options.Compliance = PdfCompliance.Pdf15;
else
options.Compliance = PdfCompliance.PdfA1b;
// ** How to deal with bookmarks
if (_conversionSettings.GenerateBookmarks ==
BookmarkGenerationOption.Automatic)
options.HeadingsOutlineLevels = 9;
else if (_conversionSettings.GenerateBookmarks ==
BookmarkGenerationOption.Custom)
options.BookmarksOutlineLevel = 9;
// ** Correct the start and end pages if needed
int startPage = _conversionSettings.StartPage != 0 ?
_conversionSettings.StartPage - 1 : 0;
int pageCount = asposeDocument.PageCount - startPage;
if (_conversionSettings.EndPage != 0)
pageCount = Math.Min(_conversionSettings.EndPage - startPage,
pageCount);
// ** Carry out the actual conversion
asposeDocument.SaveToPdf(startPage, pageCount, convertedStream,
options);
return convertedStream;
}
else
{
throw new NotSupportedException("Outputformat '" +
_conversionSettings.Format +
"' not supported by this Converter.");
}
}
catch (UnsupportedFileFormatException ex)
{
throw new WebServiceInternalException(
WebServiceExceptionType.FileFormatNotSupported, ex.Message);
}
catch (Exception ex)
{
string message = "An error occurred while converting a file";
if (_openOptions != null && _openOptions.OriginalFileName != null)
message += " - " + _openOptions.OriginalFileName;
Logger.Error(message, ex);
throw new WebServiceInternalException(
WebServiceExceptionType.InternalError, message);
}
}
53
PDF Converter - Installation & Administration Guide
PDF Converter - Installation & Administration Guide - Version 8.0 - 15/10/15
© Copyright 2015, Muhimbi Ltd
Page 70 of 84
10.
Compile the project and copy the output DLL as well as Aspose.Words.dll to the
directory that holds the Muhimbi Document Conversion Service.
11.
Edit the service's config file and make the following changes:
If the file extensions for the new converter are currently handled by a
different converter then remove these extensions from the existing
converter.
Add the definition for the new converter to the config file as per the
following example. For details see 2.6.2 Fine-tuning the Document
Conversion service.
<add key="CustomWordConverter"
description="Custom MS-Word Converter"
fidelity="Full"
supportedExtensions="doc,docx"
type="Muhimbi.DocumentConverter.WebService.CustomConverters.WordConverter,
Muhimbi.DocumentConverter.WebService.CustomConverters,
Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
12.
Restart the service to activate the changes.
Net stop "Muhimbi Document Converter Service"
Net start "Muhimbi Document Converter Service"
13.
Finally test if everything is working correctly, either from:
SharePoint: Open Central Administration / Application Management /
Muhimbi Document Converter Settings (In SharePoint 2010 / 2013 this
screen is located in Central Admin / General Application Settings / Muhimbi
Document Converter Settings), verify that the new converter is added to the
list, check the tick box and click Validate Settings. If everything is working
correctly then don’t forget to save the changes using the
OK button.
Winforms Diagnostics Tool: Launch the Diagnostics Tool from the Windows
Start Menu, navigate to the WS Diagnose Tab and click the Request
Diagnostics button. Verify the new converter is listed and Valid = True.
Any errors are logged to the Windows Application Event Log.
Congratulations, you have created your first custom converter. Source code for
WordConverter.cs and the latest version of this tutorial can be found on the Muhimbi
website
.
Please note that by default Muhimbi’s SharePoint front end software does not send
any files that are already in PDF format to the conversion server. If you have written
a custom converter that requires PDF files to be sent to the conversion server then
execute the following command on one of your SharePoint Front End Servers:
stsadm.exe -o setproperty -pn Muhimbi.SharePoint.DocumentConverter.PDF.SkipPDFFiles -pv false
Exception handling
Documents you may be interested
Documents you may be interested
