# Quick Start

This guide walks you through publishing your first event in under five minutes.

## 1. Install the packages

```bash
dotnet add package Hermodr.Publisher
dotnet add package Hermodr.Annotations
```

Add a channel package for the transport you want to use, for example Azure Service Bus:

```bash
dotnet add package Hermodr.Publisher.AzureServiceBus
```

## 2. Annotate your event data class

Create a class that represents the data payload of your event and decorate it with `[Event]`:

```csharp
using System.ComponentModel.DataAnnotations;
using Hermodr;

[Event("order.placed", "1.0")]
public class OrderPlacedData
{
    [Required]
    public Guid OrderId { get; set; }

    [Required]
    [Range(0.01, 1_000_000.0)]
    public decimal Amount { get; set; }

    [Required]
    public string Currency { get; set; } = default!;

    public string? Notes { get; set; }
}
```

The `[Event]` attribute records the **event type** string and its **version**. The framework uses these values when constructing the `CloudEvent` envelope.

## 3. Register the publisher

In your `Program.cs` (or wherever you configure DI), register the event publisher and the Azure Service Bus channel:

```csharp
using Hermodr;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddEventPublisher(options =>
    {
        options.Source = new Uri("https://myapp.example.com");
    })
    .AddServiceBus(options =>
    {
        options.ConnectionString = builder.Configuration["ServiceBus:ConnectionString"]!;
        options.QueueName        = builder.Configuration["ServiceBus:QueueName"]!;
    });
```

> **Tip:** You can also bind options from `appsettings.json` by passing a configuration-section path instead of a delegate — see [Azure Service Bus](/publisher-channels/azure-service-bus.md).

## 4. Inject and publish

Inject `EventPublisher` wherever you need it and call `PublishAsync`:

```csharp
using Hermodr;

public class OrderService
{
    private readonly EventPublisher _publisher;

    public OrderService(EventPublisher publisher)
    {
        _publisher = publisher;
    }

    public async Task PlaceOrderAsync(Guid orderId, decimal amount, string currency)
    {
        var data = new OrderPlacedData
        {
            OrderId  = orderId,
            Amount   = amount,
            Currency = currency
        };

        // The framework builds the CloudEvent envelope from the [Event] attribute
        // and publishes it to all registered channels.
        await _publisher.PublishAsync(data);
    }
}
```

## 5. Publishing a raw CloudEvent

If you already have a `CloudEvent` instance you can publish it directly:

```csharp
using CloudNative.CloudEvents;
using Hermodr;

var @event = new CloudEvent
{
    Type    = "com.example.myevent",
    Source  = new Uri("https://myapp.example.com"),
    DataContentType = "application/json",
    Data    = new { Message = "Hello, World!" }
};

await publisher.PublishEventAsync(@event);
```

## What's next?

| Topic                                                   | Description                            |
| ------------------------------------------------------- | -------------------------------------- |
| [Core Concepts](/core-concepts/concepts.md)             | Understand how the pieces fit together |
| [Publisher Channels](/publisher-channels/publishers.md) | Configure specific transports          |
| [Event Schema](/event-schema/schema.md)                 | Validate events before publishing      |
| [Testing](/testing/testing.md)                          | Unit-test your event publishing        |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hermodr.deveel.org/getting-started/quick-start.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.