BO4E-dotnet

BO4E-dotnet is a C# implementation of Business Objects for Energy (BO4E), a standard used to model business objects in the German energy market. This repository contains class definitions and enumerations for most of the Business Objects, however as of today it's not complete yet and pull requests are very welcome. JSON.net attributes are used to model obligatory and optional fields of the single business objects and components.

The source code in this repository is Open Source and available under a MIT license; see the license file.

See also our (still very alpha) Python Implementation of BO4E (pypi).

Nuget Packages and Usage of BO4E-dotnet

The content of this repository is used to build the following nuget packages:

Package Name	Description	Stability & Maturity
Hochfrequenz.BO4Enet	Definitions of the business objects (namespace BO4E.BO), compontents (namespace BO4E.COM) and enumerations (namespace BO4E.ENUM)	not feature complete but stable and widely used in production for JSON serialization; still alpha for GRPC serialization
Hochfrequenz.BO4E.Extensions	Contains extension methods for business objects and components (as of now mostly BO.Energiemenge and COM.Verbrauch, which are heavily used by Hochfrequenz cloud solutions).	stable, high test coverage, production use
Hochfrequenz.BO4E.Reporting	Contains tools to analyse single business objects and sets of objects	stable, high test coverage, production use
Hochfrequenz.BO4E.Extensions.Encryption	Provides methods to encrypt and anonymize business objects and compontents using libsodium/Sodium and Bouncy Castle/Org.BouncyCastle APIs	high test coverage, so far missing real world usage

This Repository Is Not Feature Complete Yet

Please see Issue #29 for a list of Business Objects, that are not yet implemented. Your contributions are very welcome.

Detailed Documentation

The docstrings from within the source code are used to automatically generate a doc.fx based documentation. Please also consider the official documentation maintained by Interessengemeinschaft Geschäftsobjekte Energiewirtschaft e.V. from which most of the source code docstrings are copied/derived.

Getting Started / Basic Examples

1. install the nuget package Hochfrequenz.BO4Enet
2. import it

using BO4E;

3. start developing applications based on Business Objects for Energy (BO4E)

Create BusinessObjects

using BO4E.BO;
using BO4E.ENUM;
// ...
var energiemenge = new Energiemenge()
{
    LokationsId = "DE0123456789012345678901234567890",
    LokationsTyp = LokationsTyp.MeLo,
    Energieverbrauch = new List<Verbrauch>()
};

Make Use of Built in Validation Methods for German Location IDs

using BO4E.BO;
using BO4E.ENUM;
// ...
var malo = new Marktlokation()
{
    MarktlokationsId = "1235678901",
    Sparte = Sparte.STROM,
    Energierichtung = Energierichtung.AUSSP
};
Assert.IsFalse(malo.IsValid()); // because the obligatory bilanzierungsmethode is not set
malo.bilanzierungsmethode = Bilanzierungsmethode.SLP;
Assert.IsTrue(malo.IsValid(checkId:false)); // because all obligatory fields are set
Assert.IsFalse(malo.IsValid()); // but the marklokationsId is still wrong
malo.MarktlokationsId = "51238696781"; // matches the appropriate regex and has the right check sum
Assert.IsTrue(malo.IsValid());

Add Custom Fields on the Fly via UserProperties

using BO4E.BO;
using Newtonsoft.Json;
// ...
string meloJson = @"{'messlokationsId': 'DE0123456789012345678901234567890', 'sparte': 'STROM', 'myCustomInfo': 'some_value_not_covered_by_bo4e', 'myCustomValue': 123.456}";
var melo = JsonConvert.DeserializeObject<Messlokation>(meloJson);
Assert.IsTrue(melo.IsValid());
Assert.IsNotNull(melo.UserProperties);
Assert.AreEqual("some_value_not_covered_by_bo4e", melo.UserProperties["myCustomInfo"].ToObject<string>());
Assert.AreEqual(123.456M, melo.UserProperties["myCustomValue"].ToObject<decimal>());

Don't Write Your Own Logic for Basic Operations

using BO4E.COM;
using BO4E.ENUM;
// ...
var v1 = new Verbrauch()
{
    Einheit = Mengeneinheit.KWH,
    Obiskennzahl = "1-1:1.8.0",
    Startdatum = new DateTime(2019, 1, 1, 0, 0, 0, DateTimeKind.Utc),
    Enddatum = new DateTime(2020, 1, 1, 0, 0, 0, DateTimeKind.Utc)
};
var v2 = new Verbrauch()
{
    Einheit = Mengeneinheit.KWH,
    Obiskennzahl = "1-1:1.8.0",
    Startdatum = new DateTime(2019, 1, 1, 0, 0, 0, DateTimeKind.Utc),
    Enddatum = new DateTime(2020, 1, 1, 0, 0, 0, DateTimeKind.Utc)
};

Assert.AreEqual(v1, v2);
Assert.IsTrue(v1.Equals(v2));
Assert.AreEqual(v1.GetHashCode(), v2.GetHashCode());
Assert.IsFalse(v1 == v2);

Feature Rich Extension Packages

Using the Hochfrequenz.BO4E.Extensions gives you access to powerful analysis methods for Business Objects. We present them directly as minimal working examples in executable show case tests.

• Energiemenge
• Verbrauch
• CompletenessReport
• Encrypted Business Objects
• (Partially) Anonymized Business Objects

Stable and Reliable Due to Good Test Coverage

(branch coverage as of 2020-04-09, not yet automated)

• ~54% in BO4E main project
• ~69% in the extensions package
• ~66% in the reporting package

Batteries Included

We try to make the usage of BO4E in general and this library in particular as smooth as possible. Therefore it not only includes bare C# files but also some extra ressources that might be usefule to you.

PlantUML files

The folder puml-files contains autogenerated PlantUML definitions for Business Objects, COMponents and ENUMs that are currently implemented in this repository. You can use the files provided in this repository or generate them on your own using PlantUmlClassDiagramGenerator by Hirotada Kobayashi aka pierre3. Please find instructions on how to use the tool in their repository. Please especially note that include.puml includes all definitions inside just one file.

Easy Validation using Json.NET Schema (JSchema)

The folder json-schema-files contains autogenerated JSON.net schemas for all Business Objects that are currently implemented in this repository. Using these schemas allows for easy, transparent and cross plattform validation of your Business Objects. (Find out more about Json Schema.)

Protocol-Buffer Definitions

In the folder BO4E-dotnet/protobuf-files you can find autogenerated .proto files for all implemented Business Objects (except for those with multiple inheritance like e.g. BO.Marktteilnehmer or those derived from BO.Preisblatt which still causes headache using protobuf-net). The proto files are embedded into the BO4E nuget package as content files. This allows you to reference them.

Contributing

Contributions are welcome. Feel free to open a Pull Request against the develop branch of this repository. Please provide unit tests if you contribute logic beyond bare bare business object definitions. We do track our modification proposals to the official BO4E standard in a separate repository: BO4E-modification-proposals.

Hochfrequenz

Hochfrequenz Unternehmensberatung GmbH is a Grünwald (near Munich) based consulting company with offices in Berlin and Bremen. We're not only the main contributor to open source BO4E software 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) and our Stack Overflow profile that also contains job openings.