.NET API

.NET API Reference — Classes, members and enumerations.

Working with file data? Import CSV or XML and create a PDF.

Assemblies and NuGet Package

TFORMer provides two managed assemblies in the TECIT.TFORMer namespace:

• TECIT.TFORMer.dll, built for .NET Framework 4.5
• TECIT.TFORMer.Std.dll for .NET Standard 2.0

The maintained .NET 8 Linux command-line sample also references TECIT.TFORMer.dll; this packaged-sample use is separate from the assembly's .NET Framework build target.

Windows setup places both assemblies in the SDK Bin directory. When .NET Framework 4.5 or later is available, setup can additionally install only TECIT.TFORMer.dll in the Global Assembly Cache (GAC).

The TFORMer NuGet package provides native Windows x86 and x64 runtimes and managed assets for .NET Framework 4.6.2 and .NET Standard 2.0. Install it from NuGet.org. The NuGet package's .NET Framework selection floor is separate from the classic assembly's .NET Framework 4.5 build target. Linux applications need the separate Linux SDK distribution.

Import CSV or XML Data

Use a file instead of creating the data records in C#. This example uses the same ProductLabel.tff layout and PDF output as the .NET Quick Start; only the source of the field values changes.

• Select the layout as before.
• Assign a JobDataCsv or JobDataXml source to job.JobData.
• Keep the PDF output settings and call job.Print().

You can run the complete file-import project or adapt your existing Quick Start project.

Read CSV Data

The supplied Data.csv contains two records. Its column names match the layout's ProductName and ArticleNumber fields:

ProductName,ArticleNumber
"Coffee 250 g","ART-1001"
"Tea 100 g","ART-1002"

With job already created and its layout selected, provide the file data:

string csvPath = Path.Combine(AppContext.BaseDirectory, "Data.csv");
job.JobData = new JobDataCsv(csvPath, ',', '"');

The comma argument selects the column separator; the double quote selects the text qualifier. For a semicolon-separated file, change only the separator argument to ';'. See CSV format details and shared field-handling rules when adapting your own data.

Read XML Data

The supplied Data.xml contains the same records. Select it with JobDataXml instead:

string xmlPath = Path.Combine(AppContext.BaseDirectory, "Data.xml");
job.JobData = new JobDataXml(xmlPath);

See supported XML structures for the file format; the same field-handling rules apply.

Run the File-Import Example

Download the complete CSV/XML example and extract it into a new directory. It includes the project, both data files and the unchanged Quick Start layout. Use the same Windows x64 and .NET 8 environment described in the Quick Start prerequisites.

Run the commands below from the extracted project directory. The project copies the layout and data files beside the executable; the snippets above therefore do not depend on the application's working directory.

dotnet restore --source https://api.nuget.org/v3/index.json
dotnet build --no-restore --configuration Release
dotnet .\bin\Release\net8.0\win-x64\TFORMerDataImport.dll csv
dotnet .\bin\Release\net8.0\win-x64\TFORMerDataImport.dll xml

Open the PDF at the printed path. It contains the Coffee and Tea labels, with article numbers ART-1001 and ART-1002. Each run creates a new folder below %TEMP%\TFORMerDataImport; earlier results remain unchanged. Without a license, evaluation markings may appear.

To try your own values, edit Data.csv or Data.xml in the project directory, keep the field names, and run the build and corresponding application command again. See the complete source for the surrounding layout setup, output selection and error handling.

Adapt the Quick Start (Optional)

If you prefer to adapt your existing Quick Start project rather than use the file-import project:

1. In its Program.cs, replace the entire block from JobDataRecordSet data = new(); through job.JobData = data; with either the CSV or the XML snippet above. Keep the layout selection, PDF output settings and error handling unchanged.
2. Rebuild with the Quick Start commands. Copy Data.csv or Data.xml, matching the chosen snippet, beside the built application in bin\Release\net8.0\win-x64. The original Quick Start project does not automatically copy these new data files.
3. Run the Quick Start's existing application command. After changing the data, update the file beside the built application before running it again.

Use a Configured Data Source

Select the ODBC source in the supplied picking-list layout, set PickingListParameter to 2, and write a PDF. The layout's stored query uses this parameter to select that picking list; the application does not supply a separate SQL statement or modify the database. For definition settings, field mappings and parameter rules, see Data Sources Defined in a Layout.

For a configured CSV source instead, adapt this program to choose the CSV file at runtime.

Before You Run

• Set up the SDK for your language, including its native runtime and matching process architecture.
• Locate (6) Samples_Picking List.tff in the SDK's Templates folder. The default Windows location is %ProgramData%\TEC-IT\TFORMer\9\Templates.
• The layout uses DSN=TFORMer_Sample;, user admin, table tbl_PickingList, and the predefined parameter PickingListParameter. Its driver and DSN must match the application's architecture.
• The sample database is ODBCReportPDF.mdb, installed under %ProgramData%\TEC-IT\TFORMer\9\Examples\Command Line\ODBCReportPDF. The sample DSN must point to this database. This particular example uses the Windows Access ODBC driver; it is not a Linux setup example.
• Choose a new PDF path in an existing writable directory. The program refuses to overwrite an existing output file.

Run the Example

Pass the full layout path and PDF path as the two command-line arguments.

Use the SDK assemblies or NuGet package as in your existing console project. Save the following program as ConfiguredSource.cs and make it the project's entry point. Run the built program with the two paths, quoted if they contain spaces.

Assign the data object to Job.JobData before printing. The using block releases the job even if output fails.

Complete Example

using System;
using System.IO;
using TECIT.TFORMer;

internal static class ConfiguredSource
{
    private static int Main(string[] args)
    {
        if (args.Length != 2)
        {
            Console.Error.WriteLine("Usage: ConfiguredSource <layout.tff> <output.pdf>");
            return 1;
        }
        try
        {
            string layout = Path.GetFullPath(args[0]);
            string output = Path.GetFullPath(args[1]);
            if (!File.Exists(layout))
                throw new FileNotFoundException("Layout not found", layout);
            if (File.Exists(output))
                throw new IOException("Choose a new output file: " + output);

            using (Job job = new Job())
            {
                job.RepositoryName = layout;

                // Select the stored definition and override its parameter.
                JobDataDataSource data = new JobDataDataSource("ODBC");
                data.ParameterValues.Add("PickingListParameter", "2");
                job.JobData = data;

                // Generate a PDF; no physical printer is used.
                job.PrinterType = PrinterType.PdfFile;
                job.OutputName = output;
                job.Print();
            }
            if (!File.Exists(output) || new FileInfo(output).Length == 0)
                throw new IOException("No PDF was created: " + output);
            Console.WriteLine("Created PDF: " + output);
            return 0;
        }
        catch (Exception error)
        {
            Console.Error.WriteLine(error.Message);
            return 1;
        }
    }
}

Check the Result

Open the PDF at the path reported by the program. Check that it contains picking list 2, not the layout parameter's default selection 1. Evaluation output may include a demo marking.

If no PDF is produced, check the reported error, layout path, ODBC driver, DSN and database before changing the parameter value. For the other data-input mechanisms, see Providing Job Data.

Find Data Fields Used by a Layout

Use the repository API to inspect a layout's data fields before preparing input data:

1. Select the layout
   Open the .tff or .tfr with Repository. For a stand-alone .tff, use Repository.GlobalProject and its FirstFormLayout. For a .tfr, select the project with GetProject(...) and its layout with GetFormLayout(...).
2. Enumerate the project fields
   Start with Project.FirstDataField and follow DataField.Next until it returns null. This visits the selected project's fields, not every project in the repository.
3. Check each field's use
   Call FormLayout.GetDataFieldUsage(field.Name). DataFieldUsage.Normal identifies ordinary fields used by that layout; calculated, system and unused fields have separate classifications. This is not a list of mandatory input columns.

See the field-usage example and DataFieldUsage values.

Additional Samples

Create a PDF from ODBC Data

The following example uses direct ODBC input: the application supplies the connection string and SQL query, then creates a PDF file. To use a query already defined in the layout instead, see Use a Configured ODBC Source.

using System.IO;
using TECIT.TFORMer;

using (Job job = new Job())
{
    job.RepositoryName = "FILENAME_OF_YOUR_FORMLAYOUT.tff";
    job.JobData = new JobDataOdbc(
        "DSN=TFORMer_Sample",
        "", // user name
        "", // password
        "SELECT * FROM tbl_Example");

    job.OutputName = Path.Combine(Path.GetTempPath(), "output.pdf");
    job.PrinterType = PrinterType.PdfFile;
    job.Print();
}

Create a PNG from CSV Data

For a first file import with the supplied ProductLabel layout, use the CSV/XML PDF example. The following example instead demonstrates PNG output and image resolution.

The resolution option sets the image resolution in DPI.

The input file in this example is deployed next to the application. The generated image is written to the system temporary directory:

using System;
using System.IO;
using TECIT.TFORMer;

string inputPath = Path.Combine(
    AppDomain.CurrentDomain.BaseDirectory, "Import.txt");
string outputPath = Path.Combine(Path.GetTempPath(), "output.png");

using (Job job = new Job())
{
    job.RepositoryName = "FILENAME_OF_YOUR_FORMLAYOUT.tff";
    job.JobData = new JobDataCsv(inputPath, ',', '"');
    job.OutputName = outputPath;
    job.PrinterType = PrinterType.ImagePng;
    job.Options = "resolution=96";
    job.Print();
}

Apply a License

Apply your license during application initialization, before the first output operation. With Base64 license data supplied by TEC-IT, use:

TECIT.TFORMer.TFORMer.LicenseBase64(
    "BASE64_LICENSE_DATA_FROM_TEC_IT");

Replace the placeholder with your license data and keep it confidential. Handle TFORMerException if licensing fails; do not continue to output after a failed call. See Licensing for license types, validity and file-based licensing.

Reference and Sample Links

Use the .NET programming reference and the maintained programming samples supplied with the SDK. The NuGet package does not include the form layout used by its README's introductory code snippet. Supply a compatible layout and adapt its path and field names before running that snippet.