|
| 1 | +# .NET Repository |
| 2 | + |
| 3 | +**Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.** |
| 4 | + |
| 5 | +## Working Effectively |
| 6 | + |
| 7 | +### Essential Build Commands |
| 8 | +- **Restore dependencies**: `dotnet restore` |
| 9 | + |
| 10 | +- **Build the entire solution**: `dotnet build` |
| 11 | + |
| 12 | +- **Run tests**: `dnx --yes retest` |
| 13 | + - Runs all unit tests across the solution |
| 14 | + - If tests fail due to Azure Storage, run the following commands and retry: `npm install azurite` and `npx azurite &` |
| 15 | + |
| 16 | +### Build Validation and CI Requirements |
| 17 | +- **Always run before committing**: |
| 18 | + * `dnx --yes retest` |
| 19 | + * `dotnet format whitespace -v:diag --exclude ~/.nuget` |
| 20 | + * `dotnet format style -v:diag --exclude ~/.nuget` |
| 21 | + |
| 22 | +### Project Structure and Navigation |
| 23 | + |
| 24 | +| Directory | Description | |
| 25 | +|-----------|-------------| |
| 26 | +| `src/` | Contains the repo source code. | |
| 27 | +| `bin/` | Contains built packages (if any) | |
| 28 | + |
| 29 | +### Code Style and Formatting |
| 30 | + |
| 31 | +#### EditorConfig Rules |
| 32 | +The repository uses `.editorconfig` at the repo root for consistent code style. |
| 33 | + |
| 34 | +- **Indentation**: 4 spaces for C# files, 2 spaces for XML/YAML/JSON |
| 35 | +- **Line endings**: LF (Unix-style) |
| 36 | +- **Sort using directives**: System.* namespaces first (`dotnet_sort_system_directives_first = true`) |
| 37 | +- **Type references**: Prefer language keywords over framework type names (`int` vs `Int32`) |
| 38 | +- **Modern C# features**: Use object/collection initializers, coalesce expressions when possible, use var when the type is apparent from the right-hand side of the assignment |
| 39 | +- **Visibility modifiers**: only explicitly specify visibility when different from the default (e.g. `public` for classes, no `internal` for classes or `private` for fields, etc.) |
| 40 | + |
| 41 | +#### Formatting Validation |
| 42 | +- CI enforces formatting with `dotnet format whitespace` and `dotnet format style` |
| 43 | +- Run locally: `dotnet format whitespace --verify-no-changes -v:diag --exclude ~/.nuget` |
| 44 | +- Fix formatting: `dotnet format` (without `--verify-no-changes`) |
| 45 | + |
| 46 | +### Testing Practices |
| 47 | + |
| 48 | +#### Test Framework |
| 49 | +- **xUnit** for all unit and integration tests |
| 50 | +- **Moq** for mocking dependencies |
| 51 | +- Located in `src/*.Tests/` |
| 52 | + |
| 53 | +#### Test Attributes |
| 54 | +Custom xUnit attributes are sometimes used for conditional test execution: |
| 55 | +- `[SecretsFact("XAI_API_KEY")]` - Skips test if required secrets are missing from user secrets or environment variables |
| 56 | +- `[LocalFact("SECRET")]` - Runs only locally (skips in CI), requires specified secrets |
| 57 | +- `[CIFact]` - Runs only in CI environment |
| 58 | + |
| 59 | +### Dependency Management |
| 60 | + |
| 61 | +#### Adding Dependencies |
| 62 | +- Add to appropriate `.csproj` file |
| 63 | +- Run `dotnet restore` to update dependencies |
| 64 | +- Ensure version consistency across projects where applicable |
| 65 | + |
| 66 | +#### CI/CD Pipeline |
| 67 | +- **Build workflow**: `.github/workflows/build.yml` - runs on PR and push to main/rel/feature branches |
| 68 | +- **Publish workflow**: Publishes to Sleet feed when `SLEET_CONNECTION` secret is available |
| 69 | +- **OS matrix**: Configured in `.github/workflows/os-matrix.json` (defaults to ubuntu-latest) |
| 70 | + |
| 71 | +### Special Files and Tools |
| 72 | + |
| 73 | +#### dnx Command |
| 74 | +- **Purpose**: built-in tool for running arbitrary dotnet tools that are published on nuget.org. `--yes` auto-confirms install before run. |
| 75 | +- **Example**: `dnx --yes retest` - runs tests with automatic retry on transient failures (retest being a tool package published at https://www.nuget.org/packages/retest) |
| 76 | +- **In CI**: `dnx --yes retest -- --no-build` (skips build, runs tests only) |
| 77 | + |
| 78 | +#### Directory.Build.rsp |
| 79 | +- MSBuild response file with default build arguments |
| 80 | +- `-nr:false` - disables node reuse |
| 81 | +- `-m:1` - single-threaded build (for stability) |
| 82 | +- `-v:m` - minimal verbosity |
| 83 | + |
| 84 | +#### Code Quality |
| 85 | +- All PRs must pass format validation |
| 86 | +- Tests must pass on all target frameworks |
| 87 | +- Follow existing patterns and conventions in the codebase |
| 88 | + |
| 89 | +## Documenting Work |
| 90 | + |
| 91 | +Project implemention details, design and key decisions should be documented in a top-level AGENTS.md file at the repo root. |
| 92 | +Keep this file updated whenever you make change significant changes for future reference. |
| 93 | + |
| 94 | +User-facing features and APIs should be documented to highlight (not extensively, as an overview) key project features and capabilities, in the readme.md file at the repo root. |
0 commit comments