C# / .NET

Prerequisites

For Windows, there is also a .NET version of the library.

To use it in a C# project, add a reference to the ids_peak_dotnet.dll to the project.

Before starting your application, make sure that the DLL-Loader can find all required libraries. This means that ids_peak_dotnet.dll, ids_peak_dotnet_interface.dll, ids_peak.dll and all GenICam libraries required by ids_peak.dll are located next to your application binary or that the directory where they are located is added to the DLL-Loader's search directories. To add their directory to the DLL-Loader's search directories, you could simply append their directory to the environment variable Path:

• PowerShell

  $env:Path="$env:Path;<Installation-Directory-Of-ids_peak.dll>"
  $env:Path="$env:Path;<Installation-Directory-Of-ids_peak_dotnet.dll>"
  # Then start your application

• CMD

  set Path=%Path%;<Installation-Directory-Of-ids_peak.dll>
  set Path=%Path%;<Installation-Directory-Of-ids_peak_dotnet.dll>
  REM Then start your application

Usage

The .NET API works much like the C++ API. The same principles, class and method names apply. For example, listing all available devices:

using peak; 
try
{
    Library.Initialize();
    var deviceManager = DeviceManager.Instance();
    deviceManager.Update();
    var deviceDescriptors = deviceManager.Devices();
    foreach (var deviceDescriptor in deviceDescriptors)
    {
        Console.WriteLine(deviceDescriptor.DisplayName());
    }
}
catch (System.ApplicationException e)
{
    Console.WriteLine("Exception: " + e.Message);
}

Warning

The DeviceManager is incompatible with using statements or declarations, since it is implemented as a singleton. Being part of a using statement or declaration would result in Dispose() being called on the DeviceManager at the end of the scope. Further use of the reference returned by DeviceManager.Instance would then result in a crash, since that instance has been disposed already.

Converting a Buffer to an Image

It is possible to convert the content of a Buffer into an image by directly employing Buffer::BasePtr alongside a custom conversion routine to ensure compatibility with any image processing library. However, the recommended method is to use the BufferToImage function. This function is included in the supplementary assembly ids_peak_ipl_extension_dotnet.dll. BufferToImage is specifically engineered to simplify the conversion process of raw memory data stored within a Buffer into an peak::ipl::Image that can be used for further processing.

In order to make use of this functionality, an assembly reference must be added to the project and the ids_peak_ipl_extension_dotnet_interface.dll needs to be available. See the Prerequisites section above for further instructions or use one of the provided samples that are shipped with the SDK as a starting template.

An example usage could look like as follows:

// Get buffer from device's data stream
buffer = dataStream.WaitForFinishedBuffer(1000);
 
// Create peak::ipl::Image (shallow copy)
var image = ids_peak_ipl_extension.BufferToImage(buffer);

Warning

The resulting image still uses the underlying memory of buffer. For this reason, you must ensure that you do not re-queue the buffer until you have finished processing image.

Comparison to the C++ API

There are a few differences between the C++ API and the .NET API. The most important ones are listed here:

Resource Management

The C++ API utilizes smart pointers for deterministic memory management, where the last smart pointer that holds a reference to the object destroys it when the smart pointer goes out of scope.

To close a module (e.g. the Device), you have to release all its shared_ptr instances (out-of-scope, call reset(), set to nullptr), then the module closes immediately.

• C++

  {
      auto device = deviceDescriptors[0].OpenDevice(DeviceAccessType.Control);
      // ...
  } // Device closes here

By default C# uses garbage collection to handle memory and resources, as a result an object that has no outstanding references anymore won't be closed and deleted immediately. Instead, it will be deleted at some point in the future, when the garbage collection deems it necessary. Often, that's no problem. But if it is, there are 2 options:

Call Dispose() explicitly:

• C#

  var device = deviceDescriptors[0].OpenDevice(DeviceAccessType.Control);
  device.Dispose(); // Device closes here

Or let a using statement handle calling Dispose() at the end of the scope:

• C#

  using (var device = deviceDescriptors[0].OpenDevice(DeviceAccessType.Control))
  {
      // ...
  } // Device closes here

Change Notification

To be notified when certain events happen, the C++ API employs callbacks that you have to register and unregister. C# has the concept of events built-in and similarly to C++ you have to register a delegate as an event handler:

• C++ Callbacks

  device_manager.RegisterDeviceFoundCallback(
      [](const std::shared_ptr<peak::core::DeviceDescriptor>& newDev)
      { std::cout << "Device found: " << newDev->DisplayName() << '\n'; });

• C# Events + Delegates

  deviceManager.DeviceFoundEvent += (object o, DeviceDescriptor newDev)
      => Console.WriteLine("Device found: {0}", newDev.DisplayName());

Overloads vs. Default Parameters

While C# supports optional parameters as well, the current C# API provides an overload for each default parameter instead:

• C++ Method Default Parameters

  DataStream::StartAcquisition(
      AcquisitionStartMode mode=AcquisitionStartMode::Default,
      uint64_t numToAcquire=INFINITE_NUMBER);

• C# Method Overloads

  DataStream.StartAcquisition(peak.core.AcquisitionStartMode mode, ulong numToAcquire)
  DataStream.StartAcquisition(peak.core.AcquisitionStartMode mode) // with numToAcquire=INFINITE_NUMBER
  DataStream.StartAcquisition() // with mode=Default and numToAcquire=INFINITE_NUMBER

Generic Methods

C# also supports function templates (i.e. generic methods), which can be used as follows:

• C++ Function Templates

  nodeMapRemoteDevice->FindNode<peak::core::nodes::StringNode>("DeviceModelName")->Value()

• C# Generic Methods

  nodeMapRemoteDevice.FindNode<peak.core.nodes.StringNode>("DeviceModelName").Value());

However, some IDE's and/or .NET implementations might not support such generic methods (e.g. NI Labview). Therefore all template specifications have been made available separately:

• C#

  nodeMapRemoteDevice.FindNodeString("DeviceModelName").Value());