NetEvolve.Defaults 1.5.0

NetEvolve.Defaults

NetEvolve.Defaults is a comprehensive build automation and configuration package that establishes consistent development standards across all NetEvolve projects. It provides standardized configuration files, build properties, analyzer settings, and development guidelines that enforce code quality, consistency, and best practices throughout your project lifecycle.

Overview

This package encapsulates enterprise-grade configuration standards including:

• Centralized Build Configuration: Unified project settings and compilation options across multi-targeted projects
• Code Analysis & Quality Enforcement: Automated static analysis with Roslyn analyzers and code style enforcement
• Language & Compiler Settings: Modern C# language features with nullable reference types and implicit usings
• Continuous Integration Support: Automatic detection and optimization for CI/CD environments
• NuGet Security Auditing: Integrated vulnerability scanning for package dependencies
• Editor Configuration: Standardized coding styles and formatting rules (.editorconfig)
• Documentation Generation: Automatic XML documentation file generation for NuGet packages

Installation

Using the NuGet CLI

dotnet add package NetEvolve.Defaults

Manual Package Reference

Add the following to your project file (.csproj, .fsproj, or .vbproj):

<PackageReference Include="NetEvolve.Defaults" Version="x.x.x" PrivateAssets="all" />

The PrivateAssets="all" attribute ensures that the defaults package configuration is only applied to your project and not propagated to consumers of your package.

Project Configuration

NetEvolve.Defaults automatically configures your project based on its naming conventions and context. All settings can be customized by defining corresponding MSBuild properties in your project file or via the command line.

Project Classification

The build system automatically categorizes projects based on their names:

Test Projects (IsTestableProject)

Projects containing .Tests. in their name are automatically identified as testable projects. These projects receive specialized configurations:

• Specific analyzer rules are relaxed for testing purposes
• Code coverage reporting is excluded for test projects
• Documentation generation can be disabled
• Warnings related to testing are suppressed

Customization:

<PropertyGroup>
  <IsTestableProject>true</IsTestableProject>
</PropertyGroup>

Example Projects (IsXampleProject)

Projects containing .Xample or starting with Xample. are identified as example/demonstration projects with similar relaxed configurations as test projects.

Customization:

<PropertyGroup>
  <IsXampleProject>true</IsXampleProject>
</PropertyGroup>

Build & Compilation Settings

Language and Runtime Configuration

Example:

<PropertyGroup>
  <LangVersion>preview</LangVersion>
  <Nullable>enable</Nullable>
</PropertyGroup>

Code Analysis & Compilation

Example to customize warnings:

<PropertyGroup>
  <NoWarn>$(NoWarn);CA1810;CA1031</NoWarn>
</PropertyGroup>

Example to suppress specific warnings in test projects:

<ItemGroup>
  <CompilerVisibleProperty Include="IsTestableProject" />
</ItemGroup>

Build Performance

Continuous Integration

NetEvolve.Defaults automatically detects CI/CD environments and applies optimization settings:

Automatic CI Detection

The package detects execution in the following CI/CD platforms:

• GitHub Actions (GITHUB_ACTIONS)
• Azure DevOps / TFS (TF_BUILD)
• GitLab CI (GITLAB_CI)
• Jenkins (JENKINS_URL, BUILD_ID, BUILD_URL)
• TeamCity (TEAMCITY_VERSION)
• AppVeyor (APPVEYOR)
• Travis CI (TRAVIS)
• CircleCI (CIRCLECI)
• AWS CodeBuild (CODEBUILD_BUILD_ID, AWS_REGION)
• Google Cloud Build (BUILD_ID, PROJECT_ID)
• JetBrains Space (JB_SPACE_API_URL)
• General CI (CI)

CI-Specific Settings

When CI is detected, the following settings are automatically applied:

Manual Override:

<PropertyGroup>
  <IsContinuousIntegration>true</IsContinuousIntegration>
</PropertyGroup>

NuGet Package Generation

Package Information

For non-test projects built outside Visual Studio, the package is automatically generated during build:

Disable package generation:

<PropertyGroup>
  <GeneratePackageOnBuild>false</GeneratePackageOnBuild>
</PropertyGroup>

Version Information

Example:

<PropertyGroup>
  <Company>NetEvolve</Company>
  <CopyrightYearStart>2020</CopyrightYearStart>
</PropertyGroup>

Security & Vulnerability Management

NuGet Audit

NetEvolve.Defaults includes comprehensive NuGet vulnerability scanning:

Custom configuration:

<PropertyGroup>
  <NuGetAudit>true</NuGetAudit>
  <NuGetAuditMode>direct</NuGetAuditMode>
  <NuGetAuditLevel>high</NuGetAuditLevel>
</PropertyGroup>

Platform & Framework Support

Target Framework Configuration

Advanced Settings

Diagnostic Output

Example:

<PropertyGroup>
  <ErrorLog>custom-diagnostics.sarif</ErrorLog>
</PropertyGroup>

Preview Feature Support

NetEvolve.Defaults supports C# preview features:

<PropertyGroup>
  <LangVersion>preview</LangVersion>
</PropertyGroup>

Suppressed Warnings

Global Suppressions

The following warnings are globally suppressed as they conflict with modern C# practices:

• CA1810: Do not initialize static fields on type. (Initialization design pattern)
• CA1031: Do not catch general exception types. (Often necessary in middleware/handlers)

Test Project Suppressions

Test projects additionally suppress:

• CS8604: Possible null reference argument
• CA2007: Consider calling ConfigureAwait on awaitable
• CA1707: Identifiers should not contain underscores (xUnit naming)
• IDE1006: Naming style (test method naming)
• CA1822: Mark members as static (test utilities)
• And others for testing-specific patterns

Override suppressions:

<PropertyGroup>
  <NoWarn>$(NoWarn);CA1234</NoWarn>
</PropertyGroup>

Non-Error Warnings

The following warnings are always treated as warnings, never errors:

• CA5394: Do not use insecure randomness
• NU1701: Package compatibility issues
• CS0618: Obsolete members (sometimes necessary for compatibility)
• S1133: Deprecated code patterns
• NU1510: Package not directly referenced

Common Customization Scenarios

Creating a Public Library

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <IncludeSymbols>true</IncludeSymbols>
  <SymbolPackageFormat>snupkg</SymbolPackageFormat>
  <Company>YourCompany</Company>
  <Description>Your package description</Description>
</PropertyGroup>

Creating a Console Application

<PropertyGroup>
  <OutputType>Exe</OutputType>
  <IsTestableProject>false</IsTestableProject>
  <GenerateDocumentationFile>false</GenerateDocumentationFile>
</PropertyGroup>

Strict Quality Enforcement

<PropertyGroup>
  <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
  <CodeAnalysisTreatWarningsAsErrors>true</CodeAnalysisTreatWarningsAsErrors>
  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  <NuGetAudit>true</NuGetAudit>
  <NuGetAuditLevel>low</NuGetAuditLevel>
</PropertyGroup>

Relaxed Configuration (Development/Testing)

<PropertyGroup>
  <TreatWarningsAsErrors>false</TreatWarningsAsErrors>
  <CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
  <NuGetAudit>false</NuGetAudit>
</PropertyGroup>

EditorConfig Integration

NetEvolve.Defaults includes a comprehensive .editorconfig file that enforces:

• Code formatting standards (indentation, spacing, line lengths)
• Naming conventions (PascalCase for types, camelCase for locals)
• Code style rules (var usage, expression preferences)
• Roslyn analyzer configuration

The .editorconfig is automatically deployed to your build output and is applied across all supported IDEs and editors.

MSBuild Integration

All NetEvolve.Defaults settings are implemented as MSBuild properties and can be overridden at any level:

Override Priority (highest to lowest)

1. Command-line properties: dotnet build -p:PropertyName=Value
2. Project file (.csproj): <PropertyGroup> elements
3. Directory.Build.props: Shared project settings
4. NetEvolve.Defaults package properties

Example override via command line:

dotnet build -p:TreatWarningsAsErrors=false

Dependency Management

NetEvolve.Defaults requires:

• .NET 5.0 or higher for consumption as a package reference
• C# 9.0 or higher for projects using this package

No additional NuGet dependencies are introduced to your project.

Support & Troubleshooting

Disable Specific Features

Disable package information generation:

<PropertyGroup>
  <DisableSupportPackageInformation>true</DisableSupportPackageInformation>
</PropertyGroup>

Diagnostic Reports

Build diagnostic reports are generated as SARIF files (one per project, target framework, and configuration) for integration with analysis tools and IDE extensions.

Version History

Refer to the project's CHANGELOG for version-specific changes and compatibility information.

Contributing

We welcome contributions! Please ensure all code contributions:

• Follow the code style defined in .editorconfig
• Pass all code analysis checks
• Include comprehensive XML documentation
• Have appropriate test coverage