# Dotnet Dev

> Dotnet Dev is an Agent Skill for development published in the GitTools/GitVersion repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Expert guidance for .NET development in this repository. Use this skill for building, testing, debugging, and understanding project structure, coding conventions, dependency injection patterns, and testing practices.

- Skill name: `dotnet-dev`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/GitTools/GitVersion/blob/HEAD/.github/skills/dotnet-dev/SKILL.md
- Repository: GitTools/GitVersion (3,135 GitHub stars when collected)

## SKILL.md

# .NET Development Skills

Expert guidance for .NET development in this repository.

## Build & Test Commands

```bash
# Build the solution
dotnet build ./src/GitVersion.slnx

# Build a single project
dotnet build --project ./src/GitVersion.Core/GitVersion.Core.csproj

# Run all tests
dotnet test --solution ./src/GitVersion.slnx

# Run tests for a specific project
dotnet test --project ./src/GitVersion.Core.Tests/GitVersion.Core.Tests.csproj

# Run tests with specific framework
dotnet test --project ./src/GitVersion.Core.Tests/GitVersion.Core.Tests.csproj --framework net10.0

# Run specific test by filter
dotnet test --project ./src/GitVersion.Core.Tests/GitVersion.Core.Tests.csproj --filter "FullyQualifiedName~TestClassName"

# Format code
dotnet format ./src/GitVersion.slnx

# Verify formatting (CI-friendly)
dotnet format --verify-no-changes ./src/GitVersion.slnx
```

## Package Management

This repository uses **Central Package Management** via `Directory.Packages.props`.

### Adding/Updating Packages

```bash
# Add a package (version managed centrally)
dotnet add ./src/ProjectName/ProjectName.csproj package PackageName

# Update central package version in src/Directory.Packages.props
```

**Important**: Always update versions in `src/Directory.Packages.props`, not in individual `.csproj` files.

### Directory.Packages.props Structure

```xml

<Project>
    <PropertyGroup>
        <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
    </PropertyGroup>
    <ItemGroup>
        <PackageVersion Include="PackageName" Version="1.0.0" />
    </ItemGroup>
</Project>
```

## Project Structure

- `src/` - Main solution with production code and tests
- `new-cli/` - New CLI implementation (separate solution)
- `build/` - Build automation (Cake-based)
- `docs/` - Documentation

### Key Projects

| Project                    | Purpose                               |
|----------------------------|---------------------------------------|
| `GitVersion.Core`          | Core version calculation logic        |
| `GitVersion.App`           | CLI application                       |
| `GitVersion.Configuration` | Configuration file handling           |
| `GitVersion.Output`        | Output formatters (JSON, BuildServer) |
| `GitVersion.BuildAgents`   | CI/CD platform integrations           |
| `GitVersion.MsBuild`       | MSBuild task integration              |
| `GitVersion.LibGit2Sharp`  | Git repository abstraction            |

## Coding Conventions

### Primary Constructors

Prefer primary constructors with readonly field assignments:

```csharp
internal class BuildAgentResolver(IEnumerable<IBuildAgent> buildAgents, ILogger<BuildAgentResolver> logger) : IBuildAgentResolver
{
    private readonly IEnumerable<IBuildAgent> buildAgents = buildAgents.NotNull();
    private readonly ILogger<BuildAgentResolver> logger = logger.NotNull();

    public IBuildAgent? Resolve()
    {
        // Use this.buildAgents and this.logger
    }
}
```

### Dependency Injection

Use constructor injection with `ILogger<T>` for logging:

```csharp
public class MyService
{
    private readonly ILogger<MyService> logger;

    public MyService(ILogger<MyService> logger)
    {
        this.logger = logger;
    }
}
```

### Logging

Use Microsoft.Extensions.Logging with Serilog:

```csharp
// Information level
this.logger.LogInformation("Processing {BranchName}", branch.Name);

// Warning level
this.logger.LogWarning("Configuration not found, using defaults");

// Error level
this.logger.LogError(ex, "Failed to calculate version");

// Debug level (verbose)
this.logger.LogDebug("Cache hit for {CacheKey}", key);
```

### Nullable Reference Types

All projects use nullable reference types. Handle nullability explicitly:

```csharp
public string? OptionalProperty { get; set; }

public string RequiredProperty { get; set; } = string.Empty;
```

### File-Scoped Namespaces

Use file-scoped namespaces:

```csharp
namespace GitVersion;

public class MyClass
{
    // ...
}
```

## Testing

### Test Project Naming

- Test projects mirror source projects: `GitVersion.Core` → `GitVersion.Core.Tests`

### Test Frameworks

- **NUnit** - Primary test framework
- **NSubstitute** - Mocking framework
- **Shouldly** - Assertion library

### Test Patterns

```csharp
[TestFixture]
public class MyServiceTests
{
    [Test]
    public void MethodName_Scenario_ExpectedResult()
    {
        // Arrange
        var service = new MyService();

        // Act
        var result = service.DoSomething();

        // Assert
        result.ShouldBe(expected);
    }

    [TestCase("input1", "expected1")]
    [TestCase("input2", "expected2")]
    public void MethodName_WithParameters_ReturnsExpected(string input, string expected)
    {
        var result = service.Process(input);
        result.ShouldBe(expected);
    }
}
```

## Configuration Files

### Supported Names

- `GitVersion.yml`
- `GitVersion.yaml`
- `.GitVersion.yml`
- `.GitVersion.yaml`

### Schema Location

JSON schemas are in `schemas/` directory for validation.

## Build Agents

Build agent integrations write environment variables with `GitVersion_` prefix:

```csharp
// Example: GitHub Actions
Environment.SetEnvironmentVariable($"GitVersion_{name}", value);
```

## Common Tasks

### Running the CLI Locally

```bash
dotnet run --project src/GitVersion.App
```

### Debugging Tests

```bash
# Run with detailed output
dotnet test --project ./src/GitVersion.Core.Tests/GitVersion.Core.Tests.csproj -v detailed

# Run specific test
dotnet test --filter "FullyQualifiedName=GitVersion.Core.Tests.MyTest"
```

### Checking for Errors

```bash
# Build with warnings as errors
dotnet build ./src/GitVersion.slnx -warnaserror
```

## Public API Management

This repository
uses [Microsoft.CodeAnalysis.PublicApiAnalyzers](https://github.com/dotnet/roslyn-analyzers/blob/main/src/PublicApiAnalyzers/PublicApiAnalyzers.Help.md)
to track public API surface.

### Rules

- **`PublicAPI.Unshipped.txt`**: All new or modified public APIs go here
- **`PublicAPI.Shipped.txt`**: Only deletions are allowed; never add or modify entries directly

### Workflow

1. When adding new public APIs, they automatically get flagged and should be added to `PublicAPI.Unshipped.txt`
2. When modifying existing APIs, move the old entry from `PublicAPI.Shipped.txt` to `PublicAPI.Unshipped.txt` (marked as
   removed) and add the new signature to `PublicAPI.Unshipped.txt`
3. Only remove entries from `PublicAPI.Shipped.txt` when an API is being deleted
4. During release, unshipped APIs get moved to shipped via the `mark-shipped.ps1` script

---

Source: https://www.openparable.com/skill/development/dotnet-dev (OpenParable). Cite the canonical URL above.
