Migration

This document describes necessary adjustments to the code when upgrading to a higher major version. See also Changelog (or for pre-release 8.0 see Changelog).

Migrating to version 8.0

All projects are now only compiled for AnyCPU and require VS2019+ or Mono 5+ to build. Almost all assemblies are now strong-named.

Basic Steps for migrating from TeamCity artifact dependencies

1. Optional - Delete old references in your project dependencies to SIL.* and other relevant dependencies (e.g. NDesk.DBus if using SIL.Core.Desktop, NAudio if using SIL.Media, etc.)
2. In Visual Studio, right-click on your project and select Manage NuGet Packages. In Browse, search for the relevant dependency names, e.g. SIL.Core. If you wish or need to use one of the beta builds, check the "Include Prerelease" checkbox. Click Install. Continue for all the SIL dependencies you need to update.
3. If your project still references taglib-sharp (with that specific formatting), remove that dependency. (The new one is named "TagLibSharp").
4. Optional - Double-check your .csproj files (perhaps in a diff) and make sure any references to the old assemblies/locations are gone.
5. Build and test your program. Fix any breaking changes from prior versions to version 8 (see below).
6. Optional - Cleanup any scripts you have that automatically download the old dependencies.

Breaking changes

• Breaking API changes in the SIL.Media assembly:

  • IAudioRecorder.SelectedDevice now returns a IRecordingDevice instead of RecordingDevice. This is implemented in both NAudio and AlsaAudio RecordingDevice classes. This allows to use the same assembly on both Windows and Linux (although the limitations what works and what doesn't work remain the same)
  • rename AudioIrrKlangSession to WindowsAudioSession. AudioAlsaSession and WindowsAudioSession are now internal (they were never intended to be used directly)
  • move some interfaces around so that they live in SIL.Media instead of SIL.Media.Naudio: IAudioRecorder, RecordingState, IAudioPlayer, PeakLevelEventArgs
  • some functions now return IRecordingDevice instead of RecordingDevice (e.g. SIL.Media.Naudio.RecordingDevice.Devices)

• Several classes moved from SIL.Core.Desktop back to SIL.Core to make them available to .NET Standard clients:

  • IO/PathUtilities
  • IO/TempFileForSafeWriting
  • Reporting/AnalyticsEventSender
  • Reporting/ConfigurationException
  • Reporting/ConsoleErrorReporter
  • Reporting/ConsoleExceptionHandler
  • Reporting/ErrorReport
  • Reporting/ExceptionHandler
  • Reporting/ExceptionHelper
  • Reporting/Logger
  • Reporting/ReportingSettings
  • Reporting/UsageReporter

• [SIL.Core] HandleUnhandledException() method moved from derived classes to base class

• SIL.Windows.Forms depends on Markdig instead of MarkdownDeep.NET

Deprecations

• [SIL.Core] Deprecate ExceptionHandler.Init() method in favor of more explicit version ExceptionHandler.Init(ExceptionHandler), e.g. ExceptionHandler.Init(new WinFormsExceptionHandler())

• [SIL.Core] Deprecate HttpUtilityFromMono class. Use System.Web.HttpUtility instead.

• [SIL.DblBundle] Deprecate TextBundle.CopyVersificationFile, CopyFontFiles and CopyLdmlFile in favor of GetVersificationFile, GetFontFiles, and GetLdmlFile.

New methods

• [SIL.Core] XmlSerializationHelper.Serialize<T> to allow serialization to a TextWriter.
• [SIL.Core] XmlSerializationHelper.Deserialize<T> to allow deserialization from a TextReader.
• [SIL.Core] XmlSerializationHelper.SerializeToString<T> overload to allow caller to specify encoding.
• [SIL.Core] Platform.IsGnomeShell to detect if executing in a Gnome Shell
• [SIL.Core] new properties for processor architecture: Platform.ProcessArchitecture and Platform.IsRunning64Bit
• [SIL.DblBundle] DblMetadata.Load overload to allow deserialization from a TextReader.
• [SIL.DblBundle] TextBundle<TM, TL>.GetVersification (to replace deprecated CopyVersificationFile)
• [SIL.DblBundle] TextBundle<TM, TL>.GetFonts (to replace deprecated CopyFontFiles)
• [SIL.DblBundle] TextBundle<TM, TL>.GetLdml (to replace deprecated CopyLdmlFile)
• [SIL.Scripture] Versification.Table.Load overload to allow deserialization from a TextReader.
• [SIL.Scripture] ScrVers.Save overload to allow serialization to a TextWriter.

Additional things that changed for version 8

• All projects switched to the new sdk-style project files
• Projects now require Visual Studio 2019. Using VS Code or Rider will also work. On Linux we require Mono 5.
• To be able to open files in Designer on Windows you'll need at least Visual Studio 2019 version 16.8
• Check platform at runtime instead of compile-time - no more #if MONO statements in the code; same binary will work cross-platform.
• All projects are only compiled for AnyCPU
• Refactored SIL.Media:
  • IAudioRecorder.SelectedDevice now returns a newly defined IRecordingDevice interface. This interface is implemented in the RecordingDevice class of both NAudio and AlsaAudio.
  • Load the correct 32- or 64-bit version of irrKlang.NET4 at runtime.
• Added a CHANGELOG.md file. Relevant changes and bugfixes should be documented in here. What gets added will show up as release notes on the nuget packages on nuget.org. What should go in this document is:
  • Any changes to the API
  • Bugfixes since the last released version
  • Other relevant changes that affect the consumers of the library
• Added GitVersion to calculate the version number

See the Google doc for a more detailed discussion of some of the changes and the reasons why things were done a certain way.

(In case you're wondering: There's also a version 7. That was released a bit prematurely; trying to use the nuget packages of that version revealed some problems. To fix them required more breaking changes which increased the version to 8)