DbgCensus.EventStream.EventHandlers 1.0.0-beta.3

This is a prerelease version of DbgCensus.EventStream.EventHandlers.
There is a newer version of this package available.
See the version list below for details.
dotnet add package DbgCensus.EventStream.EventHandlers --version 1.0.0-beta.3
NuGet\Install-Package DbgCensus.EventStream.EventHandlers -Version 1.0.0-beta.3
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="DbgCensus.EventStream.EventHandlers" Version="1.0.0-beta.3" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add DbgCensus.EventStream.EventHandlers --version 1.0.0-beta.3
#r "nuget: DbgCensus.EventStream.EventHandlers, 1.0.0-beta.3"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install DbgCensus.EventStream.EventHandlers as a Cake Addin
#addin nuget:?package=DbgCensus.EventStream.EventHandlers&version=1.0.0-beta.3&prerelease

// Install DbgCensus.EventStream.EventHandlers as a Cake Tool
#tool nuget:?package=DbgCensus.EventStream.EventHandlers&version=1.0.0-beta.3&prerelease

<img title="DbgCensus Icon" alt="DbgCensus Icon" src="https://github.com/carlst99/DbgCensus/blob/main/Assets/Icon_128.png?raw=true" align="left"></img>

DbgCensus

DbgCensus is a C# wrapper for Daybreak Game Company's Census API. It was built with PlanetSide 2's endpoints in mind, but should work across all namespaces.

This package is unofficial and is not affiliated with Daybreak Games Company in any way.

Nuget | DbgCensus.Core - Core data types and utilities.
Nuget | DbgCensus.Rest - Services for interacting with the query endpoints.
Nuget | DbgCensus.EventStream - Base services for interacting with the event streaming API.
Nuget | DbgCensus.EventStream.EventHandlers - An abstraction of DbgCensus.EventStream providing an asynchronous and decoupled event handling model.


Features

  • Fluent query building API
  • Full coverage of the Census query and event streaming interfaces.
  • Fully asynchronous.
  • Built around the Microsoft.Extensions framework.
  • Compiled for .NET 5.0.

⚠️ DbgCensus is currently in an unstable state. This means that:

  • The code has been 'tested' by my own workloads, but not thoroughly hand or unit tested.
  • The API is liable to change, although it is beginning to reach maturity.
  • Documentation is a bit lacking, although the code is fully XML documented.

Getting Started

Before you do anything, you should consider getting a custom Census Service ID. The process is free and it generally only takes a few hours to hear back about your registration, which you can do here.

Note that you can use the example service ID, however you will be rate-limited to 10 requests per minute, per client IP address.

You will also need to have a good understanding of how the Census API works. I highly recommend making your way through these excellent official/community docs:

Examples

Check out the samples to get up and running quickly with DbgCensus. These demonstrate typical usage of the libraries within the Generic Host framework.

The EventStreamSample utilises DbgCensus' event handling framework. If you'd prefer to use another method of dispatching and handling events, you'll need to extend the BaseEventStreamClient instead, and register it yourself using the AddCensusEventStreamServices extension method.

Core Components

The Core library contains common types and extensions. Of these, it is likely you will find the Census objects useful (DbgCensus.Core.Objects). There are:

  • Enumerations of the faction, world and zone IDs that Census uses.
  • A ZoneId record that represents Census' special zone ID format - see here for more info. JSON converters are registered by default for this type, so you can use it anywhere that you would normally use an integer zone ID in your models.

There are also converters, extensions and naming policies for System.Text.Json that you may find useful should you decide to perform your own JSON deserialisation.

Interacting with Census Query Endpoints

Check out REST Sample as you read through this.

Start off by creating a new project. I would highly recommend using a template that implements the Generic Host, such as a Worker Service or an ASP.NET Core project.

Then, install the REST package:

# Visual Studio Package Manager
Install-Package DbgCensus.Rest
# dotnet console
dotnet add package DbgCensus.Rest

If your project integrates with the Microsoft.Extensions framework, you can easily register the required services to the container with the AddCensusRestServices extension method:

using DbgCensus.Rest.Extensions;

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureServices((configuration, services) =>
        {
            services.AddCensusRestServices();
        });

If you aren't using the Microsoft.Extensions framework, take a look at this file to see how the required services are setup.

Customising Query Options

You will need configure an instance of the CensusQueryOptions class to ensure that your service ID is utilised. I like to register my options from a configuration source (usually a section of appsettings.json) to retrieve any secrets that shouldn't be stored with the code, and then follow up with any additional configuration.

.ConfigureServices((hostContext, services) =>
    {
        services.Configure<CensusQueryOptions>(hostContext.Configuration.GetSection(nameof(CensusQueryOptions)));
        // AND/OR
        services.Configure<CensusQueryOptions>(o => o.DeserializationOptions = new JsonSerializerOptions(...));
    });

Performing Queries

Grab an IQueryService instance. This is a wrapper around the registered IQueryBuilderFactory and ICensusRestClient objects, which you can use individually if you need slightly more control over your queries.

IQueryBuilder query = _queryService.CreateQuery()
    .OnCollection("character")
    .Where("name.first_lower", SearchModifier.Equals, "falconeye36");

try
{
    Character? character = await _queryService.GetAsync<Character>(query, ct).ConfigureAwait(false);
    if (character is null)
    {
        _logger.LogInformation("That character does not exist.");
        return;
    }
}
catch (Exception ex)
{
    _logger.LogError(ex, "Failed to retrieve character.");
}
Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
3.7.2 97 4/16/2024
3.7.1 82 4/16/2024
3.7.0 83 4/16/2024
3.6.0 223 11/15/2023
3.5.1 151 7/11/2023
3.5.0 191 4/1/2023
3.4.0 221 3/8/2023
3.3.0 383 10/6/2022
3.2.0 370 9/8/2022
3.1.5 361 8/27/2022
3.1.4 365 8/19/2022
3.1.3 368 8/6/2022
3.1.2 394 6/16/2022
3.1.1 379 6/8/2022
3.1.0 459 4/2/2022
3.0.4 401 3/23/2022
3.0.3 409 3/11/2022
3.0.2 404 3/10/2022
3.0.1 395 3/9/2022
3.0.0 389 3/9/2022
2.4.0 427 3/8/2022
2.3.1 439 3/8/2022
2.3.0 443 3/7/2022
2.2.0 470 3/7/2022
2.1.0 413 3/7/2022
2.0.3 392 3/4/2022
2.0.2 426 2/3/2022
2.0.1 406 1/20/2022
2.0.0 248 1/1/2022
1.0.2 280 12/4/2021
1.0.1 260 11/22/2021
1.0.0 543 11/20/2021
1.0.0-beta.3 155 10/15/2021
1.0.0-beta.1 163 9/16/2021
1.0.0-beta 211 9/5/2021
1.0.0-alpha 147 8/19/2021

Reduce memory allocations on payload send and receive.