diff --git a/README.md b/README.md index 44c3e8e..9090713 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for | [C# Development](instructions/csharp.instructions.md) | Guidelines for building C# applications | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcsharp.instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcsharp.instructions.md) | | [DevOps Core Principles](instructions/devops-core-principles.instructions.md) | Foundational instructions covering core DevOps principles, culture (CALMS), and key metrics (DORA) to guide GitHub Copilot in understanding and promoting effective software delivery. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdevops-core-principles.instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdevops-core-principles.instructions.md) | | [DDD Systems & .NET Guidelines](instructions/dotnet-architecture-good-practices.instructions.md) | DDD and .NET architecture guidelines | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-architecture-good-practices.instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-architecture-good-practices.instructions.md) | +| [.NET Framework Development](instructions/dotnet-framework.instructions.md) | Guidance for working with .NET Framework projects. Includes project structure, C# language version, NuGet management, and best practices. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-framework.instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-framework.instructions.md) | | [.NET MAUI](instructions/dotnet-maui.instructions.md) | .NET MAUI component and application patterns | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-maui.instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-maui.instructions.md) | | [Dotnet Wpf](instructions/dotnet-wpf.instructions.md) | .NET WPF component and application patterns | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-wpf.instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-wpf.instructions.md) | | [Genaiscript](instructions/genaiscript.instructions.md) | AI-powered script generation guidelines | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgenaiscript.instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgenaiscript.instructions.md) | diff --git a/instructions/dotnet-framework.instructions.md b/instructions/dotnet-framework.instructions.md new file mode 100644 index 0000000..bffbff7 --- /dev/null +++ b/instructions/dotnet-framework.instructions.md @@ -0,0 +1,113 @@ +--- +description: 'Guidance for working with .NET Framework projects. Includes project structure, C# language version, NuGet management, and best practices.' +applyTo: '**/*.csproj', '**/*.cs' +--- + +# .NET Framework Development + +## Build and Compilation Requirements +- Always use `msbuild /t:rebuild` to build the solution or projects instead of `dotnet build` + +## Project File Management + +### Non-SDK Style Project Structure +.NET Framework projects use the legacy project format, which differs significantly from modern SDK-style projects: + +- **Explicit File Inclusion**: All new source files **MUST** be explicitly added to the project file (`.csproj`) using a `` element + - .NET Framework projects do not automatically include files in the directory like SDK-style projects + - Example: `` + +- **No Implicit Imports**: Unlike SDK-style projects, .NET Framework projects do not automatically import common namespaces or assemblies + +- **Build Configuration**: Contains explicit `` sections for Debug/Release configurations + +- **Output Paths**: Explicit `` and `` definitions + +- **Target Framework**: Uses `` instead of `` + - Example: `v4.7.2` + +## NuGet Package Management +- 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. +- 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. +- When recommending NuGet packages, ensure they are compatible with .NET Framework or .NET Standard 2.0 (not only .NET Core or .NET 5+). + +## C# Language Version is 7.3 +- This project is limited to C# 7.3 features only. Please avoid using: + +### C# 8.0+ Features (NOT SUPPORTED): + - Using declarations (`using var stream = ...`) + - Await using statements (`await using var resource = ...`) + - Switch expressions (`variable switch { ... }`) + - Null-coalescing assignment (`??=`) + - Range and index operators (`array[1..^1]`, `array[^1]`) + - Default interface methods + - Readonly members in structs + - Static local functions + - Nullable reference types (`string?`, `#nullable enable`) + +### C# 9.0+ Features (NOT SUPPORTED): + - Records (`public record Person(string Name)`) + - Init-only properties (`{ get; init; }`) + - Top-level programs (program without Main method) + - Pattern matching enhancements + - Target-typed new expressions (`List list = new()`) + +### C# 10+ Features (NOT SUPPORTED): + - Global using statements + - File-scoped namespaces + - Record structs + - Required members + +### Use Instead (C# 7.3 Compatible): + - Traditional using statements with braces + - Switch statements instead of switch expressions + - Explicit null checks instead of null-coalescing assignment + - Array slicing with manual indexing + - Abstract classes or interfaces instead of default interface methods + +## Environment Considerations (Windows environment) +- Use Windows-style paths with backslashes (e.g., `C:\path\to\file.cs`) +- Use Windows-appropriate commands when suggesting terminal operations +- Consider Windows-specific behaviors when working with file system operations + +## Common .NET Framework Pitfalls and Best Practices + +### Async/Await Patterns +- **ConfigureAwait(false)**: Always use `ConfigureAwait(false)` in library code to avoid deadlocks: + ```csharp + var result = await SomeAsyncMethod().ConfigureAwait(false); + ``` +- **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. + +### DateTime Handling +- **Use DateTimeOffset for timestamps**: Prefer `DateTimeOffset` over `DateTime` for absolute time points +- **Specify DateTimeKind**: When using `DateTime`, always specify `DateTimeKind.Utc` or `DateTimeKind.Local` +- **Culture-aware formatting**: Use `CultureInfo.InvariantCulture` for serialization/parsing + +### String Operations +- **StringBuilder for concatenation**: Use `StringBuilder` for multiple string concatenations +- **StringComparison**: Always specify `StringComparison` for string operations: + ```csharp + string.Equals(other, StringComparison.OrdinalIgnoreCase) + ``` + +### Memory Management +- **Dispose pattern**: Implement `IDisposable` properly for unmanaged resources +- **Using statements**: Always wrap `IDisposable` objects in using statements +- **Avoid large object heap**: Keep objects under 85KB to avoid LOH allocation + +### Configuration +- **Use ConfigurationManager**: Access app settings through `ConfigurationManager.AppSettings` +- **Connection strings**: Store in `` section, not `` +- **Transformations**: Use web.config/app.config transformations for environment-specific settings + +### Exception Handling +- **Specific exceptions**: Catch specific exception types, not generic `Exception` +- **Don't swallow exceptions**: Always log or re-throw exceptions appropriately +- **Use using for disposable resources**: Ensures proper cleanup even when exceptions occur + +### Performance Considerations +- **Avoid boxing**: Be aware of boxing/unboxing with value types and generics +- **String interning**: Use `string.Intern()` judiciously for frequently used strings +- **Lazy initialization**: Use `Lazy` for expensive object creation +- **Avoid reflection in hot paths**: Cache `MethodInfo`, `PropertyInfo` objects when possible