.. _get-started-windows-imgsdk-cs-label:

ImageSDK : C# (Windows)
~~~~~~~~~~~~~~~~~~~~~~~

We provide .NET language bindings based on `.NET Standard 2.0 <https://docs.microsoft.com/en-us/dotnet/standard/net-standard>`_. Even though .NET is cross platform, our .NET assembly is not. Since it depends directly on :term:`unmanaged code` compiled for Windows.

Prerequisites
^^^^^^^^^^^^^

* Windows 10 (x64)
* .NET Standard 2.0 compatible .NET SDK
* MSVC Redistributable 2015-2022

.. content-if::
    :format: html

    The C# libraries are provided as part of our standard Windows library ZIP packages. You can download the package, containing both C# and C++ libraries at the :ref:`download-label` page.

.. content-if::
    :format: pdf
    
    The C# libraries are provided as part of our standard Windows library ZIP packages. You can download the package, containing both C# and C++ libraries at `developer.phaseone.com <https://developer.phaseone.com>`_.

.. tip:: 
    If you do not have the Microsoft Visual C++ toolchain installed, you will need to download and install the *redistributable runtime*. 
    
    Download the newest runtime from Microsoft here: `Latest Visual C++ Redistributable downloads <https://docs.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist>`_.

Setup Your Project
^^^^^^^^^^^^^^^^^^

To account for those who do not use *Visual Studio*, we use the command line .NET Core utility ``dotnet`` in this tutorial.

Open up *PowerShell* or *command prompt*, and navigate to the location where you want to put our sample project. Initialize a new .NET Core console based application:

.. code:: powershell

    PS> dotnet new console -n helloworld

Here we called our sample project ``helloworld``.

Now, ``cd`` into the ``helloworld`` directory. Copy your downloaded ImageSDK zip file into the project folder and extract the archive. If you use *PowerShell* you can: 

.. code:: powershell

    PS> Expand-Archive .\ImageSdk-Win_Release_2.X.X.zip -DestinationPath .

You will end up with libraries for both *C++* and *C#* inside a folder named: ``dest``. The resulting directory layout should be::

    dest
    |-- Cs
    |-- include
    `-- lib

We do not need neither the ``include`` nor the ``lib`` subdirectories, you can delete those if you want to.

Project File
^^^^^^^^^^^^

The ``dotnet`` util created a project file for us: ``helloworld.csproj``. We need to add the ImageSDK assembly to this, and also add a post-build copy step. This should copy the file ``ImageSdkCBindingsForCs.dll`` to the build output directory. This file is needed by the ImageSDK library assembly.

Add the ImageSDK C# library assembly and dependency to ``helloworld.csproj``. The xml snippet below should be appended inside the existing ``Project`` tag:

.. literalinclude:: ../../labels/csImageSampleProjectCsproj
    :language: xml

We added both the assembly (``ImageSdkCs.dll``) for the C# API and its dependency, a DLL file compiled by the Visual C++ compiler (``ImageSdkCBindingsForCs.dll``).

.. note:: Despite of the both files having the ``.dll`` extension, they are *not* the same format. One is a *.NET assembly* file, and the others are a standard dynamic library file with plain C functions inside.

Source Code
^^^^^^^^^^^

The console application template include a sample source file: ``Program.cs``. Replace its content with this:

.. literalinclude:: ../../labels/csImageSampleProjectSource
    :language: csharp


Build & Run
^^^^^^^^^^^

To compile the project, simply run the ``build`` command:

.. code:: powershell

    PS> dotnet build

This will build and copy the needed (assembly's and DLL's) to the build output directory. For .NET 5 this is ``bin/Debug/net5``.

To run the application, first ``cd`` into the build directory and run the executable:

.. code:: powershell

    PS> cd bin/Debug/net5
    PS> helloworld.exe
    Open IIQ file
    Do the conversion...
    Write image to tiff file...
    Done!    
    PS>

.. warning::
    We deliberately changed the working directory to the location of the executable. This is because the .NET runtime expects to find the ``ImageSdkCBindingsForCs.dll`` file in the *current working directory*.
    
    If we attempted to run the application from the ``helloworld`` project folder, we would get an exception::
        
        System.DllNotFoundException: C Bindings DLL (ImageSdkCBindingsForCs.dll) not found at: .\helloworld