AvoidUse attribute: do not use this member!

[CypherPotato]

The problem

My proposal is to create an attribute to limit the use of a public API, but not make it inaccessible in the assembly hiding or defining it private or friend-access. Something similar to what we have for the ExperimentalAttribute and ObsoleteAttribute, but used when the member must exist, is not experimental and is also not deprecated, but was not made for public use and instead to satisfy an internal condition or use.

Let's consider a use case: I have a class that has two different constructors, and I need this class to be created with one of those constructors when used by the public API. The problem is that this class needs to be serialized and deserialized by JSON, so a public parameterless constructor is required. However, this constructor would be a logical error in the API, with uninitialized members or behavior not expected by the other two constructors. Therefore, we would have an attribute indicating that this constructor should not be used.

public Attachment ( string fileNameTemplate, AttachmentDynamicParameters dynamicParameters ) {
    this.FileNameTemplate = fileNameTemplate;
    this.DynamicParameters = dynamicParameters ?? throw new ArgumentNullException ( nameof ( dynamicParameters ) );
}

public Attachment ( string fileNameTemplate, AttachmentStaticParameters staticParameters ) {
    this.FileNameTemplate = fileNameTemplate;
    this.StaticParameters = staticParameters ?? throw new ArgumentNullException ( nameof ( staticParameters ) );
}

#pragma warning disable CS8618
[Obsolete ( "This constructor only exists for the JSON serializer to create the object. Avoid using it.", error: true )]
public Attachment () {
}
#pragma warning restore CS8618

Above, the code works well with the ObsoleteAttribute, but as I said, this constructor is not obsolete, and it would also not make sense to use Experimental because it is not experimental.

The solution

My proposal is for an attribute named "AvoidUsage" (or something similar), which would have the same behavior as the ExperimentalAttribute (I need to suppress the warning to use the member).

#pragma warning disable CS8618
[AvoidUsage ( "DIAGNOSTIC_ID", "This constructor only exists for the JSON serializer to create the object. Avoid using it." )]
public Attachment () {
}
#pragma warning restore CS8618

And when trying to construct it, the compiler should emit an error:

var attachment = new Attachment(); // error: Do not use this member. Reason: "This constructor only exists for the JSON serializer to create the object. Avoid using it."

You could still continue and use the constructor if you suppress the warning:

#pragma warning disable DIAGNOSTIC_ID
var attachment = new Attachment(); // ok!

Also, having a property to "hide" this member from auto-complete, such as Intellisense, would be interesting. This solution would bring more meaning to the code, and make it clear that this member must exist, but not be used without reading the reason it is hidden. This brings more confidence in situations where there is no certainty that this member will be used improperly and prevents future problems.

[huoyaoyuan]

This is a language discussion, not for runtime.

The problem is that this class needs to be serialized and deserialized by JSON, so a public parameterless constructor is required.

This is not the case. All of the popular JSON serialization library supports populating fields in constructor.

Above, the code works well with the ObsoleteAttribute, but as I said, this constructor is not obsolete

This is a well-known usage of ObsoleteAttribute. The compiler even emits ObsoleteAttribute for every ref struct to prevent usage from compilers that don't support it.

Also, having a property to "hide" this member from auto-complete, such as Intellisense, would be interesting.

There is [EditorBrowsable(Never)].