.NET Tools

.NET Annotated Monthly | January 2023

Did you know? Though these terms are often used interchangeably, there is a difference between a parameter and an argument. A parameter is only the definition of something that’s passed into a function and is found in the function’s signature. Parameters usually define the name and type of allowed for the argument to use. The argument is the actual value that’s passed into the function in calling code. 

.NET news

Through December most of the .NET folks at Microsoft headquarters take time off for Christmas, New Year, and other winter holidays. There’s been no new releases from Microsoft, but there are a few noteworthy items in their Top 10 Blog Posts of 2022.

Featured content 

We’d like to thank Chris Patterson for curating this month’s featured content! It’s story time!

Chris Patterson is an Enterprise Software Architect, the founder of Loosely Coupled, LLC, and the author of MassTransit, an open-source distributed application framework for building message-based applications. Before starting his own company, Chris spent 24 years leading the architecture and development of multiple platforms and services in a Fortune 10 company leveraging a broad range of technologies. Chris is a multi-year Microsoft MVP award recipient and regularly produces software development-related content on YouTube.

Avoid Breaking API Changes

Contract design is critical when building applications, even more so now that microservices are mainstream. Updating distributed applications requires discipline as these contracts define APIs, messages, and persistent data structures used by other services. Maintaining these contracts requires care to avoid breaking changes when releasing updated application versions.

There are numerous guidelines to avoid breaking contract changes, including not changing a property’s name, type, meaning, or cardinality and only adding nullable properties. However, there are less obvious ways that change can break an existing API, and the following is a true story of one such change.

A popular payment provider uses a string to identify customers in their API, and that identifier was always a numeric value. The API transfers data using JSON, which formats most data types as strings, so the customer identifier was assumed to be numeric. With that assumption, the engineering team used a numeric column to identify the customer in the database.

A few months ago, the webhook began receiving alphanumeric customer identifiers that immediately produced errors since the identifier could not be parsed into an integer. The payment provider changing the identifier format was not explicitly a contract change (it’s still a string), but it contradicted an established expectation. Customers treating the identifier as a numeric type were unable to process payments.

The provider reverted the behavior within a few hours.

The moral of this story: don’t change property expectations when developers may infer the content is a specific type. For example, if a text property contains a formatted number, Guid, DateTime, or TimeSpan, changing the format may cause unintended results, in this case breaking order fulfillment for new customers as they were unable to be stored in the database. 

Tutorials and tips 

.NET tutorials and tips

I occasionally see something like this when developers create SQL tables and use the string value “null” for nulls. Unfortunately, there are many negative side effects of this practice, including what’s in Joe’s tweet. Use nulls in a database the way the database creators intended. It will work better.

https://twitter.com/jguadagno/status/1606271240972509184

Related programming tutorials and tips:

Interesting and cool stuff

And finally, the latest from JetBrains!

Here’s a chance to catch up on JetBrains news that you might have missed:

Watch a recording of our ReSharper & Rider 2022.3 Release Party!

The .NET developer advocates are all on Mastodon now as well. Give them a follow!

Check out our .NET Guide! It’s a learning tool with tons of videos, tips, tricks, and info on a variety of .NET related topics.

Blog posts, webinars, etc..:

Don’t miss this fantastic offer! CODE Magazine is offering a free subscription to JetBrains customers. Get your copy today!

Sharing is caring! So share content that you find useful with other readers. Don’t keep it to yourself! Send us an email with your suggestions for publication in future newsletters!

Subscribe to .NET Annotated

Discover more