Skip to content

Add examples to FeatureGuard/FeatureSwitchDefinition docs #10304

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Aug 28, 2024
Merged

Add examples to FeatureGuard/FeatureSwitchDefinition docs #10304

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
63e3266
Add examples to Feature attributes
sbomer Aug 23, 2024
fb0b5aa
Fix typo
sbomer Aug 23, 2024
7f78236
Fix typo
sbomer Aug 23, 2024
ce3b258
Apply suggestions from code review
sbomer Aug 26, 2024
c3407af
Try markdown formatting
sbomer Aug 26, 2024
41e4d8e
Fix code block
sbomer Aug 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 29 additions & 5 deletions xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,14 +29,38 @@
</Attributes>
<Docs>
<summary>
<para>Indicates that the specified public static boolean get-only property</para>
<para>guards access to the specified feature.</para>
<para>
Indicates that the specified public static Boolean read-only property
guards access to the specified feature.</para>
</summary>
<remarks>
<para>Analyzers can use this to prevent warnings on calls to code that is</para>
<para>annotated as requiring that feature, when the callsite is guarded by a</para>
<para>call to the property.</para>
<para>
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.</para>
</remarks>
<example>
<format type="text/markdown"><![CDATA[
```csharp
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](/dotnet/core/deploying/native-aot/warnings/il3050)
and `Feature.Implementation` code is removed when publishing.
]]></format>
</example>
</Docs>
<Members>
<Member MemberName=".ctor">
Expand Down
35 changes: 31 additions & 4 deletions xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,13 +29,40 @@
</Attributes>
<Docs>
<summary>
<para>Indicates that the specified public static boolean get-only property</para>
<para>corresponds to the feature switch specified by name.</para>
<para>
Indicates that the specified public static Boolean read-only property
corresponds to the feature switch specified by name.</para>
</summary>
<remarks>
<para>IL rewriters and compilers can use this to substitute the return value</para>
<para>of the specified property with the value of the feature switch.</para>
<para>
IL rewriters and compilers can use this attribute to substitute the return value
of the specified property with the value of the feature switch.</para>
</remarks>
<example>
<format type="text/markdown"><![CDATA[
```csharp
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.

```xml
<ItemGroup>
<RuntimeHostConfigurationOption Include="Feature.IsSupported" Value="false" />
</ItemGroup>
```
]]></format>
</example>
</Docs>
<Members>
<Member MemberName=".ctor">
Expand Down