Using NiceLabel .NET API

Official translation unavailable. Translate this page with Google:

Getting Started

The easiest way to get started is to consult the samples NiceLabel has prepared to demonstrate various capabilities of NiceLabel .NET API.

Samples are located in the following folder:

c:\Users\Public\Documents\NiceLabel 10\SDK\Samples

The folder where you have extracted the NiceLabel .NET API ZIP file.

The sample applications have been written in C# with Visual Studio 2013. Each sample focuses on a typical task and is accompanied with a ReadMe.txt file and code comments which provide important notes for integrating with NiceLabel .NET API components.


We recommend to start with SimpleTestApplication sample.


Referencing NiceLabel .NET API

To include the NiceLabel Print Engine in an application, you will need to create a reference to the SDK.NET.Interface.dll assembly.

This file can be found in the SDKFiles folder, where you have extracted the NiceLabel .NET API ZIP file.

It is recommended to keep the files of NiceLabel .NET API in a separate folder to your application’s executable. When the reference to SDK.NET.Interface.dll file is made, this file may be copied to your application’s bin folder.

This file can be found in the installation folder of NiceLabel which is typically:

c:\Program Files\NiceLabel\NiceLabel 10\


Label Design

NiceLabel .NET API components have no label design capabilities and no user interface. It is strictly a print engine which is embedded into other applications.

Label templates, which the NiceLabel Print Engine will use for printing, must be created in the application NiceLabel 10. This is the label design tool that you use to create graphical layout of label templates, define object properties, and variable fields.

You will use NiceLabel Designer to create your label templates, and you will use NiceLabel .NET API to merge user data, and to manage label printing.


Typical Workflow Tasks

Print Engine Management

All NiceLabel .NET API features are exposed through the NiceLabel.SDK.IPrintEngine interface.

When the application refers the SDK.NET.Interface.dll assembly, it can access PrintEngineFactory static class. Before using any other properties, the application needs to set the SDKFilesPath property. This is necessary for the library to access the NiceLabel .NET API files, which can exist on different locations.

Once the location is known, the application can retrieve the IPrintEngine interface by accessing the PrintEngineFactory.PrintEngine property.

After retrieving the PrintEngine, a call to Initialize() method of the returned IPrintEngine instance needs to be done.

IPrintEngine printEngine = PrintEngineFactory.PrintEngine;

Before terminating the application, Shutdown() method of the IPrintEngine instance should be called to release all resources used by the library.


Label Template Management

Access to label template files will be crucial for all workflows. The OpenLabel() method allows your application to manage which template(s) your users will have access to. Templates can be opened from files on your client’s file system or from System.IO.Stream objects for users that want to deploy them embedded in their application or maintained in a database.

Additionally, NiceLabel LMS users can use Document Storage Server for document management of label files.


See the sample SimpleTestApplication.


Printer Management

NiceLabel Print Engine provides a list of locally available printer drivers to your application and is provided as a convenience to reduce coding on your side.

Printer selection followings this hierarchy:

  1. The PrinterName property is set to a valid printer name.

  2. The printer name stored on the template is found.

  3. The system’s default printer.


See the sample PrinterSelectionSample.


Graphical Preview and Digital Archiving

Label previews are a vital part of any print workflow system. Print production personnel as well as consumers rely on online- and hard copy previews as assurances of final job quality.

NiceLabel .NET API-based applications will use the same print engine for both previews and final output, thus ensuring that what you see is indeed what you get.

With the GetLabelPreview() method, your application can retrieve a graphical preview of the next label that will be printed. This method is very convenient for displaying a true preview so that the use can see what will be actually printed.

The PrintToGraphics() method will generate a series of images of all the labels that would be printed. This can be useful for achieving purposes or working with proof-of-concepts.


See the samples GetLabelPreviewSample and PrintToGraphicsSample.


Label Printing

NiceLabel technology allows you to print to any printer with a Windows driver. In addition, NiceLabel output provides printer commands for more than 4000 label printers allowing you to use native printer features, such as barcodes, font and counters, thus improving printing performance.

NiceLabel .NET API offers three different printing modes:

  • Synchronous Printing. This mode maintains a connection to the print process. In this mode, the application sends data to the print process and keeps the connection to it established as long as the print process is busy. Calling the Print() method returns feedback about the print job.

  • Asynchronous Printing. This mode processes the print job in its own thread. This boosts performance and increases the number of print jobs that can be processed in a time frame. When using the PrintAsync() method, the caller is notified via event handlers when print process status changes.

  • Session Printing. NiceLabel’s unique concept of session printing assures that every print job will be printed exactly as you intended. If you need to make sure that your print jobs are not interrupted when using shared printers or you need to print different labels on a single page, NiceLabel makes it easy with session print.

All labels within a single session print are sent to the printer as a single job, ensuring the correct printing order.

Each session printing includes three stages: StartSessionPrint() initializes a new printing session, SessionPrint() adds a print request to the current session and can be called multiple times, and EndSessionPrint() finalizes the current session.


See the sample SimpleAsyncPrintSample.


Print Job Monitoring

Regardless of the label printing mode you chose, NiceLabel .NET API lets you monitor the printing process through simple, event-based print job status updates. This detailed access to your printing process allows you to control and respond correctly to any situation.


See the sample SimpleAsyncPrintSample.


Exception Handling

All exceptions from the NiceLabel Print Engine will be of type SDKException. This class contains detailed information about errors that might be encountered.


See the sample ExceptionHandlingSample.


Print Logging

NiceLabel LMS users can benefit from NiceLabel .NET API ability to log print events from each client into the Control Center’s consolidated history database. The collected information can be drilled-in and examined from Control Center’s centralized web interface.

See the NiceLabel .NET API Programming Reference for details.