This release adds a couple minor features: easier access to the underlying compressed file within the EPUB archive and ability to obtain its compressed length.

Unfortunately, the logging feature that was also expected to be in this release had to be delayed until EpubReader drops support for .NET Framework 4.6 and .NET Standard 1.3 because .NET logging Nuget package does not support them.

Coming next: preliminary support for EPUB 3.4 standard (the full support will be available once EPUB 3.4 specification moves out the draft stage and EPUB WG publishes the first Candidate Recommendation).

New features

• Compressed length information for content files (#146).
• Access to ZIP archive entry in the EpubLocalContentFileRef class (#147).

This release includes one of the most requested features: the ability to control which EPUB validations should be enabled or disabled for a EPUB book. Now, applications can use EpubReader to open malformed EPUB files either by supplying configuration options or by using one of the configuration presets. See Handling Malformed EPUB files for more information on how to use this feature.

Coming next: configurable logging interface, so the applications that chose to ignore EPUB validation errors can still be notified of them.

New features

• Configuration options to enable / disable all validation checks (#95).

Maintenance

• The links in the XML documentation for the EPUB schema classes have been updated from EPUB 3.2 to EPUB 3.3 spec (#123, implemented by @wh1tewolfxx).
• Console demo app has been migrated to .NET 10 (#142).

Bug fixes

• Fixes the issue with handling relative paths within EPUB 2 NCX navigation files (#132, found by @kitUIN).

New features

• Automatically skipping <nav> sections without the type attribute in EPUB 3 navigation documents to avoid throwing errors for navigation sections that don't conform to the EPUB standard (#119)
• New BookCoverReaderOptions.Epub2MetadataIgnoreMissingManifestItem property to let applications ignore errors when EPUB 2 cover metadata is referencing a non-existing manifest item. This option is enabled by default for applications that don't create their own EpubReaderOptions (#109)
• New SpineReaderOptions.IgnoreMissingManifestItems property to let applications ignore errors when a EPUB spine item is referencing a non-existing manifest item (#109)
• Console demo app has been migrated to .NET 9 (#117)

Bug fixes

• Parsing <nav> elements nested in other HTML elements in EPUB 3 navigation documents (#113).

New features

• Automatic URL unescaping in EPUB 2 NCX and EPUB 3 navigation documents (#98).
• BMP image files support (#114).

Breaking changes

The types for EpubBook.Content.xxx.Local, EpubBook.Content.xxx.Remote, EpubBookRef.Content.xxx.Local, and EpubBookRef.Content.xxx.Remote have been changed from Dictionary<string, xxx> to ReadOnlyCollection<xxx>.

The following substitutions are provided for the dictionary operations:

• for EpubBook:
  • EpubBook.Content.xxx.Local.ContainsKey(key) → EpubBook.Content.xxx.ContainsLocalFileWithKey(key);
  • EpubBook.Content.xxx.Local[key] → EpubBook.Content.xxx.GetLocalFileByKey(key);
  • EpubBook.Content.xxx.Local.TryGetValue(key, out yyy) → EpubBook.Content.xxx.TryGetLocalFileByKey(key, out yyy).
• for EpubBookRef:
  • EpubBookRef.Content.xxx.Local.ContainsKey(key) → EpubBookRef.Content.xxx.ContainsLocalFileRefWithKey(key);
  • EpubBookRef.Content.xxx.Local[key] → EpubBookRef.Content.xxx.GetLocalFileRefByKey(key);
  • EpubBookRef.Content.xxx.Local.TryGetValue(key, out yyy) → EpubBookRef.Content.xxx.TryGetLocalFileRefByKey(key, out yyy).

New features

• Content file collections (EpubBook.Content and EpubBookRef.Content) now provide access to their files both by file keys as well as absolute file paths which eliminates the need to iterate the collection to find a file with a given file path. For example, for EpubBook.Content:
  • EpubBook.Content.xxx.ContainsLocalFileWithFilePath(filePath);
  • EpubBook.Content.xxx.GetLocalFileByFilePath(filePath);
  • EpubBook.Content.xxx.TryGetLocalFileByFilePath(filePath, out file).

Bug fixes

• Fix for constructing navigation items when OPF and navigation files are located in different subdirectories (#91).

Breaking changes

There are some breaking changes introduced in this release to accommodate the new features, mostly the coverage of some of the EPUB 3 schema attributes previously missing in the EpubReader (due to their type incompatibility with EPUB 2 schema types). All of them are syntactical, non-functional changes, i.e. applications will need to make code changes in the way how they access this data but not how it is being used.

EpubBook.Schema.Epub2Ncx and EpubBookRef.Schema.Epub2Ncx (#60)

• Head[n] → Head.Items[n];
• NavMap[n] → NavMap.Items[n];
• PageList[n] → PageList.Items[n].

EpubBook.Schema.Package and EpubBookRef.Schema.Package (#60)

• Guide[n] → Guide.Items[n];
• Manifest[n] → Manifest.Items[n];
• Spine[n] → Spine.Items[n].

EpubBook.Content and EpubBookRef.Content (#62 and #69)

• EpubContentFile type → EpubLocalContentFile type;
• EpubTextContentFile type → EpubLocalTextContentFile type;
• EpubByteContentFile type → EpubLocalByteContentFile type;
• EpubContentFileRef type → EpubLocalContentFileRef type;
• EpubTextContentFileRef type → EpubLocalTextContentFileRef type;
• EpubByteContentFileRef type → EpubLocalByteContentFileRef type;
• Html[key] → Html.Local[key];
• Css[key] → Css.Local[key];
• Images[key] → Images.Local[key];
• Fonts[key] → Fonts.Local[key];
• AllFiles[key] → AllFiles.Local[key];
• xxx.Local[key].FileName → xxx.Local[key].Key (the word "key" better conveys the meaning of this field in the content dictionary);
• xxx.Local[key].FilePathInEpubArchive → xxx.Local[key].FilePath.

EpubBook.Navigation[n] and EpubBookRef.GetNavigation()[n] (#71)

• Link?.ContentFilePathInEpubArchive → Link?.ContentFilePath.

VersOne.Epub.Schema namespace

• Epub3NavStructuralSemanticsProperty type → Epub3StructuralSemanticsProperty type (#78);
• EpubMetadataLinkRelationship.ACQUIRE → none (removed in EPUB 3.3 specification; #86);
• EpubMetadataLinkProperty.XMP → none (removed in EPUB 3.3 specification; #86).

EpubBook.Schema.Package.Metadata and EpubBookRef.Schema.Package.Metadata (#85)

• Titles[n] → Titles[n].Title;
• Subjects[n] → Subjects[n].Subject;
• Description → Descriptions.FirstOrDefault()?.Description;
• Publishers[n] → Publishers[n].Publisher;
• Types[n] → Types[n].Type;
• Formats[n] → Formats[n].Format;
• Sources[n] → Sources[n].Source;
• Languages[n] → Languages[n].Language;
• Relations[n] → Relations[n].Relation;
• Coverages[n] → Coverages[n].Coverage;
• Rights[n] → Rights[n].Rights.

New features

• EPUB 3.3 support. EPUB 3.3 specification is currently in the Proposed Recommendation stage but it is expected to be released by the EPUB 3 Working Group within a few months (#86).
• Support for remote content files (i.e. the files referenced in the manifest by absolute URLs, e.g. https://example.com/book/123/chapter1.html as opposed to the local files, e.g. Content/chapter1.html which are located within the EPUB file) with optional auto-downloading (#62 and #69).
• 100% coverage for all EPUB 3 schema elements and attributes, up to the version 3.3 of the EPUB specification (#85).
• Preliminary support for the EPUB 3.2 Media Overlays (a feature to include audio narrations into EPUB books). The data parsed from the media overlays is currently exposed as a collection of EPUB schema types (accessible via the EpubBook.Schema.MediaOverlays and EpubBookRef.Schema.MediaOverlays properties). EpubReader will have a more convenient way to consume this data on the EpubBook level in the future (#78).
• C# nullable reference type annotations (#71).
• Explicit .NET Standard 2.0 support to reduce the number of system Nuget packages being installed if the application targets .NET Framework >= 4.6.1 or .NET/.NET Core >= 2.0 (#52).
• Console demo app was migrated to .NET 7 (#72).

Bug fixes

• Fix for the cover extracting issue for EPUB 2 books with no cover and no guide section in their OPF files (#58).
• Fix for EPUB 2 NCX navigation list parsing (#56).
• Fix for OPF event and OPF scheme metadata attributes parsing (#54).

Breaking changes:

• Six schema classes (Epub2NcxHead, Epub2NcxNavigationMap, Epub2NcxPageList, EpubGuide, EpubManifest, EpubSpine) are no longer derived from List<T> and require the following syntax: epubSpine.Items[n] instead of epubSpine[n] to access their items (#60).

New features:

• Support for remote manifest items, i.e. files referenced by absolute URLs like http://example.com/book/123/chapter1.html as opposed to local files like Content/chapter1.html which are packaged within the EPUB file (#62).
• Explicit .NET Standard 2.0 support which reduces the number of system Nuget packages being installed if the consumer project targets .NET Framework >= 4.6.1 or .NET/.NET Core >= 2.0.

Bug fixes:

• Fix for cover extracting issue for EPUB 2 books with no cover and no guide section in their OPF files (#58).
• Fix for EPUB 2 NCX navigation list parsing (#56).
• Fix for OPF event and OPF scheme attributes parsing (#54).

New features:

• Documentation! Check out https://os.vers.one/EpubReader/ and the IntelliSense tooltips in Visual Studio / Visual Studio Code.
• Support for EPUB 3 metadata links and metadata relationships.
• Workarounds for malformed EPUB files:
  • Package reader option to skip invalid manifest items (#47).
  • Content reader options to handle missing content files (#25).
• Workaround for EPUB books containing XML 1.1 schema files (#34).
• All generic exceptions have been replaced with custom exception types.

Enhancements:

• Book cover extracting enhancements (#48) which should greatly improve the cover extraction process, especially for EPUB 3 books.

Breaking change:

• EpubNavigationItemLink.ContentFileName is no longer returning the absolute file path (it didn't work properly anyway). Instead it now returns the file path exactly as it is specified in the EPUB navigation file (which could be either absolute or relative). If you need an absolute file path, use the EpubNavigationItemLink.ContentFilePathInEpubArchive property.

New features:

• EpubContent.NavigationHtmlFile and EpubContentRef.NavigationHtmlFile properties which points to the EPUB 3 navigation XHTML file (if present).