👁 Image
OEmbed 4.0.1

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:

• CoubProvider
• DeviantartProvider
• FlickrProvider
• GiphyProvider
• GyazoProvider
• ImgurProvider
• KickstarterProvider
• PinterestProvider
• PixivProvider
• RedditProvider
• SoundcloudProvider
• SpotifyProvider
• TiktokProvider
• TumblrProvider
• TwitterProvider
• VimeoProvider
• YoutubeProvider

Additional providers can be added during configuration:

using HeyRed.OEmbed.Providers;

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
• InstagramProvider
• AfreecatvProvider
• AnnieMusicProvider
• AudioboomProvider
• AudiomackProvider
• CodepenProvider
• YandexMusicProvider
• DeezerProvider
• DailymotionProvider
• RutubeProvider

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 or HttpRequestException was thrown.
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

Basic request:

// Deserialize response based on provider preferences
var 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 hostname, "^" and "$" asserts. 
 // If this Regex is match string url, then scheme used to build request.
 matcher: new RegexMatcher(@"/\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