Details about using the Muhimbi PDF Converter Services Online from .NET, specifically C#, can be found below. If you prefer to bypass these wrapper libraries, and rather send JSON code to the REST based service directly, then please see the section containing raw JSON examples
If a cloud-based service is not suitable to your needs (e.g. for security or regulatory reasons), and you have the ability to deploy software to your own (Windows) server, then check out the Muhimbi PDF Converter Services and this sample code.
Prerequisites for using the PDF Converter in combination with C# are as follows:
- .NET framework v4.0 and later (or mono 3.0 and later)
The PDF Converter client has the following dependencies:
These dependencies are shipped alongside our libraries. However, if you integrate our software in an existing product / solution that utilise the same dependencies, then make sure the version numbers are correct.
Exact deployment and configuration steps for the various platforms vary slightly. The ones for Linux, tested with Ubuntu, and Windows are provided below.
There are multiple options for executing C# code on Linux, the examples provided in this section use mono
.
sudo apt-get install mono-devel
This single install is sufficient for executing code that use our pre-built libraries.
If, for whatever reason, you need to renegerate and / or recompile the client then you may need to run the following commands to make sure nuget
works without error..
sudo mozroots --import --machine --sync
sudo certmgr -ssl -m https://go.microsoft.com
sudo certmgr -ssl -m https://nugetgallery.blob.core.windows.net
sudo certmgr -ssl -m https://nuget.org
If you are a Windows developer, the appropriate .NET framework version is most likely already installed on your system. In case it is not, install it as described here.
With the prerequisites in place, install the PDF Converter's client libraries using one of the methods described below.
Time is precious, so with that in mind, the easiest way to get going is to download the pre-generated client libraries and unzip them to a location in your project. Add the extracted DLLs as a reference in your project.
❗ This is an advanced topic, most developers do not need to generate the client from scratch ❗
If the pre-generated client libraries are not suiting your needs, then you may want to manually generate them. If you need more control over namespaces, or need to target a specific .NET framework version, then this is the way forward.
All the PDF Converter's client libraries are generated from the Swagger API definition file using swagger-codegen.
You can either download a precompiled version of swagger-codegen
or build it from scratch.
Download the precompiled version as follows:
wget https://oss.sonatype.org/content/repositories/releases/io/swagger/swagger-codegen-cli/2.2.2/swagger-codegen-cli-2.2.2.jar -O swagger-codegen-cli.jar
java -jar swagger-codegen-cli.jar help
This downloads version 2.2.2 and, assuming all is well, shows a brief help section. As newer versions are released from time to time, you may want to check what the latest version number is.
If, rather than taking a 'fixed-in-time' precompiled version of swagger-codegen
, you prefer the very latest version then you can compile it as described below.
To build from source, you need the following installed and available in your $PATH:
- JDK 7 or 8
- Apache maven 3.3.3 or greater
Instructions for Linux (Tested in Ubuntu) are as follows.
sudo apt-get install default-jdk
sudo apt-get install maven
git clone https://github.com/swagger-api/swagger-codegen
cd swagger-codegen
mvn clean package
This installs the Java Development Kit, the Maven build system, downloads the latest swagger-codegen
source and builds it. Assuming the build process completes without error, swagger-codegen-cli.jar
can be found under modules/swagger-codegen-cli/target/
.
Instructions are correct at the time of writing, but for the latest details about building codegen, compiling on different platforms, or downloading a pre-compiled version of swagger-codegen-cli.jar
, see codegen's Readme file.
Regardless of swagger-codegen-cli.jar
being downloaded or compiled, the .NET libraries can now be generated as follows:
java -jar swagger-codegen-cli.jar \
generate \
-i https://api.muhimbi.com/api-docs/v1/swagger.json \
-l csharp \
-o MuhimbiPDFOnline-client
You may need to adjust the path to the jar file.
The command provided above generates the C# client using the default settings, including a unit-test framework and incomplete documentation. As this is of no use to us, and we need to tweak some other settings as well, you can find the exact command we used in generate-client.sh
Once the client code has been generated it must be build using the C# compiler. The commands for carrying out the build can be found in client\build.bat
(Windows) and client\build.sh
(Linux). You may need to make some changes to suit your requirements.
For a quick-and-dirty way to generate client libraries for the language of your choice, use the web based editor.swagger.io
system.
- Open editor.swagger.io
- From the
File
menu selectImport URL
- Enter
https://github.com/raw/Muhimbi/PDF-Converter-Services-Online/master/swagger/v1/muhimbi-pdf-online-swagger.json
- From the
Generate Client
menu select the language of your choice.
Sample code, and related files, for the various facilities provided by this service can be found below. It is recommended to copy all samples to your local system using one of the following options:
-
Git: Use the following command to clone the entire repository to your system. This will download all files associated with this repository, and is most likely overkill, but it is the only easy way to download files using Git. Once downloaded, you can find the examples under the
clients/v1/csharp/samples
folder.git clone https://github.com/Muhimbi/PDF-Converter-Services-Online/
-
SVN: A common trick to download only part of a Git repository is to use
svn
. Download only the C# client and sample code using the following command.svn export https://github.com/Muhimbi/PDF-Converter-Services-Online/trunk/clients/v1/csharp
-
ZIP: Download a ZIP archive of the entire repository. Once downloaded, you can find the examples under the
clients/v1/csharp/samples
folder.
An example is provided for each individual REST endpoint. A full overview can be found below.
Sample | Description |
---|---|
convert | Convert a single file to PDF or other supported output format. |
convert_html | Convert an HTML fragment, or URL, to PDF. |
merge_to_pdf | Combine multiple files, and URLs, into a single PDF. |
merge_to_pdf (SharePoint) | Combine multiple SharePoint files (by path), and URLs, into a single PDF. |
ocr_pdf | Convert a scan, fax or other image into a searchable PDF. |
ocr_text | Use OCR to extract text from a scan, fax or other image. |
secure_pdf | Apply security settings, passwords and restrictions to a PDF. |
split_pdf | Split a large PDF into smaller PDFs. |
watermarking | |
text_watermark | Add a simple text watermark to a PDF file. |
rtf_watermark | Add a rich text (RTF) based watermark to a PDF file. |
image_watermark | Add an image based watermark to a PDF file. |
qr_code_watermark | Add a QR Code to a PDF file. |
pdf_watermark | Add a PDF based watermark to a PDF file. |
ellipse_watermark | Add an ellipse based watermark to a PDF file. |
line_watermark | Add a line based watermark to a PDF file. |
rectangle_watermark | Add a rectangle based watermark to a PDF file. |
composite_watermark | Add a number of different watermarks to a PDF file in a single operation. |
Although the API is largely self-describing, especially when used in code editors with intellisense and code-complete, from time to time it may be easier to consult the full API documentation. An overview of the entire object model can be found in the Wiki.
If you have any questions or comments then please contact our friendly support desk.