Tetractic.CodeAnalysis.ExceptionAnalyzers
1.4.6
Prefix Reserved
dotnet add package Tetractic.CodeAnalysis.ExceptionAnalyzers --version 1.4.6
NuGet\Install-Package Tetractic.CodeAnalysis.ExceptionAnalyzers -Version 1.4.6
<PackageReference Include="Tetractic.CodeAnalysis.ExceptionAnalyzers" Version="1.4.6"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>
paket add Tetractic.CodeAnalysis.ExceptionAnalyzers --version 1.4.6
#r "nuget: Tetractic.CodeAnalysis.ExceptionAnalyzers, 1.4.6"
// Install Tetractic.CodeAnalysis.ExceptionAnalyzers as a Cake Addin #addin nuget:?package=Tetractic.CodeAnalysis.ExceptionAnalyzers&version=1.4.6 // Install Tetractic.CodeAnalysis.ExceptionAnalyzers as a Cake Tool #tool nuget:?package=Tetractic.CodeAnalysis.ExceptionAnalyzers&version=1.4.6
Exception Analyzers helps you check that exceptions are caught or documented in C#.
How It Works
An analyzer examines throw
statements, try
/catch
blocks, and the <exception>
elements in documentation comment XML for symbols referenced by your code to determine what exception types could escape your code. Diagnostics are reported for any of those exception types that do not appear in the <exception>
elements in the documentation comment XML for your code.
Example
void Demo1() => throw new NotSupportedException();
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Ex0100: 'Demo1()' may throw undocumented exception: NotSupportedException
/// <exception cref="NotSupportedException"/>
void Demo2() => throw new NotSupportedException(); // No diagnostic; exception is documented.
void Demo3() => Demo2();
// ~~~~~
// Ex0100: 'Demo3()' may throw undocumented exception: NotSupportedException
void Demo4(bool b)
{
try
{
if (b)
throw new NotSupportedException(); // No diagnostic; Exception is caught.
else
throw new Exception();
// ~~~~~~~~~~~~~~~~~~~~~~
// Ex0100: 'Demo4(bool)' may throw undocumented exception: Exception
}
catch (NotSupportedException)
{
throw;
// ~~~~~~
// Ex0100: 'Demo4(bool)' may throw undocumented exception: NotSupportedException
}
}
Configuration
.editorconfig
dotnet_ignored_exceptions
Provides a list of exception types that will be ignored by exception analysis.
Setting name: dotnet_ignored_exceptions
Value: A comma-separated list of fully-qualified type names.
Default value: System.NullReferenceException, System.StackOverflowException, System.Diagnostics.UnreachableException
dotnet_intransitive_exceptions
Provides a list of exception types that will be ignored by exception analysis when thrown by a referenced public or protected member. (The exception types will not be ignored when thrown via throw
or by a referenced private or internal member.) This is useful for exception types that generally indicate incorrect code when thrown. The conditions under which these exception types are thrown should be documented, but those conditions should be avoidable and avoided in correctly-written code.
For example, it should be possible to avoid providing unacceptable arguments that would cause an ArgumentException
to be thrown. ArgumentException
and its subtypes, in particular, are so pervasive that reporting a diagnostic for every method invocation that might throw one of them would be unhelpful.
Setting name: dotnet_intransitive_exceptions
Value: A comma-separated list of fully-qualified type names.
Default value: System.ArgumentException, System.IndexOutOfRangeException, System.InvalidCastException, System.InvalidOperationException, System.Collections.Generic.KeyNotFoundException
dotnet_intransitive_exceptions_private
Provides a list of exception types that will be ignored by exception analysis when thrown by a referenced private member.
Setting name: dotnet_intransitive_exceptions_private
Value: A comma-separated list of fully-qualified type names.
Default value: System.ArgumentException, System.IndexOutOfRangeException, System.InvalidCastException, System.Collections.Generic.KeyNotFoundException
dotnet_intransitive_exceptions_internal
Provides a list of exception types that will be ignored by exception analysis when thrown by a referenced internal member.
Setting name: dotnet_intransitive_exceptions_internal
Value: A comma-separated list of fully-qualified type names.
Default value: The value that was provided for dotnet_intransitive_exceptions_private
.
Exception Adjustments
An "exception adjustment" mechanism allows for tuning what exception types may be thrown by a particular member. Adjustments can be made applicable to a whole project or to a single member.
Project-wide adjustments are sourced from the "additional files" of a project that have a filename matching one of the following patterns:
- ExceptionAdjustments.txt
- ExceptionAdjustments.*.txt
Create a text file and then add an "additional file" to the project file:
<ItemGroup>
<AdditionalFiles Include="ExceptionAdjustments.txt" />
</ItemGroup>
Each line of an exception adjustments file is either empty, a comment (beginning with a #
), or an adjustment. Adjustment lines have the following syntax:
<memberId>[ <accessor>] (-/+)<exceptionTypeId>
<memberId>
is the ID of the member to which the exception type is being added (because it should be considered to potentially throw that exception type) or removed (because it should not).<accessor>
is the optional accessor of the member (ex. theget
orset
accessor of a property) to which the adjustment applies. If the accessor is omitted, the adjustment is applied to all accessors.-
or+
indicates removal or addition of the exception type, respectively.<exceptionTypeId>
is the ID of the exception type to add or remove.- The details of the ID format are found in the C# language specification.
Per-member adjustments are sourced from comments on the member:
// ExceptionAdjustment: M:System.Int32.ToString(System.String) -T:System.FormatException
string Demo(int x) => x.ToString("X4");
Exception adjustments are applied in order according to the following rules (in order of precedence):
- Project-wide adjustments are applied before per-member adjustments.
- Adjustments that omit the accessor are applied before adjustments that specify it.
- Removal adjustments are applied before addition adjustments.
Learn more about Target Frameworks and .NET Standard.
This package has no dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
1.4.6 | 271 | 10/28/2024 |
1.4.5 | 1,657 | 5/11/2024 |
1.4.4 | 1,025 | 3/7/2024 |
1.4.3 | 322 | 3/1/2024 |
1.4.2 | 941 | 12/1/2023 |
1.4.1 | 2,447 | 11/22/2022 |
1.4.0 | 524 | 10/8/2022 |
1.3.2 | 440 | 9/6/2022 |
1.3.1 | 1,895 | 5/28/2022 |
1.3.0 | 572 | 12/23/2021 |
1.2.2 | 336 | 10/22/2021 |
1.2.1 | 311 | 10/21/2021 |
1.2.0 | 347 | 10/19/2021 |
1.1.2 | 415 | 10/15/2021 |
1.1.1 | 377 | 10/13/2021 |
1.1.0 | 372 | 10/11/2021 |
1.0.1 | 501 | 10/9/2021 |