.NET

TXTextControl.ReportingCloud is the NuGet package that calls the ReportingCloud Web API from C#. Its ReportingCloud class has a method for each endpoint, those of the two tracked-changes endpoints in its property Processing.Review: you pass .NET objects and byte arrays, and the class sends the JSON request, checks the answer and returns the documents as byte arrays. Below are the package's target frameworks, how the class authenticates, a merge example and every method with the endpoint it calls.

For a first application built step by step, follow ASP.NET Core or .NET Framework in Getting Started.

Package and Requirements

The package holds one assembly, ReportingCloudWrapper.dll, for each target framework, and its classes are in the namespace TXTextControl.ReportingCloud. A project for .NET 8 or .NET 10 gets the .NET Core 1.1 build: a .NET 10 console application compiles and runs with it. Restoring the package in a .NET 10 project reports warning NU1903, a dependency with a known vulnerability, for Newtonsoft.Json 10.0.3, Microsoft.NETCore.App 1.1.2 and Microsoft.NETCore.Jit 1.1.2. Installing an SDK explains what you can do about them, shows the other ways to install the package and checks the installation with a first call.

Install the package with the .NET CLI in the folder of your project:

dotnet add package TXTextControl.ReportingCloud

The package TXTextControl.ReportingCloud.Core was a separate build for .NET Core until the multi-target package replaced it, as the blog article ReportingCloud: One Multi-Target Wrapper for .NET, .NET Core and .NET Standard announced. Its last version, 1.200.500 of November 30, 2018, describes itself as deprecated: don't use it in new projects.

Authentication

Every method runs on an instance of ReportingCloud. Its constructor takes the credentials that the class sends with each request:

Without webApiBaseUrl, the requests go to https://api.reporting.cloud. The properties APIKey, Username, Password and WebApiBaseUrl change the values later. When APIKey holds a key, the class sends it and ignores the user name and password. Use an API key: API Keys shows how to create one, and Authentication explains both methods.

Merge a Template

The following console application merges sample_invoice.tx, the demo template in the template storage of every trial account, with one invoice record and saves the result as invoice.pdf. Create it with dotnet new console, add the package, set the environment variable REPORTINGCLOUD_API_KEY to your API key and replace the contents of Program.cs with this code:

using TXTextControl.ReportingCloud;

// Send the API key with every request
ReportingCloud reportingCloud = new ReportingCloud(
    Environment.GetEnvironmentVariable("REPORTINGCLOUD_API_KEY"));

// One record with the fields and the item block of sample_invoice.tx
var invoice = new
{
    invoice_no = "778723",
    billto_name = "Joey Montana",
    billto_companyname = "Montana, LLC",
    item = new[]
    {
        new { qty = "1", item_no = "1", item_description = "Item description 1", item_total = "2130.40" },
        new { qty = "1", item_no = "2", item_description = "Item description 2", item_total = "5543" }
    },
    total = "8210.538"
};

MergeBody mergeBody = new MergeBody
{
    MergeData = new[] { invoice },
    MergeSettings = new MergeSettings { DocumentTitle = "Invoice 778723" }
};

try
{
    // Merge the stored template and return the documents as byte arrays
    List<byte[]> documents = reportingCloud.MergeDocument(
        mergeBody, "sample_invoice.tx", ReturnFormat.PDF);

    File.WriteAllBytes("invoice.pdf", documents[0]);
    Console.WriteLine("invoice.pdf has been written.");
}
catch (ArgumentException exception)
{
    // The message is the response body of the failed request
    Console.WriteLine(exception.Message);
}

The code works as follows:

• MergeBody is the request body. MergeData holds the records, any object that serializes to a JSON array; Template can hold a template as a byte array instead of a template name; MergeSettings sets merge options and document properties.
• MergeDocument sends the request to POST /v1/document/merge. Its parameters after the body are templateName (null by default), returnFormat (ReturnFormat.PDF), append (true), which combines several records into one document, and test (false).
• The method returns a List<byte[]> with one entry for each created document. ReturnFormat has the values PDF, PDFA, DOC, DOCX, RTF, TX, HTML and TXT.

Merge Settings describes every option of MergeSettings.

How Merge Data Is Serialized

The class writes MergeData with Json.NET and a camel-case naming strategy: the capital letters at the start of each property name and dictionary key become lowercase. A property InvoiceNo is sent as invoiceNo and ID as id, while invoice_no stays as it is. Give your properties the names of the merge fields, as the anonymous type above does, so that the JSON keys match the template. Merge Data describes the structure of records, fields and blocks.

ReportingCloud Methods

MergeDocument, AppendDocument, ConvertDocument and FindAndReplaceDocument take a test argument, the test parameter of the Web API: a test run adds a "TEST MODE" watermark, and a Free account can't use it. On a trial account, test runs of convert and append aren't counted against the document quota, and test runs of merge and find and replace are.

The methods add template names, the text of CheckText and the word of GetSuggestions to the query string without encoding them. A value with & or # arrives cut off, so encode such a value with Uri.EscapeDataString before you pass it.

Request Objects

GetDocumentThumbnails and GetTemplateThumbnails take an ImageFormat: JPG, PNG, BMP or GIF.

Platform Differences

The builds for the three target frameworks differ in these members:

Errors

The methods are synchronous: each one waits for the response before it returns. When the Web API answers with an error, the method throws an ArgumentException whose Message is the response body; the HTTP status code isn't passed on. A request that gets no answer, such as one to an unreachable server, throws an AggregateException that holds the HttpRequestException. Errors and Status Codes lists the status codes and their causes, and its section Handle Errors in the SDKs tells the causes apart in code.

API Documentation and Source

• API documentation. The ReportingCloud .NET Wrapper API Documentation describes every class, property and method of the namespace TXTextControl.ReportingCloud.
• Source code. The repository TextControl/TXTextControl.ReportingCloud.DotNet holds the source under a BSD license and unit test projects for .NET Framework and .NET Core, which need the credentials of an account. Its last change to the code is from September 2, 2019, the day version 1.205.500 was published.

Related Pages

• SDKs: the SDKs compared, with their status.
• Installing an SDK: add the NuGet package to a project.
• ASP.NET Core: a web application that merges a template with this package.
• Authentication: API keys and Basic authentication.
• Web API: the endpoints the methods call.