UrlPreviewParser 1.1.0

UrlPreviewParser

A .NET library for extracting link preview metadata (OpenGraph, Twitter Card, oEmbed) from URLs.

Installation

.NET CLI

dotnet add package UrlPreviewParser

Package Manager

Install-Package UrlPreviewParser

PackageReference

<PackageReference Include="UrlPreviewParser" Version="1.1.0" />

Quick Start

using UrlPreviewParser;

using var client = new UrlPreviewClient();
var result = await client.GetPreviewAsync("https://example.com");

// OpenGraph
Console.WriteLine(result.OpenGraph.Title);
Console.WriteLine(result.OpenGraph.Description);
Console.WriteLine(result.OpenGraph.Image);

// Twitter Card
Console.WriteLine(result.TwitterCard.Title);
Console.WriteLine(result.TwitterCard.Image);

// Basic page title
Console.WriteLine(result.Tags.Title);

Accessing the Data

OpenGraph (result.OpenGraph)

og:* tags are read from both the property and the name attribute; when a key appears more than once the first occurrence wins (e.g. the first og:image).

OpenGraphData extends Dictionary<string, string>. Any og:* property is accessible by key (e.g., result.OpenGraph["og:title"]). Convenience properties cover the most common fields:

Twitter Card (result.TwitterCard)

twitter:* tags are read from both the name and the property attribute (first occurrence wins).

TwitterCardData extends Dictionary<string, string>. Any twitter:* property is accessible by key (e.g., result.TwitterCard["twitter:label1"]). Convenience properties:

oEmbed (result.Oembed)

Discovered oEmbed endpoint URLs and the raw response body:

Tags (result.Tags)

Raw head elements (result.Head)

result.Head is a List<Dictionary<string, string?>> containing the raw attributes of every child element of <head>. Useful when you need access to tags not covered by the typed properties. Values in Head are never modified (relative URLs stay relative).

URLs

result.Url is the requested URL; result.FinalUrl is the URL actually parsed after redirects.

By default relative URLs in URL-valued properties (og:image, og:url, og:video, og:audio and their :url/:secure_url variants, twitter:image, twitter:image:src, twitter:player, twitter:url, Tags.Canonical, Tags.Favicon, oEmbed endpoints) are resolved to absolute URLs against <base href> or FinalUrl. Absolute values (including data: URIs) and non-URL values such as og:image:width are left untouched.

Options

var options = new UrlPreviewOptions
{
    Timeout = TimeSpan.FromSeconds(10),    // default 15 s; null = only HttpClient.Timeout
    MaxContentLength = 2 * 1024 * 1024,    // default 5 MB; the rest of the body is ignored
    FetchOembed = false,                   // default true
    ResolveRelativeUrls = true,            // default true
};

using var client = new UrlPreviewClient(httpClient, options);

When the timeout elapses GetPreviewAsync throws a TimeoutException; non-success status codes throw an HttpRequestException (with StatusCode set on .NET 5+).

The body is decoded with the charset from the Content-Type header, a byte order mark, or a <meta charset> in the first 1024 bytes, falling back to UTF-8. To support legacy code pages such as windows-1252 on .NET, register the provider once at startup:

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Using Your Own HttpClient

When using dependency injection, pass your HttpClient directly. The caller is responsible for its lifetime; UrlPreviewClient will not dispose it.

// ASP.NET Core — register via IHttpClientFactory
builder.Services.AddHttpClient<MyService>();

// Then inject and use
public class MyService(IHttpClientFactory factory)
{
    public async Task<UrlPreviewResult> GetPreviewAsync(string url, CancellationToken ct)
    {
        var httpClient = factory.CreateClient();
        using var client = new UrlPreviewClient(httpClient);
        return await client.GetPreviewAsync(url, ct);
    }
}

Offline Parsing

ParseAsync parses metadata from an HTML string without making any HTTP requests. The oEmbed endpoint is discovered but not fetched.

using var client = new UrlPreviewClient();
var result = await client.ParseAsync("https://example.com", htmlString);

License

MIT — see LICENSE for details.