VitoRestbox 1.2.0

📘 VitoRestbox

VitoRestbox is a clean, expressive HTTP request builder for .NET, designed to simplify REST API calls and enrich your application's communication with external services. Inspired by the Latin word vita (“life”), this library brings clarity, vitality, and composability to your HTTP interactions.

✨ Features

✅ Fluent, sentence-like API for building HTTP requests
✅ Supports all HTTP verbs: GET, POST, PUT, PATCH, DELETE
✅ Built-in JSON serialization with customizable options
✅ Header and authentication injection
✅ Flexible .WithHeaders(...) builder pattern
✅ Lifecycle hooks:

• BeforeSend for request inspection
• AfterSend for response handling
• OnFailure for error tracking
• OnException for graceful fallback
  ✅ Timeout configuration with .WithTimeout(...)
  ✅ Exception control with .SuppressExceptions(...)
  ✅ Sync and async execution support
  ✅ Works seamlessly with HttpClient and DI containers
  ✅ Multipart file upload support via .PostMultipart(...), .PutMultipart(...), .PatchMultipart(...)
  ✅ Multi-framework compatibility: supports .NET 5, .NET 6, .NET 7, .NET 8, .NET 9

🚀 Quick Start

var result = await VitoRestboxRequest
    .New(httpClient)
    .To("https://api.example.com/users")
    .WithBearerToken("your-token")
    .WithHeader("X-Custom", "value")
    .Post(new { name = "Reza" })
    .SendAsync<UserResponse>();

var result = await VitoRestboxRequest
    .New(httpClient)
    .To("https://api.example.com/users")
    .WithBearerToken("your-token")
    .WithHeader("X-Custom", "value")
    .Post(new { name = "Reza" })
    .WithTimeout(10)
    .SuppressExceptions()
    .BeforeSend(req => Console.WriteLine($"Sending: {req.RequestUri}"))
    .AfterSend(res => Console.WriteLine($"Status: {res.StatusCode}"))
    .OnFailure(res => Console.WriteLine($"Failed: {res.StatusCode}"))
    .OnException(ex => Console.WriteLine($"Error: {ex.Message}"))
    .SendAsync<UserResponse>();

📤 File Uploads

VitoRestbox supports multipart file uploads using .PostMultipart(...), .PutMultipart(...), and .PatchMultipart(...). You can send files, form fields, and binary content with ease:

await VitoRestboxRequest
    .New(httpClient)
    .To("api/upload")
    .PostMultipart(form =>
    {
        form.Add(new StringContent("Reza"), "username");
        form.Add(new ByteArrayContent(fileBytes), "file", "hello.txt");
    })
    .SendAsync<UploadResponse>();

You can also simulate real IFormFile uploads in tests:

FormFile formFile = await GetFileAsync();

var result = await VitoRestboxRequest
    .New(httpClient)
    .To("api/upload")
    .PostMultipart(form =>
    {
        form.Add(new StringContent("Reza"), "username");
        form.Add(new StreamContent(formFile.OpenReadStream()), "file", formFile.FileName);
    })
    .SendAsync<UploadResponseModel>();

🧠 Fluent Header Builder

Inject multiple headers using chained or multiple lambdas:

.WithHeaders
(
    h => h.Add("Authorization", "Bearer xyz"),
    h => h.Add("X-Request-ID", Guid.NewGuid().ToString())
)

Or use a single chained builder:

.WithHeaders(h => h.Add("Authorization", "Bearer xyz").Add("X-Request-ID", Guid.NewGuid().ToString()))

⏱ Timeout & Exception Control

Set a timeout for the request:

.WithTimeout(15) // Timeout after 15 seconds

Suppress exceptions and handle failures manually:

.SuppressExceptions() // Prevents exceptions from being thrown

🧪 Testing

VitoRestbox is fully testable with xUnit, FluentAssertions, and custom HttpMessageHandler mocks. You can simulate file uploads, lifecycle hooks, and error handling with ease.

✅ Sample: Uploading a File in Test

[Fact]
public async Task Should_Upload_Text_File_SuccessfullyAsync()
{
    FormFile formFile = await GetFileAsync();

    var result = await VitoRestboxRequest
        .New(_client)
        .To("api/upload")
        .PostMultipart(form =>
        {
            form.Add(new StringContent("Reza"), "username");
            form.Add(new StreamContent(formFile.OpenReadStream()), "file", formFile.FileName);
        })
        .SendAsync<UploadResponseModel>();

    Assert.NotNull(result);
    Assert.Equal("File uploaded successfully.", result.Message);
    Assert.Equal("hello.txt", result.FileName);
    Assert.Equal("Reza", result.Username);
}

🔄 Framework Compatibility

VitoRestbox supports the following target frameworks:

• .NET 5.0
• .NET 6.0
• .NET 7.0
• .NET 8.0
• .NET 9.0

Package dependencies are conditionally resolved to avoid conflicts across versions. This ensures smooth installation and runtime stability regardless of your project’s target.

📦 Installation

dotnet add package VitoRestbox

Or via NuGet Package Manager:

Install-Package VitoRestbox

📖 Philosophy

In Latin, vita means "life"—and VitoRestbox aims to bring life to your API calls by making HTTP communication readable, composable, and expressive. Whether you're building microservices, SDKs, or internal tools, this library helps you express intent and outcome with precision.

👤 Author

Reza Ghadimi
🔗 LinkedIn
🐙 GitHub Profile
📦 VitoRestbox Repository

📄 License

MIT License