This release consolidates many changes and additional nuget packages that have accumulated privately over the past few months.

v3.0.0 includes many breaking changes from the v2.x releases. There are a few other breaking changes pending for upcoming releases, but most libraries will remain pretty stable.

Port to OpenTelemetry

Neon.Common has included a homegrown logging infrastructure implemented by LogManager and INeonLogger and other types. These originated maybe 10+ years ago when I ran into trouble with Log4Net and decided to throw together a quick replacement. This looks really non-standard now and doesn't really map that well to modern dependency injection techniques.

More recently, our NeonService class added support for Prometheus metrics.

Now that OpenTelemetry has mostly matured, we've decided that now's the time to embrace the OpenTelemetry APIs and components across neonSDK, neonKUBE, and our internal projects. This will be a significant breaking change.

Here's what you'll need to do to adapt:

1. Neon.Web: The NeonController and NeonControllerBase used to have logging methods. Now it has a read-only Logger property you'll call for logging. This property makes these classes easier to maintain. You'll need to modify class like NeonController.Error(...) to NeonController.Logger.LogError(...).

2. Telemetry Changes:

   • Neon.Common:

     • We've decided to converge with OpenTelemetry and the standard Microsoft logging conventions. This means that NullLogger, TestLogger, and TextLogger, ILogManager, LogManager, NeonDiagnostics.LogLevel types have been removed (or made internal) and also that we no longer support these extended log levels: Transient, SInfo, and SError.
     • Logging configuration is no longer done via LogManager. NeonService configures console logging by default and enables tracing when the app is running in a Kubernetes cluster. These behaviors can be disabled so that applications can do custom log configuration.
     • Most code that emits logs will need to add these usings:

       using Microsoft.Extensions.Logging;   // Loads the base logging symbols, including basic `ILogger` logging extensions.
       using Neon.Diagnostics;               // Loads extended logging extensions including nicer ways to add tags
       

   • Logging and tracing from NeonSDK libraries is now disabled by default, unless you're using NeonService. To enable this for other scenarios, you'll need to modify your telemetry initialization code to call Neon.Diagnostics.TelemetryHub.Initialize(), passing the ILoggerFactory and ActivitySource.

   • We've implemented several new ILogger extension methods in Neon.Diagnostics.LoggerExtensions. These include methods that make it easier to add tags to logged events as well as for creating a new ILogger that wraps an existing logger and includes tags to be appended to all events emitted via the logger: ILogger.CreateLoggerWithTags().

     These new method names end with "Ex" as in: LogCriticalEx(), LogErrorEx(), LogWarningEx(), LogInformationEx(), LogDebugEx() and LogTraceEx().

     We recommend that you use Neon.Diagnostics; and then change all of your logging calls to these new methods.

   • Be sure that you pass a Func message function when logging a interpolated string message:

     // Instead of this:
     
     var name = "Sally";
     logger.LogTraceEx($"Hello: {name}");
     
     // Do this:
     
     logger.LogTraceEx(() => $"Hello: {name}");
     
     // Doing this more performant when the current log level will disables logging.
     // The reason is that string interpolation will create a new string in the heap 
     // (incurring GC overhead) and also will consume CPU for do the string processing.
     // This effort will be completely wasted and if you're doing a lot of debug or trace
     // logging could result in bloated memory usage and a lot of wasted cycles.
     

   • For projects using our older ILogger extensions, you'll need to rename those by adding "Ex to the method name to fix compiler errors. We've also reordered the parameters of some of the new extended methods, so you may need to tweak some of your logging calls.

   • Note that our new "ILogger.LogInformationEx()andILogger.LogWarningEx()extensions replace the oldINeonLogger.LogInfo()andINeonLogger.LogWarn()` methods (with fully spelled out levels).

   • The optional activityId parameter has been removed from JsonClient methods and are also no longer present in the ILogger methods.

   • Our logging extensions that accept an Exception parameter have relocated the exception to be the first parameter. This is a change from the old INeonLogger methods there the exception parameter was after the message parameter. We've also renamed the e parameter in these cases to exception to be more consistent with MSFT's ILogger extensions.

3. ModelGen no longer generates LogActivity parameters for generated HTTP client methods since the tracing context is implied now.

4. NeonService:

   • We've removed the NeonService.LogManager property. Use the static TelemetryHub class instead, if necessary.
   • NeonServiceFixture has been relocated from the Neon.Xunit package to the new Neon.Xunit.Service package.

5. Neon.Cryptography: We've removed the TlsCertificate class. This was a (horrible) hack from several years ago before added X509Certificate2. I doubt that many if any people are using this except for us. The fix is to switch to X509Certificate2.

6. Extension method namespace changes: Up until now, we've defined extension methods for various system types in the System or other namespaces owned by other nuget publishers. This isn't great because we might end up conflicting with extension methods that others have written and it's also not super polite to add these definitions by default rather than allowing users to opt-in.

   We moved all of these into the Neon.Diagnostics namespace and you'll need to use this to opt-into these extensions.

   When logging dynamically generated message, be sure to use the logging methods that accept a lambda function that returns your message rather than passing the message directly. This improves performance when the event won't be logged due to the current log level. See the Neon.Diagnostics.LoggerExtensions class for more information.

Other Breaking Changes

• .NET Core 3.1 is no longer supported (MSFT has not been supporting this since Oct 2022)
• .NET Core 5.0 is no longer supported (MSFT has not been supporting this since May 2022)

Neon.Common:

1. EnvironmentParser changes:

   • We've renamed these parameters: redacted --> redact
   • The parser now honors the NEON_REDACT_OVERRIDE=1 environment variable when present by ignoring any redact: true arguments and including the value being parsed in any logged events. This is useful when debugging but should never be set for production.

2. We've changed the default variable formats for PreprocessReader to make them look more like Powershell variable references as opposed to their current somewhat wonky format: #4.

   We've changed the format for referencing variables like $(NAME), environment variables like $((NAME)) and secret or profile values like $(((TYPE:NAME))) to something inspired by Powershell and more readable: $(NAME)for variables,$(env:NAME)for environment variables,$(secret:NAME) for secrets and $(profile:NAME) for profile values.

   This change probably won't impact non-neonFORGE related projects. We wanted to clean this up now before this sees more widespread use, especially for neonKUBE users who can use this to reference variables in cluster definitions, etc.

3. NeonHelper.DockerCli has been changed to return null when Docker is not installed as opposed to throwing a FileNotFoundException.

4. We've removed the ExceptionResult, ExceptionResult, and CatchAllException classes. These were intended as a way to serialize an exception for transmission from a remote call back to the client such that it can be re-thrown as the original exception type on the client if possible. We never ended up using this. The other problem is that this required reflection which means that it wouldn't be compatible with trimming and now that net7.0 publication support is so much better, we're beginning the process of trying to rely on things like reflection much less.

5. We've modified NetHelper.ModifyLocalHosts() to make it more generally useful for other than unit testing. The section parameter is no longer optional and has been moved to be the first method parameter. We've also relaxed the section requirements to allow up to 63 non-control ASCII characters.

6. NetHelper.ListLocalHostsSections() has been modified to return an IEnumerable new LocalHostSection instances that include the name of the section in addition to the dictionary of address definitions within the section. This method used to return an IEnumerable of just section names.

7. NeonHelper.GetBaseDirectory() has been renamed to GetApplicationFolder()

Neon,Cadence and Neon.Temporal:

We no longer in the .NET Cadence and Temporal client business now that temporal.io is in the process of writing an official client for .NET.

Neon.Couchbase:

The Neon.Couchbase library has been removed for v3.0.0. We haven't used Couchbase in years and our client extensions support only the Couchbase v2+ clients which have been deprecated for some time now and the v3+ clients are very different. It doesn't make sense to maintain this any more.

Neon.Service:

1. We've removed several of the optional parameters to the NeonService constructor and replaced these ...

This is the first public release for several months and includes changes we've accumulated over that time and is the first release since we've relocated these libraries from the neonKUBE repo to the new neonSDK repo in preparation for the first neonKUBE releases. It was confusing to be releasing two different projects with differing version numbers from the same repo.

There may be a few breaking changes, but frankly we haven't been tracking these. I don't believe that most folks will be impacted.

This may be the last 2.x release of the SDK since we're preparing SDK v3.0.0 to be released in the immediate future. v3.0.0 will be a breaking release with significant changes to logging and NeonService; we've ditched our semi-proprietary implementation in favor of OpenTelemetry and standard pipeline configuration. We're also tweaking our ILogger extension methods.