OEmbed 1.1.0

OEmbed

A simple oEmbed consumer library for .NET

Install

via NuGet:

PM> Install-Package OEmbed

DI extensions for Microsoft.Extensions.DependencyInjection:

PM> Install-Package OEmbed.Extensions.Microsoft.DependencyInjection

DI configuration

services.AddOEmbed();

// or

services.AddOEmbed(options =>
{
	options.EnableCache = true; // true by default
});

By default it's register all built in providers:

• InstagramProvider
• TiktokProvider
• TwitterProvider
• VimeoProvider
• YoutubeProvider
• RedditProvider

You can add a provider during configuration:

services.AddOEmbed()
	.ClearProviders() // remove all default providers
	.AddProvider<YoutubeProvider>()
	.AddProvider<VimeoProvider>();

// or with options
services.AddOEmbed()
	.ClearProviders() // remove all default providers
	.AddProvider<TwitterProvider>(options =>
	{
		options.Parameters = new Dictionary<string, string?>
		{
			["theme"] = "dark"
		};
	});

Usage

• Inject IOEmbedConsumer throught constructor injection.
• Call one of RequestAsync() overloads.

For example:

using HeyRed.OEmbed.Abstractions;
using HeyRed.OEmbed.Models;

// Returns null if provider not found for given url.
// NOTE: This method can throw HttpRequestException, so wrap your request with try/catch if it needed.
Video? result = await _oEmbedConsumer.RequestAsync<Video>("https://vimeo.com/22439234");

The result object is are similar to described in the spec

Models: Base, Link, Photo, Rich, Video

If you dont know which response models supported by provider, then use dynamic overload.

// Deserialize response based on provider preferences
dynamic? item = await _oEmbedConsumer.RequestAsync(url);

if (item is not null)
{
	if (item is Video) 
	{ 
		// work with video 
	}
	elseif (item is Photo) 
	{ 
		// work with photo 
	}
	else { //do something }
}

Caching

Configure cache options:

services.AddOEmbed().Configure<CacheOptions>(options =>
{
	options.AbsoluteExpiration = DateTimeOffset.UtcNow.AddMinutes(30); // Default is 1 hour
});

By default cache is enabled and it's default implementation is just a wrapper around MemoryCache

You can write your own implementation of ICache and replace default cache during app configuration:

services.AddOEmbed().SetCache<DistributedRedisCache>();

Additional providers

An easy way to write your own provider is inheritance of ProviderBase record:

public record ExampleProvider : ProviderBase
{
	public ExampleProvider(ProviderOptions? options = default) // Is optional, you can safely remove argument from constructor
	{
		AddParameters(options?.Parameters);

		// The Provider registry is primarily using this to select right provider at first check.
		AddAllowedHosts(new[] { "example.com", "www.example.com" });

		AddScheme(
			// Simple regex without "^" and "$" asserts. 
			// If this Regex is match string url, then scheme used to build request.
			matcher: new RegexMatcher(@"https?://(?:www\.)?example\.com/\S+"), 
			// API endpoint for current scheme
			apiEndpoint: "http://example.com/oembed",
			// The response type provided by resource.
			resourceType: ResourceType.Rich);
		}
	}
	
	// (Optional) Primary API response format(default is JSON)
	public override ResponseFormat ResponseType => ResponseFormat.Xml;
}

License

MIT