Sagara.FeedReader
5.0.0-preview.1
dotnet add package Sagara.FeedReader --version 5.0.0-preview.1
NuGet\Install-Package Sagara.FeedReader -Version 5.0.0-preview.1
<PackageReference Include="Sagara.FeedReader" Version="5.0.0-preview.1" />
<PackageVersion Include="Sagara.FeedReader" Version="5.0.0-preview.1" />
<PackageReference Include="Sagara.FeedReader" />
paket add Sagara.FeedReader --version 5.0.0-preview.1
#r "nuget: Sagara.FeedReader, 5.0.0-preview.1"
#:package Sagara.FeedReader@5.0.0-preview.1
#addin nuget:?package=Sagara.FeedReader&version=5.0.0-preview.1&prerelease
#tool nuget:?package=Sagara.FeedReader&version=5.0.0-preview.1&prerelease
Sagara.FeedReader
Sagara.FeedReader is a .NET library for downloading and parsing RSS and Atom feeds. It supports RSS 0.91, 0.92, 1.0, 2.0, Media RSS, and Atom, plus the Apple Podcasts (iTunes) and WordPress export extensions.
Requirements
.NET 10 or .NET 11.
NuGet Package
dotnet add package Sagara.FeedReader
For API docs generated from XML comments, see the GitHub repo.
Getting Started
Register the services
var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddFeedReaderServices();
Then inject IFeedReader wherever you need it.
Read a feed from a URL
GetFeedAsync returns a FeedReaderResult<Feed> instead of throwing when the request fails or the content isn't a feed. Check IsSuccess: when it's true, Value is the feed; when it's false, Error says why.
var result = await feedReader.GetFeedAsync("https://www.sagara.dev/feed.xml");
if (!result.IsSuccess)
{
Console.WriteLine($"{result.Error.Kind}: {result.Error.Message}");
return;
}
foreach (var item in result.Value.Items)
{
Console.WriteLine($"[Item] {item.Title}");
Console.WriteLine($"> Publish Date: {item.PublishingDate:yyyy-MM-dd HH:mm:ss zzzz}");
Console.WriteLine($"> URL: {item.Link}");
}
URLs must be absolute http or https URLs, e.g., https://example.com/feed.xml. Anything else, including example.com/feed.xml, throws ArgumentException. Both string and Uri overloads are available.
Find the feeds on a web page
If you have a web page URL rather than a feed URL, GetFeedUrlsFromPageAsync returns the feeds that the page links to with <link rel="alternate"> tags. The URLs are always absolute, resolved against the page's final URL after redirects.
var pageResult = await feedReader.GetFeedUrlsFromPageAsync("https://www.sagara.dev/");
if (pageResult.IsSuccess)
{
foreach (var link in pageResult.Value)
{
Console.WriteLine($"{link.Title}: {link.Url} ({link.FeedType})");
}
}
Parse a feed you already have
FeedParser parses content from a stream or a string, without making any HTTP requests:
// From a file
await using var stream = File.OpenRead("feed.xml");
var feed = await FeedParser.ParseAsync(stream);
// From a string
var feed = FeedParser.Parse(xml);
ParseAsync and Parse throw FeedParseException when the content can't be parsed. TryParseAsync and TryParse return a FeedReaderResult<Feed> instead:
var result = FeedParser.TryParse(xml);
if (!result.IsSuccess)
{
Console.WriteLine($"{result.Error.Kind}: {result.Error.Message}");
}
Streams are read from their current position. The encoding declared in the XML declaration is honored, and non-seekable streams are supported.
Handle errors
FeedReaderError.Kind tells you what went wrong, so you can decide what to do about it:
| Kind | Meaning | StatusCode |
|---|---|---|
HttpError |
The server returned a non-success status code, e.g., 404 or 500. | Set |
NetworkError |
The request failed before a response arrived (DNS, TLS, connection), or the connection dropped mid-response. | Null, or set if the body failed |
Timeout |
The request took longer than HttpClient.Timeout. The timeout covers reading the whole response, not just the headers. |
Null, or set if the body stalled |
ResponseTooLarge |
The response is larger than FeedReaderOptions.MaxResponseBytes. |
Set |
NotAFeed |
The content is an HTML page. Try GetFeedUrlsFromPageAsync instead. |
Set when downloaded |
InvalidXml |
The content is empty or not well-formed XML. | Set when downloaded |
UnsupportedFeedType |
The XML's root element isn't <rss>, <rdf:RDF>, or <feed>. |
Set when downloaded |
ParseError |
The feed is well-formed but couldn't be parsed, e.g., it has no <channel>. |
Set when downloaded |
Results from IFeedReader also have FinalUri, the URL the content was read from after redirects. If it differs from the URL you requested because of a permanent redirect, you may want to update your stored URL.
Methods throw only for invalid arguments, and OperationCanceledException when your cancellation token is cancelled.
Configure
builder.Services.AddFeedReaderServices(options =>
{
options.MaxResponseBytes = 5 * 1024 * 1024;
options.DefaultUserAgent = "MyFeedBot/1.0 (+https://example.com/bot)";
});
| Option | Default | Purpose |
|---|---|---|
MaxResponseBytes |
10 MB | Larger responses fail with ResponseTooLarge. |
DefaultUserAgent |
A browser-like User-Agent | Sent with every request. Each method also takes a userAgent argument that overrides it. |
Proxy |
None | An HTTP proxy for FeedReader's HttpClient. |
ResilienceHandler |
Retry transient failures once | Replaces the Polly resilience pipeline. |
RecyclableMemoryStreamManagerOptions |
Library defaults | Configures the RecyclableMemoryStreamManager used to buffer responses. |
SuppressRecyclableMemoryStreamManagerRegistration |
false |
Set to true if you register your own RecyclableMemoryStreamManager. An already-registered one is always kept. |
Use format-specific properties
Feed and FeedItem have the properties common to all formats. For format-specific ones, cast SpecificFeed or SpecificItem:
if (feed.SpecificFeed is Rss20Feed rss20Feed)
{
Console.WriteLine($"Generator: {rss20Feed.Generator}");
}
For Apple Podcasts and WordPress export feeds, use the extension methods feed.GetiTunesChannel(), item.GetiTunesItem(), feed.GetWordPressExportChannel(), and item.GetWordPressExportItem().
Use it without dependency injection
FeedReader takes the HttpClient to use. Configure it as you see fit, e.g., with automatic decompression:
using var httpClient = new HttpClient(new HttpClientHandler
{
AutomaticDecompression = DecompressionMethods.All,
});
IFeedReader feedReader = new FeedReader(httpClient, new RecyclableMemoryStreamManager());
Migrating from 4.x
5.0 streamlines the public API and returns results instead of throwing. Most code needs the changes in this table:
| 4.x | 5.0 |
|---|---|
Inject FeedReader |
Inject IFeedReader. It's registered as a typed HttpClient, so its lifetime is transient instead of scoped. |
feedReader.ReadFromUrlAsync(url) returns Feed |
feedReader.GetFeedAsync(url) returns FeedReaderResult<Feed> |
feedReader.GetFeedUrlsFromPageAsync(url) returns IReadOnlyCollection<HtmlFeedLink> |
Returns FeedReaderResult<IReadOnlyCollection<HtmlFeedLink>>. The URLs are absolute. |
FeedReader.ReadFromStreamAsync(stream) |
FeedParser.ParseAsync(stream) or FeedParser.TryParseAsync(stream) |
FeedReader.ReadFromFileAsync(path) |
FeedParser.ParseAsync(File.OpenRead(path)) |
FeedReader.ReadFromString(xml) |
FeedParser.Parse(xml) or FeedParser.TryParse(xml) |
Helpers.GetAbsoluteFeedUrl(pageUrl, link) |
Not needed. Discovered URLs are already absolute. |
HttpClientService |
Removed. Use GetFeedAsync and Feed.OriginalFeedXml for the raw XML, or your own HttpClient. |
using Sagara.FeedReader.Extensions; for AddFeedReaderServices |
Not needed. It's in the Microsoft.Extensions.DependencyInjection namespace. |
FeedTypeNotSupportedException, XmlException, NullReferenceException from parsing |
FeedParseException, with a Kind property |
Behavior changes to check for:
- URLs must include the scheme.
example.com/feed.xmlused to be treated ashttp://example.com/feed.xml. It now throwsArgumentException. - Failures are results, not exceptions. A 404, a timeout, or an HTML page now returns a failed result instead of throwing, or worse, being parsed as a feed.
- Streams are read from their current position. If you write to a
MemoryStreamand pass it toFeedParser, setPosition = 0first. - URLs are no longer URL-decoded before the request. 4.x decoded them, which broke URLs with encoded characters such as
%26in query strings. - Responses larger than 10 MB fail with
ResponseTooLarge. RaiseMaxResponseBytesif you need to. <rss>without aversionattribute is parsed with the RSS 2.0 parser instead of throwingNullReferenceException.- An already-registered
RecyclableMemoryStreamManageris kept. 4.x replaced it unless you setSuppressRecyclableMemoryStreamManagerRegistration.
Removed from the public API:
HttpClientService,NamedHttpClients,HttpClientPropertiesWithWaitAndRetry, and theIFeedReaderServicemarker interface.Helpers(now internal),ICollectionExtensions(now internal),HtmlHelper.GetFeedLinkFromLinkTag(now internal),UrlNotFoundException,InvalidFeedLinkException, andFeedTypeNotSupportedException.- The constructors of the format-specific feed types that take
XElementorXDocument, e.g.,new Rss20FeedItem(element). Those types are created by parsing. Their properties, including theXElementproperties for reading custom elements, are unchanged.
*** Forked from CodeHollow.FeedReader ***
This is a heavily-modified fork of CodeHollow.FeedReader. The biggest difference is that it uses .NET's dependency
injection framework to manage HttpClient instead of storing it in a static variable. I also did a fair bit of
refactoring and used more modern code constructs in some places.
This version only supports .NET 10 and higher. If you don't need .NET's DI capabilities, or you need support for earlier versions of .NET / .NET Framework, please use the original package:
https://github.com/arminreiter/FeedReader
Original readme follows.
FeedReader
FeedReader is a .net library used for reading and parsing RSS and ATOM feeds. Supports RSS 0.91, 0.92, 1.0, 2.0 and ATOM. Developed because tested existing libraries do not work with different languages, encodings or have other issues. Library tested with multiple languages, encodings and feeds.
FeedReader library is available as NuGet package: https://www.nuget.org/packages/CodeHollow.FeedReader/
Usage
The simplest way to read a feed and show the information is:
var feed = await FeedReader.ReadAsync("https://arminreiter.com/feed");
Console.WriteLine("Feed Title: " + feed.Title);
Console.WriteLine("Feed Description: " + feed.Description);
Console.WriteLine("Feed Image: " + feed.ImageUrl);
// ...
foreach(var item in feed.Items)
{
Console.WriteLine(item.Title + " - " + item.Link);
}
There are some properties that are only available in e.g. RSS 2.0. If you want to get those properties, the property "SpecificFeed" is the right one:
var feed = await FeedReader.ReadAsync("https://arminreiter.com/feed");
Console.WriteLine("Feed Title: " + feed.Title);
if(feed.Type == FeedType.Rss_2_0)
{
var rss20feed = (Feeds.Rss20Feed)feed.SpecificFeed;
Console.WriteLine("Generator: " + rss20feed.Generator);
}
If the url to the feed is not known, then you can use FeedReader.GetFeedUrlsFromUrl(url) to parse the url from the html webpage:
string url = "arminreiter.com";
var urls = FeedReader.GetFeedUrlsFromUrl(url);
string feedUrl;
if (urls.Count() < 1) // no url - probably the url is already the right feed url
feedUrl = url;
else if (urls.Count() == 1)
feedUrl = urls.First().Url;
else if (urls.Count() == 2) // if 2 urls, then its usually a feed and a comments feed, so take the first per default
feedUrl = urls.First().Url;
else
{
// show all urls and let the user select (or take the first or ...)
// ...
}
var readerTask = FeedReader.ReadAsync(feedUrl);
readerTask.ConfigureAwait(false);
foreach (var item in readerTask.Result.Items)
{
Console.WriteLine(item.Title + " - " + item.Link);
// ...
}
The code contains a sample console application: https://github.com/codehollow/FeedReader/tree/master/FeedReader.StaticConsoleSample
Specifications
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
-
net10.0
- Microsoft.Extensions.Http (>= 10.0.15)
- Microsoft.Extensions.Http.Resilience (>= 11.0.0)
- Microsoft.IO.RecyclableMemoryStream (>= 4.0.1)
- Microsoft.Net.Http.Headers (>= 10.0.15)
- Polly.Core (>= 8.9.1)
-
net11.0
- Microsoft.Extensions.Http (>= 11.0.0)
- Microsoft.Extensions.Http.Resilience (>= 11.0.0)
- Microsoft.IO.RecyclableMemoryStream (>= 4.0.1)
- Microsoft.Net.Http.Headers (>= 11.0.0)
- Polly.Core (>= 8.9.1)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 5.0.0-preview.1 | 60 | 11/15/2026 |
| 4.0.0 | 117 | 11/12/2026 |
| 3.0.3 | 86 | 11/12/2026 |
| 3.0.2 | 172 | 10/20/2026 |
| 3.0.1 | 745 | 7/21/2026 |
| 3.0.0 | 142 | 7/21/2026 |
| 2.1.0 | 5,970 | 12/13/2024 |
| 2.1.0-alpha1 | 170 | 10/30/2024 |
| 2.0.0 | 627 | 10/15/2024 |
| 1.1.1 | 284 | 10/15/2024 |
| 1.1.0 | 295 | 10/14/2024 |
| 1.0.0 | 334 | 9/2/2024 |
| 1.0.0-alpha6 | 223 | 8/31/2024 |
| 1.0.0-alpha5 | 249 | 3/12/2024 |
| 1.0.0-alpha4 | 231 | 2/20/2024 |
| 1.0.0-alpha3 | 267 | 1/10/2024 |
| 1.0.0-alpha2 | 232 | 1/10/2024 |
| 1.0.0-alpha1 | 246 | 1/4/2024 |