SDK Example 8: Upload a Template Package to the HotDocs Web Service

When using the HotDocs Web Service, you first need to upload a HotDocs Template Package to the service before users can interact with the HotDocs Interview and assemble documents. In this example, you will learn how to:

  • Connect to the HotDocs Web Service
  • Upload a Template Package file to the service

Full source code for this example is available at the bottom of the page.

Example Source Code on GitHub

The SdkExample8WebServiceUpload example project is available on GitHub, in the HotDocs-Samples repository.

Prerequisites

Before you start the examples, you must Set up the HotDocs Development Environment. The examples require:

  • HotDocs Server
  • HotDocs Web Service
  • HotDocs Open SDK

To install the HotDocs Web Service, see the HotDocs Web Service Installation Guide.

1. Create a Visual Studio Project for Example 1

Before you begin the example, create a new Console Application project named SdkExample8WebServiceUpload. You will use this solution and project to create the first example.

3. Create the File Content

When using the Web Service, you will interact with a HotDocs Package File (.hdpkg). This package is created when a template file is uploaded from HotDocs Developer. It contains several files used to display content in a HotDocs interview and create a completed document. It is from a HotDocs Package File that you will retrieve the HotDocs template to assemble a document.

3.1 Copy the example package files to a suitable folder

In these examples, you will use an existing HotDocs Package file, HelloWorld.hdpkg, that contains a sample HotDocs Template. To use this Package file in the examples:

  1. Copy the HelloWorld.hdpkg package file from the HotDocs Integration Examples > Example Files folder in the HotDocs-Samples project on GitHub.
  2. Copy the file to C:\temp\. This is the directory from which you will access the package file throughout the examples.

3.2 Upload a Template Package with a File Name

First, you will retrieve the HotDocs Template Package file. For this file to be uploaded to the service, it must be converted to a file stream. To do this, edit the WebServiceExample1Upload.cs file in the project. Create a new method, CreateFileContent, to return the steam content:

private static StreamContent CreateFileContent(string filePath)
{
}

Next, read the file from disk:

const string filePath = @"C:\temp\HelloWorld.hdpkg";
var stream = File.OpenRead(filePath);

Now that the file content has been retrieved from disk, it must be converted to a stream:

var fileContent = new StreamContent(stream);

After the file content is converted to a stream, add the correct content disposition headers to the steam, Name and FileName

fileContent.Headers.ContentDisposition = new ContentDispositionHeaderValue("form-data")
{
        Name = "\"files\"",
        FileName = "\"" + Path.GetFileName(filePath) + "\""
};

Finally, you can then return the fileContent. This will be used later in the example. The complete method looks like this:

private static StreamContent CreateFileContent()
{
        const string filePath = @"C:\temp\HelloWorld.hdpkg";
        var stream = File.OpenRead(filePath);
        
        var fileContent = new StreamContent(stream);
        fileContent.Headers.ContentDisposition = new ContentDispositionHeaderValue("form-data")
        {
                Name = "\"files\"",
                FileName = "\"" + Path.GetFileName(filePath) + "\""
        };
        return fileContent;
}

 

3.3 Create the File Content without a File Name (optional)

If you do not want to use a file name when uploading the template package, you can use the following method as an alternative to the method above.

private static StreamContent CreateFileContentNoDisposition(Stream stream)
{
        var fileContent = new StreamContent(stream);
        return fileContent;
}

4. Create the Http Request

To upload the File Content to the service, you must create an HttpRequestMessage that contains the content and other appropriate information. To do this, create a new method, CreateHttpRequestMessage:

private static HttpRequestMessage CreateHttpRequestMessage()
{
}

Next, create a new HttpRequestMessage with the following attributes:

  • RequestUri – the URL of the Web Service, with a unique package ID ("7A7BF8B9-C895-4BC9-BC1A-44E61D6008A2") appended. This ID identifies the template package when you access it in later examples. If you changed the machine name and port number of the Web Service during installation, substitute the correct values in the URL: http://machine_name:port_number/HDSWEBAPI/api/HDCS/0/7A7BF8B9-C895-4BC9-BC1A-44E61D6008A2
  • Method – use HttpMethod.Put to send the request to the Web Service and store the content
  • Content – the file content retrieved from the CreateFileContent method created above

The request looks like this:

var request = new HttpRequestMessage
{
        RequestUri = new Uri("http://localhost:80/HDSWEBAPI/api/HDCS/0/7A7BF8B9-C895-4BC9-BC1A-44E61D6008A2"),
        Method = HttpMethod.Put,
        Content = CreateFileContent(),
};

Finally, add a new attribute to the Content Headers, TryAddWIthoutValidation:

request.Content.Headers.TryAddWithoutValidation("Content-Type", "application/binary");

The request can now be returned. This will be used in the next step of the example. The final method looks like this:

private static HttpRequestMessage CreateHttpRequestMessage()
{
        var request = new HttpRequestMessage
        {
                RequestUri = new Uri("http://localhost:80/HDSWEBAPI/api/HDCS/0/7A7BF8B9-C895-4BC9-BC1A-44E61D6008A2"),
                Method = HttpMethod.Put,
                Content = CreateFileContent(),
        };
        request.Content.Headers.TryAddWithoutValidation("Content-Type", "application/binary");
        return request;
}

5. Connect to the Service

To connect to the HotDocs Web Service, you must create a HttpClient. This is used for sending requests to the Service and receiving responses. In the Main method of the project, create a new HttpClient object:

var client = new HttpClient();

Next, retrieve the request message using the CreateHttpMessage method created in the previous step:

var request = CreateHttpRequestMessage();

You can now send the request to the service using the HTTP Client and retrieve the result:

var result = client.SendAsync(request).Result;

Write the result status code to the console, to confirm that the request has been received and the Template Package File has been uploaded:

Console.WriteLine("FinishedUploading. Status Code: " + result.StatusCode);
Console.ReadLine();

The code is now ready to test.

6. Test

To test uploading a Template Package file to the service:

  1. Set the current project as the Startup Project (Right-click the SdkExample8WebServiceUpload project in Visual Studio and select Startup Project from the drop-down menu)
  2. Press F5 to run the Project. The console opens.
  3. Once the template finishes uploading, you will see the message "Finished Uploading. Status Code: Created."
  4. Navigate to the directory (by default, this is C:\Program Files (x86)\HotDocs Server\HDSWebAPI\Content). You will see a directory named 7A7BF8B9-C895-4BC9-BC1A-44E61D6008A2. This directory contains the HelloWorld.hdpkg HotDocs Template Package file.

Example Source Code (C#)

using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
namespace SdkExample8WebServiceUpload
{
    internal class SdkExample8WebServiceUpload
    {
        private static void Main()
        {            
            //Create Http Client, to send the request and receive the response
            var client = new HttpClient();
            //Create Http Request
            var request = CreateHttpRequestMessage();
            //Send request and receive result
            var result = client.SendAsync(request).Result;          
            Console.WriteLine("Finished Uploading. Status Code: " + result.StatusCode);
            Console.ReadLine();
        }
        //Create new Http Request
        private static HttpRequestMessage CreateHttpRequestMessage()
        {
            var request = new HttpRequestMessage
            {
                RequestUri = new Uri("http://localhost:80/HDSWEBAPI/api/HDCS/0/7A7BF8B9-C895-4BC9-BC1A-44E61D6008A2"),
                Method = HttpMethod.Put,
                Content = CreateFileContent(),
            };
            request.Content.Headers.TryAddWithoutValidation("Content-Type", "application/binary");
            return request;
        }
        //Upload a template with a filename
        private static StreamContent CreateFileContent()
        {
            const string filePath = @"C:\temp\HelloWorld.hdpkg";
            var stream = File.OpenRead(filePath);
            var fileContent = new StreamContent(stream);
            fileContent.Headers.ContentDisposition = new ContentDispositionHeaderValue("form-data")
            {
                Name = "\"files\"",
                FileName = "\"" + Path.GetFileName(filePath) + "\""
            };
            return fileContent;
        }
        //Upload a template without a filename
        private static StreamContent CreateFileContentNoDisposition(Stream stream)
        {
            var fileContent = new StreamContent(stream);
            return fileContent;
        }
    }
}