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
<PackageReference Include="Elvia.Edna.Events" Version="12.0.0" />
<PackageVersion Include="Elvia.Edna.Events" Version="12.0.0" />
<PackageReference Include="Elvia.Edna.Events" />
paket add Elvia.Edna.Events --version 12.0.0
#r "nuget: Elvia.Edna.Events, 12.0.0"
#:package Elvia.Edna.Events@12.0.0
#addin nuget:?package=Elvia.Edna.Events&version=12.0.0
#tool nuget:?package=Elvia.Edna.Events&version=12.0.0
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)
RunAsyncfraBackgroundService.ExecuteAsync.BackgroundServiceobserverer tasken, og med standardBackgroundServiceExceptionBehavior.StopHoststopper en feilende consumer hele hosten i stedet for å etterlate en død consumer. - Ikke await
RunAsyncfraIHostedService.StartAsync; da blir hosten aldri ferdig startet. - Sett message handler før
RunAsynckalles. É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)));
StartConsumerLooper omdøpt tilRunAsyncog er obsolete.StartAsyncer 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-createdpublic.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 loggesAll- 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
systemNameMÅ matche namespaceapplicationNameMÅ matche serviceAccountName
Dette valideres automatisk i Kubernetes-miljø.
HashiVault Secrets
Pakken henter automatisk Kafka-credentials fra HashiVault:
edna/kv/cloudevents/creds/{systemName}/keyedna/kv/cloudevents/creds/{systemName}/secretedna/kv/cloudevents/creds/{systemName}/schema_registry_keyedna/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 viaBlockAndContinue. Blokkerte meldinger telles ikke iedna_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 ernull).
🔧 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:
- Team Edna
- GitHub Issues
📄 License
Intern Elvia-pakke - ikke for ekstern bruk.
| Product | Versions 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. |
-
net10.0
- Chr.Avro.Binary (>= 10.13.1)
- Chr.Avro.Codegen (>= 10.13.1)
- Chr.Avro.Confluent (>= 10.13.1)
- Confluent.Kafka (>= 2.14.2)
- Confluent.SchemaRegistry (>= 2.14.2)
- Elvia.Configuration (>= 8.0.0)
- Elvia.Meldingsportalen.Logger (>= 2.3.2)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 11.0.0)
- Microsoft.Extensions.Logging (>= 11.0.0)
- NJsonSchema (>= 11.6.2)
- NJsonSchema.CodeGeneration.CSharp (>= 11.6.2)
- NodaTime (>= 3.3.7)
- NodaTime.Serialization.SystemTextJson (>= 1.4.0 && < 2.0.0)
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 |
Breaking changes in 12.0.0. Migration guide: https://github.com/3lvia/libraries-elvia-edna-events/blob/trunk/MIGRATION_GUIDE_v12.md. Changelog: https://github.com/3lvia/libraries-elvia-edna-events/blob/trunk/CHANGELOG.md