seraphx2 / ESI.NET

A C# wrapper for the Eve Online ESI API.
https://www.nuget.org/packages/ESI.NET/
MIT License
40 stars 23 forks source link

Build status Quality gate NuGet

What is ESI.NET?

ESI.NET is a .NET wrapper for the Eve Online ESI API. This wrapper simplifies the process of integrating ESI into your .NET application.

Resources

It is extremely important to not solely rely on ESI.NET. You may need to refer to the official specifications to understand what data is expected to be provided. For example, in some instances, ESI.NET will ask for specific values in the endpoint method and construct the JSON object that needs to be sent in the POST request body because it is a simple object that requires a few values. Some of the more complex objects will need to be constructed with anonymous objects by the developer and this can be determined when the endpoint method requires an object instead of an int or a string. Refer to the official documentation and construct the anonymous object to reflect what is expected as Json.NET will be able to convert that anonymous object into the appropriate JSON data.

ESI.NET on NuGet

https://www.nuget.org/packages/ESI.NET

dotnet add package ESI.NET

Client Instantiation

ESI.NET is Dependency Injection compatible. There are a few parts required to set this up properly in a .NET Standard/Core application:

.NET Standard (Dependency Injection)

In your appsettings.json, add the following object and fill it in appropriately:

"EsiConfig": {
    "EsiUrl": "https://esi.evetech.net/",
    "DataSource": "Tranquility",
    "ClientId": "**********",
    "SecretKey": "**********",
    "CallbackUrl": "",
    "UserAgent": ""
  }

For your protection (and mine), you are required to supply a user_agent value. This can be your character name and/or project name. CCP will be more likely to contact you than just cut off access to ESI if you provide something that can identify you within the New Eden galaxy. Without this property populated, the wrapper will not work.

Inject the EsiConfig object into your configuration in Startup.cs in the ConfigureServices() method:

services.AddEsi(Configuration.GetSection("ESIConfig"));

Lastly, access the client in your class constructor (the config options above will automatically be injected into it:

private readonly IEsiClient _client;
public ApiTestController(IEsiClient client) { _client = client; }

.NET Framework

If you are using a .NET Standard-compatible .NET Framework application, you can instantiate the client in this manner:

IOptions<EsiConfig> config = Options.Create(new EsiConfig()
{
    EsiUrl = "https://esi.evetech.net/",
    DataSource = DataSource.Tranquility,
    ClientId = "**********",
    SecretKey = "**********",
    CallbackUrl = "",
    UserAgent = ""
});

EsiClient client = new EsiClient(config);

For your protection (and mine), you are required to supply a user_agent value. This can be your character name and/or project name. CCP will be more likely to contact you than just cut off access to ESI if you provide something that can identify you within the New Eden galaxy. Without this property populated, the wrapper will not work.

NOTE: You will need to import Microsoft.Extensions.Options to accomplish the above.

Endpoint Example

Accessing a public endpoint is extremely simple:

EsiResponse response = _client.Universe.Names(new List<long>()
{
    1590304510,
    99006319,
    20000006
}).Result;

SSO Example

SSO Login URL generator

ESI.NET has a helper method to generate the URL required to authenticate a character or authorize roles (by providing a List of scopes) for the Eve Online SSO. You should also provide a value for "state" that you verify when it is returned (it will be included in the callback).

var url = _client.SSO.CreateAuthenticationUrl();

Initial SSO Token Request

SsoToken token = await _client.SSO.GetToken(GrantType.AuthorizationCode, code);
AuthorizedCharacterData auth_char = await _client.SSO.Verify(token);

Refresh Token Request

SsoToken token = await _client.SSO.GetToken(GrantType.RefreshToken, auth_char.RefreshToken);

Performing an authenticated request

Set the character data on the client before performing the request.

_client.SetCharacterData(authorizedCharacterData)