CurlDotNet 9.7.0

CurlDotNet - curl for C# and .NET

<div align="center"> <img src="https://github.com/jacob-mellor/curl-dot-net/blob/master/src/CurlDotNet/icon128.png?raw=true" alt="CurlDotNet Icon" width="128" height="128"/> </div>

🆕 New to curl? Start Here!

📖 Complete Beginner's Guide to curl in C# →

The Industry Standard curl Experience for C# and .NET Developers

CurlDotNet brings the power and simplicity of curl to the .NET ecosystem. Execute curl commands directly in C#, make HTTP requests with curl's battle-tested reliability, and leverage decades of curl development - all with pure .NET code.

🚀 Quick Start with curl for C# and .NET

using CurlDotNet;

// Execute curl commands directly in C#
var result = await Curl.ExecuteAsync("curl -X GET https://api.github.com/users/octocat -H 'Accept: application/json'");

// Or use the fluent API for type safety
var response = await Curl.GetAsync("https://api.github.com/users/octocat")
    .WithHeader("Accept", "application/vnd.github.v3+json")
    .ExecuteAsync();

// Simple one-liners for common operations
var json = await Curl.GetJsonAsync<GitHubUser>("https://api.github.com/users/octocat");

📊 Code Coverage

• Line Coverage: 65.9%
• Branch Coverage: 72%
• Method Coverage: 59.9%
• Tests: 657 total, 619 passing, 38 failing
• Last Updated: 2025-11-18

📦 Installation

# .NET CLI
dotnet add package CurlDotNet

# Package Manager Console
Install-Package CurlDotNet

# PackageReference
<PackageReference Include="CurlDotNet" Version="*" />

✨ Why CurlDotNet?

curl Compatibility in .NET

• 100% curl behavior - Your C# code works exactly like curl commands
• Parse any curl command - Copy from documentation and paste into your code
• Industry standard - Used by millions of developers worldwide

Superior to HttpClient

• More features - Proxies, authentication chains, retries, rate limiting
• Better debugging - curl-style verbose output
• Simpler API - One-line operations that would take 20+ lines with HttpClient

Pure .NET Implementation

• No native dependencies - 100% managed C# code
• Universal compatibility - Runs anywhere .NET runs: Windows, Linux, macOS, iOS, Android, IoT devices, Docker, cloud
• Safe and secure - No P/Invoke, no unmanaged memory

🎯 Key Features

HTTP/REST Operations

// GET request
var data = await Curl.GetAsync("https://api.example.com/users");

// POST JSON
var user = await Curl.PostJsonAsync("https://api.example.com/users",
    new { name = "Alice", email = "alice@example.com" });

// PUT with authentication
await Curl.PutAsync("https://api.example.com/users/123")
    .WithBearerToken(token)
    .WithJson(updatedData)
    .ExecuteAsync();

// DELETE
await Curl.DeleteAsync("https://api.example.com/users/123");

// PATCH
await Curl.PatchAsync("https://api.example.com/users/123")
    .WithJson(new { status = "active" })
    .ExecuteAsync();

Authentication Methods

// Bearer Token
await Curl.GetAsync("https://api.example.com")
    .WithBearerToken("your-token")
    .ExecuteAsync();

// Basic Auth
await Curl.GetAsync("https://api.example.com")
    .WithBasicAuth("username", "password")
    .ExecuteAsync();

// API Key
await Curl.GetAsync("https://api.example.com")
    .WithApiKey("X-API-Key", "your-api-key")
    .ExecuteAsync();

// OAuth 2.0
await Curl.GetAsync("https://api.example.com")
    .WithOAuth2("access-token", "Bearer")
    .ExecuteAsync();

// Custom headers
await Curl.GetAsync("https://api.example.com")
    .WithHeader("X-Custom-Auth", "token123")
    .ExecuteAsync();

AWS Signature V4 Authentication (--aws-sigv4)

// Sign requests with AWS SigV4 - works with AWS, GCP, and custom providers
var result = await Curl.ExecuteAsync(
    @"curl --aws-sigv4 ""aws:amz:us-east-1:s3"" -u ""AKID:SECRET"" https://s3.us-east-1.amazonaws.com/my-bucket");

// API Gateway with request body
var result = await Curl.ExecuteAsync(
    @"curl --aws-sigv4 ""aws:amz:eu-central-1:execute-api"" -u ""AKID:SECRET""
    --json '{""action"":""invoke""}' https://abc123.execute-api.eu-central-1.amazonaws.com/prod/fn");

// Google Cloud Platform
var result = await Curl.ExecuteAsync(
    @"curl --aws-sigv4 ""gcp:goog:us-central1:storage"" -u ""KEY:SECRET""
    https://storage.googleapis.com/my-bucket/my-object");

// Temporary credentials with session token
var result = await Curl.ExecuteAsync(
    @"curl --aws-sigv4 ""aws:amz:us-east-1:s3"" -u ""AKID:SECRET""
    -H ""x-amz-security-token: SESSION_TOKEN"" https://s3.amazonaws.com/bucket");

File Operations

// Download file with progress
await Curl.DownloadFileAsync(
    "https://example.com/large-file.zip",
    "local-file.zip",
    progress: (percent) => Console.WriteLine($"Progress: {percent:F1}%")
);

// Upload file
await Curl.PostAsync("https://api.example.com/upload")
    .WithFile("file", "/path/to/file.pdf")
    .ExecuteAsync();

// Multipart form data
await Curl.PostAsync("https://api.example.com/upload")
    .WithMultipartForm(form => form
        .AddString("name", "John")
        .AddFile("document", "/path/to/doc.pdf")
        .AddFile("image", "/path/to/image.jpg"))
    .ExecuteAsync();

JSON API Requests (--json flag)

// Use curl's --json flag - automatically sets Content-Type and Accept headers
var result = await Curl.ExecuteAsync(
    "curl --json '{\"query\":\"search term\"}' https://api.example.com/search");

// Read JSON body from a file (just like curl) - @file reads file contents at execution time
var result = await Curl.ExecuteAsync(
    @"curl --json @""c:\data\query.json"" https://api.example.com/search");

// Combine with other curl flags - proxies, auth, output, etc.
var result = await Curl.ExecuteAsync(@"curl -X POST
    -H ""Authorization: Bearer token""
    --json @query.json
    -L -k -o result.json
    https://graph.microsoft.com/beta/security/runHuntingQuery");

@file References for Request Data

// -d @file reads file contents and sends as request body (like curl)
var result = await Curl.ExecuteAsync(@"curl -d @data.json https://api.example.com");

// --data-binary @file also reads file contents
var result = await Curl.ExecuteAsync(@"curl --data-binary @payload.bin https://api.example.com");

// --data-raw @file sends the literal string "@file" (no file reading - matches curl behavior)
var result = await Curl.ExecuteAsync(@"curl --data-raw @not-a-file https://api.example.com");

Binary File Downloads

// Download binary files (Office docs, PDFs, ZIPs, etc.) - automatically detected
var result = await Curl.ExecuteAsync("curl -o report.xlsx https://example.com/report.xlsx");

// Force binary mode for servers with incorrect Content-Type headers
var report = await CurlRequestBuilder.Get("https://example.com/report.xlsx")
    .AsBinary()
    .WithOutput("report.xlsx")
    .ExecuteAsync();

// Register custom MIME types as binary
var data = await CurlRequestBuilder.Get("https://example.com/data")
    .WithBinaryContentType("application/x-custom-format")
    .ExecuteAsync();
data.SaveToFile("output.bin");

Proxy Support

// HTTP proxy
await Curl.GetAsync("https://api.example.com")
    .WithProxy("http://proxy.example.com:8080")
    .WithProxyAuth("username", "password")
    .ExecuteAsync();

// SOCKS5 proxy (Tor)
await Curl.GetAsync("https://check.torproject.org")
    .WithSocks5Proxy("socks5://127.0.0.1:9050")
    .ExecuteAsync();

// Residential proxy
await Curl.GetAsync("https://api.example.com")
    .WithProxy("http://gate.smartproxy.com:10000")
    .WithProxyAuth("user-country-us", "password")
    .ExecuteAsync();

// Rotating proxy
await Curl.GetAsync("https://api.example.com")
    .WithProxy("http://proxy.provider.com:8000")
    .WithProxyAuth($"user-session-{Guid.NewGuid()}", "password")
    .ExecuteAsync();

// Backconnect proxy
await Curl.GetAsync("https://api.example.com")
    .WithBackconnectProxy("proxy.provider.com", 20001)
    .ExecuteAsync();

Advanced Features

// Retry with exponential backoff
await Curl.GetAsync("https://api.example.com")
    .WithRetry(maxAttempts: 3)
    .WithExponentialBackoff()
    .ExecuteAsync();

// Rate limiting
await Curl.GetAsync("https://api.example.com")
    .WithRateLimit(requestsPerMinute: 60)
    .ExecuteAsync();

// Timeout handling
await Curl.GetAsync("https://api.example.com")
    .WithTimeout(TimeSpan.FromSeconds(30))
    .WithConnectTimeout(TimeSpan.FromSeconds(10))
    .ExecuteAsync();

// Follow redirects
await Curl.GetAsync("https://bit.ly/shortened")
    .FollowRedirects(maxRedirects: 5)
    .ExecuteAsync();

// Cookie management
var cookieJar = new CookieContainer();
await Curl.GetAsync("https://example.com")
    .WithCookieContainer(cookieJar)
    .ExecuteAsync();

📊 Performance & Reliability

• ✅ 244 Unit Tests - 100% pass rate
• ✅ Self-Contained Testing - No external dependencies
• ✅ Cross-Platform CI/CD - Windows, Linux, macOS
• ✅ Production Ready - Used in enterprise applications

🏗️ Platform Support

📖 Documentation

• 🆕 Beginner's Guide - New to curl? Start here
• 📚 API Reference - Complete API documentation
• 👨‍🍳 Cookbook - Ready-to-use recipes
• 📝 Tutorials - Step-by-step guides
• 🔄 Migration Guides - Migration from HttpClient/RestSharp

💡 Use Cases

REST API Integration

// GitHub API example
var repos = await Curl.GetJsonAsync<List<Repository>>(
    "https://api.github.com/users/octocat/repos"
);

Web Scraping

// Scrape with proper headers
var html = await Curl.GetAsync("https://example.com")
    .WithUserAgent("Mozilla/5.0 (Windows NT 10.0; Win64; x64)")
    .WithHeader("Accept-Language", "en-US")
    .ExecuteAsync();

Microservices Communication

// Service-to-service with retry
var response = await Curl.PostAsync("http://service-b/api/process")
    .WithJson(requestData)
    .WithRetry(3)
    .WithTimeout(TimeSpan.FromSeconds(5))
    .ExecuteAsync();

CI/CD Automation

// Deploy webhook
await Curl.PostAsync("https://deploy.example.com/webhook")
    .WithJson(new {
        version = "1.2.3",
        environment = "production"
    })
    .WithBearerToken(deployToken)
    .ExecuteAsync();

🔧 Advanced Usage

Custom Middleware

// Add custom middleware for logging, caching, etc.
var result = await Curl.GetAsync("https://api.example.com")
    .UseMiddleware(async (context, next) => {
        Console.WriteLine($"Request: {context.Request.Url}");
        var response = await next();
        Console.WriteLine($"Response: {response.StatusCode}");
        return response;
    })
    .ExecuteAsync();

Code Generation

// Convert curl to other languages
var pythonCode = Curl.ToPythonRequests("curl -X GET https://api.example.com");
var jsCode = Curl.ToJavaScriptFetch("curl -X POST https://api.example.com -d '{}'");
var httpClientCode = Curl.ToHttpClient("curl https://api.example.com");

Debugging

// Enable verbose output like curl -v
var result = await Curl.GetAsync("https://api.example.com")
    .Verbose(true)
    .ExecuteAsync();

// Access detailed timing information
Console.WriteLine($"DNS Lookup: {result.Timings.DnsLookup}ms");
Console.WriteLine($"Connect: {result.Timings.Connect}ms");
Console.WriteLine($"TLS Handshake: {result.Timings.TlsHandshake}ms");
Console.WriteLine($"First Byte: {result.Timings.FirstByte}ms");
Console.WriteLine($"Total: {result.Timings.Total}ms");

Detailed Trace Logging (--trace / --trace-ascii / --trace-time)

When you need to know exactly where a request succeeds or gets blocked — especially behind a corporate proxy — write a full diagnostic trace to a log file. The trace captures connection and proxy selection, TLS certificate verification, the exact request/response headers and bodies, transfer timings, and the precise error if the request fails.

// Paste-a-curl-command style: write a full hex+ASCII trace to a file
await Curl.ExecuteAsync("curl --trace curl-trace.log https://api.example.com");

// Compact, ASCII-only trace with timestamps on every line
await Curl.ExecuteAsync("curl --trace-ascii curl-trace.txt --trace-time https://api.example.com");

// Send the trace to standard output instead of a file
await Curl.ExecuteAsync("curl --trace - https://api.example.com");

// Fluent builder equivalent
var result = await CurlRequestBuilder
    .Get("https://api.example.com")
    .WithTrace("curl-trace.log", includeTimestamps: true)
    .ExecuteAsync();

A trace file looks like this:

== Info: CurlDotNet trace started 2026-06-03 14:03:27
== Info: Command: curl --trace curl-trace.log https://api.example.com
== Info: Trying api.example.com:443...
== Info: Using explicit proxy http://proxy.corp.local:8080 (with credentials)
== Info: Connected to api.example.com (api.example.com) port 443
== Info: TLS: certificate verification enabled
=> Send header, 142 bytes (0x8e)
0000: 47 45 54 20 2f 20 48 54 54 50 2f 31 2e 31 0d 0a  GET / HTTP/1.1..
...
<= Recv header, 173 bytes (0xad)
0000: 48 54 54 50 2f 31 2e 31 20 32 30 30 20 4f 4b 0d  HTTP/1.1 200 OK.
...
== Info: Transfer complete: HTTP 200, 1256 bytes received.

If the request is blocked, the exact failure is recorded so you can see which stage rejected it:

== Error: Connection failed: The proxy tunnel request to proxy 'http://proxy.corp.local:8080' failed with status code '407'.
== Error:   caused by: HttpRequestException: Proxy authentication required

Code Generation

CurlDotNet can transpile curl commands into code for other languages. This is perfect for building developer tools or converting documentation examples.

// Convert curl to PowerShell
var powershellCode = Curl.ToPowershellCode("curl -X POST https://api.example.com -d 'data'");

// Convert curl to Python Requests
var pythonCode = Curl.ToPythonCode("curl -X POST https://api.example.com -d 'data'");

// Convert curl to JavaScript Fetch
var jsCode = Curl.ToFetchCode("curl -X POST https://api.example.com -d 'data'");

// Convert curl to C# HttpClient
var csharpCode = Curl.ToHttpClientCode("curl -X POST https://api.example.com -d 'data'");

❓ Troubleshooting

SSL/TLS Issues

If you encounter SSL errors (e.g., self-signed certificates), you can disable verification for development:

// Global setting (affects all requests)
Curl.DefaultInsecure = true;

// Per-request setting
await Curl.Execute("curl -k https://self-signed.local");

Timeouts

If requests are timing out, increase the timeout settings:

// Set global timeout to 60 seconds
Curl.DefaultMaxTimeSeconds = 60;

// Or per request
await Curl.Execute("curl --max-time 60 https://slow-api.example.com");

Proxy Authentication

If your proxy requires authentication:

await Curl.Execute("curl -x http://user:pass@proxy.example.com:8080 https://api.example.com");

Where are my requests being blocked? (proxy / firewall debugging)

If requests work locally but fail behind a proxy or firewall, add --trace to capture a detailed log of every stage of the transfer. The log shows which proxy was selected, whether the TLS handshake completed, the request/response headers, and the precise error if the connection is rejected:

await Curl.ExecuteAsync("curl --trace-ascii proxy-debug.log -x http://proxy.corp.local:8080 https://api.example.com");
// Then open proxy-debug.log and look for the first "== Error:" line.

Note: As of v9.6.0, -x/--proxy, --proxy-user, --socks5 and -k/--insecure are honored for HTTP/HTTPS requests (previously they were only applied to FTP).

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/jacob-mellor/curl-dot-net.git

# Build the project
dotnet build

# Run tests
dotnet test

# Run with coverage
dotnet test /p:CollectCoverage=true

📊 Examples

Comprehensive examples are available in the examples directory:

• Basic Examples - Simple GET, POST, error handling
• Authentication - Bearer tokens, OAuth, API keys
• File Operations - Upload, download, progress tracking
• Advanced Scenarios - Proxies, retries, rate limiting
• Real World - GitHub API, web scraping, complete applications

📄 License

CurlDotNet is MIT licensed. See LICENSE for details.

🌟 Why Developers Choose CurlDotNet

"Finally, I can just paste curl commands from API docs!" - Senior Developer

"The proxy support is fantastic for our web scraping needs." - Data Engineer

"Migrating from HttpClient saved us hundreds of lines of code." - Tech Lead

"The retry logic and rate limiting just work." - DevOps Engineer

🚦 Getting Started

1. Install the package: dotnet add package CurlDotNet
2. Add using: using CurlDotNet;
3. Make your first request: await Curl.GetAsync("https://api.example.com");

That's it! You're now using the power of curl in C# and .NET.

🆘 Support

• GitHub Issues - Report bugs or request features
• Discussions - Ask questions and share ideas
• Stack Overflow - Community Q&A

📎 Additional Resources

• Repository – https://github.com/jacob-mellor/curl-dot-net
• NuGet – https://www.nuget.org/packages/CurlDotNet
• CI/CD Integration Guide – https://github.com/jacob-mellor/curl-dot-net/blob/master/docs/articles/ci-cd-integration.md
• Logging & Observability Guide – https://github.com/jacob-mellor/curl-dot-net/blob/master/docs/guides/logging-observability.md
• Shell Compatibility Guide – https://jacob-mellor.github.io/curl-dot-net/reference/index.md

📖 Our Story

Read about how CurlDotNet is bringing curl superpowers to every corner of the .NET 10 & C# stack: 📰 Featured Article: CurlDotNet - Bringing curl Superpowers to Every Corner of the .NET 10 & C# Stack

🌐 Part of UserLand.NET

CurlDotNet is part of the UserLand.NET initiative - bringing Unix/Linux tools to .NET through pure C# implementations.

Keywords: curl C#, curl .NET, C# HTTP client, .NET curl, REST API C#, HTTP requests .NET, web scraping C#, proxy C#, curl for Windows, curl alternative, HttpClient alternative

Author: Jacob Mellor | Sponsored by IronSoftware.com