Skip to content

Commit b83d348

Browse files
Copilothazzik
Copilot
and
hazzik
committed
Add comprehensive Copilot instructions for DelegateDecompiler
Co-authored-by: hazzik <144791+hazzik@users.noreply.github.com>
1 parent 9e4ed51 commit b83d348

File tree

1 file changed

+186
-0
lines changed

1 file changed

+186
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# DelegateDecompiler - GitHub Copilot Instructions
2+
3+
## Project Overview
4+
5+
DelegateDecompiler is a .NET library that decompiles delegates and method bodies to their lambda representation. It enables computed properties in LINQ queries by translating `[Computed]` attributes into executable expressions that can be processed by Entity Framework and other ORMs.
6+
7+
### Key Purpose
8+
- Convert method implementations marked with `[Computed]` attribute into LINQ expressions
9+
- Enable complex computed properties in database queries
10+
- Support multiple Entity Framework versions and .NET Framework/Core versions
11+
- Provide IL (Intermediate Language) decompilation capabilities using Mono.Reflection
12+
13+
## Project Structure
14+
15+
```
16+
src/
17+
├── DelegateDecompiler/ # Core library
18+
├── DelegateDecompiler.EntityFramework/ # EF 6.x support
19+
├── DelegateDecompiler.EntityFrameworkCore5/ # EF Core 5 support
20+
├── DelegateDecompiler.EntityFrameworkCore6.Tests/ # EF Core 6 tests
21+
├── DelegateDecompiler.EntityFrameworkCore8.Tests/ # EF Core 8 tests
22+
├── DelegateDecompiler.EntityFrameworkCore9.Tests/ # EF Core 9 tests
23+
├── DelegateDecompiler.EntityFramework.Tests/ # EF 6.x tests
24+
├── DelegateDecompiler.Tests/ # Core library tests
25+
└── DelegateDecompiler.Tests.VB/ # VB.NET tests
26+
```
27+
28+
## Core Components
29+
30+
### Main Library (`DelegateDecompiler/`)
31+
- **`ComputedAttribute`**: Marks properties/methods for decompilation
32+
- **`MethodBodyDecompiler`**: Core IL decompilation engine
33+
- **`DecompileExtensions`**: Public API for decompiling delegates/queries
34+
- **`DecompileExpressionVisitor`**: Expression tree visitor for transformation
35+
- **`Processors/`**: Pluggable processors for different IL opcodes
36+
37+
### Key Concepts
38+
- **Computed Properties**: Properties marked with `[Computed]` that are decompiled at runtime
39+
- **IL Decompilation**: Converting CIL bytecode back to expression trees
40+
- **Expression Visitors**: Classes that traverse and transform expression trees
41+
- **Processor Architecture**: Modular system for handling different IL instructions
42+
43+
## Architecture Patterns
44+
45+
### Processor Pattern
46+
The library uses a pluggable processor architecture where each processor handles specific IL opcodes:
47+
- `ConstantProcessor`: Handles constant values
48+
- `LdfldProcessor`: Handles field loading
49+
- `ConvertProcessor`: Handles type conversions
50+
- `UnaryExpressionProcessor`: Handles unary operations
51+
52+
### Expression Visitor Pattern
53+
Multiple expression visitors handle different transformation aspects:
54+
- `DecompileExpressionVisitor`: Main decompilation logic
55+
- `OptimizeExpressionVisitor`: Optimizes generated expressions
56+
- `ReplaceExpressionVisitor`: Replaces expression nodes
57+
58+
## Testing Strategy
59+
60+
### Test Organization
61+
Tests are organized by functionality and Entity Framework version:
62+
63+
1. **Core Tests** (`DelegateDecompiler.Tests/`):
64+
- Unit tests for decompilation engine
65+
- Tests for specific language features (closures, generics, etc.)
66+
- Issue regression tests (Issue13.cs, Issue67.cs, etc.)
67+
68+
2. **Entity Framework Tests**:
69+
- Structured test groups using naming conventions
70+
- `TestGroup##` directories for categorization
71+
- Automatic documentation generation from test results
72+
73+
### Test Naming Conventions
74+
- Test groups: `TestGroup##Description` (e.g., `TestGroup05BasicFeatures`)
75+
- Test files: `Test##Description.cs` (e.g., `Test01Select.cs`)
76+
- Test methods: `Test##Description` where ## provides ordering
77+
78+
### Documentation Generation
79+
The EF test projects automatically generate documentation:
80+
- `SummaryOfSupportedCommands.md`: High-level feature support
81+
- `DetailedListOfSupportedCommands.md`: Detailed test results
82+
- `DetailedListOfSupportedCommandsWithSQL.md`: Includes SQL output
83+
84+
## Development Guidelines
85+
86+
### Code Style
87+
- C# 12.0 language features enabled
88+
- Assembly signing with `DelegateDecompiler.snk`
89+
- Treat warnings as errors (`TreatWarningsAsErrors=True`)
90+
- EditorConfig defines naming conventions (PascalCase for types, interfaces start with 'I')
91+
92+
### Target Frameworks
93+
- .NET Framework 4.0, 4.5
94+
- .NET Standard 2.0, 2.1
95+
- .NET 8.0, 9.0 for tests
96+
97+
### Dependencies
98+
- **Mono.Reflection**: Core IL reading capabilities
99+
- **NUnit**: Testing framework
100+
- **Entity Framework**: Various versions for ORM integration
101+
102+
## Build & Deployment
103+
104+
### Build Process
105+
- MSBuild-based with `Directory.Build.props` for common settings
106+
- GitVersion for automatic versioning
107+
- Strong-name signing for assemblies
108+
- NuGet package generation on build
109+
110+
### Scripts
111+
- `build.cmd`: Build the solution
112+
- `test.cmd`: Run all tests across frameworks
113+
- `!release.cmd`: Release process
114+
115+
### CI/CD
116+
- AppVeyor for continuous integration
117+
- Automatic NuGet package publishing
118+
- Support for multiple .NET versions
119+
120+
## Common Patterns for Contributors
121+
122+
### Adding New Features
123+
1. Add core logic to `DelegateDecompiler/` project
124+
2. Create unit tests in `DelegateDecompiler.Tests/`
125+
3. Add Entity Framework integration tests if applicable
126+
4. Update README.md with examples if it's a public feature
127+
128+
### Adding IL Processor Support
129+
1. Create new processor class implementing `IProcessor`
130+
2. Add to processor registration in main decompiler
131+
3. Add comprehensive tests covering edge cases
132+
4. Document supported IL opcodes
133+
134+
### Adding Entity Framework Support
135+
1. Follow existing test group naming conventions
136+
2. Create test methods that compare LINQ vs Decompiled results
137+
3. Use `CompareAndLogSingleton`/`CompareAndLogList` for validation
138+
4. Tests automatically generate documentation
139+
140+
## Debugging Tips
141+
142+
### Common Issues
143+
- **IL Decompilation Failures**: Check if method contains unsupported IL opcodes
144+
- **Expression Tree Complexity**: Some compiler optimizations may not be supported
145+
- **Entity Framework Translation**: Not all decompiled expressions translate to SQL
146+
147+
### Debug Information
148+
- Enable `Microsoft.NETFramework.ReferenceAssemblies` for multi-targeting
149+
- Use `ContinuousIntegrationBuild` for reproducible builds
150+
- Source link enabled for debugging into source
151+
152+
## Testing Specific Guidance
153+
154+
### Entity Framework Test Patterns
155+
```csharp
156+
[Test]
157+
public void TestFeatureName()
158+
{
159+
var env = new EfTestContext();
160+
161+
// Test LINQ version first
162+
var linqResult = env.Database.Items
163+
.Where(x => x.SomeProperty == "value")
164+
.Select(x => x.ComputedProperty);
165+
166+
// Signal switch to decompiled version
167+
env.AboutToUseDelegateDecompiler();
168+
169+
// Test decompiled version
170+
var decompiled = env.Database.Items
171+
.Where(x => x.SomeProperty == "value")
172+
.Select(x => x.ComputedProperty)
173+
.Decompile();
174+
175+
// Compare results
176+
env.CompareAndLogList(linqResult, decompiled);
177+
}
178+
```
179+
180+
### Documentation Generation
181+
- Tests automatically generate markdown documentation
182+
- Use descriptive test names as they appear in docs
183+
- Group related functionality in same test group
184+
- Test failures help identify unsupported scenarios
185+
186+
This project requires careful attention to IL decompilation accuracy, Entity Framework compatibility, and comprehensive testing across multiple .NET versions.

0 commit comments

Comments
 (0)