Class CurlRequestBuilder

Namespace

CurlDotNet.Core

Assembly

CurlDotNet.dll

🎨 Fluent Builder API - Build curl requests programmatically!

For developers who prefer a fluent API over curl command strings. This builder lets you construct HTTP requests using method chaining, perfect for IntelliSense and compile-time checking.

When to use Builder vs Curl String:

• Use Builder - When building requests dynamically, need IntelliSense, or prefer type safety
• Use Curl String - When you have curl commands from docs/examples (paste and go!)

Quick Example:

// Build a request fluently
var result = await CurlRequestBuilder
    .Get("https://api.example.com/users")
    .WithHeader("Accept", "application/json")
    .WithHeader("Authorization", "Bearer token123")
    .WithTimeout(TimeSpan.FromSeconds(30))
    .ExecuteAsync();

// Same as: curl -H 'Accept: application/json' -H 'Authorization: Bearer token123' --max-time 30 https://api.example.com/users

public class CurlRequestBuilder

Inheritance

object

CurlRequestBuilder

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The builder provides a type-safe, IntelliSense-friendly way to build HTTP requests. All builder methods return the builder itself for method chaining.

You can convert a builder to a curl command string using ToCurlCommand().

Methods

Compressed(bool)

Enable compression (gzip, deflate, etc.).

public CurlRequestBuilder Compressed(bool compressed = true)

Parameters

compressed bool

Returns

CurlRequestBuilder

Delete(string)

Create a DELETE request builder.

public static CurlRequestBuilder Delete(string url)

Parameters

url string

Returns

CurlRequestBuilder

Execute()

Execute the request synchronously.

public CurlResult Execute()

Returns

CurlResult

ExecuteAsync(CurlSettings, CancellationToken)

Execute the request with custom settings.

public Task<CurlResult> ExecuteAsync(CurlSettings settings, CancellationToken cancellationToken = default)

Parameters

settings CurlSettings

cancellationToken CancellationToken

Returns

Task<CurlResult>

ExecuteAsync(CancellationToken)

Execute the request asynchronously.

public Task<CurlResult> ExecuteAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

Task<CurlResult>

FailOnError(bool)

Fail on HTTP errors (like curl -f).

public CurlRequestBuilder FailOnError(bool fail = true)

Parameters

fail bool

Returns

CurlRequestBuilder

FollowRedirects(bool)

Enable following redirects (301, 302, etc.).

public CurlRequestBuilder FollowRedirects(bool follow = true)

Parameters

follow bool

Returns

CurlRequestBuilder

Get(string)

Create a GET request builder.

public static CurlRequestBuilder Get(string url)

Parameters

url string

The URL to GET

Returns

CurlRequestBuilder

Builder for method chaining

Examples

// Simple GET request
var result = await CurlRequestBuilder
    .Get("https://api.github.com/users/octocat")
    .ExecuteAsync();

// GET with headers
var result = await CurlRequestBuilder
    .Get("https://api.example.com/data")
    .WithHeader("Accept", "application/json")
    .WithHeader("X-API-Key", "your-key")
    .ExecuteAsync();

// GET with authentication
var result = await CurlRequestBuilder
    .Get("https://api.example.com/protected")
    .WithBearerToken("your-token")
    .FollowRedirects()
    .ExecuteAsync();

GetOptions()

Get the underlying options object (for advanced scenarios).

public CurlOptions GetOptions()

Returns

CurlOptions

Head(string)

Create a HEAD request builder.

public static CurlRequestBuilder Head(string url)

Parameters

url string

Returns

CurlRequestBuilder

IncludeHeaders(bool)

Include headers in response output (like curl -i).

public CurlRequestBuilder IncludeHeaders(bool include = true)

Parameters

include bool

Returns

CurlRequestBuilder

Insecure(bool)

Ignore SSL certificate errors (not recommended for production!).

public CurlRequestBuilder Insecure(bool insecure = true)

Parameters

insecure bool

Returns

CurlRequestBuilder

Patch(string)

Create a PATCH request builder.

public static CurlRequestBuilder Patch(string url)

Parameters

url string

Returns

CurlRequestBuilder

Post(string)

Create a POST request builder.

public static CurlRequestBuilder Post(string url)

Parameters

url string

The URL to POST to

Returns

CurlRequestBuilder

Builder for method chaining

Examples

// POST with JSON
var result = await CurlRequestBuilder
    .Post("https://api.example.com/users")
    .WithJson(new { name = "John", email = "john@example.com" })
    .ExecuteAsync();

// POST with form data
var result = await CurlRequestBuilder
    .Post("https://api.example.com/login")
    .WithFormData(new Dictionary<string, string> {
        { "username", "user123" },
        { "password", "pass456" }
    })
    .ExecuteAsync();

// POST with raw string data
var result = await CurlRequestBuilder
    .Post("https://api.example.com/data")
    .WithData("key1=value1&key2=value2")
    .WithHeader("Content-Type", "application/x-www-form-urlencoded")
    .ExecuteAsync();

Put(string)

Create a PUT request builder.

public static CurlRequestBuilder Put(string url)

Parameters

url string

Returns

CurlRequestBuilder

Request(string, string)

Create a custom method request builder.

public static CurlRequestBuilder Request(string method, string url)

Parameters

method string

url string

Returns

CurlRequestBuilder

SaveToFile(string)

Save response to file (like curl -o).

public CurlRequestBuilder SaveToFile(string filePath)

Parameters

filePath string

Returns

CurlRequestBuilder

SaveWithRemoteName()

Use remote filename for output (like curl -O).

public CurlRequestBuilder SaveWithRemoteName()

Returns

CurlRequestBuilder

Silent(bool)

Enable silent mode (like curl -s).

public CurlRequestBuilder Silent(bool silent = true)

Parameters

silent bool

Returns

CurlRequestBuilder

ToCurlCommand()

Convert this builder to a curl command string. Useful for debugging or logging what will be executed.

public string ToCurlCommand()

Returns

string

Verbose(bool)

Enable verbose output (like curl -v).

public CurlRequestBuilder Verbose(bool verbose = true)

Parameters

verbose bool

Returns

CurlRequestBuilder

WithAuth(string)

Set custom authentication header.

public CurlRequestBuilder WithAuth(string authHeader)

Parameters

authHeader string

Returns

CurlRequestBuilder

WithBasicAuth(string, string)

Set basic authentication (username:password).

public CurlRequestBuilder WithBasicAuth(string username, string password)

Parameters

username string

password string

Returns

CurlRequestBuilder

WithBearerToken(string)

Set bearer token authentication.

public CurlRequestBuilder WithBearerToken(string token)

Parameters

token string

Returns

CurlRequestBuilder

WithBinaryData(byte[])

Add binary data for upload.

public CurlRequestBuilder WithBinaryData(byte[] data)

Parameters

data byte[]

Returns

CurlRequestBuilder

WithConnectTimeout(TimeSpan)

Set connection timeout.

public CurlRequestBuilder WithConnectTimeout(TimeSpan timeout)

Parameters

timeout TimeSpan

Returns

CurlRequestBuilder

WithCookie(string)

Set cookie string.

public CurlRequestBuilder WithCookie(string cookie)

Parameters

cookie string

Returns

CurlRequestBuilder

WithCookieJar(string)

Set cookie jar file path.

public CurlRequestBuilder WithCookieJar(string cookieJarPath)

Parameters

cookieJarPath string

Returns

CurlRequestBuilder

WithData(string)

Add POST/PUT data as string.

public CurlRequestBuilder WithData(string data)

Parameters

data string

Returns

CurlRequestBuilder

WithFile(string, string)

Upload a file.

public CurlRequestBuilder WithFile(string fieldName, string filePath)

Parameters

fieldName string

filePath string

Returns

CurlRequestBuilder

WithFormData(Dictionary<string, string>)

Add form data (application/x-www-form-urlencoded).

public CurlRequestBuilder WithFormData(Dictionary<string, string> formData)

Parameters

formData Dictionary<string, string>

Returns

CurlRequestBuilder

WithHeader(string, string)

Add a header to the request.

public CurlRequestBuilder WithHeader(string name, string value)

Parameters

name string

Header name (e.g., "Content-Type")

value string

Header value (e.g., "application/json")

Returns

CurlRequestBuilder

Builder for method chaining

Examples

// Add Content-Type header
var result = await CurlRequestBuilder
    .Post("https://api.example.com/data")
    .WithHeader("Content-Type", "application/json")
    .WithJson(new { key = "value" })
    .ExecuteAsync();

// Add custom API key header
var result = await CurlRequestBuilder
    .Get("https://api.example.com/protected")
    .WithHeader("X-API-Key", "your-api-key-here")
    .WithHeader("X-Client-Version", "1.0.0")
    .ExecuteAsync();

// Add Accept header for API versioning
var result = await CurlRequestBuilder
    .Get("https://api.github.com/user")
    .WithHeader("Accept", "application/vnd.github.v3+json")
    .WithBearerToken("your-token")
    .ExecuteAsync();

WithHeaders(Dictionary<string, string>)

Add multiple headers at once.

public CurlRequestBuilder WithHeaders(Dictionary<string, string> headers)

Parameters

headers Dictionary<string, string>

Returns

CurlRequestBuilder

WithHttpVersion(string)

Set HTTP version (1.0, 1.1, or 2.0).

public CurlRequestBuilder WithHttpVersion(string version)

Parameters

version string

Returns

CurlRequestBuilder

WithJson(object)

Add POST/PUT data as JSON (automatically serializes and sets Content-Type).

public CurlRequestBuilder WithJson(object data)

Parameters

data object

The object to serialize as JSON. Can be any class, anonymous object, or built-in type.

Returns

CurlRequestBuilder

Builder for method chaining

Examples

// POST with anonymous object
var result = await CurlRequestBuilder
    .Post("https://api.example.com/users")
    .WithJson(new { name = "John", email = "john@example.com", age = 30 })
    .ExecuteAsync();

// POST with typed class
public class User {
    public string Name { get; set; }
    public string Email { get; set; }
}
var user = new User { Name = "John", Email = "john@example.com" };
var result = await CurlRequestBuilder
    .Post("https://api.example.com/users")
    .WithJson(user)
    .ExecuteAsync();

// PUT with JSON update
var result = await CurlRequestBuilder
    .Put("https://api.example.com/users/123")
    .WithJson(new { name = "Jane", email = "jane@example.com" })
    .WithBearerToken("your-token")
    .ExecuteAsync();

WithMaxRedirects(int)

Set maximum number of redirects to follow.

public CurlRequestBuilder WithMaxRedirects(int maxRedirects)

Parameters

maxRedirects int

Returns

CurlRequestBuilder

WithMultipartForm(Dictionary<string, string>, Dictionary<string, string>)

Add multipart form data with file uploads.

public CurlRequestBuilder WithMultipartForm(Dictionary<string, string> fields, Dictionary<string, string> files = null)

Parameters

fields Dictionary<string, string>

files Dictionary<string, string>

Returns

CurlRequestBuilder

WithProxy(string)

Set proxy URL.

public CurlRequestBuilder WithProxy(string proxyUrl)

Parameters

proxyUrl string

Returns

CurlRequestBuilder

WithProxy(string, string, string)

Set proxy with authentication.

public CurlRequestBuilder WithProxy(string proxyUrl, string username, string password)

Parameters

proxyUrl string

username string

password string

Returns

CurlRequestBuilder

WithRange(string)

Set range for partial downloads (like curl -r).

public CurlRequestBuilder WithRange(string range)

Parameters

range string

Returns

CurlRequestBuilder

WithReferer(string)

Set the Referer header.

public CurlRequestBuilder WithReferer(string referer)

Parameters

referer string

Returns

CurlRequestBuilder

WithTimeout(TimeSpan)

Set timeout for the entire operation.

public CurlRequestBuilder WithTimeout(TimeSpan timeout)

Parameters

timeout TimeSpan

Returns

CurlRequestBuilder

WithUserAgent(string)

Set the User-Agent header.

public CurlRequestBuilder WithUserAgent(string userAgent)

Parameters

userAgent string

Returns

CurlRequestBuilder