Skip to content

Instantly share code, notes, and snippets.

@brantburnett

brantburnett/CouchbaseNetCore.md

Created July 22, 2016 00:32
Show Gist options
  • Save brantburnett/10b64fc733ad4d38be6c47846a37c0c7 to your computer and use it in GitHub Desktop.
Save brantburnett/10b64fc733ad4d38be6c47846a37c0c7 to your computer and use it in GitHub Desktop.
Download ZIP
Discussion regarding different approaches to implementing .Net Core support in the Couchbase .Net Client
Raw
CouchbaseNetCore.md

Couchbase .Net Core Support

Overview

This document describes various approaches that might be used to add .Net Core support to the Couchbase .Net SDK. It is based upon some preexisting work that has already been completed, detailed in https://issues.couchbase.com/browse/NCBC-915.

Understanding .Net Standard

It is important to understand the basic precepts behind .Net Standard in order to understand this document. Some good information can be found at https://docs.microsoft.com/en-us/dotnet/articles/standard/library.

The basic idea is that Microsoft has moved away from the idea of libraries targeting .Net Core directly, because this creates too many issues with compatibility and maintainability. Instead, the want library developers to target .Net Standard, at the minimum level they can support, which provides broad compatibility across the different .Net platforms. A single binary can be used for UWP, .Net Core, .Net Desktop, etc.

Compatibility Issues

There are certain features available in .Net 4.5 (the current SDK version) that are not available in .Net Standard or .Net Core. Many of these have equivalent replacements, and most of these conversions have already been completed. However, others are more difficult to replace or work around.

  1. ServicePointManager is obsolete. There are some replacements in the HttpClient layer. For .Net 4.5 desktop, you can use a WebRequestHandler, for .Net Standard 1.3 you can use WinHttpHandler. Both of these provide some key features, such as SSL certificate validation control.
  2. .Net Standard does not support XML configuration files. So far, support has been added for other configuration approaches using the *Definition abstractions. However, for compatibility the .Net Desktop SDK should probably still maintain support for XML Configuration using the existing model.
  3. The current logging abstraction, Common.Logging, hasn't completed .Net Core support yet. This is hopefully forthcoming.

Approach 1

The first appraoch is to deliver two separate binaries in the same nuget package:

  • CouchbaseNetClient - .Net 4.5 Desktop SDK
  • CouchbaseNetClient - .Net Standard 1.5 SDK

This can be accomplished using the xproj and project.json project structure. It allows the project to dual build both binary outputs, and even provides warnings and errors separately for each build mode.

To account for some of the differences between the two platforms, conditional compilation directives may be used. For example, XML Configuration related classes and methods can be excluded from the build.

Advantages:

  • .Net Desktop version can still target .Net 4.5
  • Can be released as a minor point release without breaking semver
  • TBD: Both binaries could be included in the same Nuget package, allowing them the correct platform to be delivered transparently, using folder naming conventions

Disadvantages:

  • It is slightly more difficult to maintain, due to the conditional compilation directives
  • Unit and integration testing in Visual Studio doesn't seem to support executing tests against both binaries. The test libaries would need to be duplicated to get good test coverage, one for each platform.

Approach 2

The second approach is to deliver a single primary binary in the CouchbaseNetClient package:

  • CouchbaseNetClient - .Net Standard 1.3

Then, deliver additional functionality in a secondary package:

  • Couchbase.Configuration.Xml - .Net Desktop 4.6

Advantages

  • Single codebase to maintain, no conditional compilation directives
  • More consistent with the new .Net approach
  • Support for UWP on Win10 (not sure what demand is like in this space)

Disadvantages

  • Minimum .Net Desktop version must be increased to .Net 4.6 in order to get required functionality from .Net Standard 1.3 (Sockets, etc)
  • Type.GetTypeCode() isn't supported until .Net Standard 1.5, so DefaultTranscoder would need to be refactored to use a different type identification mechanism
  • This would not be a backwards compatible change for .Net Desktop, so to follow semver the package version would need to move to 3.0

Notes

  • This option could also be modified to target .Net Standard 1.5 instead of 1.3. This eliminates the problem with Type.GetTypeCode(). However, it makes the minimum .Net Desktop version 4.6.2 instead of 4.6. It also eliminates UWP support.

Approach 2 Logging Extension

If Approach 2 is chosen, this also simplifies the issue with Common.Logging support for .Net Core. Since we're incrementing to a new major version, there is the option to completely change the logging approach. A Couchbase-specific abstraction could be added, if desired. Then Nuget packages could be made to tie into different logging packages, similar to the way Common.Logging offers logging packages for log4net, NLog, etc.

However, since this is basically repeating the work already done by Common.Logging, waiting for full .Net Standard support for Common.Logging still has advantages. Since Common.Logging is an open source project, contributions could be made that would finish adding .Net Standard support.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment