You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Keep build/test helper cleanup out of the render commit.
Keep agent, installer, and xWorks cleanup separate.
Normalize TonePars generated-file comparisons for Windows paths.
description: 'Guidelines for building C# applications'
3
+
applyTo: '**/*.cs'
4
+
---
5
+
6
+
# C# Development
7
+
8
+
## Scope
9
+
- FieldWorks managed code is a Windows desktop codebase built on .NET Framework 4.8 and native dependencies.
10
+
- Treat this file as guidance for existing FieldWorks C# projects, not for ASP.NET or service-oriented .NET applications.
11
+
- On Linux and macOS, limit work to editing, search, docs, and specs. Do not claim to have built or run managed binaries there.
12
+
13
+
## Language Version And Features
14
+
- Use the repo default C# language version unless a project explicitly overrides it. Today that default is C# 8.0 via `Directory.Build.props`.
15
+
- Do not introduce C# features that require a newer language version without first updating repo-wide build policy.
16
+
- Nullable reference types are disabled by default. Only use nullable annotations and nullable-flow assumptions in projects that opt in explicitly.
17
+
- Prefer syntax that is already common in the touched area. Consistency with nearby code is more important than using the newest available syntax.
18
+
19
+
## General Instructions
20
+
- Make only high-confidence suggestions when reviewing code changes.
21
+
- Fix the root cause when practical, but keep edits narrow and compatible with existing behavior.
22
+
- Handle edge cases and exception paths explicitly. Do not swallow exceptions without a documented reason.
23
+
- Treat native interop, COM, registry-free COM, file formats, and serialization boundaries as high-risk areas that need extra care.
24
+
25
+
## Naming Conventions
26
+
- Follow PascalCase for types, methods, properties, events, and public members.
27
+
- Use camelCase for locals and private fields.
28
+
- Prefix interfaces with `I`.
29
+
- Keep namespaces aligned with the existing project root namespace instead of inventing new top-level naming schemes.
30
+
31
+
## Formatting And Style
32
+
- Apply the formatting rules defined in `.editorconfig` and match surrounding code.
33
+
- Prefer block-scoped namespaces. Do not default to file-scoped namespaces in this repo.
34
+
- Keep using directives simple and consistent with the file you are editing.
35
+
- Use `nameof` instead of string literals when referencing member names.
36
+
- Use pattern matching where it improves clarity and is supported by the project language version. Do not force newer syntax into older-looking code.
37
+
38
+
## Documentation And Comments
39
+
- Public APIs should have XML documentation comments.
40
+
- Add code comments only when intent, invariants, or interop constraints are not obvious from the code itself.
41
+
- Do not add boilerplate comments to every method.
42
+
43
+
## Project Conventions
44
+
- Most managed projects here are SDK-style `.csproj` files targeting `net48`.
45
+
- Keep `GenerateAssemblyInfo` disabled where the project relies on linked `CommonAssemblyInfo.cs`.
46
+
- Preserve project-specific build settings such as warnings-as-errors, x64 assumptions, WinExe/WindowsDesktop settings, and registration-free COM behavior.
47
+
- When adding new files, update the project file only if the specific project format requires it.
48
+
49
+
## Desktop, UI, And Localization
50
+
- FieldWorks is a desktop application. Favor guidance relevant to WinForms, WPF, dialogs, view models, threading, and long-running UI work.
51
+
- UI-affecting code must respect the UI thread. Avoid blocking calls that can freeze the application.
52
+
- Keep user-visible strings in `.resx` resources and follow existing localization patterns. Do not hardcode new UI strings.
53
+
- Preserve designer compatibility for WinForms and avoid edits that break generated code patterns.
54
+
55
+
## Nullability And Defensive Code
56
+
- Because nullable reference types are usually disabled, write explicit null checks at public entry points and interop boundaries when required by the surrounding code.
57
+
- Prefer `is null` and `is not null` checks when adding new null checks.
58
+
- Do not pretend the compiler will enforce null-state safety unless the project has opted into nullable analysis.
59
+
60
+
## Testing
61
+
- For behavior changes and bug fixes, add or update tests when practical.
62
+
- Follow nearby test naming and structure conventions. Do not add `Arrange`, `Act`, or `Assert` comments unless the existing file already uses them.
63
+
- Prefer fast, deterministic NUnit tests for managed code.
64
+
- Use `./test.ps1` on Windows to run tests, and `./build.ps1` when you need a supporting build first. Do not recommend ad-hoc `dotnet test` or `msbuild` commands as the normal path for this repo.
65
+
66
+
## Build And Validation
67
+
- Use `./build.ps1` for builds and `./test.ps1` for tests in normal repo workflows.
68
+
- Avoid changing build, packaging, COM, or registry behavior without checking the existing build instructions and affected tests.
69
+
- Treat compiler warnings as actionable unless the repo already documents a specific exception.
70
+
71
+
## What Not To Assume
72
+
- Do not assume ASP.NET Core, Minimal APIs, Entity Framework Core, Swagger/OpenAPI, cloud deployment, container publishing, or JWT authentication are relevant unless the user is explicitly working in a repo area that adds those technologies.
Copy file name to clipboardExpand all lines: .github/instructions/debugging.instructions.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -49,7 +49,7 @@ description: "Runtime debugging and tracing guidance for FieldWorks"
49
49
50
50
## Dev switch (auto config)
51
51
- FieldWorks now supports a swappable diagnostics config via `FieldWorks.Diagnostics.config`.
52
-
- Default is quiet. `build.ps1` now enables the dev diagnostics config automatically for Debug builds unless you override `/p:UseDevTraceConfig`. You can also force it via `UseDevTraceConfig=true`, by setting environment variable `FW_TRACE_LOG` before the build, or by passing `-TraceCrashes` to `build.ps1`; the dev diagnostics file is copied as `FieldWorks.Diagnostics.config` in the output.
52
+
- Default is quiet. Use `build.ps1 -EnableTracing` to copy the dev diagnostics file into the output as `FieldWorks.Diagnostics.config`. You can also force it via `UseDevTraceConfig=true` or by setting environment variable `FW_TRACE_LOG` before the build.
53
53
- Dev log location: `Output/Debug/FieldWorks.trace.log` (relative to the app folder) so it’s easy to collect alongside binaries.
54
54
- Dev config logs to `%temp%/FieldWorks.trace.log` and turns on the core switches above. Edit `Src/Common/FieldWorks/FieldWorks.Diagnostics.dev.config` to change log path or switches.
55
55
@@ -59,5 +59,5 @@ description: "Runtime debugging and tracing guidance for FieldWorks"
59
59
60
60
## Proposed Improvements (dev-only)
61
61
- Add `Docs/FieldWorks.trace.sample.config` with the snippet above for easy reuse.
62
-
-Introduce a dev flag (`UseDevTraceConfig=true` or `FW_TRACE_LOG` env var) that copies the dev diagnostics file next to `FieldWorks.exe`in Debug builds so tracing is on by default for local runs.
62
+
-Keep `build.ps1 -EnableTracing` as the single scripted path that copies the dev diagnostics file next to `FieldWorks.exe` for local trace-enabled runs.
63
63
- Document standard trace switches in `Docs/logging.md` and keep `EnvVarTraceListener` as the default listener for dev traces.
-**Implicit file inclusion is common**: SDK-style projects usually include new `.cs` files automatically.
19
+
-**Check the touched project before editing**: Some projects still carry explicit includes, linked files, designer items, generated code, or custom metadata that must be preserved.
20
+
-**Assembly metadata is managed explicitly**: Keep `GenerateAssemblyInfo` disabled where the project links `CommonAssemblyInfo.cs`.
21
+
-**Preserve project-specific settings**: Keep existing settings for x64, WinExe, WindowsDesktop, COM, resources, warnings-as-errors, and custom MSBuild targets.
19
22
20
-
-**No Implicit Imports**: Unlike SDK-style projects, .NET Framework projects do not automatically import common namespaces or assemblies
21
-
22
-
-**Build Configuration**: Contains explicit `<PropertyGroup>` sections for Debug/Release configurations
23
+
-**Do not normalize projects unnecessarily**: Avoid converting project structure, import style, or target declarations unless that is the task.
23
24
24
-
-**Output Paths**: Explicit `<OutputPath>` and `<IntermediateOutputPath>` definitions
25
-
26
-
-**Target Framework**: Uses `<TargetFrameworkVersion>` instead of `<TargetFramework>`
Some non-SDK-style or tool-specific projects may still exist. When you encounter one:
27
+
- Keep explicit `<Compile Include=... />` items and other legacy structure intact.
28
+
- Update the project file only as much as the change requires.
29
+
- Do not assume you can migrate it to SDK-style as part of routine code edits.
28
30
29
31
## NuGet Package Management
30
32
- Installing and updating NuGet packages in .NET Framework projects is a complex task requiring coordinated changes to multiple files. Therefore, **do not attempt to install or update NuGet packages** in this project.
31
33
- Instead, if changes to NuGet references are required, ask the user to install or update NuGet packages using the Visual Studio NuGet Package Manager or Visual Studio package manager console.
32
34
- When recommending NuGet packages, ensure they are compatible with .NET Framework or .NET Standard 2.0 (not only .NET Core or .NET 5+).
33
35
34
-
## C# Language Version is 7.3
35
-
- This project is limited to C# 7.3 features only. Please avoid using:
36
+
## C# Language Version
37
+
- The repo-wide default language version for C# projects is 8.0.
38
+
- Do not introduce features that require a newer language version unless the specific project or repo policy is updated first.
39
+
- Prefer syntax already used in the touched area so edits remain consistent with surrounding code.
40
+
41
+
### C# 8.0 features available by default
42
+
- Switch expressions and pattern matching enhancements.
43
+
- Using declarations where disposal scope remains clear.
44
+
- Null-coalescing assignment and range/index operators when they improve clarity.
36
45
37
-
### C# 8.0+ Features (NOT SUPPORTED):
38
-
- Using declarations (`using var stream = ...`)
39
-
- Await using statements (`await using var resource = ...`)
40
-
- Switch expressions (`variable switch { ... }`)
41
-
- Null-coalescing assignment (`??=`)
42
-
- Range and index operators (`array[1..^1]`, `array[^1]`)
- Nullable reference types are not enabled repo-wide. Do not introduce `string?`, `#nullable enable`, or nullable-flow assumptions unless the project explicitly opts in.
48
+
- File-scoped namespaces are not available under the repo default language version and should not be introduced.
-**Avoid sync-over-async**: Don't use `.Result` or `.Wait()` or `.GetAwaiter().GetResult()`. These sync-over-async patterns can lead to deadlocks and poor performance. Always use `await` for asynchronous calls.
80
+
-**Avoid sync-over-async**: Don't use `.Result`, `.Wait()`, or `.GetAwaiter().GetResult()` unless you have a clear, reviewed reason. These patterns can deadlock desktop UI code.
81
+
-**Respect the UI thread**: Do not move UI-bound code onto background threads or block the UI while waiting on long-running work.
81
82
82
83
### DateTime Handling
83
84
-**Use DateTimeOffset for timestamps**: Prefer `DateTimeOffset` over `DateTime` for absolute time points
Copy file name to clipboardExpand all lines: .github/instructions/terminal.instructions.md
-2Lines changed: 0 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,8 +13,6 @@ Placement policy for wrappers:
13
13
14
14
**MCP-first:** When the `ps-tools` MCP server is running, prefer MCP tools (`Git-Search`, `Read-FileContent`, `Invoke-AgentTask`, `build`, `test`, agent tools) instead of direct terminal commands. Use wrappers only when MCP is unavailable.
15
15
16
-
**Task-first for CI parity:** Prefer the existing VS Code tasks `CI: Whitespace check`, `CI: Commit messages`, and `CI: Full local check` over ad-hoc shell commands. These tasks are already allowed for agent use and match the repository CI checks.
0 commit comments