.NET HTTP Client Builder

Expert guidance for working with the Albatross.Http repository, a .NET library providing HttpClient extensions and fluent request builders for HTTP client code generation.

Repository Context

This repository contains a .NET library (`Albatross.Http`) that extends HttpClient with fluent builders, typed error handling, and logging capabilities.

**Target Framework:** `net8.0`

**Namespace:** `Albatross.Http`

**Solution:** `http.sln`

Build Commands

When the user asks you to build, test, or package the project, use these commands:

```bash

Build the entire solution

dotnet build http.sln

Build a specific project

dotnet build Albatross.Http/Albatross.Http.csproj

Run all tests

dotnet test

Run a specific test by filter

dotnet test --filter "FullyQualifiedName~TestCreateUrl.WithNullQueryString_ReturnsUrlOnly"

Create NuGet package

dotnet pack Albatross.Http/Albatross.Http.csproj

```

Architecture & Key Components

RequestBuilder

Fluent builder for creating `HttpRequestMessage` instances with various content types:

JSON content

String content

Stream content

Form content

Multipart form content

Query string helpers for `DateTime`, `DateOnly`, `TimeOnly`, `DateTimeOffset`

**Important:** Automatically resets after `Build()` is called

HttpClientExtensions

Execute methods that handle HTTP request/response with typed error handling:

`ExecuteOrThrow`: For reference types

`ExecuteOrThrowStruct`: For value types

`ExecuteAsStream`: For streaming `IAsyncEnumerable` responses

Uses `ServiceException<T>` for structured error handling

UrlExtensions

URL and query string utilities:

Query string building

URL batching for large array parameters

`GetFullUri`: Resolves relative URIs against a base address

ServiceException

Typed exception class that carries:

HTTP status code

HTTP method

Endpoint URL

Deserialized error object

LoggingHandler

`DelegatingHandler` implementation for structured logging of HTTP request/response details via `ILogger`.

ContentTypes

MIME type constants for common content types.

Testing

The project uses **xUnit** as the testing framework.

**Test Project:** `Albatross.Http.Test`

When running tests, use `dotnet test` or filter by fully qualified name for specific tests.

Sample Projects

The repository includes sample projects for internal testing and demonstration:

`Sample.WebApi`

`Sample.WebClient`

`Sample.CommandLine`

**IMPORTANT:** Do NOT add documentation (XML doc comments, README files, release notes, etc.) to these sample projects. They are for testing purposes only.

Code Modifications

When working with this codebase:

1. **Maintain .NET 8 compatibility** — all code must target `net8.0`

2. **Keep namespace consistent** — all public types belong in `Albatross.Http`

3. **Follow fluent builder patterns** — especially when modifying `RequestBuilder`

4. **Preserve automatic reset behavior** — `RequestBuilder.Build()` must reset state

5. **Use structured logging** — when modifying `LoggingHandler`, maintain structured log format

6. **Test thoroughly** — add xUnit tests for new functionality in `Albatross.Http.Test`

7. **Avoid sample project documentation** — no XML comments, READMEs, or release notes in `Sample.*` projects

Common Tasks

Adding New HTTP Extensions

Extend `HttpClientExtensions` class

Follow existing patterns for typed error handling with `ServiceException<T>`

Add corresponding unit tests

Modifying RequestBuilder

Maintain fluent API design

Ensure `Build()` resets internal state

Test all content type variations

Adding Query String Helpers

Extend `UrlExtensions`

Support nullable types appropriately

Handle encoding correctly

Testing Error Handling

Use `ServiceException<T>` for expected error scenarios

Test both success and failure paths

Verify status codes, methods, and endpoints are captured correctly

.NET HTTP Client Builder

.NET HTTP Client Builder

Repository Context

Build Commands

Build the entire solution

Build a specific project

Run all tests

Run a specific test by filter

Create NuGet package

Architecture & Key Components

RequestBuilder

HttpClientExtensions

UrlExtensions

ServiceException

LoggingHandler

ContentTypes

Testing

Sample Projects

Code Modifications

Common Tasks

Adding New HTTP Extensions

Modifying RequestBuilder

Adding Query String Helpers

Testing Error Handling

Reviews (0)