diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 23738d65..1215f2a7 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -35,6 +35,13 @@ When a rule in this analyzer is equivalent to or similar to a rule in another an Do NOT add equivalence/similarity notes directly to individual rule documentation files (e.g., `docs/Rules/MA0158.md`). +## Maintaining Meziantou.Analyzer.Annotations + +When you change any file under `src/Meziantou.Analyzer.Annotations`, you MUST: + +- Update [`src/Meziantou.Analyzer.Annotations/README.md`](/src/Meziantou.Analyzer.Annotations/README.md) if the package behavior, exposed attributes, or usage guidance changed. +- Bump `` in [`src/Meziantou.Analyzer.Annotations/Meziantou.Analyzer.Annotations.csproj`](/src/Meziantou.Analyzer.Annotations/Meziantou.Analyzer.Annotations.csproj). + ## Implementing Roslyn analyzers - When creating a new rule, create a new constant in `src/Meziantou.Analyzer/RuleIdentifiers.cs` using the name of the new rule. The value must be unique and incremented from the last rule. diff --git a/docs/Rules/MA0003.md b/docs/Rules/MA0003.md index 17a66074..f909df8d 100644 --- a/docs/Rules/MA0003.md +++ b/docs/Rules/MA0003.md @@ -32,8 +32,8 @@ MA0003.excluded_methods = M:A.B(System.Int32) | M:C.D() MA0003.excluded_methods_regex = Sample.*Test ```` -You can annotate a parameter with `Meziantou.Analyzer.Annotations.RequireNamedArgumentAttribute`. This attribute is available using the -`Meziantou.Analyzer.Annotations` NuGet package. +You can annotate a parameter with `Meziantou.Analyzer.Annotations.RequireNamedArgumentAttribute`. +To use this attribute, add the `Meziantou.Analyzer.Annotations` NuGet package (or copy the attribute source into your project). See [Meziantou.Analyzer.Annotations README](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer.Annotations/README.md). ```c# Test("test"); // report a diagnostic as the parameter is not named diff --git a/docs/Rules/MA0011.md b/docs/Rules/MA0011.md index 44b18bf3..4e75ab2a 100644 --- a/docs/Rules/MA0011.md +++ b/docs/Rules/MA0011.md @@ -39,4 +39,4 @@ MA0011.exclude_tostring_methods=true MA0011.consider_nullable_types=true ```` -You can also annotate a type with `[Meziantou.Analyzer.Annotations.CultureInsensitiveTypeAttribute]` to disable the rule for this type. See [CultureInsensitiveTypeAttribute](../CultureInsensitiveTypeAttribute.md) for more details. +You can also annotate a type with `[Meziantou.Analyzer.Annotations.CultureInsensitiveTypeAttribute]` to disable the rule for this type. See [CultureInsensitiveTypeAttribute](../CultureInsensitiveTypeAttribute.md) for details and [Meziantou.Analyzer.Annotations README](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer.Annotations/README.md) for installation options. diff --git a/docs/Rules/MA0042.md b/docs/Rules/MA0042.md index e8298a98..180c2c23 100644 --- a/docs/Rules/MA0042.md +++ b/docs/Rules/MA0042.md @@ -111,7 +111,8 @@ MA0042.enable_sqlite_special_cases = true MA0042.enable_db_special_cases = true ```` -You can also exclude specific method/property diagnostics for MA0042/MA0045 using assembly-level annotations: +You can also exclude specific method/property diagnostics for MA0042/MA0045 using assembly-level annotations. +To use `Meziantou.Analyzer.Annotations.ExcludeFromBlockingCallAnalysisAttribute`, add the `Meziantou.Analyzer.Annotations` NuGet package (or copy the attribute source into your project). See [Meziantou.Analyzer.Annotations README](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer.Annotations/README.md). ```csharp [assembly: Meziantou.Analyzer.Annotations.ExcludeFromBlockingCallAnalysisAttribute("M:System.Threading.Tasks.Task.Wait")] diff --git a/docs/Rules/MA0045.md b/docs/Rules/MA0045.md index 339fa017..599ab43e 100644 --- a/docs/Rules/MA0045.md +++ b/docs/Rules/MA0045.md @@ -54,7 +54,8 @@ MA0042.enable_sqlite_special_cases = true MA0042.enable_db_special_cases = true ```` -You can also exclude specific method/property diagnostics for MA0042/MA0045 using assembly-level annotations: +You can also exclude specific method/property diagnostics for MA0042/MA0045 using assembly-level annotations. +To use `Meziantou.Analyzer.Annotations.ExcludeFromBlockingCallAnalysisAttribute`, add the `Meziantou.Analyzer.Annotations` NuGet package (or copy the attribute source into your project). See [Meziantou.Analyzer.Annotations README](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer.Annotations/README.md). ```csharp [assembly: Meziantou.Analyzer.Annotations.ExcludeFromBlockingCallAnalysisAttribute("M:System.Threading.Tasks.Task.Wait")] diff --git a/docs/Rules/MA0075.md b/docs/Rules/MA0075.md index 5cbe7ec8..ba3e7233 100644 --- a/docs/Rules/MA0075.md +++ b/docs/Rules/MA0075.md @@ -45,4 +45,4 @@ MA0075.exclude_tostring_methods=true MA0075.consider_nullable_types=true ```` -You can also annotate a type with `[Meziantou.Analyzer.Annotations.CultureInsensitiveTypeAttribute]` to disable the rule for this type. See [CultureInsensitiveTypeAttribute](../CultureInsensitiveTypeAttribute.md) for more details. +You can also annotate a type with `[Meziantou.Analyzer.Annotations.CultureInsensitiveTypeAttribute]` to disable the rule for this type. See [CultureInsensitiveTypeAttribute](../CultureInsensitiveTypeAttribute.md) for details and [Meziantou.Analyzer.Annotations README](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer.Annotations/README.md) for installation options. diff --git a/docs/Rules/MA0076.md b/docs/Rules/MA0076.md index bc57ee1e..e7f2a915 100644 --- a/docs/Rules/MA0076.md +++ b/docs/Rules/MA0076.md @@ -21,4 +21,4 @@ MA0076.exclude_tostring_methods=true MA0076.consider_nullable_types=true ```` -You can also annotate a type with `[Meziantou.Analyzer.Annotations.CultureInsensitiveTypeAttribute]` to disable the rule for this type. See [CultureInsensitiveTypeAttribute](../CultureInsensitiveTypeAttribute.md) for more details. +You can also annotate a type with `[Meziantou.Analyzer.Annotations.CultureInsensitiveTypeAttribute]` to disable the rule for this type. See [CultureInsensitiveTypeAttribute](../CultureInsensitiveTypeAttribute.md) for details and [Meziantou.Analyzer.Annotations README](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer.Annotations/README.md) for installation options. diff --git a/docs/Rules/MA0124.md b/docs/Rules/MA0124.md index 47354261..3f554829 100644 --- a/docs/Rules/MA0124.md +++ b/docs/Rules/MA0124.md @@ -35,6 +35,7 @@ Then, you need to add the file to the `AdditionalFiles` collection in the `cspro ```` You can also configure the allowed types by using an assembly attribute. These attributes are applied only for the current assembly. The rule does not consider attributes defined in referenced assemblies. +To use `Meziantou.Analyzer.Annotations.StructuredLogFieldAttribute`, add the `Meziantou.Analyzer.Annotations` NuGet package (or copy the attribute source into your project). See [Meziantou.Analyzer.Annotations README](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer.Annotations/README.md). ````c# // Requires the Meziantou.Analyzer.Annotations package diff --git a/docs/Rules/MA0139.md b/docs/Rules/MA0139.md index 2cbf7e7e..52128c63 100644 --- a/docs/Rules/MA0139.md +++ b/docs/Rules/MA0139.md @@ -35,6 +35,7 @@ Then, you need to add the file to the `AdditionalFiles` collection in the `cspro ```` You can also configure the allowed types by using an assembly attribute. These attributes are applied only for the current assembly. The rule does not consider attributes defined in referenced assemblies. +To use `Meziantou.Analyzer.Annotations.StructuredLogFieldAttribute`, add the `Meziantou.Analyzer.Annotations` NuGet package (or copy the attribute source into your project). See [Meziantou.Analyzer.Annotations README](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer.Annotations/README.md). ````c# // Requires the Meziantou.Analyzer.Annotations package diff --git a/docs/Rules/MA0185.md b/docs/Rules/MA0185.md index 4fb10f1c..21209516 100644 --- a/docs/Rules/MA0185.md +++ b/docs/Rules/MA0185.md @@ -30,6 +30,8 @@ The analyzer detects when all interpolated values are culture-invariant, such as - Boolean values - and other culture-insensitive types +You can annotate custom types with `[Meziantou.Analyzer.Annotations.CultureInsensitiveTypeAttribute]` to mark them as culture-insensitive and make additional `string.Create(CultureInfo.InvariantCulture, ...)` usages eligible for simplification. See [CultureInsensitiveTypeAttribute](../CultureInsensitiveTypeAttribute.md) for details and [Meziantou.Analyzer.Annotations README](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer.Annotations/README.md) for installation options. + The analyzer will NOT suggest simplification when: - Any parameter is culture-sensitive (e.g., `double`, `DateTime` with culture-sensitive format) - The culture is not `CultureInfo.InvariantCulture` diff --git a/src/Meziantou.Analyzer.Annotations/Meziantou.Analyzer.Annotations.csproj b/src/Meziantou.Analyzer.Annotations/Meziantou.Analyzer.Annotations.csproj index 133ea23d..4922212f 100644 --- a/src/Meziantou.Analyzer.Annotations/Meziantou.Analyzer.Annotations.csproj +++ b/src/Meziantou.Analyzer.Annotations/Meziantou.Analyzer.Annotations.csproj @@ -2,7 +2,7 @@ netstandard2.0 - 1.3.0 + 1.3.1 Annotations to configure Meziantou.Analyzer Meziantou.Analyzer, analyzers True diff --git a/src/Meziantou.Analyzer.Annotations/README.md b/src/Meziantou.Analyzer.Annotations/README.md index 140d2724..cfdc9ddf 100644 --- a/src/Meziantou.Analyzer.Annotations/README.md +++ b/src/Meziantou.Analyzer.Annotations/README.md @@ -1,9 +1,28 @@ +# Meziantou.Analyzer.Annotations + `Meziantou.Analyzer.Annotations` enables you to configure certain analyzer rules by adding annotations directly to your code. +`Meziantou.Analyzer.Annotations` is a separate dependency from `Meziantou.Analyzer`. If you want to use these attributes in your code, add an explicit package reference: + +```bash +dotnet add package Meziantou.Analyzer.Annotations +``` + +You can also copy the attribute source files into your project as long as the namespace and type names match. The copied types can be `public` or `internal`. + By default, all usages of attributes from `Meziantou.Analyzer.Annotations` are removed from the compiled assembly metadata. This means your binaries will not reference the `Meziantou.Analyzer.Annotations.dll` assembly. If you want to keep these attributes in the metadata (for example, for reflection or tooling purposes), define the `MEZIANTOU_ANALYZER_ANNOTATIONS` conditional compilation symbol in your project settings. +## Available attributes + +| Attribute | Purpose | Related rules | +| --- | --- | --- | +| `CultureInsensitiveTypeAttribute` | Marks a type (or a specific format) as culture-insensitive. | [MA0011](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0011.md), [MA0075](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0075.md), [MA0076](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0076.md), [MA0185](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0185.md) | +| `ExcludeFromBlockingCallAnalysisAttribute` | Excludes specific methods/properties from blocking-call diagnostics. | [MA0042](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0042.md), [MA0045](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0045.md) | +| `RequireNamedArgumentAttribute` | Requires named arguments for decorated parameters. | [MA0003](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0003.md) | +| `StructuredLogFieldAttribute` | Declares allowed types for named log properties in an assembly. | [MA0124](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0124.md), [MA0139](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0139.md) | + ## ExcludeFromBlockingCallAnalysisAttribute Use `ExcludeFromBlockingCallAnalysisAttribute` to exclude specific MA0042/MA0045 method/property diagnostics at the assembly level.