Getting Started

Welcome to Gryd.IO! This guide will help you get up and running quickly.

Quick Start with Templates

The fastest way to start a new project is using our CLI templates:

bash

# Install Gryd.IO templates
dotnet new install Gryd.IO.Templates

# Create a complete API with Auth + Crud
dotnet new gryd-api -n MyApiProject

# Or create a minimal API
dotnet new gryd-minimal -n MyMinimalApi

# Or create a new module for an existing project
dotnet new gryd-module -n Catalog --ModuleName Products

TIP

See the CLI Templates documentation for all available options and generated structures.

Prerequisites

.NET 9.0 SDK or later
Your favorite IDE (Visual Studio, VS Code, Rider)
Basic knowledge of C# and ASP.NET Core

Manual Installation

Using NuGet

Install the packages you need via NuGet:

.NET CLIPackage ManagerPackageReference

bash

# Install all core packages
dotnet add package Gryd.Core
dotnet add package Gryd.Domain
dotnet add package Gryd.Application
dotnet add package Gryd.Infrastructure
dotnet add package Gryd.API

bash

Install-Package Gryd.Core
Install-Package Gryd.Domain
Install-Package Gryd.Application
Install-Package Gryd.Infrastructure
Install-Package Gryd.API

xml

<&lt;ItemGroup&gt;
  <PackageReference Include="Gryd.Core" Version="1.0.*" />
  <PackageReference Include="Gryd.Domain" Version="1.0.*" />
  <PackageReference Include="Gryd.Application" Version="1.0.*" />
  <PackageReference Include="Gryd.Infrastructure" Version="1.0.*" />
  <PackageReference Include="Gryd.API" Version="1.0.*" />
</ItemGroup>

Project Structure

Gryd.IO follows Clean Architecture principles. Here's the recommended structure:

📦 YourApplication/
├── 📁 src/
│   ├── 📁 Core/
│   │   ├── 📁 YourApp.Domain/         # Entities, ValueObjects, Events
│   │   └── 📁 YourApp.Application/    # Commands, Queries, Handlers
│   ├── 📁 Infrastructure/
│   │   └── 📁 YourApp.Infrastructure/ # Repositories, External Services
│   └── 📁 Presentation/
│       └── 📁 YourApp.API/            # Controllers, Middlewares
└── 📁 tests/
    ├── 📁 YourApp.Domain.Tests/
    ├── 📁 YourApp.Application.Tests/
    └── 📁 YourApp.API.Tests/

Quick Example

Let's create a simple entity and use the framework:

1. Create a Domain Entity

csharp

using Gryd.Domain.Base;
using Gryd.Domain.Events;

namespace YourApp.Domain.Entities;

public class Product : AggregateRoot<&lt;Guid&gt;
{
    public string Name { get; private set; } = string.Empty;
    public string Description { get; private set; } = string.Empty;
    public decimal Price { get; private set; }
    public bool IsActive { get; private set; } = true;

    protected Product() { } // EF Core constructor

    public static Product Create(string name, string description, decimal price)
    {
        var product = new Product
        {
            Id = Guid.NewGuid(),
            Name = name,
            Description = description,
            Price = price
        };

        product.AddDomainEvent(new ProductCreatedEvent(product.Id, name));
        
        return product;
    }

    public void UpdatePrice(decimal newPrice)
    {
        Guard.Against.NegativeOrZero(newPrice, nameof(newPrice));
        
        Price = newPrice;
        SetUpdatedAt();
    }

    public void Deactivate()
    {
        IsActive = false;
        SetUpdatedAt();
    }
}

// Domain Event
public record ProductCreatedEvent(Guid ProductId, string Name) : DomainEvent;

2. Create a Command

csharp

using Gryd.Application.Abstractions.Messaging;
using Gryd.Application.Common;

namespace YourApp.Application.Products.Commands;

// Command
public record CreateProductCommand(
    string Name,
    string Description,
    decimal Price
) : ICommand<&lt;Guid&gt;;

// Validator
public class CreateProductCommandValidator 
    : AbstractValidator<&lt;CreateProductCommand&gt;
{
    public CreateProductCommandValidator()
    {
        RuleFor(x => x.Name)
            .NotEmpty()
            .MaximumLength(200);

        RuleFor(x => x.Description)
            .MaximumLength(1000);

        RuleFor(x => x.Price)
            .GreaterThan(0);
    }
}

// Handler
public class CreateProductCommandHandler 
    : ICommandHandler&lt;CreateProductCommand, Guid&gt;
{
    private readonly IProductRepository _repository;
    private readonly IUnitOfWork _unitOfWork;

    public CreateProductCommandHandler(
        IProductRepository repository,
        IUnitOfWork unitOfWork)
    {
        _repository = repository;
        _unitOfWork = unitOfWork;
    }

    public async Task<Result<&lt;Guid&gt;> Handle(
        CreateProductCommand request,
        CancellationToken cancellationToken)
    {
        var product = Product.Create(
            request.Name,
            request.Description,
            request.Price
        );

        await _repository.AddAsync(product, cancellationToken);
        await _unitOfWork.CommitAsync(cancellationToken);

        return Result<&lt;Guid&gt;.Success(product.Id);
    }
}

3. Create an API Controller

csharp

using Gryd.API.Controllers;
using MediatR;
using Microsoft.AspNetCore.Mvc;

namespace YourApp.API.Controllers;

[Route("api/[controller]")]
public class ProductsController : GrydBaseController
{
    public ProductsController(IMediator mediator) : base(mediator)
    {
    }

    [HttpPost]
    public async Task<&lt;IActionResult&gt; Create(
        [FromBody] CreateProductCommand command,
        CancellationToken cancellationToken)
    {
        var result = await Mediator.Send(command, cancellationToken);
        
        return HandleResult(result, id => CreatedAtAction(
            nameof(GetById), 
            new { id }, 
            new { id }
        ));
    }

    [HttpGet("{id:guid}")]
    public async Task<&lt;IActionResult&gt; GetById(
        Guid id,
        CancellationToken cancellationToken)
    {
        var query = new GetProductByIdQuery(id);
        var result = await Mediator.Send(query, cancellationToken);
        
        return HandleResult(result);
    }
}

4. Configure Services

csharp

using Gryd.API.Extensions;
using Gryd.Application.Extensions;
using Gryd.Infrastructure.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Add Gryd.IO services
builder.Services
    .AddGrydApplication(typeof(CreateProductCommand).Assembly)
    .AddGrydInfrastructure(builder.Configuration)
    .AddGrydApi();

// Add your own services
builder.Services.AddScoped&lt;IProductRepository, ProductRepository&gt;();

var app = builder.Build();

// Use Gryd.IO middleware
app.UseGryd();

app.MapControllers();
app.Run();