AhbichtClient.NET

A client to use features of the Python library AHBicht in the .NET universe. For this library to work you need a backend, that exposes AHBicht features via a REST API. This backend is available on the public internet, free of charge but without warranty by Hochfrequenz (based on Azure Functions). But you can host it yourself like any other microservice. Hochfrequenz can provide you with a standalone Docker image; Contact @JoschaMetze (joscha.metze+ahbicht@hochfrequenz.de).

Installation

Install it from nuget AhbichtClient:

dotnet add package AhbichtClient

How to use this library (Quickstart with public backend)

AhbichtClient.net/AhbichtClient/AhbichtClientQuickStartApp/Program.cs

Lines 1 to 54 in b234147

	using AhbichtClient;
	using AhbichtClient.Model;
	using EDILibrary;
	namespace AhbichtClientQuickStartApp;
	public class MyHttpClientFactory : IHttpClientFactory
	{
	public HttpClient CreateClient(string name)
	{
	return new HttpClient
	{
	BaseAddress = new Uri("http://ahbicht.azurewebsites.net")
	};
	}
	}
	class Program
	{
	static async Task Main(string[] args)
	{
	var client = new AhbichtRestClient(new MyHttpClientFactory(), new NoAuthenticator());
	var packageMapping = await client.ResolvePackage("10P", EdifactFormat.UTILMD, EdifactFormatVersion.FV2404);
	Console.WriteLine($"The package '10P' is equivalent to {packageMapping.PackageExpression}");
	var conditionMapping = await client.ResolveCondition("244", EdifactFormat.UTILMD, EdifactFormatVersion.FV2404);
	Console.WriteLine($"where '[244]' refers to '{conditionMapping.ConditionText}'");
	const string expression = "Muss ([1] O [2])[951]";
	var categorizedKeyExtract = await client.ExtractKeys(expression);
	Console.WriteLine($"To evaluate the expression '{expression}' you need to provide values for the following keys: " +
	string.Join(", ", categorizedKeyExtract.RequirementConstraintKeys) + " and " + string.Join(", ", categorizedKeyExtract.FormatConstraintKeys));
	var myResults = new ContentEvaluationResult
	{
	Hints = new Dictionary<string, string?>(),
	FormatConstraints = new Dictionary<string, EvaluatedFormatConstraint>
	{
	{
	"951", new EvaluatedFormatConstraint
	{
	FormatConstraintFulfilled = true
	}
	}
	},
	RequirementConstraints = new Dictionary<string, ConditionFulfilledValue>()
	{
	{ "1", ConditionFulfilledValue.Fulfilled },
	{ "2", ConditionFulfilledValue.Unfulfilled }
	}
	};
	var evaluationResult = await client.Evaluate(expression, myResults);
	Console.WriteLine($"The expression '{expression}' is evaluated to: {evaluationResult.RequirementConstraintEvaluationResult.RequirementConstraintsFulfilled}");
	}
	}

This prints:

The package '10P' is equivalent to [20] ∧ [244]

where '[244]' refers to 'Wenn SG10 CCI+6++ZA9 (Aggreg. verantw. ÜNB) in dieser SG8 vorhanden'

To evaluate the expression 'Muss ([1] O [2])[951]' you need to provide values for the following keys: 1, 2 and 951

The expression 'Muss ([1] O [2])[951]' is evaluated to: True

How to use this library (Detailed)

Prerequisites / Account

First of all, you need access to either a local instance of the backend aka ahbicht-functions (private repo, private docker image) or use our public API.

Local Instance

If you have access to our docker image, check out the docker-compose.yml from the integration tests to pull and start the image.

Public Instance

If you're just playing around, you can use our public instance at https://ahbicht.azurewebsites.net. We can't guarantee uptime or performance, but it should be good enough for testing.

Authentication

You need to provide something that implements IAhbichtAuthenticator to the AhbichtClient. Theoretically there are two ways to authenticate, but in practice there is no authentication as of today.

No Authentication

If you're hosting ahbicht-function in the same network or your localhost or our public API, there is no authentication, you can use the NoAuthenticator.

using AhbichtClient;
var myAuthenticator = new NoAuthenticator();

Its name says it all 😉 - but you still need it.

OAuth2 Client and Secret

If, in the future, Hochfrequenz provided you with a client Id and secret, you can use the ClientIdClientSecretAuthenticator class like this:

using AhbichtClient;
var myAuthenticator = new ClientIdClientSecretAuthenticator("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");

Base Address

The HttpClient instance used by the AhbichtRestClient class has to have a BaseAddress set. Use e.g. https://ahbicht.azurewebsites.net for our demo system.

Use with ASP.NET Core

This library is thought to be primarily used in ASP.NET Core applications. That's why it assumes that you have an IHttpClientFactory available in your dependency injection container. See the ExampleAspNetCoreApplication/Program.cs for a minimal working example.

Use without ASP.NET Core

If you're not using ASP.NET Core, you can still use this library but setting up th IHttpClientFactory comes with a bit of boilerplate. See the MweWithoutAspNetTest.cs for a minimal working example.

Modular by Design

All the features from above are available in the AhbichtRestClient class but abstracted into small distinct interfaces:

AhbichtClient.net/AhbichtClient/AhbichtClient/AhbichtRestClient.cs

Line 15 in b30b2ae

public class AhbichtRestClient : IPackageKeyToConditionResolver, IConditionKeyToTextResolver, ICategorizedKeyExtractor, IContentEvaluator

This allows you to freely integrate AHBicht with your own software. You could for example implement parts of the logic AHBicht provides on your own (e.g. package/condition resolution). Also for unit testing and mocking, these interfaces are very useful.

Development

Integration Tests

To run the integration test login to your docker to access the ahbicht-functions/backend image.

docker login ghcr.io -u YOUR_GITHUB_USERNAME

then paste your PAT similarly to described in the integration test CI pipeline

Release (CI/CD)

To release a new version of this library, create a new release in GitHub. Make sure its tag starts with v and the version number, e.g. v1.2.3. Tags without a release won't trigger the release workflow; This enforces that you have to write a changelog before releasing. Releases are not restricted to the main branch, but we prefer them to happen there.

Related Tools and Context

This repository is part of the Hochfrequenz Libraries and Tools for a truly digitized market communication.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Hochfrequenz

Hochfrequenz Unternehmensberatung GmbH is a Grünwald (near Munich) based consulting company with offices in Berlin, Leipzig, Cologne and Bremen and attractive remote options. We're not only a main contributor for open source software for German utilities but, according to Kununu ratings, also among the most attractive employers within the German energy market. Applications of talented developers are welcome at any time! Please consider visiting our career page (German only).