diff --git a/CLAUDE.md b/CLAUDE.md index 9b4ad27..07c9886 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,11 +15,12 @@ dotnet restore # Build the entire solution dotnet build -# Run all tests -dotnet test +# Run all tests (requires framework specification for MTP) +dotnet run --project test/LayeredCraft.DecoWeaver.Generator.Tests/LayeredCraft.DecoWeaver.Generator.Tests.csproj --framework net8.0 -# Run tests with detailed output -dotnet test --logger "console;verbosity=detailed" +# Run tests on specific framework +dotnet run --project test/LayeredCraft.DecoWeaver.Generator.Tests/LayeredCraft.DecoWeaver.Generator.Tests.csproj --framework net9.0 +dotnet run --project test/LayeredCraft.DecoWeaver.Generator.Tests/LayeredCraft.DecoWeaver.Generator.Tests.csproj --framework net10.0 # Build in release mode dotnet build -c Release @@ -28,6 +29,8 @@ dotnet build -c Release dotnet clean ``` +**Note**: The test project uses Microsoft Testing Platform (MTP) and targets multiple frameworks (net8.0, net9.0, net10.0), so you must specify the `--framework` flag when running tests. + ## Project Structure The solution contains four main projects: diff --git a/README.md b/README.md index f8dfa72..35b171b 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ DecoWeaver is a .NET incremental source generator that brings **compile-time dec Install the NuGet package: ```bash -dotnet add package DecoWeaver +dotnet add package DecoWeaver --prerelease ``` Ensure your project uses C# 11 or later: @@ -96,7 +96,6 @@ Key sections: - [Core Concepts](https://layeredcraft.github.io/decoweaver/core-concepts/how-it-works/) - Understand how it works - [Usage Guide](https://layeredcraft.github.io/decoweaver/usage/class-level-decorators/) - Detailed usage patterns - [Examples](https://layeredcraft.github.io/decoweaver/examples/) - Real-world scenarios -- [Troubleshooting](https://layeredcraft.github.io/decoweaver/advanced/troubleshooting/) - Common issues and solutions ## Contributing diff --git a/docs/advanced/keyed-services.md b/docs/advanced/keyed-services.md new file mode 100644 index 0000000..26005d0 --- /dev/null +++ b/docs/advanced/keyed-services.md @@ -0,0 +1,30 @@ +# Keyed Services Strategy + +!!! info "Coming Soon" + This documentation is under development. Check back soon for detailed information about how DecoWeaver uses keyed services internally. + +## Overview + +This page will cover: + +- How DecoWeaver uses .NET 8.0+ keyed services to prevent circular dependencies +- The internal keying strategy for undecorated implementations +- Why keyed services are necessary for decorator chains +- Performance implications + +## Planned Content + +- [ ] Keyed services architecture explanation +- [ ] Key format and naming conventions +- [ ] How the generator creates keyed registrations +- [ ] Resolving decorated vs undecorated instances +- [ ] Troubleshooting keyed service issues + +## Requirements + +DecoWeaver requires .NET 8.0+ runtime specifically because it leverages the keyed services feature introduced in that version for its internal implementation. + +## See Also + +- [How It Works](../core-concepts/how-it-works.md) - Understanding the generation process +- [Interceptors](interceptors.md) - How interceptors redirect DI calls diff --git a/docs/advanced/performance.md b/docs/advanced/performance.md new file mode 100644 index 0000000..35e0003 --- /dev/null +++ b/docs/advanced/performance.md @@ -0,0 +1,38 @@ +# Performance + +!!! info "Coming Soon" + This documentation is under development. Check back soon for performance benchmarks and optimization guidance. + +## Overview + +This page will cover: + +- Build-time performance characteristics +- Runtime performance compared to reflection-based decorators +- Memory footprint analysis +- Benchmarks and comparisons +- Performance optimization tips + +## Planned Content + +- [ ] Build-time generation performance metrics +- [ ] Runtime overhead analysis (spoiler: zero!) +- [ ] Comparison with reflection-based decorator libraries +- [ ] Comparison with manual factory registration +- [ ] Memory allocation analysis +- [ ] Performance best practices +- [ ] Benchmarking methodology + +## Key Performance Features + +DecoWeaver is designed for zero runtime overhead: + +- **No reflection** - All decorator wiring happens at compile time +- **No assembly scanning** - Interceptors redirect specific call sites only +- **No runtime registration** - DI container configured at build time via generated code +- **Incremental generation** - Only regenerates when source changes + +## See Also + +- [How It Works](../core-concepts/how-it-works.md) - Understanding compile-time generation +- [Requirements](../getting-started/requirements.md) - Runtime and SDK requirements diff --git a/docs/advanced/troubleshooting.md b/docs/advanced/troubleshooting.md new file mode 100644 index 0000000..be2627d --- /dev/null +++ b/docs/advanced/troubleshooting.md @@ -0,0 +1,53 @@ +# Troubleshooting + +!!! info "Coming Soon" + This documentation is under development. Check back soon for common issues and solutions. + +## Overview + +This page will provide solutions to common problems encountered when using DecoWeaver. + +## Planned Content + +- [ ] Generator not running +- [ ] Decorators not being applied +- [ ] Circular dependency errors +- [ ] Generic type resolution issues +- [ ] C# language version errors +- [ ] IDE integration issues +- [ ] Build warnings and how to resolve them +- [ ] Diagnostic error codes (DECOW###) + +## Quick Diagnostics + +While detailed troubleshooting content is being developed, here are some quick checks: + +### Verify Installation +```bash +dotnet list package | grep DecoWeaver +``` + +### Check Generated Files +Look in `obj/Debug/{targetFramework}/generated/DecoWeaver/` for generated interceptor code. + +### Verify C# Version +Ensure your project targets C# 11 or later: +```xml +11 +``` + +### Check Build Output +Look for DecoWeaver diagnostics with code `DECOW###` in build output. + +## Getting Help + +If you encounter issues not covered here: + +1. Check existing [GitHub Issues](https://github.com/LayeredCraft/decoweaver/issues) +2. Review the [Requirements](../getting-started/requirements.md) page +3. Open a new issue with reproduction steps + +## See Also + +- [Requirements](../getting-started/requirements.md) - Prerequisites and configuration +- [How It Works](../core-concepts/how-it-works.md) - Understanding the generation process diff --git a/docs/api-reference/generated-code.md b/docs/api-reference/generated-code.md new file mode 100644 index 0000000..4dc1dab --- /dev/null +++ b/docs/api-reference/generated-code.md @@ -0,0 +1,43 @@ +# Generated Code + +!!! info "Coming Soon" + This documentation is under development. Check back soon for detailed information about the structure of generated interceptor code. + +## Overview + +This page will cover: + +- Structure of generated interceptor files +- How interceptors redirect DI registration calls +- Understanding `[InterceptsLocation]` attributes +- Generated factory methods for decorator chains +- Keyed service registration patterns + +## Planned Content + +- [ ] File naming and organization (`DecoWeaver.Interceptors.ClosedGenerics.g.cs`) +- [ ] Interceptor method signatures +- [ ] `[InterceptsLocation]` attribute usage +- [ ] Factory pattern for applying decorators +- [ ] Keyed service registration code +- [ ] How to read and debug generated code +- [ ] Generated code versioning + +## Locating Generated Files + +Generated interceptor code can be found in: +``` +obj/Debug/{targetFramework}/generated/DecoWeaver/DecoWeaver.Generator/DecoWeaver.Interceptors.ClosedGenerics.g.cs +``` + +## IDE Support for Generated Files + +- **Visual Studio 2022**: Enable "Show generated files" in Solution Explorer options +- **JetBrains Rider**: Files appear under "Generated Files" node +- **VS Code**: Generated files visible in obj/ directory + +## See Also + +- [Interceptors](../advanced/interceptors.md) - Understanding C# 11+ interceptors +- [How It Works](../core-concepts/how-it-works.md) - Generation process overview +- [Keyed Services](../advanced/keyed-services.md) - Internal keyed services strategy diff --git a/docs/contributing.md b/docs/contributing.md index 7388435..de94ab1 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -81,9 +81,11 @@ We welcome pull requests for: 5. **Run tests** ```bash - dotnet test + dotnet run --project test/LayeredCraft.DecoWeaver.Generator.Tests/LayeredCraft.DecoWeaver.Generator.Tests.csproj --framework net8.0 ``` + Note: The test project uses Microsoft Testing Platform (MTP) and targets multiple frameworks, so you must specify the framework. + ## Project Structure ``` @@ -180,7 +182,7 @@ public async Task Generator_AppliesDecorators_ForClassWithAttribute( 1. **Ensure all tests pass** ```bash - dotnet test + dotnet run --project test/LayeredCraft.DecoWeaver.Generator.Tests/LayeredCraft.DecoWeaver.Generator.Tests.csproj --framework net8.0 ``` 2. **Build successfully** @@ -249,15 +251,17 @@ refactor: simplify decorator resolution logic ### Running Tests +The test project uses Microsoft Testing Platform (MTP) and targets multiple frameworks (net8.0, net9.0, net10.0), so you must specify the framework when running tests: + ```bash -# Run all tests -dotnet test +# Run all tests (net8.0) +dotnet run --project test/LayeredCraft.DecoWeaver.Generator.Tests/LayeredCraft.DecoWeaver.Generator.Tests.csproj --framework net8.0 -# Run specific test -dotnet test --filter "FullyQualifiedName~DecoWeaverGeneratorTests.Generator_AppliesDecorators" +# Run tests on net9.0 +dotnet run --project test/LayeredCraft.DecoWeaver.Generator.Tests/LayeredCraft.DecoWeaver.Generator.Tests.csproj --framework net9.0 -# Run with verbose output -dotnet test --logger "console;verbosity=detailed" +# Run tests on net10.0 +dotnet run --project test/LayeredCraft.DecoWeaver.Generator.Tests/LayeredCraft.DecoWeaver.Generator.Tests.csproj --framework net10.0 ``` ### Adding Test Cases diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index f4834b7..2ab57ff 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -5,21 +5,23 @@ Install DecoWeaver via the .NET CLI: ```bash -dotnet add package DecoWeaver +dotnet add package DecoWeaver --prerelease ``` Or via Package Manager Console in Visual Studio: ```powershell -Install-Package DecoWeaver +Install-Package DecoWeaver -Prerelease ``` Or add directly to your `.csproj` file: ```xml - + ``` +Note: The full version includes a build number suffix added by the build system (e.g., `1.0.0-beta.123`). + ## Package Contents The DecoWeaver NuGet package includes: diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md index cb85519..8172179 100644 --- a/docs/getting-started/quick-start.md +++ b/docs/getting-started/quick-start.md @@ -5,7 +5,7 @@ Get started with DecoWeaver in 5 minutes by creating a simple logging decorator. ## Step 1: Install DecoWeaver ```bash -dotnet add package DecoWeaver +dotnet add package DecoWeaver --prerelease ``` ## Step 2: Create Your Service diff --git a/docs/index.md b/docs/index.md index 502b911..6ecf23e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -19,7 +19,7 @@ ## Installation ```bash -dotnet add package DecoWeaver +dotnet add package DecoWeaver --prerelease ``` ## Quick Start diff --git a/docs/usage/opt-out.md b/docs/usage/opt-out.md new file mode 100644 index 0000000..dba7315 --- /dev/null +++ b/docs/usage/opt-out.md @@ -0,0 +1,25 @@ +# Opt-Out Mechanisms + +!!! info "Coming Soon" + This documentation is under development. Check back soon for information about opting out of decorator application. + +## Overview + +This page will cover: + +- How to exclude specific decorators from being applied +- Global opt-out mechanisms +- Surgical opt-out for specific scenarios +- Use cases for opting out of decoration + +## Planned Content + +- [ ] Opt-out attribute usage +- [ ] Per-decorator exclusions +- [ ] Assembly-level opt-out mechanisms (Phase 2) +- [ ] Best practices for when to use opt-outs + +## See Also + +- [Class-Level Decorators](class-level-decorators.md) - Learn about applying decorators +- [Multiple Decorators](multiple-decorators.md) - Managing multiple decorators diff --git a/src/LayeredCraft.DecoWeaver.Generators/LayeredCraft.DecoWeaver.Generators.csproj b/src/LayeredCraft.DecoWeaver.Generators/LayeredCraft.DecoWeaver.Generators.csproj index 9099877..eba7850 100644 --- a/src/LayeredCraft.DecoWeaver.Generators/LayeredCraft.DecoWeaver.Generators.csproj +++ b/src/LayeredCraft.DecoWeaver.Generators/LayeredCraft.DecoWeaver.Generators.csproj @@ -10,8 +10,8 @@ $(PackageId) $(PackageId) $(PackageId) - DecoWeaver is a .NET incremental source generator that enables compile-time decorator registration using C# 11+ interceptors. Zero runtime overhead, type-safe decorator chains, and full open generic support for .NET dependency injection. - source-generator;roslyn;dependency-injection;decorator-pattern;interceptors;compile-time;aop;di;ioc;dotnet + DecoWeaver is a .NET incremental source generator that enables compile-time decorator registration using C# 11+ interceptors. Zero runtime overhead, type-safe decorator chains, and support for closed generic registrations in .NET dependency injection. + source-generator;roslyn;dependency-injection;decorator-pattern;interceptors;compile-time;aop;di;ioc;dotnet;csharp;decorators;code-generation;cross-cutting;performance true