JsonApiDotNetCore.Annotation for netstandard2.0

[ThomasBarnekow]

Before coming to my request, let me first say how awesome the new stuff is that you have developed since we last talked. I love the source generators.

Now to my feature request . The context is that I want to create a separate project that:

• contains the model classes hat will have to be annotated with the ResourceAttribute, among others; and
• targets netstandard2.0 because it will also be required by one or more projects that are, unfortunately, bound to .NET Framework.

I thought that I could add the JsonApiDotNetCore.Annotations package as a dependency to that model-related project. However, that NuGet package depends on net60, which I can't use for my model project for the reasons described above.

Doe the Annotations package have to depend on net60 or could this also target netstandard2.0? In other words, is there a way you could provide a NuGet package that is useable from .NET Framework or netstandard2.0?

[ThomasBarnekow]

I have now played with the JsonApiDotNetCore.Annotations project and found that it can't target netstandard2.0 "just like that". There are not only resource attributes but other classes that depend on net60 features.

Would you want to enable model (or resource) projects that target netstandard2.0?

[bkoelman]

Thanks for your compliment. I'm happy to hear that you like the new features!

The request to target lower TFMs in JsonApiDotNetCore.Annotations came up a while ago too during an internal conversation. Unfortunately, this isn't going to be straightforward today.

The biggest problem is that this assembly contains ResourceType, which depends on IReadOnlySet<>, which was added in .NET 5. ResourceType needs to be in there because it is a member of RelationshipAttribute. This problem will go away once #776 (comment) is implemented. It's on our roadmap, but our time has been very limited over the last months, so it may take a while before that's going to be available.

Another problem is that netstandard2.0 does not provide System.ComponentModel.DataAnnotations.Schema.NotMappedAttribute (which surprised me, by the way, because it's been part of .NET Framework since v4.5), which is used on Identifiable<> to avoid creating database columns for calculated properties. Removing that would require everyone to use the EF Core Fluent API instead to set up mappings correctly, which is a breaking change that's difficult for users to deal with because it doesn't cause any obvious errors. I've experimented with changing these properties into Get/Set methods a while ago (because MongoDB doesn't recognize [NotMapped]), but it resulted in somewhat ugly code at call sites.

Then there are some issues around nullability and the lack of System.Diagnostics.CodeAnalysis.NotNullAttribute, but we should be able to deal with that using conditional defines (#if ... #else ... #endif) in the code. Likewise, we can special-case for the lack of System.HashCode.Combine.

To summarize, the best we can offer for now is to multi-target against .NET 5. But that framework is out of support and it isn't going to solve your problem, so I'm not eager to do that.

To workaround your problem, I'd advise to conditionally reference JsonApiDotNetCore.Annotations in your shared project and then use conditional defines for its dependencies, for example:

#if NET6_0_OR_GREATER
    public sealed class Customer : Identifiable<long>
#else
    public sealed class Customer
#endif
    {
#if NET6_0_OR_GREATER
        [Attr]
#endif
        public int OrderCount { get; set; }

        // ...
    }

I'm aware that looks kinda ugly, though.

[ThomasBarnekow]

@bkoelman, thanks for your reply and the hint. I'll try your workaround.

You will likely be able to deal with the lack of System.Diagnostics.CodeAnalysis.NotNullAttribute by inserting the following in your codebase:

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

using JetBrains.Annotations;

namespace System.Diagnostics.CodeAnalysis
{
    /// <summary>
    /// Specifies that null is allowed as an input even if the corresponding type disallows it.
    /// </summary>
    [PublicAPI]
    [AttributeUsage(AttributeTargets.Field | AttributeTargets.Parameter | AttributeTargets.Property)]
    internal sealed class AllowNullAttribute : Attribute
    {
    }

    /// <summary>
    /// Specifies that null is disallowed as an input even if the corresponding type allows it.
    /// </summary>
    [PublicAPI]
    [AttributeUsage(AttributeTargets.Field | AttributeTargets.Parameter | AttributeTargets.Property)]
    internal sealed class DisallowNullAttribute : Attribute
    {
    }

    /// <summary>
    /// Specifies that an output may be null even if the corresponding type disallows it.
    /// </summary>
    [PublicAPI]
    [AttributeUsage(
        AttributeTargets.Field | AttributeTargets.Parameter | AttributeTargets.Property | AttributeTargets.ReturnValue)]
    internal sealed class MaybeNullAttribute : Attribute
    {
    }

    /// <summary>
    /// Specifies that an output will not be null even if the corresponding type allows it. Specifies that an input argument
    /// was not null when the call returns.
    /// </summary>
    [PublicAPI]
    [AttributeUsage(
        AttributeTargets.Field | AttributeTargets.Parameter | AttributeTargets.Property | AttributeTargets.ReturnValue)]
    internal sealed class NotNullAttribute : Attribute
    {
    }

    /// <summary>
    /// Specifies that when a method returns <see cref="ReturnValue" />, the parameter may be null even if the corresponding
    /// type disallows it.
    /// </summary>
    [PublicAPI]
    [AttributeUsage(AttributeTargets.Parameter)]
    internal sealed class MaybeNullWhenAttribute : Attribute
    {
        /// <summary>
        /// Initializes the attribute with the specified return value condition.
        /// </summary>
        /// <param name="returnValue">
        /// The return value condition. If the method returns this value, the associated parameter may be null.
        /// </param>
        public MaybeNullWhenAttribute(bool returnValue)
        {
            ReturnValue = returnValue;
        }

        /// <summary>
        /// Gets the return value condition.
        /// </summary>
        public bool ReturnValue { get; }
    }

    /// <summary>
    /// Specifies that when a method returns <see cref="ReturnValue" />, the parameter will not be null even if the
    /// corresponding type allows it.
    /// </summary>
    [PublicAPI]
    [AttributeUsage(AttributeTargets.Parameter)]
    internal sealed class NotNullWhenAttribute : Attribute
    {
        /// <summary>
        /// Initializes the attribute with the specified return value condition.
        /// </summary>
        /// <param name="returnValue">
        /// The return value condition. If the method returns this value, the associated parameter will not be null.
        /// </param>
        public NotNullWhenAttribute(bool returnValue)
        {
            ReturnValue = returnValue;
        }

        /// <summary>
        /// Gets the return value condition.
        /// </summary>
        public bool ReturnValue { get; }
    }

    /// <summary>
    /// Specifies that the output will be non-null if the named parameter is non-null.
    /// </summary>
    [PublicAPI]
    [AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property | AttributeTargets.ReturnValue, AllowMultiple = true)]
    internal sealed class NotNullIfNotNullAttribute : Attribute
    {
        /// <summary>
        /// Initializes the attribute with the associated parameter name.
        /// </summary>
        /// <param name="parameterName">
        /// The associated parameter name.  The output will be non-null if the argument to the parameter specified is non-null.
        /// </param>
        public NotNullIfNotNullAttribute(string parameterName)
        {
            ParameterName = parameterName;
        }

        /// <summary>
        /// Gets the associated parameter name.
        /// </summary>
        public string ParameterName { get; }
    }

    /// <summary>
    /// Applied to a method that will never return under any circumstance.
    /// </summary>
    [PublicAPI]
    [AttributeUsage(AttributeTargets.Method, Inherited = false)]
    internal sealed class DoesNotReturnAttribute : Attribute
    {
    }

    /// <summary>
    /// Specifies that the method will not return if the associated Boolean parameter is passed the specified value.
    /// </summary>
    [PublicAPI]
    [AttributeUsage(AttributeTargets.Parameter)]
    internal sealed class DoesNotReturnIfAttribute : Attribute
    {
        /// <summary>
        /// Initializes the attribute with the specified parameter value.
        /// </summary>
        /// <param name="parameterValue">
        /// The condition parameter value. Code after the method will be considered unreachable by diagnostics if the argument to
        /// the associated parameter matches this value.
        /// </param>
        public DoesNotReturnIfAttribute(bool parameterValue)
        {
            ParameterValue = parameterValue;
        }

        /// <summary>
        /// Gets the condition parameter value.
        /// </summary>
        public bool ParameterValue { get; }
    }

    /// <summary>
    /// Specifies that the method or property will ensure that the listed field and property members have not-null values.
    /// </summary>
    [PublicAPI]
    [AttributeUsage(AttributeTargets.Method | AttributeTargets.Property, Inherited = false, AllowMultiple = true)]
    internal sealed class MemberNotNullAttribute : Attribute
    {
        /// <summary>
        /// Initializes the attribute with a field or property member.
        /// </summary>
        /// <param name="member">
        /// The field or property member that is promised to be not-null.
        /// </param>
        public MemberNotNullAttribute(string member)
        {
            Members = new[]
            {
                member,
            };
        }

        /// <summary>
        /// Initializes the attribute with the list of field and property members.
        /// </summary>
        /// <param name="members">
        /// The list of field and property members that are promised to be not-null.
        /// </param>
        public MemberNotNullAttribute(params string[] members)
        {
            Members = members;
        }

        /// <summary>
        /// Gets field or property member names.
        /// </summary>
        public string[] Members { get; }
    }

    /// <summary>
    /// Specifies that the method or property will ensure that the listed field and property members have not-null values when
    /// returning with the specified return value condition.
    /// </summary>
    [PublicAPI]
    [AttributeUsage(AttributeTargets.Method | AttributeTargets.Property, Inherited = false, AllowMultiple = true)]
    internal sealed class MemberNotNullWhenAttribute : Attribute
    {
        /// <summary>
        /// Initializes the attribute with the specified return value condition and a field or property member.
        /// </summary>
        /// <param name="returnValue">
        /// The return value condition. If the method returns this value, the associated parameter will not be null.
        /// </param>
        /// <param name="member">
        /// The field or property member that is promised to be not-null.
        /// </param>
        public MemberNotNullWhenAttribute(bool returnValue, string member)
        {
            ReturnValue = returnValue;

            Members = new[]
            {
                member,
            };
        }

        /// <summary>
        /// Initializes the attribute with the specified return value condition and list of field and property members.
        /// </summary>
        /// <param name="returnValue">
        /// The return value condition. If the method returns this value, the associated parameter will not be null.
        /// </param>
        /// <param name="members">
        /// The list of field and property members that are promised to be not-null.
        /// </param>
        public MemberNotNullWhenAttribute(bool returnValue, params string[] members)
        {
            ReturnValue = returnValue;
            Members = members;
        }

        /// <summary>
        /// Gets the return value condition.
        /// </summary>
        public bool ReturnValue { get; }

        /// <summary>
        /// Gets field or property member names.
        /// </summary>
        public string[] Members { get; }
    }
}

[ThomasBarnekow]

@bkoelman, your hint above helped me solve my immediate problem. However, as you say, the code does not look particularly beautiful.

Would you want to keep this issue open or do you want me to close it. I don't know whether you are planning to offer this enhancement in the not-too-distant future.

[bkoelman]

I don't see us solving the problem with [NotMapped] anytime soon. Nevertheless, we can provide just empty (non-working) attributes when targeting netstandard20, so you don't need to use conditional defines. I've created a PR to try that.

Knowing that @maurei has other things on his mind right now, it would be great if you can try this out and review my PR. I've sent you an invite to join the team, which I think is needed to request a review from you via GitHub.

[ThomasBarnekow]

Thanks, @bkoelman, I just accepted the invite and will try out and review that PR tomorrow.

[ThomasBarnekow]

@bkoelman, owing to some urgent tasks, I will not be able to do the review today.

[bkoelman]

No problem, thanks for letting me know.

[bkoelman]

@ThomasBarnekow Do you think you'll be able to review within the next few days? I'm asking because #1197 depends on it.

[ThomasBarnekow]

To be honest, I am not sure. Do you have a hard deadline?

[bkoelman]

The hard deadline is the release of .NET 7 in a few weeks. We'll need to release something by then, JADNC won't work as-is. I'm still experimenting to decide on the best approach. Without going into much details, it looks like its going to need some form of multi-targeting, likely conflicting with the multi-targeting in this PR.

This week I have time to spend on JADNC, my time is going to be limited in the weeks after that. If you and @maurei aren't able to review open PRs soon, I'm going to have choose between merging without review or leaving it out on a case-by-case basis.

Now is your opportunity to influence how this is going to work and get it released so your project can make use of it. Once released, its unlikely we're going to change it, because it may break existing users that have taken a dependency on it.

As a review usually goes back and forth a few times, I'd like to get the first pass of feedback before Wednesday end of day. Do you think that's feasible?