Description
Background and Motivation
Currently the shape of these attributes is like:
class RequiresUnreferencedCodeAttribute : Attribute
{
public RequiresUnreferencedCodeAttribute(string message);
public string Message { get; }
public string Url { get; set; }
}
class RequiresAssemblyFilesAttribute : Attribute
{
public RequiresAssemblyFilesAttribute();
public string Message { get; set; }
public string Url { get; set; }
}The two attributes are very similar in their usage, they annotate a certain method as problematic when used with trimming or single-file respectively. But their usage is different:
[RequiresUnreferencedCode("This method doesn't play nice with trimming")]
[RequiresAssemblyFiles(Message = "This method doesn't play nice with single-file either")]
void ReallyProblematicMethod() {}The first attribute makes the Message mandatory since it's a constructor parameter which can't be omitted. The second attribute makes Message optional and doesn't provide a way to specify it in the constructor.
From UX perspective we want people to specify the message if they at all can, since without it the produced warnings are not very actionable. It would also be good for these two attributes to have consistent usage patterns.
Proposed API
We can't really change RequiresUnreferencedCode since that already shipped in .NET 5. But we can adapt RequiresAssemblyFiles to match its behavior:
namespace System.Diagnostics.CodeAnalysis;
class RequiresAssemblyFilesAttribute : Attribute
{
- public RequiresAssemblyFilesAttribute();
+ public RequiresAssemblyFilesAttribute(string message);
- public string Message { get; set; }
+ public string Message { get; }
public string Url { get; set; }
}If we think that message should be optional, then keep the parameter less constructor as well.
Usage Examples
[RequiresUnreferencedCode("This method doesn't play nice with trimming")]
[RequiresAssemblyFiles("This method doesn't play nice with single-file either")]
void ReallyProblematicMethod() {}Risks
As proposed it's a breaking change compared to previously released .NET 6 Previews. We don't expect this attribute to be used by many people yet.
There's associated cost in the "breaking" change that we would need to fix all of the occurrences of this attribute in the framework (less than 100) and that the Roslyn analyzer for this attribute will need to react to the change.