clash-client

The Clash-Client .NET Framework library simplifies integration with the Clash of Clans API provided by SuperCell. It exposes IApiClient and ApiClient types that handle serialization and deserialization while consuming the available REST endpoints.

Getting Started

NuGet

To install and use the library in your project, run the following NuGet command:

Install-Package ClashClient

You can optionally specify a version using the -Version x.* flag.

Code Integration

To use the library, first you’ll need to create a developer account with SuperCell at: https://developer.clashofclans.com

Once you have an account, set up a key: Create Token

Configuration

The clash-client library has extensibility in mind to suit needs for multiple configurations. The ClashClient.Common.Configuration.IConfigurationProvider can be implemented to look at a Web.config or similar configuration file, a SQL database, or some other source by implementing it in your code. Provided with the library is the ClashClient.Configuration.InMemoryConfigurationProvider that can be used.

Depending on how you set your configuration, the following keys are required for the library to function:

Key Value Description
ApiVersion v1 The version of the clash of clans API to use (currently v1)
ClashAPI `https://api.clashofclans.com’ The base URL for the API
ApiToken {your-token-here} The token you created on your Clash of Clans developer account

Optional Arguments

Key Value Description
Caching_Enabled true / false Disabled if not specified. It is recommended to use caching in your production environment where possible

Logging

The library is setup to use log4net for logging purposes. The log4net library is very flexible in it’s logging capabilities and reviewing all of them is already done well in the log4net documentation. You don’t have to record any log information from the library but if you need to debug or want to enable logging, you have to configure it within your application. For a quick-start, here is an example configuration in a web.config file that will write to a formatted log file, automatically incrementing a log file number when the file exceeds 10MB:

<?xml version="1.0" encoding="utf-8"?>
<!--
  For more information on how to configure your ASP.NET application, please visit
  https://go.microsoft.com/fwlink/?LinkId=301879
  -->
<configuration>
  <configSections>
    <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net" />
  </configSections>
  ...
  <log4net>
    <appender name="RollingLogFileAppender" type="log4net.Appender.RollingFileAppender">
      <file value="logs\debug.log" />
      <appendToFile value="true" />
      <rollingStyle value="size" />
      <maxSizeRollBackups value="30" />
      <maximumFileSize value="10MB" />
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="[%date %-2thread %-5level %-12logger %-10method] %message%newline" />
      </layout>
      <StaticLogFileName value="false" />
      <countDirection value="1" />
    </appender>
    <root>
      <level value="ALL" />
      <appender-ref ref="RollingLogFileAppender" />
    </root>
  </log4net>
</configuration>

Caching

The application supports a configurable caching mechanism that leverages the .NET In-memory cache (though you can write your own implementation of the ICacheProvider and ICacheSettings interfaces).

A custom set of configuration classes are used to control cache life-times based on your preferences. A design decision was made to avoid hard-coding the cache durations in code by providing general cache preferences whose values are mapped to durations in the configuration.

Below is an example use of the custom configuration sections in a web.config file:

    <configSections>
        <sectionGroup name="cacheConfigurationGroup">
            <section name="cacheConfiguration" type="ClashClient.Common.Caching.CacheConfigurationSection, ClashClient.Common" allowDefinition="Everywhere" allowLocation="true" />
        </sectionGroup>
    </configSections>
    ...
    <cacheConfigurationGroup>
        <cacheConfiguration>
            <preferences>
                <add preference="Default" duration="30" />
                <add preference="ShortLivedSliding" duration="2" />
                <add preference="ShortLived" duration="2" />
                <add preference="ExtendedSliding" duration="60" />
                <add preference="Extended" duration="60" />
                <add preference="LongTermSliding" duration="120" />
                <add preference="LongTerm" duration="120" />
            </preferences>
        </cacheConfiguration>
    </cacheConfigurationGroup>

Usage

Once your configuration, account, and token are created using the library is simple.

This example uses the InMemoryConfigurationProvider. It is recommended to implement your own provider for the web or app.config in your application and leverage a dependency injection container to map the dependencies.

    // Build a configuration provider instance required by the ApiClient
    ClashClient.Configuration.InMemoryConfigurationProvider configProvider = new ClashClient.Configuration.InMemoryConfigurationProvider();
    
    // Set configuration options
    configProvider.AddValue("ApiVersion", "v1");
    configProvider.AddValue("Caching_Enabled", true);
    configProvider.AddValue("ClashAPI", "https://api.clashofclans.com");
    configProvider.AddValue("ApiToken", "{token-goes-here}");

    // Setup cache dependencies
    ICacheSettings cacheSettings = new CacheSettings(configProvider);
    ICacheProvider cacheProvider = new RuntimeCacheProvider(cacheSettings);
    
    // Build a new request model instance with the desired parameters
    var searchRequest = new ClanSearchRequest() { ClanName = "Pretty Useless", WarFrequency = WarFrequency.Unknown, MinimumMembers = 20, Limit = 20  };
    
    // Initialize a new instance of the client with dependencies
    ApiClient client = new ApiClient(configProvider, cacheProvider);
    
    // Invoke the API
    var response = client.Load<ClanSearchResponse>(searchRequest);

Further Reading

For more detailed integration guides and information, see the relevant section in the Wiki

Disclaimer

This content is not affiliated with, endorsed, sponsored, or specifically approved by Supercell and Supercell is not responsible for it. For more information see Supercell’s Fan Content Policy: www.supercell.com/fan-content-policy.