OEmbed 1.3.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 providers listed below:

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

Additional providers can be added during configuration:

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

// or with options
// NOTE: Some oembed providers defines additional parameters, so use "Parameters" option if you need them.
services.AddOEmbed()
    .ClearProviders() // remove all default providers
    .AddProvider<TwitterProvider>(options =>
    {
        options.Parameters = new Dictionary<string, string?>
        {
            ["theme"] = "dark"
        };
    })
    .AddProvider<FacebookProvider>(options =>
    {
        options.Parameters = new Dictionary<string, string?>
        {
            ["access_token"] = "app_id|token"
        };
    });

Additional providers:

• FacebookProvider
• CoubProvider
• ImgurProvider
• SoundcloudProvider
• GfycatProvider
• GiphyProvider
• GyazoProvider

NOTE: While Instagram can work without access_token(with limited legacy endpoint), Facebook is just throw exception if you didn't provide these token.

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 
    }
    else if (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
{
    // "ProviderOptions" is optional, you can safely remove argument from constructor
    public ExampleProvider(ProviderOptions? options = default)
    {
        AddParameters(options?.Parameters);
        
        // The Provider registry is primarily using this to select right provider at first check.
        // NOTE: Add all the hosts that will be used in the schemes below.
        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