```bash
# dotnet-solution-navigation
Teaches agents to orient in .NET solutions: finding entry points, parsing solution files, traversing project dependencies, locating configuration files, and recognizing common solution layouts. Each subsection includes discovery commands/heuristics and example output.
## Scope
- Entry point discovery (Program.cs, top-level statements, worker services)
- Solution file parsing (.sln, .slnx)
- Project dependency graph traversal
- Configuration file location (appsettings.json, launchSettings.json)
## Out of scope
- Project file structure and modification -- see [skill:dotnet-csproj-reading]
- Project organization decisions and SDK selection -- see [skill:dotnet-project-structure]
- Test framework configuration and test type decisions -- see [skill:dotnet-testing-strategy]
## Prerequisites
.NET 8.0+ SDK. `dotnet` CLI available on PATH. Familiarity with SDK-style projects.
Cross-references: [skill:dotnet-project-structure] for project organization guidance, [skill:dotnet-csproj-reading] for reading and modifying .csproj files found during navigation, [skill:dotnet-testing-strategy] for test project identification and test type decisions.
---
## Subsection 1: Entry Point Discovery
.NET applications can start from several patterns. Do not assume every app has a traditional `Program.cs` with a `Main` method.
### Pattern 1: Traditional Program.cs with Main Method
Used in older projects, worker services, and when explicit control over hosting is needed.
**Discovery command:**
```bash
# Find Program.cs files containing a Main method
grep -rn "static.*void Main\|static.*Task Main\|static.*async.*Main" --include="*.cs" .
```bash
**Example output:**
```text
src/MyApp.Worker/Program.cs:5: public static async Task Main(string[] args)
src/MyApp.Console/Program.cs:3: static void Main(string[] args)
```csharp
### Pattern 2: Top-Level Statements (C# 9+)
Modern .NET projects (templates since .NET 6) use top-level statements -- the file contains no class or Main method, just executable code.
**Discovery command:**
```bash
# Find Program.cs files that do NOT contain class/namespace declarations
# (top-level statements have no enclosing class)
for f in $(find . -name "Program.cs" -not -path "*/obj/*" -not -path "*/bin/*"); do
if ! grep -Eq '^[[:space:]]*(class|namespace)[[:space:]]' "$f" 2>/dev/null; then
echo "Top-level: $f"
fi
done
```text
**Example output:**
```text
Top-level: ./src/MyApp.Api/Program.cs
Top-level: ./src/MyApp.Web/Program.cs
```csharp
**Typical content of a top-level Program.cs:**
```csharp
// No namespace, no class, no Main -- this IS the entry point
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
var app = builder.Build();
app.MapControllers();
app.Run();
```text
### Pattern 3: Worker Services and Background Hosts
Worker services use `Host.CreateDefaultBuilder` or `Host.CreateApplicationBuilder` without a web server. They appear as `Exe` output type with `Microsoft.NET.Sdk.Worker` SDK.
**Discovery command:**
```bash
# Find worker service projects by SDK type
grep -rn 'Sdk="Microsoft.NET.Sdk.Worker"' --include="*.csproj" .
# Or find IHostedService/BackgroundService implementations
grep -rn "BackgroundService\|IHostedService" --include="*.cs" . | grep -v "obj/" | grep -v "bin/"
```csharp
**Example output:**
```text
src/MyApp.Worker/MyApp.Worker.csproj:1:<Project Sdk="Microsoft.NET.Sdk.Worker">
src/MyApp.Worker/Services/OrderProcessor.cs:8:public class OrderProcessor : BackgroundService
src/MyApp.Worker/Services/EmailSender.cs:5:public class EmailSender : IHostedService
```csharp
### Pattern 4: Test Projects
Test projects are entry points for `dotnet test`. They may not have a `Program.cs` at all -- the test runner provides the entry point.
**Discovery command:**
```bash
# Find test projects by IsTestProject property or test SDK references
grep -rn "<IsTestProject>true</IsTestProject>" --include="*.csproj" .
grep -rn "Microsoft.NET.Test.Sdk\|xunit\|NUnit\|MSTest" --include="*.csproj" . | grep -v "obj/" # Matches both xunit.v3 and legacy xunit
```bash
**Example output:**
```text
tests/MyApp.Api.Tests/MyApp.Api.Tests.csproj:5: <IsTestProject>true</IsTestProject>
tests/MyApp.Core.Tests/MyApp.Core.Tests.csproj:8: <PackageReference Include="xunit.v3" />
```csharp
### Summary Heuristic
When orienting in a new .NET solution, run these commands in sequence:
```bash
# 1. Find all .csproj files
find . -name "*.csproj" -not -path "*/obj/*" | sort
# 2. Identify output types (Exe = app entry point, Library = dependency)
grep -rn "<OutputType>" --include="*.csproj" .
# 3. Find all Program.cs files
find . -name "Program.cs" -not -path "*/obj/*" -not -path "*/bin/*"
# 4. Identify test projects
grep -rn "<IsTestProject>true" --include="*.csproj" .
```csharp
---
## Subsection 2: Solution File Formats
.NET solutions use `.sln` (text-based, legacy format) or `.slnx` (XML-based, .NET 9+ preview). Both files list projects and their relationships.
### .sln Format
The traditional solution format is a text file with a custom syntax (not XML).
**Discovery and parsing commands:**
```bash
# Find solution files
find . -name "*.sln" -maxdepth 2
# List all projects in a solution using dotnet CLI
dotnet sln list
# Or specify the solution file explicitly:
dotnet sln MyApp.sln list
```text
**Example output of `dotnet sln list`:**
```text
Project(s)
----------
src/MyApp.Api/MyApp.Api.csproj
src/MyApp.Core/MyApp.Core.csproj
src/MyApp.Infrastructure/MyApp.Infrastructure.csproj
tests/MyApp.Api.Tests/MyApp.Api.Tests.csproj
tests/MyApp.Core.Tests/MyApp.Core.Tests.csproj
```csharp
**Reading the .sln file directly** (useful when `dotnet sln list` is not available):
```bash
# Extract project entries from .sln file
grep "^Project(" MyApp.sln
```bash
**Example output:**
```text
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MyApp.Api", "src\MyApp.Api\MyApp.Api.csproj", "{A1B2C3D4-E5F6-7890-ABCD-EF1234567890}"
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MyApp.Core", "src\MyApp.Core\MyApp.Core.csproj", "{B2C3D4E5-F6A7-8901-BCDE-F12345678901}"
```csharp
The GUID `{FAE04EC0-...}` identifies C# projects. The second value is the relative path to the `.csproj` file.
### .slnx Format (.NET 9+)
The `.slnx` format is an XML-based solution file introduced as a preview feature in .NET 9.
**Discovery and parsing commands:**
```bash
# Find .slnx files
find . -name "*.slnx" -maxdepth 2
# dotnet sln commands work with .slnx files too
dotnet sln MyApp.slnx list
```bash
**Example .slnx content:**
```xml
<Solution>
<Folder Name="/src/">
<Project Path="src/MyApp.Api/MyApp.Api.csproj" />
<Project Path="src/MyApp.Core/MyApp.Core.csproj" />
</Folder>
<Folder Name="/tests/">
<Project Path="tests/MyApp.Api.Tests/MyApp.Api.Tests.csproj" />
</Folder>
</Solution>
```csharp
**Key differences from .sln:**
| Feature | .sln | .slnx |
|---------|------|-------|
| Format | Custom text | XML |
| Readability | Low (GUIDs, custom syntax) | High (clean XML) |
| Availability | All .NET versions | .NET 9+ preview |
| Tooling | Full support | Partial (growing) |
| Solution folders | Nested GUID references | `<Folder>` elements |
### When No Solution File Exists
Some repositories use individual `.csproj` files without a `.sln`. Build and run from project directories:
```bash
# If no .sln exists, find all .csproj files and build individually
find . -name "*.csproj" -not -path "*/obj/*" | sort
dotnet build src/MyApp.Api/MyApp.Api.csproj
```bash
---
## Subsection 3: Project Dependency Traversal
Understanding `ProjectReference` chains is critical for determining build order, finding shared code, and identifying the impact of changes.
### Discovery Commands
```bash
# Find all ProjectReference entries across the solution
grep -rn "<ProjectReference" --include="*.csproj" . | grep -v "obj/"
```bash
**Example output:**
```text
src/MyApp.Api/MyApp.Api.csproj:12: <ProjectReference Include="../MyApp.Core/MyApp.Core.csproj" />
src/MyApp.Api/MyApp.Api.csproj:13: <ProjectReference Include="../MyApp.Infrastructure/MyApp.Infrastructure.csproj" />
src/MyApp.Infrastructure/MyApp.Infrastructure.csproj:10: <ProjectReference Include="../MyApp.Core/MyApp.Core.csproj" />
tests/MyApp.Api.Tests/MyApp.Api.Tests.csproj:14: <ProjectReference Include="../../src/MyApp.Api/MyApp.Api.csproj" />
```csharp
### Building a Dependency Graph
From the above output, the dependency graph is:
```text
MyApp.Api.Tests
-> MyApp.Api
-> MyApp.Core
-> MyApp.Infrastructure
-> MyApp.Core
```text
**Automated traversal using `dotnet list reference`:**
```bash
# List direct references for a specific project
dotnet list src/MyApp.Api/MyApp.Api.csproj reference
```bash
**Example output:**
```text
Project reference(s)
--------------------
../MyApp.Core/MyApp.Core.csproj
../MyApp.Infrastructure/MyApp.Infrastructure.csproj
```csharp
**Full transitive dependency analysis:**
```bash
# Build the full dependency tree by traversing transitively
# Start from the top-level project and follow each reference
dotnet list src/MyApp.Api/MyApp.Api.csproj reference
dotnet list src/MyApp.Infrastructure/MyApp.Infrastructure.csproj reference
# Continue until you reach projects with no ProjectReference entries
```csharp
### Impact Analysis
When modifying a shared project like `MyApp.Core`, all projects that reference it (directly or transitively) are affected:
```bash
# Find all projects that reference a specific project
grep -rn "MyApp.Core.csproj" --include="*.csproj" . | grep -v "obj/"
```bash
**Example output:**
```text
src/MyApp.Api/MyApp.Api.csproj:12: <ProjectReference Include="../MyApp.Core/MyApp.Core.csproj" />
src/MyApp.Infrastructure/MyApp.Infrastructure.csproj:10: <ProjectReference Include="../MyApp.Core/MyApp.Core.csproj" />
tests/MyApp.Core.Tests/MyApp.Core.Tests.csproj:14: <ProjectReference Include="../../src/MyApp.Core/MyApp.Core.csproj" />
```csharp
This means changes to `MyApp.Core` require testing `MyApp.Api`, `MyApp.Infrastructure`, and `MyApp.Core.Tests`.
---
## Subsection 4: Configuration File Locations
.NET projects use several configuration files scattered across the solution. Knowing where to find them is essential for understanding application behavior.
### appsettings*.json
**Discovery command:**
```bash
# Find all appsettings files
find . -name "appsettings*.json" -not -path "*/obj/*" -not -path "*/bin/*" | sort
```bash
**Example output:**
```text
./src/MyApp.Api/appsettings.json
./src/MyApp.Api/appsettings.Development.json
./src/MyApp.Api/appsettings.Production.json
./src/MyApp.Worker/appsettings.json
```json
**Key behavior:** Environment-specific files (`appsettings.{ENVIRONMENT}.json`) override values from the base `appsettings.json`. The environment is set via `DOTNET_ENVIRONMENT` or `ASPNETCORE_ENVIRONMENT`.
### launchSettings.json
**Discovery command:**
```bash
# Find launch settings (inside Properties/ folder of each project)
find . -name "launchSettings.json" -not -path "*/obj/*" -not -path "*/bin/*"
```bash
**Example output:**
```text
./src/MyApp.Api/Properties/launchSettings.json
./src/MyApp.Web/Properties/launchSettings.json
```json
**Key behavior:** Used by `dotnet run` and Visual Studio to configure launch profiles (ports, environment variables, launch URLs). Not deployed to production.
### Directory.Build.props and Directory.Build.targets
**Discovery command:**
```bash
# Find all Directory.Build.props/targets files (may exist at multiple levels)
find . -name "Directory.Build.props" -o -name "Directory.Build.targets" | sort
```bash
**Example output:**
```text
./Directory.Build.props
./Directory.Build.targets
./src/Directory.Build.props
./tests/Directory.Build.props
```xml
**Key behavior:** MSBuild imports the nearest file found walking upward from the project directory. Nested files shadow parent files unless they explicitly import the parent (see [skill:dotnet-csproj-reading] for chaining).
### Other Configuration Files
```bash
# Find all .NET configuration files in one sweep
find . \( -name "nuget.config" -o -name "global.json" -o -name ".editorconfig" \
-o -name "Directory.Packages.props" \) -not -path "*/obj/*" | sort
```bash
**Example output:**
```text
./.editorconfig
./Directory.Packages.props
./global.json
./nuget.config
./src/.editorconfig
```json
| File | Purpose | Resolution |
|------|---------|-----------|
| `nuget.config` | NuGet package sources and mappings | Hierarchical upward from project dir |
| `global.json` | SDK version pinning | Nearest file walking upward |
| `.editorconfig` | Code style and analyzer severity | Hierarchical (sections merge upward) |
| `Directory.Packages.props` | Central package version management | Hierarchical upward from project dir |
---
## Subsection 5: Common Solution Layouts
Recognizing the layout pattern helps agents navigate unfamiliar codebases faster.
### Pattern 1: src/tests Layout
The most common layout. Source projects in `src/`, test projects in `tests/`, mirroring names.
```text
MyApp/
MyApp.sln
Directory.Build.props
Directory.Packages.props
global.json
nuget.config
.editorconfig
src/
MyApp.Api/
MyApp.Api.csproj
Program.cs
Controllers/
Services/
MyApp.Core/
MyApp.Core.csproj
Models/
Interfaces/
MyApp.Infrastructure/
MyApp.Infrastructure.csproj
Data/
Repositories/
tests/
MyApp.Api.Tests/
MyApp.Api.Tests.csproj
MyApp.Core.Tests/
MyApp.Core.Tests.csproj
docs/
architecture.md
```csharp
**Heuristics:**
- `src/` and `tests/` directories at root level.
- Test project names mirror source project names with `.Tests` suffix.
- Shared build config (`Directory.Build.props`, `global.json`) at the root.
**Discovery:**
```bash
# Detect src/tests layout
ls -d src/ tests/ 2>/dev/null && echo "src/tests layout detected"
```bash
### Pattern 2: Vertical Slice Layout
Organizes code by feature rather than by technical layer. Each slice contains its own models, handlers, and endpoints.
```text
MyApp/
MyApp.sln
src/
MyApp.Api/
MyApp.Api.csproj
Program.cs
Features/
Orders/
CreateOrder.cs # Handler + request + response
GetOrder.cs
OrderValidator.cs
OrderEndpoints.cs # Minimal API endpoint mapping
Products/
CreateProduct.cs
ListProducts.cs
ProductEndpoints.cs
Common/
Behaviors/
ValidationBehavior.cs
Middleware/
ExceptionMiddleware.cs
tests/
MyApp.Api.Tests/
Features/
Orders/
CreateOrderTests.cs
GetOrderTests.cs
```csharp
**Heuristics:**
- `Features/` directory within a project.
- Each feature folder contains multiple related files (handler, validator, endpoint).
- Tests mirror the feature folder structure.
**Discovery:**
```bash
# Detect vertical slice layout
find . -type d -name "Features" -not -path "*/obj/*" -not -path "*/bin/*"
```bash
### Pattern 3: Modular Monolith
Multiple bounded contexts as separate projects within a single solution, communicating through explicit interfaces or a shared message bus.
```text
MyApp/
MyApp.sln
src/
MyApp.Host/
MyApp.Host.csproj # Composition root -- references all modules
Program.cs
Modules/
Ordering/
MyApp.Ordering/
MyApp.Ordering.csproj
OrderingModule.cs # Module registration (DI, endpoints)
Domain/
Application/
Infrastructure/
MyApp.Ordering.Tests/
Catalog/
MyApp.Catalog/
MyApp.Catalog.csproj
CatalogModule.cs
Domain/
Application/
Infrastructure/
MyApp.Catalog.Tests/
MyApp.Shared/
MyApp.Shared.csproj # Cross-cutting contracts (events, interfaces)
```csharp
**Heuristics:**
- `Modules/` directory with self-contained bounded contexts.
- A `Host` or `Startup` project that references all modules.
- A `Shared` project for cross-module contracts.
**Discovery:**
```bash
# Detect modular monolith layout
find . -type d -name "Modules" -not -path "*/obj/*" -not -path "*/bin/*"
# Or look for module registration patterns
grep -rn "Module\|AddModule\|RegisterModule" --include="*.cs" . | grep -v "obj/" | head -10
```csharp
---
## Slopwatch Anti-Patterns
These patterns in test project discovery indicate an agent is hiding testing gaps rather than addressing them. See [skill:dotnet-slopwatch] for the automated quality gate that detects these patterns.
### Disabled or Skipped Tests in Test Project Discovery
When navigating a solution and identifying test projects, watch for tests that exist but are silently disabled:
```csharp
// RED FLAG: skipped tests that will not run during dotnet test
[Fact(Skip = "Flaky -- revisit later")]
public async Task ProcessOrder_ConcurrentRequests_HandledCorrectly() { }
// RED FLAG: entire test class disabled via conditional compilation
#if false
public class OrderIntegrationTests
{
[Fact]
public async Task CreateOrder_PersistsToDatabase() { }
}
#endif
// RED FLAG: commented-out test methods
// [Fact]
// public void CalculateDiscount_NegativeAmount_ThrowsException() { }
```text
**Discovery commands to check for disabled tests:**
```bash
# Find skipped tests
grep -rEn 'Skip[[:space:]]*=' --include="*.cs" . | grep -v "obj/" | grep -v "bin/"
# Find tests hidden behind #if false
grep -rn "#if false" --include="*.cs" . | grep -v "obj/" | grep -v "bin/"
# Find commented-out test attributes
grep -rEn '//[[:space:]]*\[(Fact|Theory|Test)\]' --include="*.cs" . | grep -v "obj/" | grep -v "bin/"
```csharp
**Fix:** Investigate why tests are disabled. If they are flaky due to timing, fix the non-determinism or use `[Retry]` (xUnit v3). If they test removed functionality, delete them. Never leave disabled tests as invisible technical debt.
---
## Cross-References
- [skill:dotnet-project-structure] -- project organization, SDK selection, solution layout decisions
- [skill:dotnet-csproj-reading] -- reading and modifying .csproj files found during navigation
- [skill:dotnet-testing-strategy] -- test project identification, test types, test organization
## References
- [.NET Project SDK Overview](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/overview)
- [dotnet sln Command](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-sln)
- [.slnx Solution Format](https://learn.microsoft.com/en-us/visualstudio/ide/reference/solution-file-slnx)
- [Configuration in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/)
- [Directory.Build.props/targets](https://learn.microsoft.com/en-us/visualstudio/msbuild/customize-by-directory)
Code Navigation (Serena MCP)
Primary approach: Use Serena symbol operations for efficient code navigation:
- Find definitions:
serena_find_symbol instead of text search
- Understand structure:
serena_get_symbols_overview for file organization
- Track references:
serena_find_referencing_symbols for impact analysis
- Precise edits:
serena_replace_symbol_body for clean modifications
When to use Serena vs traditional tools:
- Use Serena: Navigation, refactoring, dependency analysis, precise edits
- Use Read/Grep: Reading full files, pattern matching, simple text operations
- Fallback: If Serena unavailable, traditional tools work fine
Example workflow:
# Instead of:
Read: src/Services/OrderService.cs
Grep: "public void ProcessOrder"
# Use:
serena_find_symbol: "OrderService/ProcessOrder"
serena_get_symbols_overview: "src/Services/OrderService.cs"
1---2name: dotnet-solution-navigation-83category: developer-experience4subcategory: project5description: Orients in .NET solutions -- entry points, .sln/.slnx, dependency graphs, config.6license: MIT7targets: ['*']8tags: [csharp, dotnet, skill]9version: '0.0.1'10author: 'dotnet-agent-harness'11invocable: true12claudecode:13 allowed-tools: ['Read', 'Grep', 'Glob', 'Bash', 'Write', 'Edit']14 model: haiku15copilot: {}16codexcli:17 short-description: '.NET skill guidance for csharp tasks'18geminicli: {}19opencode:20 allowed-tools: ['Read', 'Grep', 'Glob', 'Bash', 'Write', 'Edit']21antigravity: {}22metadata:23 source: https://skillmd.com/skills/rudironsoni/dotnet-solution-navigation-824---2526````! find . -maxdepth 2 ( -name "*.sln" -o -name "*.slnx" ) 2>/dev/null | head -5272829```bash3031# dotnet-solution-navigation3233Teaches agents to orient in .NET solutions: finding entry points, parsing solution files, traversing project dependencies, locating configuration files, and recognizing common solution layouts. Each subsection includes discovery commands/heuristics and example output.3435## Scope3637- Entry point discovery (Program.cs, top-level statements, worker services)38- Solution file parsing (.sln, .slnx)39- Project dependency graph traversal40- Configuration file location (appsettings.json, launchSettings.json)4142## Out of scope4344- Project file structure and modification -- see [skill:dotnet-csproj-reading]45- Project organization decisions and SDK selection -- see [skill:dotnet-project-structure]46- Test framework configuration and test type decisions -- see [skill:dotnet-testing-strategy]4748## Prerequisites4950.NET 8.0+ SDK. `dotnet` CLI available on PATH. Familiarity with SDK-style projects.5152Cross-references: [skill:dotnet-project-structure] for project organization guidance, [skill:dotnet-csproj-reading] for reading and modifying .csproj files found during navigation, [skill:dotnet-testing-strategy] for test project identification and test type decisions.5354---5556## Subsection 1: Entry Point Discovery5758.NET applications can start from several patterns. Do not assume every app has a traditional `Program.cs` with a `Main` method.5960### Pattern 1: Traditional Program.cs with Main Method6162Used in older projects, worker services, and when explicit control over hosting is needed.6364**Discovery command:**6566```bash6768# Find Program.cs files containing a Main method69grep -rn "static.*void Main\|static.*Task Main\|static.*async.*Main" --include="*.cs" .7071```bash7273**Example output:**7475```text7677src/MyApp.Worker/Program.cs:5: public static async Task Main(string[] args)78src/MyApp.Console/Program.cs:3: static void Main(string[] args)7980```csharp8182### Pattern 2: Top-Level Statements (C# 9+)8384Modern .NET projects (templates since .NET 6) use top-level statements -- the file contains no class or Main method, just executable code.8586**Discovery command:**8788```bash8990# Find Program.cs files that do NOT contain class/namespace declarations91# (top-level statements have no enclosing class)92for f in $(find . -name "Program.cs" -not -path "*/obj/*" -not -path "*/bin/*"); do93 if ! grep -Eq '^[[:space:]]*(class|namespace)[[:space:]]' "$f" 2>/dev/null; then94 echo "Top-level: $f"95 fi96done9798```text99100**Example output:**101102```text103104Top-level: ./src/MyApp.Api/Program.cs105Top-level: ./src/MyApp.Web/Program.cs106107```csharp108109**Typical content of a top-level Program.cs:**110111```csharp112113// No namespace, no class, no Main -- this IS the entry point114var builder = WebApplication.CreateBuilder(args);115builder.Services.AddControllers();116var app = builder.Build();117app.MapControllers();118app.Run();119120```text121122### Pattern 3: Worker Services and Background Hosts123124Worker services use `Host.CreateDefaultBuilder` or `Host.CreateApplicationBuilder` without a web server. They appear as `Exe` output type with `Microsoft.NET.Sdk.Worker` SDK.125126**Discovery command:**127128```bash129130# Find worker service projects by SDK type131grep -rn 'Sdk="Microsoft.NET.Sdk.Worker"' --include="*.csproj" .132133# Or find IHostedService/BackgroundService implementations134grep -rn "BackgroundService\|IHostedService" --include="*.cs" . | grep -v "obj/" | grep -v "bin/"135136```csharp137138**Example output:**139140```text141142src/MyApp.Worker/MyApp.Worker.csproj:1:<Project Sdk="Microsoft.NET.Sdk.Worker">143src/MyApp.Worker/Services/OrderProcessor.cs:8:public class OrderProcessor : BackgroundService144src/MyApp.Worker/Services/EmailSender.cs:5:public class EmailSender : IHostedService145146```csharp147148### Pattern 4: Test Projects149150Test projects are entry points for `dotnet test`. They may not have a `Program.cs` at all -- the test runner provides the entry point.151152**Discovery command:**153154```bash155156# Find test projects by IsTestProject property or test SDK references157grep -rn "<IsTestProject>true</IsTestProject>" --include="*.csproj" .158grep -rn "Microsoft.NET.Test.Sdk\|xunit\|NUnit\|MSTest" --include="*.csproj" . | grep -v "obj/" # Matches both xunit.v3 and legacy xunit159160```bash161162**Example output:**163164```text165166tests/MyApp.Api.Tests/MyApp.Api.Tests.csproj:5: <IsTestProject>true</IsTestProject>167tests/MyApp.Core.Tests/MyApp.Core.Tests.csproj:8: <PackageReference Include="xunit.v3" />168169```csharp170171### Summary Heuristic172173When orienting in a new .NET solution, run these commands in sequence:174175```bash176177# 1. Find all .csproj files178find . -name "*.csproj" -not -path "*/obj/*" | sort179180# 2. Identify output types (Exe = app entry point, Library = dependency)181grep -rn "<OutputType>" --include="*.csproj" .182183# 3. Find all Program.cs files184find . -name "Program.cs" -not -path "*/obj/*" -not -path "*/bin/*"185186# 4. Identify test projects187grep -rn "<IsTestProject>true" --include="*.csproj" .188189```csharp190191---192193## Subsection 2: Solution File Formats194195.NET solutions use `.sln` (text-based, legacy format) or `.slnx` (XML-based, .NET 9+ preview). Both files list projects and their relationships.196197### .sln Format198199The traditional solution format is a text file with a custom syntax (not XML).200201**Discovery and parsing commands:**202203```bash204205# Find solution files206find . -name "*.sln" -maxdepth 2207208# List all projects in a solution using dotnet CLI209dotnet sln list210# Or specify the solution file explicitly:211dotnet sln MyApp.sln list212213```text214215**Example output of `dotnet sln list`:**216217```text218219Project(s)220----------221src/MyApp.Api/MyApp.Api.csproj222src/MyApp.Core/MyApp.Core.csproj223src/MyApp.Infrastructure/MyApp.Infrastructure.csproj224tests/MyApp.Api.Tests/MyApp.Api.Tests.csproj225tests/MyApp.Core.Tests/MyApp.Core.Tests.csproj226227```csharp228229**Reading the .sln file directly** (useful when `dotnet sln list` is not available):230231```bash232233# Extract project entries from .sln file234grep "^Project(" MyApp.sln235236```bash237238**Example output:**239240```text241242Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MyApp.Api", "src\MyApp.Api\MyApp.Api.csproj", "{A1B2C3D4-E5F6-7890-ABCD-EF1234567890}"243Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MyApp.Core", "src\MyApp.Core\MyApp.Core.csproj", "{B2C3D4E5-F6A7-8901-BCDE-F12345678901}"244245```csharp246247The GUID `{FAE04EC0-...}` identifies C# projects. The second value is the relative path to the `.csproj` file.248249### .slnx Format (.NET 9+)250251The `.slnx` format is an XML-based solution file introduced as a preview feature in .NET 9.252253**Discovery and parsing commands:**254255```bash256257# Find .slnx files258find . -name "*.slnx" -maxdepth 2259260# dotnet sln commands work with .slnx files too261dotnet sln MyApp.slnx list262263```bash264265**Example .slnx content:**266267```xml268269<Solution>270 <Folder Name="/src/">271 <Project Path="src/MyApp.Api/MyApp.Api.csproj" />272 <Project Path="src/MyApp.Core/MyApp.Core.csproj" />273 </Folder>274 <Folder Name="/tests/">275 <Project Path="tests/MyApp.Api.Tests/MyApp.Api.Tests.csproj" />276 </Folder>277</Solution>278279```csharp280281**Key differences from .sln:**282283| Feature | .sln | .slnx |284|---------|------|-------|285| Format | Custom text | XML |286| Readability | Low (GUIDs, custom syntax) | High (clean XML) |287| Availability | All .NET versions | .NET 9+ preview |288| Tooling | Full support | Partial (growing) |289| Solution folders | Nested GUID references | `<Folder>` elements |290291### When No Solution File Exists292293Some repositories use individual `.csproj` files without a `.sln`. Build and run from project directories:294295```bash296297# If no .sln exists, find all .csproj files and build individually298find . -name "*.csproj" -not -path "*/obj/*" | sort299dotnet build src/MyApp.Api/MyApp.Api.csproj300301```bash302303---304305## Subsection 3: Project Dependency Traversal306307Understanding `ProjectReference` chains is critical for determining build order, finding shared code, and identifying the impact of changes.308309### Discovery Commands310311```bash312313# Find all ProjectReference entries across the solution314grep -rn "<ProjectReference" --include="*.csproj" . | grep -v "obj/"315316```bash317318**Example output:**319320```text321322src/MyApp.Api/MyApp.Api.csproj:12: <ProjectReference Include="../MyApp.Core/MyApp.Core.csproj" />323src/MyApp.Api/MyApp.Api.csproj:13: <ProjectReference Include="../MyApp.Infrastructure/MyApp.Infrastructure.csproj" />324src/MyApp.Infrastructure/MyApp.Infrastructure.csproj:10: <ProjectReference Include="../MyApp.Core/MyApp.Core.csproj" />325tests/MyApp.Api.Tests/MyApp.Api.Tests.csproj:14: <ProjectReference Include="../../src/MyApp.Api/MyApp.Api.csproj" />326327```csharp328329### Building a Dependency Graph330331From the above output, the dependency graph is:332333```text334335MyApp.Api.Tests336 -> MyApp.Api337 -> MyApp.Core338 -> MyApp.Infrastructure339 -> MyApp.Core340341```text342343**Automated traversal using `dotnet list reference`:**344345```bash346347# List direct references for a specific project348dotnet list src/MyApp.Api/MyApp.Api.csproj reference349350```bash351352**Example output:**353354```text355356Project reference(s)357--------------------358../MyApp.Core/MyApp.Core.csproj359../MyApp.Infrastructure/MyApp.Infrastructure.csproj360361```csharp362363**Full transitive dependency analysis:**364365```bash366367# Build the full dependency tree by traversing transitively368# Start from the top-level project and follow each reference369dotnet list src/MyApp.Api/MyApp.Api.csproj reference370dotnet list src/MyApp.Infrastructure/MyApp.Infrastructure.csproj reference371# Continue until you reach projects with no ProjectReference entries372373```csharp374375### Impact Analysis376377When modifying a shared project like `MyApp.Core`, all projects that reference it (directly or transitively) are affected:378379```bash380381# Find all projects that reference a specific project382grep -rn "MyApp.Core.csproj" --include="*.csproj" . | grep -v "obj/"383384```bash385386**Example output:**387388```text389390src/MyApp.Api/MyApp.Api.csproj:12: <ProjectReference Include="../MyApp.Core/MyApp.Core.csproj" />391src/MyApp.Infrastructure/MyApp.Infrastructure.csproj:10: <ProjectReference Include="../MyApp.Core/MyApp.Core.csproj" />392tests/MyApp.Core.Tests/MyApp.Core.Tests.csproj:14: <ProjectReference Include="../../src/MyApp.Core/MyApp.Core.csproj" />393394```csharp395396This means changes to `MyApp.Core` require testing `MyApp.Api`, `MyApp.Infrastructure`, and `MyApp.Core.Tests`.397398---399400## Subsection 4: Configuration File Locations401402.NET projects use several configuration files scattered across the solution. Knowing where to find them is essential for understanding application behavior.403404### appsettings*.json405406**Discovery command:**407408```bash409410# Find all appsettings files411find . -name "appsettings*.json" -not -path "*/obj/*" -not -path "*/bin/*" | sort412413```bash414415**Example output:**416417```text418419./src/MyApp.Api/appsettings.json420./src/MyApp.Api/appsettings.Development.json421./src/MyApp.Api/appsettings.Production.json422./src/MyApp.Worker/appsettings.json423424```json425426**Key behavior:** Environment-specific files (`appsettings.{ENVIRONMENT}.json`) override values from the base `appsettings.json`. The environment is set via `DOTNET_ENVIRONMENT` or `ASPNETCORE_ENVIRONMENT`.427428### launchSettings.json429430**Discovery command:**431432```bash433434# Find launch settings (inside Properties/ folder of each project)435find . -name "launchSettings.json" -not -path "*/obj/*" -not -path "*/bin/*"436437```bash438439**Example output:**440441```text442443./src/MyApp.Api/Properties/launchSettings.json444./src/MyApp.Web/Properties/launchSettings.json445446```json447448**Key behavior:** Used by `dotnet run` and Visual Studio to configure launch profiles (ports, environment variables, launch URLs). Not deployed to production.449450### Directory.Build.props and Directory.Build.targets451452**Discovery command:**453454```bash455456# Find all Directory.Build.props/targets files (may exist at multiple levels)457find . -name "Directory.Build.props" -o -name "Directory.Build.targets" | sort458459```bash460461**Example output:**462463```text464465./Directory.Build.props466./Directory.Build.targets467./src/Directory.Build.props468./tests/Directory.Build.props469470```xml471472**Key behavior:** MSBuild imports the nearest file found walking upward from the project directory. Nested files shadow parent files unless they explicitly import the parent (see [skill:dotnet-csproj-reading] for chaining).473474### Other Configuration Files475476```bash477478# Find all .NET configuration files in one sweep479find . \( -name "nuget.config" -o -name "global.json" -o -name ".editorconfig" \480 -o -name "Directory.Packages.props" \) -not -path "*/obj/*" | sort481482```bash483484**Example output:**485486```text487488./.editorconfig489./Directory.Packages.props490./global.json491./nuget.config492./src/.editorconfig493494```json495496| File | Purpose | Resolution |497|------|---------|-----------|498| `nuget.config` | NuGet package sources and mappings | Hierarchical upward from project dir |499| `global.json` | SDK version pinning | Nearest file walking upward |500| `.editorconfig` | Code style and analyzer severity | Hierarchical (sections merge upward) |501| `Directory.Packages.props` | Central package version management | Hierarchical upward from project dir |502503---504505## Subsection 5: Common Solution Layouts506507Recognizing the layout pattern helps agents navigate unfamiliar codebases faster.508509### Pattern 1: src/tests Layout510511The most common layout. Source projects in `src/`, test projects in `tests/`, mirroring names.512513```text514515MyApp/516 MyApp.sln517 Directory.Build.props518 Directory.Packages.props519 global.json520 nuget.config521 .editorconfig522 src/523 MyApp.Api/524 MyApp.Api.csproj525 Program.cs526 Controllers/527 Services/528 MyApp.Core/529 MyApp.Core.csproj530 Models/531 Interfaces/532 MyApp.Infrastructure/533 MyApp.Infrastructure.csproj534 Data/535 Repositories/536 tests/537 MyApp.Api.Tests/538 MyApp.Api.Tests.csproj539 MyApp.Core.Tests/540 MyApp.Core.Tests.csproj541 docs/542 architecture.md543544```csharp545546**Heuristics:**547- `src/` and `tests/` directories at root level.548- Test project names mirror source project names with `.Tests` suffix.549- Shared build config (`Directory.Build.props`, `global.json`) at the root.550551**Discovery:**552553```bash554555# Detect src/tests layout556ls -d src/ tests/ 2>/dev/null && echo "src/tests layout detected"557558```bash559560### Pattern 2: Vertical Slice Layout561562Organizes code by feature rather than by technical layer. Each slice contains its own models, handlers, and endpoints.563564```text565566MyApp/567 MyApp.sln568 src/569 MyApp.Api/570 MyApp.Api.csproj571 Program.cs572 Features/573 Orders/574 CreateOrder.cs # Handler + request + response575 GetOrder.cs576 OrderValidator.cs577 OrderEndpoints.cs # Minimal API endpoint mapping578 Products/579 CreateProduct.cs580 ListProducts.cs581 ProductEndpoints.cs582 Common/583 Behaviors/584 ValidationBehavior.cs585 Middleware/586 ExceptionMiddleware.cs587 tests/588 MyApp.Api.Tests/589 Features/590 Orders/591 CreateOrderTests.cs592 GetOrderTests.cs593594```csharp595596**Heuristics:**597- `Features/` directory within a project.598- Each feature folder contains multiple related files (handler, validator, endpoint).599- Tests mirror the feature folder structure.600601**Discovery:**602603```bash604605# Detect vertical slice layout606find . -type d -name "Features" -not -path "*/obj/*" -not -path "*/bin/*"607608```bash609610### Pattern 3: Modular Monolith611612Multiple bounded contexts as separate projects within a single solution, communicating through explicit interfaces or a shared message bus.613614```text615616MyApp/617 MyApp.sln618 src/619 MyApp.Host/620 MyApp.Host.csproj # Composition root -- references all modules621 Program.cs622 Modules/623 Ordering/624 MyApp.Ordering/625 MyApp.Ordering.csproj626 OrderingModule.cs # Module registration (DI, endpoints)627 Domain/628 Application/629 Infrastructure/630 MyApp.Ordering.Tests/631 Catalog/632 MyApp.Catalog/633 MyApp.Catalog.csproj634 CatalogModule.cs635 Domain/636 Application/637 Infrastructure/638 MyApp.Catalog.Tests/639 MyApp.Shared/640 MyApp.Shared.csproj # Cross-cutting contracts (events, interfaces)641642```csharp643644**Heuristics:**645- `Modules/` directory with self-contained bounded contexts.646- A `Host` or `Startup` project that references all modules.647- A `Shared` project for cross-module contracts.648649**Discovery:**650651```bash652653# Detect modular monolith layout654find . -type d -name "Modules" -not -path "*/obj/*" -not -path "*/bin/*"655# Or look for module registration patterns656grep -rn "Module\|AddModule\|RegisterModule" --include="*.cs" . | grep -v "obj/" | head -10657658```csharp659660---661662## Slopwatch Anti-Patterns663664These patterns in test project discovery indicate an agent is hiding testing gaps rather than addressing them. See [skill:dotnet-slopwatch] for the automated quality gate that detects these patterns.665666### Disabled or Skipped Tests in Test Project Discovery667668When navigating a solution and identifying test projects, watch for tests that exist but are silently disabled:669670```csharp671672// RED FLAG: skipped tests that will not run during dotnet test673[Fact(Skip = "Flaky -- revisit later")]674public async Task ProcessOrder_ConcurrentRequests_HandledCorrectly() { }675676// RED FLAG: entire test class disabled via conditional compilation677#if false678public class OrderIntegrationTests679{680 [Fact]681 public async Task CreateOrder_PersistsToDatabase() { }682}683#endif684685// RED FLAG: commented-out test methods686// [Fact]687// public void CalculateDiscount_NegativeAmount_ThrowsException() { }688689```text690691**Discovery commands to check for disabled tests:**692693```bash694695# Find skipped tests696grep -rEn 'Skip[[:space:]]*=' --include="*.cs" . | grep -v "obj/" | grep -v "bin/"697698# Find tests hidden behind #if false699grep -rn "#if false" --include="*.cs" . | grep -v "obj/" | grep -v "bin/"700701# Find commented-out test attributes702grep -rEn '//[[:space:]]*\[(Fact|Theory|Test)\]' --include="*.cs" . | grep -v "obj/" | grep -v "bin/"703704```csharp705706**Fix:** Investigate why tests are disabled. If they are flaky due to timing, fix the non-determinism or use `[Retry]` (xUnit v3). If they test removed functionality, delete them. Never leave disabled tests as invisible technical debt.707708---709710## Cross-References711712- [skill:dotnet-project-structure] -- project organization, SDK selection, solution layout decisions713- [skill:dotnet-csproj-reading] -- reading and modifying .csproj files found during navigation714- [skill:dotnet-testing-strategy] -- test project identification, test types, test organization715716## References717718- [.NET Project SDK Overview](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/overview)719- [dotnet sln Command](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-sln)720- [.slnx Solution Format](https://learn.microsoft.com/en-us/visualstudio/ide/reference/solution-file-slnx)721- [Configuration in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/)722- [Directory.Build.props/targets](https://learn.microsoft.com/en-us/visualstudio/msbuild/customize-by-directory)723````724725## Code Navigation (Serena MCP)726727**Primary approach:** Use Serena symbol operations for efficient code navigation:7287291. **Find definitions**: `serena_find_symbol` instead of text search7302. **Understand structure**: `serena_get_symbols_overview` for file organization7313. **Track references**: `serena_find_referencing_symbols` for impact analysis7324. **Precise edits**: `serena_replace_symbol_body` for clean modifications733734**When to use Serena vs traditional tools:**735736- **Use Serena**: Navigation, refactoring, dependency analysis, precise edits737- **Use Read/Grep**: Reading full files, pattern matching, simple text operations738- **Fallback**: If Serena unavailable, traditional tools work fine739740**Example workflow:**741742```text743# Instead of:744Read: src/Services/OrderService.cs745Grep: "public void ProcessOrder"746747# Use:748serena_find_symbol: "OrderService/ProcessOrder"749serena_get_symbols_overview: "src/Services/OrderService.cs"750```