Analyzer Rules

This topic is incomplete and is currently being improved.
Also, this topic relates to the Vogen project and not directly related to users of the Vogen package.

The Vogen analyzers enforce certain rules around value objects.

These analyzers can be found in the tests/AnalyzerTests/AnalyzerTests.csproj project.

• The AnalyzerTests project uses the CSharpAnalyzerVerifier class to help run the tests.

The CSharpAnalyzerVerifier class provides a few extension methods to support testing analyzers:

• Diagnostic(): This method returns a DiagnosticResult which is used to create a diagnostic result that the tests can use.
• VerifyAnalyzerAsync(string source, params DiagnosticResult[] expected): This method takes the source code to test and an array of expected diagnostics. It then runs the analyzer and compares the actual diagnostics with the expected diagnostics.

You can use these methods to test your own analyzers.

Example

// Source Code to test the analyzer
          string sourceCode = @"
          using System;
          
          namespace MyNamespace
          {
              public struct MyValueObject
              {
                  public int Value;
          
                  public MyValueObject(int value)
                  {
                      Value = value;
                  }
              }
          }
          ";
          
          // Expected diagnostic result
          DiagnosticResult[] expectedDiagnostics = new DiagnosticResult[]
          {
              DiagnosticResult.CompilerError("VO1003", "Value objects should have a private constructor.").WithLocation(5, 18).WithSeverity(DiagnosticSeverity.Error),
          };
          
          // Run the test
          await CSharpAnalyzerVerifier<DoNotUseNewAnalyzerTests>.VerifyAnalyzerAsync(sourceCode, expectedDiagnostics);
          

Testing the Analyzer

This is how the Vogen analyzers are tested:

• The tests are in the tests/AnalyzerTests project. This project uses the CSharpAnalyzerVerifier class to help run the tests.

The CSharpAnalyzerVerifier class provides a few extension methods to support testing analyzers:

• Diagnostic(): This method returns a DiagnosticResult which is used to create a diagnostic result that the tests can use.
• VerifyAnalyzerAsync(string source, params DiagnosticResult[] expected): This method takes the source code to test and an array of expected diagnostics. It then runs the analyzer and compares the actual diagnostics with the expected diagnostics.

You can use these methods to test your own analyzers.

Running the Tests

The tests are run using the test.ps1 script. This script builds and packs Vogen using a ridiculously high version number and then restores the tests NuGet dependencies to use that package. This will allow you run and debug debug these tests in VS, but to use any new code changes in the analyzer, you need to rerun this script to force a refresh of the package.

Top-Level Directory Explanations

samples/ - This directory contains example projects that demonstrate the usage of the Vogen library. Each subdirectory represents a different example, and contains the necessary files and configurations for that example.

src/ - This directory contains the source code for the project. It includes the Vogen library itself, as well as any shared types and code fixers.

src/obj/ - This directory contains object files generated during the compilation process.

src/Vogen/ - This subdirectory contains the core Vogen library code. It includes subdirectories for diagnostics, extensions, generators, properties, rules, suppressors, templates, and binaries and object files.

tests/ - This directory contains unit tests and benchmarks for the project. It includes subdirectories for analyzer tests, consumer tests, snapshot tests, and Vogen benchmarks.

tests/AnalyzerTests/ - This subdirectory contains unit tests for the analyzer component of the Vogen library.

tests/ConsumerTests/ - This subdirectory contains unit tests for the consumer-side components of the Vogen library.

tests/SnapshotTests/ - This subdirectory contains snapshot tests, which test the output of the code generation and serialization components of the Vogen library.

tests/Vogen.Benchmarks/ - This subdirectory contains benchmarks for the performance of the Vogen library.