I’ve seen several examples of creating document converters in SharePoint that convert documents to PDF format, using tools like Aspose and other print-based solutions.
I recently did a proof of concept for a customer that used a different product, Outside In PDF Export from Oracle. This is an interpretive converter that can take a slew of file formats (including MS Office) and automatically convert them into a PDF file. If you aren’t familiar with PDF conversion, there are two basic kinds:
- Print based conversion – This is the Acrobat Distiller approach. Uses a printer driver that accepts the PostScript output from an application (such as Microsoft Word), and converts it to PDF. This approach results in the most accurate conversions, but is hardest to automate because it involves opening the native application and automating its “Print” functionality.
- Interpretive conversion – This is an approach that reads the contents of a native file format and translates the contents into PDF format. This results in potentially less accurate conversions, but is much easier to automate.
Outside In, and in particular the PDF Export SDK, is an EXE and set of DLLs that contains logic to covert over 400 different file types to PDF. In combination with Transformation Server (a web services wrapper to PDF Export), you can create SharePoint Document Converters that will convert your documents to PDF format.
How I Did It
For the proof of concept, I followed these steps to get it working
- Download PDF Export, Transformation Server, and SrvAny.exe.
- Install and Configure the Transformation Server and Web Service
- Develop and Install the Document Converter
Download of PDF Export 8.3.0 and Transformation Server 8.2.0
You can download both products here:
http://www.oracle.com/technology/products/content-management/oit/oit_dl_otn.html
You’ll have to register with an Oracle account to get it, but it is a freely available trial version, and does not appear to have any trial expiration limitations.
You will also need SrvAny.exe to run Transformation Server as a Windows Service. I found this site that had a download:
http://www.tacktech.com/display.cfm?ttid=197
Install and Configure the Transformation Server and Web Service
Extract the contents of the Transformation Server zip you downloaded to a folder on your server that will do the document conversions (e.g. “C:PDFConverter”). There will be a bunch of dlls, some wsdl files (we’ll use those later), some EXE’s (which are run as a service), and some XML config files.
Transformation Server doesn’t really know anything about PDF generation, it is just a web service wrapper, so we’ll need to place the PDF Export library into our folder so it can use it. Extract the contents of PDF Export 8.3.0 to a separate folder on your machine. Grab every DLL in the root folder, as well as exporter.exe, px.cfg, and cmmap000.bin and copy those files into “C:PDFConverter”.
Open the file called server_startup.xml in “C:PDFConverter”. This configures the service to listen on a specific port and hostname/ip address. I went ahead and changed the port, but you can leave it as is if you wish, just make note of the port for later:
<!--Connections are the TCP/IP socket connections that the server accepts from clients.-->
<connectionsInfo xsi:type="tss:ConnectionsInfo">
<!--The serverName is the host name, or dotted IP address that the server will use when establishing its presence on the network.-->
<serverName xsi:type="xsd:string">localhost</serverName>
<!--The port is the TCP/IP port that the server will establish a listener on for accepting connections.-->
<port xsi:type="xsd:unsignedInt">9000</port>
<!--The server will disconnect idle connections that have remained idle for too long. The activityTimeout sets the period of time a connection must be idle before it will be disconnected by the server.-->
<activityTimeoutSecs xsi:type="xsd:unsignedInt">1800</activityTimeoutSecs>
</connectionsInfo>
Go ahead and double-click tsmanager.exe to make sure it is working. It should open a console window and show you what host/port it is listening on.
Press Ctrl + C to quit.
Now we need to run this program as a service, so that it is always available, even when nobody is logged on to the server. Place instsrv.exe and srvany.exe in your C:PDFConverter folder. Run the following command prompt:
C:PDFConverter>instsrv.exe "Transformation Server" c:PDFConvertersrvany.exe
The service was successfuly added! Make sure that you go into the Control Panel
and use the Services applet to change the Account Name and Password that this
newly installed service will use for its Security Context.
Open regedit, and browse to HKEY_LOCAL_MACHINESYSTEMCurrentControlSetServicesTransformation Server.
Create a new key called Parameters, and add a new string value inside this key called Application, with a value of C:PDFConvertertsmanager.exe.
Go to the services console and start the Transformation Server service. Optionally, you can also go to the Properties for this service account, and change the Identity that this service runs under.
Develop the Document Converter
Create a new .NET C# console application project and solution from within Visual Studio 2008, called PDFConverter.
Right-click the project in Solution Explorer and choose Add Service Reference…
Since the wsdl files for Transformation Server are not compliant with WCF services, choose the Advanced… button on the Add Service Reference dialog, and then choose the Add Web Reference… button to add a .NET 2.0 style web service reference. In the Add Web Reference dialog, enter the path to the wsdl file: C:PDFConvertertransform_net_2005.wsdl. Hit Go.
Once your web reference has resolved, enter TransformationServer in the Web reference name box and click the Add Reference button.
Open your Properties/Settings.settings file. There will be one setting in the file for the web service URL. Change this to the right hostname/port in your server_settings.xml for Transformation Server. Make sure to include a trailing “/transform” on the end, e.g.:
https://grey-frog-177824.hostingersite.com/transform
A document converter is just a console EXE that is called by SharePoint with command line arguments, so we’ll setup our console app to handle the arguments. In Program.cs, before static void Main, add the following code (taken from the WSS SDK here):
#region Argument Handling Data
private enum ArgumentCode
{
Help,
InputFile,
OutputFile,
LogFile,
ConfigFile
}
private struct ArgumentPair
{
public ArgumentPair(ArgumentCode c, string s)
{
this.argType = c;
this.argFlagString = s;
}
public ArgumentCode argType;
public string argFlagString;
}
private static ArgumentPair[] PossibleArguments = new ArgumentPair[] {
new ArgumentPair(ArgumentCode.Help, "-?"),
new ArgumentPair(ArgumentCode.Help, "-help"),
new ArgumentPair(ArgumentCode.InputFile, "-in"),
new ArgumentPair(ArgumentCode.OutputFile, "-out"),
new ArgumentPair(ArgumentCode.LogFile, "-log"),
new ArgumentPair(ArgumentCode.ConfigFile, "-config"),
};
private static Dictionary<ArgumentCode, string> actualArguments = new Dictionary<ArgumentCode, string>();
#endregion
/// <summary>
/// Prints out the usage help to the console.
/// </summary>
static void PrintUsage()
{
Console.WriteLine("Usage: {0} -in <inputfilename> -out <outputfilename> -config <configfilename> [-log <logfilename>]",
Assembly.GetExecutingAssembly().ManifestModule.Name);
}
Add the following code inside static void Main:
#region Argument Handling Code
// Read arguments.
for (int i = 0; i < args.Length; i++)
{
bool argumentValid = false;
foreach (ArgumentPair ap in PossibleArguments)
{
if (String.Compare(ap.argFlagString, args[i], StringComparison.OrdinalIgnoreCase) == 0)
{
switch (ap.argType)
{
case ArgumentCode.Help:
PrintUsage();
return;
case ArgumentCode.InputFile:
case ArgumentCode.OutputFile:
case ArgumentCode.ConfigFile:
case ArgumentCode.LogFile:
if (i + 1 < args.Length)
{
actualArguments[ap.argType] = args[i + 1];
i++;
argumentValid = true;
}
break;
}
break;
}
}
if (!argumentValid)
{
Console.WriteLine("unknown argument {0}", args[i]);
PrintUsage();
return;
}
}
// Validate arguments.
if (!actualArguments.ContainsKey(ArgumentCode.InputFile) ||
String.IsNullOrEmpty(actualArguments[ArgumentCode.InputFile]) ||
!actualArguments.ContainsKey(ArgumentCode.OutputFile) ||
String.IsNullOrEmpty(actualArguments[ArgumentCode.OutputFile]) ||
!actualArguments.ContainsKey(ArgumentCode.ConfigFile) ||
String.IsNullOrEmpty(actualArguments[ArgumentCode.ConfigFile]))
{
Console.WriteLine("required argument missing");
PrintUsage();
return;
}
#endregion
Now that the command line arguments can be parsed, it is time to use the web service and do the document conversion. The Transformation Server download contained some code samples for C#, and I was able to basically use as-is, only modifying the input and output file paths. After the argument handling code in static void Main, add the following code:
TransformationServer.transform t = new TransformationServer.transform();
TransformationServer.IOSpec source = new TransformationServer.IOSpec();
source.spec = new TransformationServer.stringData();
source.spec.base64 = false;
source.spec.charset = TransformationServer.CharacterSetEnum.windows1250;
source.spec.str = actualArguments[ArgumentCode.InputFile];
source.specType = "path";
TransformationServer.IOSpec sink = new TransformationServer.IOSpec();
sink.spec = new TransformationServer.stringData();
sink.spec.base64 = false;
sink.spec.charset = TransformationServer.CharacterSetEnum.windows1250;
sink.spec.str = actualArguments[ArgumentCode.OutputFile];
sink.specType = "path";
string outputFormat = "pdf";
string optionSet = "";
TransformationServer.Option[] options = new TransformationServer.Option[0];
TransformationServer.stringData resultMsg;
TransformationServer.IOSpec[] resultDocs;
UInt32 result = t.Transform(source, sink, outputFormat, optionSet, options, out resultMsg, out resultDocs);
Console.WriteLine("The result is {0} {1}", result, resultMsg.str);
foreach (TransformationServer.IOSpec ios in resultDocs)
{
ASCIIEncoding encoding = new ASCIIEncoding();
string constructedString = encoding.GetString(Convert.FromBase64String(ios.spec.str));
Console.WriteLine(" {0}", constructedString);
}
Most of this code is cut-and-paste from the sample, and we are just swapping the input file path (source.spec.str) and output file path (sink.spec.str) with the arguments from the command line.
Installing the Converter
To install the converter, you need to create a feature file, install the feature, and place the converter EXE in the proper directory.
Create a feature.xml file and add the following:
<Feature xmlns="http://schemas.microsoft.com/sharepoint/"
Id="{9E2A5231-0D81-4de8-8504-36A61026680E}"
Title="PDF Converter"
Description="PDF Converter."
Scope="WebApplication">
<ElementManifests>
<ElementManifest Location="Elements.xml"/>
<ElementFile Location="PDFConverter.exe"/>
</ElementManifests>
</Feature>
Create an Elements.xml file, and add the following code. You can create as many document converter nodes as you need for each file type you want to convert (just make sure each has a unique guid).
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<DocumentConverter Id="{513130EB-A1BC-46d3-919C-1E00B6BCA742}"
Name="DOCX to PDF Converter"
App="PDFConverter.exe"
From="docx"
To="pdf"
/>
<DocumentConverter Id="{E7374437-157E-4fb4-A4E9-A19026BAE17A}"
Name="VSD to PDF Converter"
App="PDFConverter.exe"
From="vsd"
To="pdf"
/>
</Elements>
Place both these files in a folder called PDFConverter in your …/12/TEMPLATE/Features folder, and use stsadm to activate the feature on a particular web application.
C:Program FilesCommon FilesMicrosoft Sharedweb server extensions12BIN>stsadm
-o installfeature -name PDFConverter
Operation completed successfully.
C:Program FilesCommon FilesMicrosoft Sharedweb server extensions12BIN>stsadm
-o activatefeature -name PDFConverter -url http://mossdev:8080
Operation completed successfully.
After activating the feature, go to Central Administration, Applications tab, and click the Document Conversions link. Ensure that your web application has document conversions turned on. You should see your document converters in the list at the bottom of the screen:
Since you are using a Web Service, a proxy class needs to be generated dynamically, and so you’ll need to give your SharePoint Document Conversion User Account rights to create this in C:WindowsTemp (or whatever your system temp directory is). Grant List Folder Contents and Read permissions to the Document Conversion account (usually a local machine account that starts with “HVU_”) on your Temp folder.
The Document Conversion service stores temporary documents in the following folder: C:Program FilesMicrosoft Office Servers12.0BINHtmlTrLauncher. By default, this folder only grants the Document Conversion User account access. Since the Transformation Server windows service is running under its own account, you need to give this account access to the folder. Grant the account that your Transformation Server windows service is running under Read and Write access to this folder.
The last step involves copying over your compiled console EXE and exe.config file into the following SharePoint folder (the actual path may vary depending on your setup, but you should be able to find the TransformApps folder):
C:Program FilesMicrosoft Office Servers12.0TransformApps
Results
Navigate to your SharePoint site. Upload a document into your document library (make sure it is a file extension that you’ve configured in your Elements.xml file). Open the drop down menu and choose Convert Document. Your document converter should appear in the list. Run the conversion. After around a minute if you refresh your document library and all went well, you should see your PDF file in the library.
Here is a picture of a generated Visio document in PDF format, not too bad:
