|
| 1 | +# ResultR VS Code Toolkit |
| 2 | + |
| 3 | +Supercharge your ResultR development workflow with instant navigation from requests to handlers and one-click scaffolding of new request/handler pairs. The ResultR VS Code Toolkit is the essential companion extension for developers using the ResultR library. |
| 4 | + |
| 5 | +## Installation |
| 6 | + |
| 7 | +### From VS Code Marketplace |
| 8 | + |
| 9 | +1. Open VS Code |
| 10 | +2. Go to **Extensions** (Ctrl+Shift+X) |
| 11 | +3. Search for "ResultR" |
| 12 | +4. Click **Install** |
| 13 | + |
| 14 | +### From GitHub Releases |
| 15 | + |
| 16 | +1. Download the `.vsix` file from the [releases page](https://github.com/AlanBarber/ResultR/releases) |
| 17 | +2. Install via command line: `code --install-extension ResultR.VSCodeToolkit.x.x.x.vsix` |
| 18 | + |
| 19 | +### From Open VSX Registry |
| 20 | + |
| 21 | +The extension is also available on [Open VSX](https://open-vsx.org) for VS Code forks like VSCodium. |
| 22 | + |
| 23 | +## Requirements |
| 24 | + |
| 25 | +- VS Code 1.85.0 or later |
| 26 | +- Projects using the [ResultR](https://www.nuget.org/packages/ResultR) library |
| 27 | + |
| 28 | +## Features |
| 29 | + |
| 30 | +### Go to Handler Navigation |
| 31 | + |
| 32 | +Instantly navigate from any `IRequest` or `IRequest<T>` type to its corresponding handler implementation. |
| 33 | + |
| 34 | +#### How to Use |
| 35 | + |
| 36 | +1. Place your cursor on any `IRequest` type (variable, parameter, or class definition) |
| 37 | +2. Use one of these methods: |
| 38 | + - **Keyboard**: Press `Ctrl+R, Ctrl+H` |
| 39 | + - **Command Palette**: `ResultR: Go to Handler` |
| 40 | + - **Context Menu**: Right-click and select **"Go to Handler..."** |
| 41 | + |
| 42 | +#### What It Finds |
| 43 | + |
| 44 | +The toolkit searches your entire workspace for handlers that implement: |
| 45 | +- `IRequestHandler<TRequest>` for `IRequest` types |
| 46 | +- `IRequestHandler<TRequest, TResponse>` for `IRequest<TResponse>` types |
| 47 | + |
| 48 | +It works across projects, so your handler can be in a completely different folder or project. |
| 49 | + |
| 50 | +#### Example |
| 51 | + |
| 52 | +```csharp |
| 53 | +// Place cursor on HelloWorldRequest and press Ctrl+R, Ctrl+H |
| 54 | +var request = new HelloWorldRequest(); |
| 55 | +var result = await dispatcher.Dispatch(request); |
| 56 | +``` |
| 57 | + |
| 58 | +The toolkit will navigate to: |
| 59 | + |
| 60 | +```csharp |
| 61 | +public class HelloWorldHandler : IRequestHandler<HelloWorldRequest> |
| 62 | +{ |
| 63 | + public async ValueTask<Result> HandleAsync(HelloWorldRequest request, CancellationToken cancellationToken) |
| 64 | + { |
| 65 | + // Handler implementation |
| 66 | + } |
| 67 | +} |
| 68 | +``` |
| 69 | + |
| 70 | +### Scaffold Request/Handler Pairs |
| 71 | + |
| 72 | +Quickly create new request and handler classes with proper namespaces and structure. |
| 73 | + |
| 74 | +#### How to Use |
| 75 | + |
| 76 | +1. In the **Explorer**, right-click on a folder |
| 77 | +2. Select **"ResultR: New Request/Handler"** |
| 78 | +3. Enter the request name (e.g., "HelloWorld") |
| 79 | +4. Press Enter |
| 80 | + |
| 81 | +Or use the Command Palette: |
| 82 | +1. Press `Ctrl+Shift+P` |
| 83 | +2. Type "ResultR: New Request/Handler" |
| 84 | +3. Select the target folder |
| 85 | +4. Enter the request name |
| 86 | + |
| 87 | +#### What Gets Generated |
| 88 | + |
| 89 | +The toolkit creates a single `.cs` file containing both the request and handler: |
| 90 | + |
| 91 | +```csharp |
| 92 | +using ResultR; |
| 93 | + |
| 94 | +namespace HelloWorldApp; |
| 95 | + |
| 96 | +public record HelloWorldRequest() : IRequest; |
| 97 | + |
| 98 | +public class HelloWorldHandler : IRequestHandler<HelloWorldRequest> |
| 99 | +{ |
| 100 | + public async ValueTask<Result> HandleAsync(HelloWorldRequest request, CancellationToken cancellationToken) |
| 101 | + { |
| 102 | + throw new NotImplementedException(); |
| 103 | + } |
| 104 | +} |
| 105 | +``` |
| 106 | + |
| 107 | +#### Smart Namespace Detection |
| 108 | + |
| 109 | +The toolkit automatically: |
| 110 | +- Detects your project's namespace conventions from existing files |
| 111 | +- Uses file-scoped namespaces if your project uses them |
| 112 | +- Uses block-scoped namespaces if that's your convention |
| 113 | +- Derives the namespace from the folder structure and project name |
| 114 | + |
| 115 | +## Keyboard Shortcuts |
| 116 | + |
| 117 | +| Action | Shortcut | |
| 118 | +|--------|----------| |
| 119 | +| Go to Handler | `Ctrl+R, Ctrl+H` | |
| 120 | + |
| 121 | +## Commands |
| 122 | + |
| 123 | +| Command | Description | |
| 124 | +|---------|-------------| |
| 125 | +| `ResultR: Go to Handler` | Navigate to the handler for the request under cursor | |
| 126 | +| `ResultR: New Request/Handler` | Create a new request/handler pair | |
| 127 | + |
| 128 | +## Troubleshooting |
| 129 | + |
| 130 | +### "No handler found" message |
| 131 | + |
| 132 | +This can happen if: |
| 133 | +- The handler doesn't exist yet |
| 134 | +- The handler is in a folder excluded from search |
| 135 | +- The handler doesn't implement the correct interface |
| 136 | + |
| 137 | +### Navigation goes to wrong handler |
| 138 | + |
| 139 | +Ensure your handler implements the exact interface for your request type. For example: |
| 140 | +- `GetUserRequest : IRequest<User>` should have a handler implementing `IRequestHandler<GetUserRequest, User>` |
| 141 | + |
| 142 | +### Scaffold command not working |
| 143 | + |
| 144 | +- Make sure you have a folder selected or right-clicked |
| 145 | +- Ensure the workspace contains C# files for namespace detection |
| 146 | + |
| 147 | +## Configuration |
| 148 | + |
| 149 | +The extension works out of the box with sensible defaults. It automatically excludes common folders like `bin`, `obj`, and `node_modules` from searches. |
| 150 | + |
| 151 | +## Links |
| 152 | + |
| 153 | +- [ResultR on NuGet](https://www.nuget.org/packages/ResultR) |
| 154 | +- [ResultR.Validation on NuGet](https://www.nuget.org/packages/ResultR.Validation) |
| 155 | +- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=AlanBarber.ResultR-VSCodeToolkit) |
0 commit comments