# Using the powerGate .NET library

## Follow these steps to use the powerGate library in your C# project

With the [installation](</installation>) of powerGate on your development machine, the required .NET library will be installed for all users.\
It contains the relevant API's to communicate with an ERP System via OData.

The powerGate .NET library requires your project to target at least **.NET framework v4.7**!

:::{dropdown} 1. Reference the _powerGate.Erp.Client_ assembly

In Visual Studio right-click on *References* and click "*Add References*".\
Search for the assembly "*powerGate.Erp.Client*" in Assemblies-tab and add it to your project.

```{image} /img/getting_started/add_reference_to_vs.png
   :width: 1000px
```

The assembly will be referenced from the **GAC**, therefore set *"Copy Local"* to *"false"* (when using Visual Studio 2017 this should be done automatically).
:::

:::{dropdown} 2. Create an ErpClient instance and connect to a service

In order to gain access to the powerGate API's, the following **namespace** must be imported:

```csharp
using powerGate.Erp.Client;
```

Root entry point is the class [ErpClient](</code_reference/net_library/erpclient>):

```csharp
var client = new ErpClient();
```

Call the **ConnectErp()** method in order to have access to the prefered Service:

```csharp
var northwindService = client.ConnectErp(new Uri("http://services.odata.org/V4/Northwind/Northwind.svc/"));
```

:::

:::{dropdown} 3. Communicate with the service

If we have successfully connected to a [Service](</code_reference/net_library/ierpservice>) *(service.Available will return true)*, then we are able to make CRUD operations on the prefered [EntitySet](</code_reference/net_library/ierpentityset>).

See the following example with a **single get**, which retrieves exactly one entry:

```{code-block} csharp
:emphasize-lines: 3

var categories =  client.Services["Northwind.svc"].EntitySets["Categories"];
var categoryKeys = new Dictionary<string,object> { {"CategoryID", 3} };
var category = categories.GetErpObject(categoryKeys);
Console.WriteLine("Successful retrieved category '{0}' with Id '{1}'.",
category["CategoryName"], (int)category["CategoryID"]);
```

:::

:::{dropdown} 4. Release the service when done

When you are done working with your ERP System, the [ErpClient](</code_reference/net_library/erpclient>) should be **disposed**, in order to disconnect from all the connected [services](</code_reference/net_library/ierpservice>) and release all the resources.

```csharp
client.Dispose();
```

We recommend using the ["using" statement](<https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/using-statement>) on the *ErpClient*, so *Dispose()* will be called in each situation, also when unexpected exceptions are thrown!
:::

:::{admonition} Install powerGate on customer machine
:class: warning

When shipping your projects binaries to your customer, **also the customers machine requires a powerGate installation**.\
Therefore delivering the *powerGate.Erp.Client* assembly within your project should be avoided, in order to not lose the benefits from powerGates [Update strategy](<installation:updates>).
:::

See the **complete example**:

```{code-block} csharp
:emphasize-lines: 11

using System;
using System.Collections.Generic;
using powerGate.Erp.Client;

namespace HelloWorldServices
{
    class Program
    {
        static void Main(string[] args)
        {
            using (var client = new ErpClient())
            {
                var northwindService = client.ConnectErp(new Uri("http://services.odata.org/V4/Northwind/Northwind.svc/"));
                var categories = client.Services["Northwind.svc"].EntitySets["Categories"];

                var categoryKeys = new Dictionary<string, object>{ {"CategoryID", 3} };
                var category = categories.GetErpObject(categoryKeys);

                Console.WriteLine("Successful retrieved category '{0}' with Id '{1}'.", category["CategoryName"], (int)category["CategoryID"]);
            }

            Console.ReadLine();
        }
    }
}
```