Capture a website screenshot with C#.

dotnet new console -o Screenshot
cd Screenshot

// Program.cs in a `dotnet new console` project: request one screenshot and save it.
using System.Net.Http.Headers;
using System.Text.Json;

var query = await new FormUrlEncodedContent(
[
    new("url", "https://en.wikipedia.org/wiki/Cartography"),
    new("format", "webp"),
    new("quality", "80"),
    new("viewport_width", "1280"),
    new("viewport_height", "800"),
    new("device_scale_factor", "2"),
]).ReadAsStringAsync();

using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("URLSHOT_API_KEY"));

using var response = await client.GetAsync($"https://api.urlshot.io/v1/screenshot?{query}");

// Anything that is not an image is the JSON error envelope.
if (!response.IsSuccessStatusCode)
{
    using var body = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
    var error = body.RootElement.GetProperty("error");
    throw new InvalidOperationException(
        $"{error.GetProperty("code")}: {error.GetProperty("message")} (request {error.GetProperty("requestId")})");
}

await File.WriteAllBytesAsync("screenshot.webp", await response.Content.ReadAsByteArrayAsync());
Console.WriteLine("Wrote screenshot.webp");

// After the request: what it cost, and how to refer to it. Header names are
// matched whatever their case.
var credits = response.Headers.GetValues("X-Urlshot-Credits-Used").First(); // "1", or "0" from cache
var requestId = response.Headers.GetValues("X-Request-ID").First();
Console.WriteLine($"request {requestId} used {credits} credit(s)");

using System.Net.Http.Headers;
using System.Text.Json;

using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("URLSHOT_API_KEY"));

// Requests a screenshot, retrying only when the API says how long to wait.
async Task<byte[]> Screenshot(string query, int attempts = 4)
{
    for (var attempt = 1; ; attempt++)
    {
        using var response = await client.GetAsync($"https://api.urlshot.io/v1/screenshot?{query}");
        if (response.IsSuccessStatusCode) return await response.Content.ReadAsByteArrayAsync();

        // Only a 429 or 503 carries Retry-After, in seconds. Anything else fails
        // the same way however often it is sent.
        var retryAfter = response.Headers.RetryAfter?.Delta;
        if (retryAfter is null || attempt == attempts)
        {
            using var body = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
            var error = body.RootElement.GetProperty("error");
            throw new InvalidOperationException(
                $"{error.GetProperty("code")}: {error.GetProperty("message")} (request {error.GetProperty("requestId")})");
        }
        await Task.Delay(retryAfter.Value);
    }
}

var query = await new FormUrlEncodedContent(
[
    new("url", "https://en.wikipedia.org/wiki/Cartography"),
    new("format", "webp"),
]).ReadAsStringAsync();

await File.WriteAllBytesAsync("screenshot.webp", await Screenshot(query));
Console.WriteLine("Wrote screenshot.webp");

using System.Net.Http.Headers;
using System.Text.Json;

// A list of pairs, not a Dictionary: a list can hold hide_selectors once for
// each selector, which is how the API takes a list.
var query = await new FormUrlEncodedContent(
[
    new("url", "https://en.wikipedia.org/wiki/Atlas"),
    new("full_page", "true"),
    new("format", "png"),
    new("hide_selectors", ".vector-header-container"),
    new("hide_selectors", ".mw-footer"),
]).ReadAsStringAsync();

using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("URLSHOT_API_KEY"));

using var response = await client.GetAsync($"https://api.urlshot.io/v1/screenshot?{query}");

// Anything that is not an image is the JSON error envelope.
if (!response.IsSuccessStatusCode)
{
    using var body = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
    var error = body.RootElement.GetProperty("error");
    throw new InvalidOperationException(
        $"{error.GetProperty("code")}: {error.GetProperty("message")} (request {error.GetProperty("requestId")})");
}

await File.WriteAllBytesAsync("atlas.png", await response.Content.ReadAsByteArrayAsync());
Console.WriteLine("Wrote atlas.png");

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("URLSHOT_API_KEY"));

// Property names as the API spells them; the camelCase policy PostAsJsonAsync
// applies leaves them as they are. JSON types: true rather than "true", and a
// list as an array.
using var response = await client.PostAsJsonAsync("https://api.urlshot.io/v1/screenshot", new
{
    url = "https://en.wikipedia.org/wiki/Atlas",
    full_page = true,
    format = "png",
    hide_selectors = new[] { ".vector-header-container", ".mw-footer" },
    custom_css = "#siteNotice { display: none !important }",
});

// Anything that is not an image is the JSON error envelope.
if (!response.IsSuccessStatusCode)
{
    using var body = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
    var error = body.RootElement.GetProperty("error");
    throw new InvalidOperationException(
        $"{error.GetProperty("code")}: {error.GetProperty("message")} (request {error.GetProperty("requestId")})");
}

await File.WriteAllBytesAsync("atlas.png", await response.Content.ReadAsByteArrayAsync());

// Program.cs in a `dotnet new web` project.
using System.Net.Http.Headers;

var builder = WebApplication.CreateBuilder(args);

// One named client, configured once. IHttpClientFactory pools its connections.
builder.Services.AddHttpClient("urlshot", client =>
{
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
        "Bearer", builder.Configuration["URLSHOT_API_KEY"]);
    client.Timeout = TimeSpan.FromSeconds(60);
});

var app = builder.Build();

// The pages this app shows previews of. Visitors pick a name, never an
// address: a route that took any URL would render any page on your credits.
var pages = new Dictionary<string, string>
{
    ["home"] = "https://example.com",
    ["atlas"] = "https://en.wikipedia.org/wiki/Atlas",
};

app.MapGet("/previews/{page}", async (string page, IHttpClientFactory clients, HttpContext context, ILogger<Program> logger) =>
{
    if (!pages.TryGetValue(page, out var url)) return Results.NotFound();

    var query = await new FormUrlEncodedContent(
    [
        new("url", url),
        new("viewport_width", "1280"),
        new("format", "webp"),
        new("cache_ttl", "3600"),
    ]).ReadAsStringAsync();

    using var response = await clients.CreateClient("urlshot").GetAsync($"https://api.urlshot.io/v1/screenshot?{query}");
    if (!response.IsSuccessStatusCode)
    {
        // The body is the JSON error envelope: its code and requestId say what happened.
        logger.LogError("urlshot.io refused a preview: {Body}", await response.Content.ReadAsStringAsync());
        return Results.StatusCode(StatusCodes.Status502BadGateway);
    }

    context.Response.Headers.CacheControl = "public, max-age=3600";
    return Results.File(
        await response.Content.ReadAsByteArrayAsync(),
        response.Content.Headers.ContentType?.MediaType);
});

app.Run();

// .NET 6 or later: a `dotnet new console` project. No packages.
using System.Security.Cryptography;
using System.Text;

static string SignedUrl(IDictionary<string, string> options)
{
    var parameters = new Dictionary<string, string>
    {
        ["key"] = Environment.GetEnvironmentVariable("URLSHOT_KEY")!,
    };
    foreach (var (name, value) in options) parameters[name] = value;

    var query = string.Join("&", parameters.Select(p =>
        $"{Uri.EscapeDataString(p.Key)}={Uri.EscapeDataString(p.Value)}"));

    var secret = Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable("URLSHOT_SIGNING_SECRET")!);
    var hash = HMACSHA256.HashData(secret, Encoding.UTF8.GetBytes(query));

    // Lowercase: the signature is compared exactly, and Convert.ToHexString returns uppercase.
    var signature = Convert.ToHexString(hash).ToLowerInvariant();

    return $"https://api.urlshot.io/v1/screenshot?{query}&signature={signature}";
}

var src = SignedUrl(new Dictionary<string, string>
{
    ["url"] = "https://example.com",
    ["viewport_width"] = "1200",
});