#######################
Set Up Your Environment
#######################

.. sidebar:: Contents

    .. contents::
        :local:

This documentation provides step-by-step instructions for setting up your environment for developing with the HOOPS Exchange C# API.

The process includes installing a development environment, downloading and extracting the library package, obtaining and configuring the license, and testing the installation using sample code.

If you already followed the instructions for :doc:`installing the C/C++ development environment </tutorials/c/environment-setup.rst>`, you can skip most of the sections in this document and directly jump to :ref:`download the C# package <download_cs_library>` then :ref:`instaling the license <cs_install_license>`. 

Installing Your Development Environment
=======================================

.. tabs::

   .. group-tab:: Windows

      Developing applications with HOOPS Exchange for Windows is typically done using the Visual Studio Integrated Development Environment (IDE).
      
      To get started, visit the `Microsoft Visual Studio download page <https://visualstudio.microsoft.com/downloads/>`__ and choose the edition of Visual Studio that suits your needs. Be mindful that your chosen compiler adheres to the :doc:`HOOPS Exchange platform requirements </start/supported-platforms>`.
      
      During the installation process, select the **Console Application** component set.
      
      .. image:: /_assets/images/console-application.png
         :align: center
      
      
   .. group-tab:: Linux

         **Configure Linux:**
      
         * Go to the :doc:`required components </start/supported-platforms>` page.
         * Make sure that your *Minimum supported OS* and *compiler* are compatible with HOOPS Exchange.

   .. group-tab:: macOS

         **Configure macOS:**

         * Go to the :doc:`required components </start/supported-platforms>` page.
         * Make sure that your *Minimum supported OS* and *compiler* are compatible with HOOPS Exchange.
      
.. _cs_install_license:

Installing HOOPS Exchange
=========================

.. tabs::

   .. group-tab:: New Evaluator

      #. **Getting HOOPS Exchange:**
      
         If this is your first visit to our website, and neither you nor your company has ever used or licensed our products before:
         
            * Go to our `User Dashboard <https://manage.techsoft3d.com>`__ page and click the **Sign Up** link.
               
               .. image:: /_assets/images/user-dashboard.png
                  :width: 50%
                  :align: center
            
            * Create your self-evaluation account. You will be emailed a link to verify your account details.
            
            * Once you've verified your account, click on **Product Downloads** and then **Download HOOPS Exchange** to be taken to the Developer Zone.
            
               .. image:: /_assets/images/download-links.png
                  :width: 50%
                  :align: center
               
            * Lastly, click the **Download** button for your chosen operating system.
               
               .. image:: /_assets/images/download-exchange.png
                  :width: 50%
                  :align: center
                     
         If you are on a Windows or Linux platform, you may download the installer or the ZIP file.
         macOS users must use the ZIP file.
         To download the iOS or Android package, please :doc:`Contact Us </contact_us>`.

            .. image:: /_assets/images/download-installers-zip.png
               :width: 50%
               :align: center
            
         Read the :ref:`package_hierarchy` page for more information about the download package content.

            * Installer: Run the installer and follow the instructions to install the package on your local machine.
            * ZIP file: Locate the downloaded package file, which is a zip archive.
           
         You can use either a built-in extractor or third-party software to extract the contents to your chosen destination folder.
         
      #. **Additional C# Library:**

         .. _download_cs_library:

         C# support in HOOPS Exchange is optional and is delivered by a separate API library.
         Download this library from `the Developer Zone <https://developer.techsoft3d.com/hoops/exchange/downloads/latest>`__.

         It is located under *Products → HOOPS Exchange → Related Technologies → HOOPS Exchange C# API*.

         The package is delivered in the form of a *.zip* file.
         Unzip this package into the root directory of your HOOPS Exchange installation from the previous step.
         
      #. **Obtaining and setting the license:**
         
         Before you can use this product, you must have a valid HOOPS Exchange license key. The keys are usually compiled into the application as part of a header file. The license can be acquired in two ways: it can be obtained as a string from the Developer Zone downloads page, or embedded in a preconfigured header file.
         
            
            * The generated key is permanent and accessible from the `Developer Zone <https://developer.techsoft3d.com/start>`__ at any time during your evaluation.

               .. image:: /_assets/images/HE-License-Key.png
                  :width: 50%
                  :align: center
                  
         If you are using the installer, you'll be required to input the license key to complete installation of the SDK. 

         If you are using the ZIP file, you will need to copy and paste your new license key into the license header file available in your installation folder:
   
            * Locate the folder where you have previously extracted HOOPS Exchange on your system.
            * Navigate to the *include* directory.
            * Either replace *hoops_license.cpp* with the preconfigured header file downloaded from the Developer Zone, or edit the existing file *include/hoops_license.cpp* and enter your new license key in the ``KEY`` string.
            * If you are planing to develop in C#, you'll also need to download the *hoops_license.cs* header or enter the license manually in *hoops_license.cs*. The file should be copied to *<HOOPS_EXCHANGE_INSTALL_DIR>/csharp/ExchangeCSharp/*.
   
               .. image:: /_assets/images/Enter-the-Key-cs.png
                  :width: 50%
                  :align: center
               
         From the `Developer Zone <https://developer.techsoft3d.com/start>`__, clicking **Active Evaluations** at the top right of the page and then **License Key** will give you access to your license status.

            .. image:: /_assets/images/dz-main-screen.png
               :width: 50%
               :align: center
         
         HOOPS Exchange only requires a new license key if you are currently using a key which was generated for a prior *major version*.
         For example, developers upgrading from HE 2024.6.0 to HE 2024.7.0 may use the same key, but those upgrading from 2024.0.0 to 2025.0.0 need to generate a new key.

         The expiration date for the generated license key is tied to your contract with Tech Soft 3D. If you have signed a license agreement for HOOPS Exchange,
         then the license key that is generated will be a perpetual (non-expiring) license key.
         If you are evaluating HOOPS Exchange, then the license key will expire when your evaluation expires.
         **Evaluation license keys will expire at the end of the evaluation period and are not suitable for production software. Any software that uses an evaluation license key will no longer work after the evaluation period.**

         HOOPS Exchange releases are not binary compatible with older releases.
         **You must recompile your application when updating to a new version of HOOPS Exchange.**
         Please see :doc:`/distributing` section for an up-to-date list of binaries required for distribution.
            

   .. group-tab:: Existing Partner

      #. **Getting HOOPS Exchange:**
            
         Your company is already evaluating or licensing one of our products, go to the `Developer Zone <https://developer.techsoft3d.com/start>`__.

         At the top right of the page, click on the **Sign In** button:
                 
            * If you have an existing account, simply enter your credentials.
            * If your company is already licensing our technology, please :doc:`contact us <contact_us>`. 
            * After our team has attached your contact to your company records, you will receive a personal invitation to log in.

               .. image:: /_assets/images/dz-licensed-products.png
                  :width: 50%
                  :align: center
            
         From here, you can download:
         
            * Your license file (perpetual and evaluation license key).
            * ZIP files of current and previous versions for Windows, Linux, macOS, iOS, Android platforms.
            * "From the Vault" Importers for the no longer supported formats: HSF, OneSpace Designer, KMZ, Lattice XVL and CADDS.
            * All of our other HOOPS, Ceetron, Partners, and OEM CAD technologies and viewers.
      
         Read the :ref:`package_hierarchy` page for more information about the download package content.

            * ZIP file: Locate the downloaded package file, which is a zip archive.
           
         You can use either a built-in extractor or third-party software to extract the contents to your chosen destination folder.
            
      #. **Obtaining and setting the license:**          

         Existing partners can download ZIP files and their license file from the Developer Zone:
   
            * Visit the `Developer Zone <https://developer.techsoft3d.com//>`__ and click the **View License Keys** button.

               .. image:: /_assets/images/dz-licensed-products.png
                  :width: 50%
                  :align: center

            * Click the **C Header** button in the *Header Files* section.

               .. image:: /_assets/images/dz-license-keys.png
                  :width: 50%
                  :align: center

         This will generate a file named *hoops_license.h* for you. Once done, simply:
   
            * Download the license file
            * Locate the folder where you have previously extracted HOOPS Exchange on your system.
            * Navigate to the *<HOOPS_EXCHANGE_INSTALL_DIR>/include/* directory.
            * Copy the downloaded *hoops_license.h* and replace the default one in the *include* directory.

               .. image:: /_assets/images/Enter-the-Key.png
                  :width: 50%
                  :align: center
                  
         If you're planning to use the C# API, you'll also need to download the C# version of the header and copy it to *<HOOPS_EXCHANGE_INSTALL_DIR>/csharp/ExchangeCSharp/hoops_license.cs*.
               
         HOOPS Exchange only requires a **new** license key if you are currently using a key which was generated for a prior *major version*.
         For example, developers upgrading from HE 2024.0.0 to HE 2024.1.0 may use the same key, but those upgrading from 2023.0.0 to 2024.0.0 need to generate a new key.

         The expiration date for the generated license key is tied to your contract with Tech Soft 3D. If you have signed a license agreement for HOOPS Exchange,
         then the license key that is generated will be a perpetual (non-expiring) license key.
         If you are evaluating HOOPS Exchange, then the license key will expire when your evaluation expires.
         **Evaluation license keys will expire at the end of the evaluation period and are not suitable for production software. Any software that uses an evaluation license key will no longer work after the evaluation period.**

         HOOPS Exchange releases are not binary compatible with older releases.
         **You must recompile your application when updating to a new version of HOOPS Exchange.**
         Please see :doc:`/distributing` section for an up-to-date list of binaries required for distribution.
         

Testing the Installation
========================

Now that you've completed the setup, it's time to test the installation using sample code provided with HOOPS Exchange.

Locate the folder where you have previously extracted HOOPS Exchange on your system and navigate to the *samples* directory:

.. tabs::

   .. group-tab:: Windows
   
      #. **Build the solution**
      
         If you are on a Windows platform:

         * Open *<HOOPS_EXCHANGE_INSTALL_DIR>/csharp/samples/HOOPSExchangeSamples.sln* file using Visual Studio.
         * Select the Debug, x64 mode.
         * Go to the tab *Build* and build the entire solution.

         .. image:: /_assets/images/vs-build-solution-cs.png
            :width: 50%
            :align: center
            
         .. admonition:: Important
         
            The *HOOPSExchangeSamples.sln* file is preconfigured to work with the C# library you unzipped in your HOOPS Exchange installation folder. When you are building an application from scratch, you'll need to add a reference to your project in order for the HOOPS Exchange C# API to work. The reference is *<HOOPS_EXCHANGE_INSTALL_DIR>/csharp/ExchangeCSharp/bin/Debug/netcoreapp3.1/ExchangeCSharp.dll*.
            
            **However**, this file is not distributed with the package. It is built as you compile the *samples* solution.

      #. **Test a sample**

         From the Solution Tree explorer in Visual Studio:
         
                  * Locate the sample *ImportExport*.
                  * To run the sample, right click on it and select *Debug -> Start New Instance*.
                     * The sample will read a sample input file, *_Aquo Bottle.CATProduct*, and convert it to PRC format.
                     * The result file is located alongside the input file.
                  * Locate the newly created file *_Aquo Bottle.CATProduct.prc* in your output folder from the installation folder *..\samples\data\catiaV5\CV5_Aquo_Bottle*
                  * Open the HOOPS Demo Viewer desktop application.
                  * Drag and drop your resulting *_Aquo Bottle.CATProduct.prc* file to quickly visualize the assembly:
                  
         .. image:: /_assets/images/AquaBottle.png
            :width: 50%
            :align: center

         For more details on using the *HOOPS Demo Viewer*, consult the `HDV Documentation Page <https://docs.techsoft3d.com/hdv/latest/>`__.

   .. group-tab:: Linux

      #. **Build the solution**
      
         If you are on a Linux platform:
                  * Locate the folder *samples* from the installation folder.
                  * Right click on the folder and select *Open in Terminal*.
                  * In your terminal, type ``make`` to build all the samples.

         Out of the box, all samples are built except the sample *TranslateToPkParts*, which is our *Bridge* to the `Siemens Parasolid API <https://www.techsoft3d.com/products/parasolid/>`__. This requires more configuration to run - please visit the `TranslateToPkParts <https://docs.techsoft3d.com/exchange/latest/guide/parasolid.html>`__ page for more details.

         .. image:: /_assets/images/make_all_sample.png
            :width: 50%
            :align: center
            
         .. admonition:: Note
         
            The HOOPS Exchange samples are preconfigured to work with the C# library you unzipped in your HOOPS Exchange installation folder. If you are building an application from scratch, you'll need to add a reference to your project in order for the HOOPS Exchange C# API to work. The reference is *<HOOPS_EXCHANGE_INSTALL_DIR>/csharp/ExchangeCSharp/bin/Debug/netcoreapp3.1/ExchangeCSharp.so*.
            
            *However*, this file is not distributed with the package. It is built as you compile the *samples* solution.

      #. **Test a sample**

         The `HOOPS Demo Viewer application <https://docs.techsoft3d.com/hdv/latest/>`__ being a Windows only application, for Linux we will use the samples ``ImportExport`` AND ``Viewer`` instead.
         
                  * Locate the sample ``ImportExport`` from the installation folder ``../samples/hello_world/ImportExport``
                  * Right click on the folder and select *Open in Terminal*.
                  * Locate the file **_Aquo Bottle.CATProduct** from the installation folder ``../samples/data/catiaV5/``
                  * Make sure the sample is already built otherwise build it again: Command Line: ``make``
                  
         .. image:: /_assets/images/Import_export_make.png
            :width: 50%
            :align: center
            
         * *Run* the sample ``ImportExport`` to convert a CATIA V5 assembly called **_Aquo Bottle.CATProduct** to PRC format. 
         * Command Line : ``./ImportExport ../samples/data/catiaV5/_Aquo Bottle.CATProduct ../samples/data/catiaV5/_Aquo Bottle.CATProduct.prc``
         
         .. image:: /_assets/images/Import_export_output.png
            :width: 50%
            :align: center

         * Locate the resulting file **_Aquo Bottle.CATProduct.prc** from the installation folder ``../samples/data/catiaV5/``
         * *Run* the sample ``Viewer`` to  load the PRC file in the OpenGL sample Viewer. Command Line ``./Viewer ../samples/data/catiaV5/_Aquo Bottle.CATProduct.prc``
         * **_Aquo Bottle.CATProduct.prc** file will be displayed in an OpenGL Windows:
            
         .. image:: /_assets/images/viewer_sample.png
            :width: 50%
            :align: center
            

   .. group-tab:: macOS

      #. **Build the solution**
      
         If you are on a macOS platform:
                  * Locate the folder ``../samples/`` from the installation folder.
                  * Open the *Terminal* and set the current directory to ``../Samples``
                  * In Terminal Type ``make``

         Out of the box, all samples are built but the sample ``TranslateToPkParts``, our *Bridge* to the `Siemens Parasolid API <https://www.techsoft3d.com/products/parasolid/>`__ requires further more configuration to run, please visit the `TranslateToPkParts <https://docs.techsoft3d.com/exchange/latest/guide/parasolid.html>`__ page for more details.
         
         .. image:: /_assets/images/build-mac-samples.png
            :width: 50%
            :align: center
            
         .. admonition:: Note
         
            The HOOPS Exchange samples are preconfigured to work with the C# library you unzipped in your HOOPS Exchange installation folder. If you are building an application from scratch, you'll need to add a reference to your project in order for the HOOPS Exchange C# API to work. The reference is *<HOOPS_EXCHANGE_INSTALL_DIR>/csharp/ExchangeCSharp/bin/Debug/netcoreapp3.1/ExchangeCSharp.so*.
            
            *However*, this file is not distributed with the package. It is built as you compile the *samples* solution.
            

      #. **Test a sample**

         The `HOOPS Demo Viewer application <https://docs.techsoft3d.com/hdv/latest/>`__ being a Windows only application, for macOS we will use the samples ``ImportExport`` AND ``Viewer`` (C/C++) instead.
         
                  * Locate the sample ``ImportExport`` from the installation folder ``../samples/hello_world/ImportExport``
                  * Open the *Terminal* and set the working directory to ``../samples/hello_world/ImportExport``
                  * Make sure the sample is already built. If not built, you can build it using *make* from your command line.
                  
         .. image:: /_assets/images/make-importexport-mac.png
            :width: 50%
            :align: center
            
         * On macOS go to *System Settings* and open the *Privacy and Security* tab.
         * Check that the ``libA3DLIBS-xx.x.xx.dylib`` file is not blocked - if this is the case click *Allow Anyway*.
         
         .. image:: /_assets/images/privacy-security-mac.png
            :width: 50%
            :align: center
            
         * Locate the file **_Aquo Bottle.CATProduct** from the installation folder ``../samples/data/catiaV5/``
         * *Run* the sample ``ImportExport`` to convert a CATIA V5 assembly called **_Aquo Bottle.CATProduct** to PRC format.
         * Command Line: ``./ImportExport ../samples/data/catiaV5/_Aquo Bottle.CATProduct ../samples/data/catiaV5/_Aquo Bottle.CATProduct.prc``
         
         .. image:: /_assets/images/import-export-mac.png
            :width: 50%
            :align: center
            

         * Locate the resulting file **_Aquo Bottle.CATProduct.prc** from the installation folder ``../samples/data/catiaV5/``
         * *Run* the sample ``Viewer`` to  load the PRC file in the OpenGL sample Viewer. Command Line ``./Viewer ../samples/data/catiaV5/_Aquo Bottle.CATProduct.prc``
         * **_Aquo Bottle.CATProduct.prc** file will be displayed in an OpenGL Windows:
         
         .. image:: /_assets/images/sample-viewer-mac.png
            :width: 50%
            :align: center

Conclusion
==========

You have successfully set up your environment for HOOPS Exchange, including Visual Studio installation, package download and extraction, license configuration, and testing using sample code.

You are now ready to start working with HOOPS Exchange.
If you encounter any issues or have questions, please refer to our `support resources <https://developer.techsoft3d.com/developer-support/>`__ or `forum <https://forum.techsoft3d.com/>`__.

You are now ready for our next tutorial: :doc:`file-to-file-translation`.

