Elvia.Edna.Events 12.0.0

dotnet add package Elvia.Edna.Events --version 12.0.0
                    
NuGet\Install-Package Elvia.Edna.Events -Version 12.0.0
                    
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="Elvia.Edna.Events" Version="12.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Elvia.Edna.Events" Version="12.0.0" />
                    
Directory.Packages.props
<PackageReference Include="Elvia.Edna.Events" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Elvia.Edna.Events --version 12.0.0
                    
#r "nuget: Elvia.Edna.Events, 12.0.0"
                    
#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.
#:package Elvia.Edna.Events@12.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Elvia.Edna.Events&version=12.0.0
                    
Install as a Cake Addin
#tool nuget:?package=Elvia.Edna.Events&version=12.0.0
                    
Install as a Cake Tool

Elvia.Edna.Events

En intern NuGet-pakke for Kafka-kommunikasjon i Elvia. Pakken gir en enkel og type-sikker abstraksjon over Confluent Kafka med innebygd støtte for:

  • ✅ Avro og JSON serialisering
  • ✅ Schema Registry integrasjon
  • ✅ OpenTelemetry / Application Insights telemetry
  • ✅ Meldingsportalen logging
  • ✅ Prometheus metrics
  • ✅ Batch processing
  • ✅ Fake messages for testing

📦 Installasjon

dotnet add package Elvia.Edna.Events

🚀 Quick Start

Producer (Publisher)

using Elvia.Edna.Events.Extensions;
using Elvia.Edna.Events.Kafka;

// I Startup.cs / Program.cs
services.AddKafkaPublisher<MyMessage>(
    applicationName: "my-application",
    topicName: "private.domain.system.my-topic",
    topicSchemaStrategy: TopicSchemaStrategy.UseGeneratedAvroSchemaFromMessageType(),
    meldingsportalenLoggingOptions: MeldingsportalenLoggingOptions.All
);

// I din service
public class MyService
{
    private readonly IKafkaPublisher<MyMessage> _publisher;

    public MyService(IKafkaPublisher<MyMessage> publisher)
    {
        _publisher = publisher;
    }

    public async Task PublishAsync(MyMessage message, CancellationToken ct)
    {
        await _publisher.Publish(
            data: message,
            subject: "my-subject-key",
            stoppingToken: ct
        );
    }
}

Consumer

using Elvia.Edna.Events.Extensions;
using Elvia.Edna.Events.Kafka;

// I Startup.cs / Program.cs
services.AddKafkaConsumer<MyMessage>(
    systemName: "my-system",  // Må matche namespace i Kubernetes
    topicName: "private.domain.system.my-topic",
    applicationName: "my-application",  // Må matche serviceAccountName i Kubernetes
    meldingsportalenLoggingOptions: MeldingsportalenLoggingOptions.Errors,
    options: new ConsumerOptions<MyMessage>
    {
        BatchSize = 100
    }
);

// I en BackgroundService
public class MyKafkaConsumerService : BackgroundService
{
    private readonly IKafkaConsumer<MyMessage> _consumer;

    public MyKafkaConsumerService(IKafkaConsumer<MyMessage> consumer)
    {
        _consumer = consumer;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // Enkel message-for-message håndtering
        _consumer.SetHandleMessage(async (message, context) =>
        {
            // Process message
            Console.WriteLine($"Received: {message.Subject}");

            return MessageHandlerResult.Ok();
        });

        await _consumer.RunAsync(stoppingToken);
    }
}

RunAsync kjører consumeren til stoppingToken kanselleres eller en feil oppstår. Tasken fullføres altså først når consumeren har stoppet, ikke når den har startet (samme semantikk som IHost.RunAsync). Derfor:

  • Await (eller returner) RunAsync fra BackgroundService.ExecuteAsync. BackgroundService observerer tasken, og med standard BackgroundServiceExceptionBehavior.StopHost stopper en feilende consumer hele hosten i stedet for å etterlate en død consumer.
  • Ikke await RunAsync fra IHostedService.StartAsync; da blir hosten aldri ferdig startet.
  • Sett message handler før RunAsync kalles. Én consumer-instans kan bare kjøre én loop om gangen.
  • Flere consumere i samme service: await Task.WhenAll(consumers.Select(c => c.RunAsync(stoppingToken)));

StartConsumerLoop er omdøpt til RunAsync og er obsolete. StartAsync er obsolete fordi den kjører loopen i bakgrunnen og bare logger feil.

📚 Detaljert Dokumentasjon

Topic Naming Convention

Topics følger Elvia-standarden:

{visibility}.{domain}.{system}.{type}

Eksempler:

  • private.customer.customer-api.customer-created
  • public.meter.metering.hourly-reading

Topic Schema Strategies

1. Auto-generert Avro Schema
TopicSchemaStrategy.UseGeneratedAvroSchemaFromMessageType()

Genererer Avro-schema automatisk fra C# typen. Anbefalt for de fleste use cases.

2. Bruk Existing Schema fra Registry
TopicSchemaStrategy.UseLatestSchema(schemaCacheSeconds: 60)

Henter siste registrerte schema fra Schema Registry.

3. Custom Avro Schema
TopicSchemaStrategy.UseAvroSchema(schemaAsJson)

Bruk en egen .avsc fil.

4. JSON Schema
TopicSchemaStrategy.UseJsonSchema(schemaAsJson)

For JSON-serialisering med schema validering.

5. Ingen Schema (Raw Strings)
TopicSchemaStrategy.NoSchemaRawStrings()

⚠️ Kun for spesielle tilfeller hvor schema ikke kan bestemmes.

Meldingsportalen logging options

meldingsportalenLoggingOptions er en påkrevd parameter til AddKafkaPublisher/AddKafkaConsumer og styrer kun logging til Meldingsportalen:

MeldingsportalenLoggingOptions.All   // None, Errors, All

MeldingsportalenLoggingOptions:

  • None - Ingen vanlige suksess-/feillogger. Blokkerte meldinger logges alltid med full payload.
  • Errors - Kun feil logges
  • All - All meldinger logges (success + errors)

MeldingsportalenLoggingOptions styrer vanlig logging til Meldingsportalen. Blokkerte meldinger logges alltid med full payload slik at de kan kjøres på nytt. Biblioteket lager traces og metrics; appens OpenTelemetry-oppsett styrer hvilke instrumenteringer som samles inn og eksporteres. Tracing styres i Elvia.Telemetry, som som standard inkluderer AddSource("Elvia.*") (opt-out via SkipElviaLibrariesTracing).

For logging til OpenTelemetry settes default filter for Elvia.Edna.Events til Information i denne pakken, og du kan overstyre med:

builder.Logging.SetEdnaEventsLogLevel(LogLevel.Information);

Se MIGRATION_GUIDE_v12.md for konkret mapping fra gamle TelemetryMode-verdier.

Batch Processing

For høy throughput, prosesser meldinger i batch:

services.AddKafkaConsumer<MyMessage>(
    // ... other params
    options: new ConsumerOptions<MyMessage>
    {
        BatchSize = 100  // Prosesser 100 meldinger om gangen
    }
);

// I consumer. Returner ett resultat per melding.
_consumer.HandleMessageBatch = async (batch) =>
{
    var results = new List<HandleMessageResult<MyMessage>>();

    foreach (var message in batch.Messages)
    {
        try
        {
            await ProcessAsync(message.Data, batch.CancellationToken);
            results.Add(HandleMessageResult<MyMessage>.Success(message));
        }
        catch (TransientException ex)
        {
            // Logg feilen og fortsett med neste melding
            results.Add(HandleMessageResult<MyMessage>.LogAndContinue(message, ex));
        }
    }

    return new HandleMessageBatchResult<MyMessage>(results);
};

Tilgjengelige resultater: Success, LogAndContinue, BlockAndContinue og Error. Error stopper consumeren. En exception som ikke fanges i handleren, stopper også consumeren.

Error Handling

Velg resultat i handleren
_consumer.SetHandleMessage(async (message, context) =>
{
    try
    {
        await ProcessAsync(message, context.CancellationToken);
        return MessageHandlerResult.Ok();
    }
    catch (CriticalException ex)
    {
        // Stopp consumering. RunAsync feiler, og hosten stopper.
        return MessageHandlerResult.Failed(ex);
    }
    catch (InvalidMessageException ex)
    {
        // Ta vare på meldingen i Meldingsportalen for senere replay, og fortsett.
        return MessageHandlerResult.BlockAndContinue(ex, blockKey: context.Subject);
    }
    catch (TransientException ex)
    {
        // Logg feilen og fortsett med neste melding.
        return MessageHandlerResult.LogAndContinue(ex);
    }
});

En exception som ikke fanges i handleren, stopper consumeren på samme måte som Failed.

Custom ConsumeException handler

HandleConsumeException kalles ved feil under consume, typisk deserialisering. Kast exception videre for å stoppe consumeren:

consumer.HandleConsumeException = exception =>
{
    _logger.LogError(exception, "Kafka consume error");

    if (exception.Error.IsFatal)
    {
        throw exception;
    }

    return Task.CompletedTask;
};

Publish Multiple Messages (High Throughput)

var messages = new List<Message<MyMessage>>
{
    new Message<MyMessage>(new MyMessage(1), "subject-1"),
    new Message<MyMessage>(new MyMessage(2), "subject-2"),
    new Message<MyMessage>(new MyMessage(3), "subject-3")
};

// Publiserer parallelt med throttling
await _publisher.PublishParallel(messages, cancellationToken);

Custom Headers

await _publisher.Publish(
    data: message,
    subject: "my-subject",
    customHeaders: new Dictionary<string, string>
    {
        { "X-Correlation-Id", correlationId },
        { "X-User-Id", userId }
    },
    stoppingToken: ct
);

Consumer Startup Options

Start fra beginning
var startupOptions = new ConsumerStartupOptions 
{ 
    Start = StartFrom.OffsetBeginning() 
};
await _consumer.RunAsync(startupOptions, stoppingToken);
Start fra siste committed offset
var startupOptions = new ConsumerStartupOptions 
{ 
    Start = StartFrom.OffsetLastCommitted() 
};
Start fra spesifikt tidspunkt
var startupOptions = new ConsumerStartupOptions 
{ 
    Start = StartFrom.DateTimeOffset(DateTimeOffset.UtcNow.AddHours(-1)) 
};
Start fra spesifikk offset
var startupOptions = new ConsumerStartupOptions 
{ 
    Start = StartFrom.AssignOffsets([
        new PartitionOffset("my-topic", partition: 0, offset: 1000)
    ])
};

Flere meldingstyper på samme topic

Med PolymorphicMessageConfig<TBase> kan flere meldingstyper som arver fra samme basetype, sendes på samme topic. Typene finnes automatisk i samme assembly som basetypen, og schema, serialisering og deserialisering settes opp for deg. Handleren mottar basetypen og må selv sjekke den konkrete typen.

using Elvia.Edna.Events.Serialization;

var options = new PublisherOptions<MeterEvent>
{
    CustomSerializationConfig = [new PolymorphicMessageConfig<MeterEvent>()]
};

Bruk samme konfigurasjon i ConsumerOptions<MeterEvent> på consumer-siden. Typene kan ikke være nestede klasser.

For andre spesialtyper kan du lage en egen CustomAvroSerializationConfig med Chr.Avro-builder-cases (SchemaCaseBuilders, SerializerCaseBuilders, DeserializerCaseBuilders).

Tombstones (Delete Messages)

For å slette/markere meldinger som slettet i Kafka:

var options = new PublisherOptions<MyMessage>
{
    EnableTombstones = true
};

// Publiser null for å slette
await _publisher.Publish(data: null, subject: "my-key");

🧪 Testing

Test handleren, ikke Kafka-koblingen. Legg handleren i en egen metode, og enhetstest den med mocks av IMessageContext og IKafkaPublisher<T>:

var publisher = A.Fake<IKafkaPublisher<ReadingAccepted>>();
var context = A.Fake<IMessageContext>();
A.CallTo(() => context.Subject).Returns("m1");
var sut = new ReadingConsumer(A.Fake<IKafkaConsumer<MeterReading>>(), publisher);

var result = await sut.HandleAsync(new MeterReading("m1", 10), context);

Assert.False(result.IsFaulted);

Se testing-referansen i skillen for flere eksempler, og vurderingen av hvorfor pakken ikke har egne test doubles.

⚙️ Konfigurasjon

Kubernetes Requirements

  • systemName MÅ matche namespace
  • applicationName MÅ matche serviceAccountName

Dette valideres automatisk i Kubernetes-miljø.

HashiVault Secrets

Pakken henter automatisk Kafka-credentials fra HashiVault:

  • edna/kv/cloudevents/creds/{systemName}/key
  • edna/kv/cloudevents/creds/{systemName}/secret
  • edna/kv/cloudevents/creds/{systemName}/schema_registry_key
  • edna/kv/cloudevents/creds/{systemName}/schema_registry_secret

Vault-oppslaget er internt og kan ikke overstyres fra applikasjonskode. I tester bytter du ut IKafkaPublisher<T> og IKafkaConsumer<T> med mocks, se Testing.

📊 Metrics

Biblioteket registrerer følgende counters. Konfigurer appens OpenTelemetry metrics-provider og exporter for å samle dem inn og eksponere dem:

Producer:

  • edna_published_messages_total{domain, system, topic, source, type, success}
  • edna_published_fake_messages_total{domain, system, topic, source, type, success}

Consumer:

  • edna_consumed_messages_total{system, consumerGroupId, topic, success}
  • edna_consumed_fake_messages_total{system, consumerGroupId, topic, success}
  • edna_blocked_messages_total{system, consumerGroupId, topic, reason} - meldinger satt til side via BlockAndContinue. Blokkerte meldinger telles ikke i edna_consumed_messages_total. reason=error: handleren feilet på denne meldingen (exception er satt). reason=preceding_block: meldingen er satt til side fordi en tidligere melding med samme block-key allerede er blokkert (exception er null).

🔧 Advanced

Custom Producer/Consumer Config

var customConfig = new KafkaConsumerConfig(
    topic: "my-topic",
    consumerGroupId: "custom-group",
    systemName: "my-system",
    applicationName: "my-app",
    consumerConfig: new ConsumerConfig
    {
        // Custom Confluent.Kafka ConsumerConfig
        MaxPollIntervalMs = 300000
    },
    schemaRegistryConfig: new SchemaRegistryConfig
    {
        // Custom schema registry config
    }
);

services.AddKafkaConsumer<MyMessage>(
    // ... params
    kafkaConsumerConfig: customConfig
);

Message Context

Message context gir tilgang til metadata:

_consumer.SetHandleMessage(async (message, context) =>
{
    var messageId = context.Id;
    var subject = context.Subject;               // Kafka-nøkkelen
    var topic = context.Topic;
    var partition = context.Offset.Partition;
    var offset = context.Offset.Offset;
    var createdTime = context.CreatedTime;
    var header = context.GetHeaderValue("X-Correlation-Id");
    var activity = context.TraceActivity;         // Trace-kontekst fra produsenten

    return MessageHandlerResult.Ok();
});

🆘 Troubleshooting

"GroupAuthorizationFailed"

Sjekk at applicationName matcher Terraform-oppsett og at Terraform er kjørt i miljøet.

"Schema Registry timeout"

Schema Registry kan være treg første gang. Default timeout er 5 sekunder.

"UnsupportedTypeException"

Hvis en type arver en generisk collection, legg til en constructor som tar IEnumerable<T>:

public class MyCollection : List<MyItem>
{
    public MyCollection() { }
    public MyCollection(IEnumerable<MyItem> items) : base(items) { }
}

🤖 Bruk med AI-agenter

Repoet har en agent-skill for GitHub Copilot og Claude Code. Den beskriver hvordan pakken skal brukes og testes. Kopier mappen skills/elvia-edna-events til .github/skills/ (Copilot) eller .claude/skills/ (Claude Code) i applikasjonens repo.

📝 Changelog

Se CHANGELOG.md for versjonhistorikk.

🤝 Bidra

Dette er en intern Elvia-pakke. For spørsmål eller issues, kontakt:

📄 License

Intern Elvia-pakke - ikke for ekstern bruk.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on Elvia.Edna.Events:

Package Downloads
Elvia.Messagebalancer.Client

Package Description

adms-extensions-lib-messagetracker

Package Description

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
12.0.0 536 11/16/2026
12.0.0-rc1 86 11/12/2026
12.0.0-preview.1-9 60 11/14/2026
12.0.0-preview.1-8 55 11/14/2026
12.0.0-preview.1-7 58 11/13/2026
12.0.0-preview.1-6 58 11/12/2026
12.0.0-preview.1-5 55 11/2/2026
12.0.0-preview.1-4 69 10/30/2026
12.0.0-preview.1-3 68 10/28/2026
12.0.0-preview.1-21 48 11/16/2026
12.0.0-preview.1-2 68 10/20/2026
12.0.0-preview.1-1 71 10/20/2026
12.0.0-beta3 104 10/13/2026
12.0.0-beta2 102 10/13/2026
12.0.0-beta1 98 10/7/2026
11.11.0-preview.1-77 69 10/13/2026
11.11.0-preview.1-76 60 10/10/2026
11.11.0-preview.1-75 74 10/9/2026
11.11.0-preview.1-74 77 10/1/2026
11.11.0-preview.1-73 72 9/24/2026
Loading failed