From 63e32663aa38d0b157f310d6bf4d3cd279d645a7 Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Fri, 23 Aug 2024 20:31:51 +0000 Subject: [PATCH 1/6] Add examples to Feature attributes --- .../FeatureGuardAttribute.xml | 31 ++++++++++++++++--- .../FeatureSwitchDefinitionAttribute.xml | 31 ++++++++++++++++--- 2 files changed, 53 insertions(+), 9 deletions(-) diff --git a/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml b/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml index d5a85d51400..c41ce5fa464 100644 --- a/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml +++ b/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml @@ -29,14 +29,35 @@ - Indicates that the specified public static boolean get-only property - guards access to the specified feature. + + Indicates that the specified public static boolean get-only property + guards access to the specified feature. - Analyzers can use this to prevent warnings on calls to code that is - annotated as requiring that feature, when the callsite is guarded by a - call to the property. + + Analyzers can use this to prevent warnings on calls to code that is + annotated as requiring that feature, when the callsite is guarded by a + call to the property. + + + if (Feature.IsSupported) + Feature.Implementation(); + + public class Feature + { + [FeatureGuard(typeof(RequiresDynamicCodeAttribute))] + internal static bool IsSupported => RuntimeFeature.IsDynamicCodeSupported; + + [RequiresDynamicCode("Feature requires dynamic code support.")] + internal static Implementation() => ...; // Uses dynamic code + } + + When the app is built with `<PublishAot>true</PublishAot>`, the call to + `Feature.Implementation()` doesn't produce analyzer warning + IL3050, + and `Feature.Implementation` code is removed when publishing. + diff --git a/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml b/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml index cf8b0e4ee20..e8109e18a50 100644 --- a/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml +++ b/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml @@ -29,13 +29,36 @@ - Indicates that the specified public static boolean get-only property - corresponds to the feature switch specified by name. + + Indicates that the specified public static boolean get-only property + corresponds to the feature switch specified by name. - IL rewriters and compilers can use this to substitute the return value - of the specified property with the value of the feature switch. + + IL rewriters and compilers can use this to substitute the return value + of the specified property with the value of the feature switch. + + + if (Feature.IsSupported) + Feature.Implementation(); + + public class Feature + { + [FeatureSwitchDefinition("Feature.IsSupported")] + internal static bool IsSupported => AppContext.TryGetSwitch("Feature.IsSupported", out bool isEnabled) ? isEnabled : true; + + internal static Implementation() => ...; + } + + When the app is trimmed with the following feature settings in the project file, + `Feature.IsSupported` is treated as `false`, and `Feature.Implementation` code is removed. + + <ItemGroup> + <RuntimeHostConfigurationOption Include="Feature.IsSupported" Value="false" /> + </ItemGroup> + + From fb0b5aae350e7d34bc7243713b8e442db7880d0e Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Fri, 23 Aug 2024 20:42:03 +0000 Subject: [PATCH 2/6] Fix typo --- xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml b/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml index c41ce5fa464..d6ea5f5aba1 100644 --- a/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml +++ b/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml @@ -53,7 +53,7 @@ internal static Implementation() => ...; // Uses dynamic code } - When the app is built with `<PublishAot>true</PublishAot>`, the call to + When the app is built with `<PublishAot>true</PublishAot>`, the call to `Feature.Implementation()` doesn't produce analyzer warning IL3050, and `Feature.Implementation` code is removed when publishing. From 7f78236fe7330a94332ffa48bb863bbec0920c1b Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Fri, 23 Aug 2024 21:11:49 +0000 Subject: [PATCH 3/6] Fix typo --- xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml b/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml index d6ea5f5aba1..f2610997953 100644 --- a/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml +++ b/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml @@ -53,7 +53,7 @@ internal static Implementation() => ...; // Uses dynamic code } - When the app is built with `<PublishAot>true</PublishAot>`, the call to + When the app is built with `<PublishAot>true<PublishAot>`, the call to `Feature.Implementation()` doesn't produce analyzer warning IL3050, and `Feature.Implementation` code is removed when publishing. From ce3b25834bb23d03f16d5ad8b1065d6a0a52fa94 Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Mon, 26 Aug 2024 11:40:59 -0700 Subject: [PATCH 4/6] Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- .../FeatureGuardAttribute.xml | 6 +++--- .../FeatureSwitchDefinitionAttribute.xml | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml b/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml index f2610997953..6f86f51167a 100644 --- a/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml +++ b/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml @@ -30,12 +30,12 @@ - Indicates that the specified public static boolean get-only property + Indicates that the specified public static Boolean read-only property guards access to the specified feature. - Analyzers can use this to prevent warnings on calls to code that is + Analyzers can use this attribute to prevent warnings on calls to code that's annotated as requiring that feature, when the callsite is guarded by a call to the property. @@ -55,7 +55,7 @@ When the app is built with `<PublishAot>true<PublishAot>`, the call to `Feature.Implementation()` doesn't produce analyzer warning - IL3050, + IL3050, and `Feature.Implementation` code is removed when publishing. diff --git a/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml b/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml index e8109e18a50..eeec0cd6eee 100644 --- a/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml +++ b/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml @@ -30,12 +30,12 @@ - Indicates that the specified public static boolean get-only property + Indicates that the specified public static Boolean read-only property corresponds to the feature switch specified by name. - IL rewriters and compilers can use this to substitute the return value + IL rewriters and compilers can use this attribute to substitute the return value of the specified property with the value of the feature switch. From c3407afd4fe13fd6a1b38d8264ed2d77a4c7c9ca Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Mon, 26 Aug 2024 18:50:34 +0000 Subject: [PATCH 5/6] Try markdown formatting --- .../FeatureGuardAttribute.xml | 33 +++++++++-------- .../FeatureSwitchDefinitionAttribute.xml | 36 ++++++++++--------- 2 files changed, 37 insertions(+), 32 deletions(-) diff --git a/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml b/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml index 6f86f51167a..aa4efe29a6f 100644 --- a/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml +++ b/xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml @@ -40,23 +40,26 @@ call to the property. - - if (Feature.IsSupported) - Feature.Implementation(); + RuntimeFeature.IsDynamicCodeSupported; +public class Feature +{ + [FeatureGuard(typeof(RequiresDynamicCodeAttribute))] + internal static bool IsSupported => RuntimeFeature.IsDynamicCodeSupported; - [RequiresDynamicCode("Feature requires dynamic code support.")] - internal static Implementation() => ...; // Uses dynamic code - } - - When the app is built with `<PublishAot>true<PublishAot>`, the call to - `Feature.Implementation()` doesn't produce analyzer warning - IL3050, - and `Feature.Implementation` code is removed when publishing. + [RequiresDynamicCode("Feature requires dynamic code support.")] + internal static Implementation() => ...; // Uses dynamic code +} +``` + +When the app is built with `true`, the call to +`Feature.Implementation()` doesn't produce analyzer warning +[IL3050](/dotnet/core/deploying/native-aot/warnings/il3050) +and `Feature.Implementation` code is removed when publishing. +]]> diff --git a/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml b/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml index eeec0cd6eee..31ba4427073 100644 --- a/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml +++ b/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml @@ -39,25 +39,27 @@ of the specified property with the value of the feature switch. - - if (Feature.IsSupported) - Feature.Implementation(); + AppContext.TryGetSwitch("Feature.IsSupported", out bool isEnabled) ? isEnabled : true; +public class Feature +{ + [FeatureSwitchDefinition("Feature.IsSupported")] + internal static bool IsSupported => AppContext.TryGetSwitch("Feature.IsSupported", out bool isEnabled) ? isEnabled : true; - internal static Implementation() => ...; - } - - When the app is trimmed with the following feature settings in the project file, - `Feature.IsSupported` is treated as `false`, and `Feature.Implementation` code is removed. - - <ItemGroup> - <RuntimeHostConfigurationOption Include="Feature.IsSupported" Value="false" /> - </ItemGroup> - + internal static Implementation() => ...; +} +` +When the app is trimmed with the following feature settings in the project file, +`Feature.IsSupported` is treated as `false`, and `Feature.Implementation` code is removed. +```xml + + + +``` +]]> From 41e4d8edcabfc066a8add8024dfcd8cf0aa14e00 Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Mon, 26 Aug 2024 20:24:48 +0000 Subject: [PATCH 6/6] Fix code block --- .../FeatureSwitchDefinitionAttribute.xml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml b/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml index 31ba4427073..c8f6111e6c8 100644 --- a/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml +++ b/xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml @@ -51,9 +51,11 @@ public class Feature internal static Implementation() => ...; } -` +``` + When the app is trimmed with the following feature settings in the project file, `Feature.IsSupported` is treated as `false`, and `Feature.Implementation` code is removed. + ```xml