Cursor rule

1---
2description: Async/await and threading patterns for WPF UI updates
3globs: ["**/*.cs"]
4alwaysApply: true
5---
6 
7# Async/Await and Threading Patterns
8 
9## UI Thread Updates
10 
11### Dispatcher Pattern
12**CRITICAL**: All UI updates must happen on the UI thread. Use `Dispatcher.Invoke()` or `Dispatcher.InvokeAsync()` when updating UI from background threads.
13 
14```csharp
15// From background thread - update UI
16Application.Current.Dispatcher.Invoke(() =>
17{
18    StatusText.Text = "Processing...";
19    StatusText.Foreground = Brushes.Blue;
20});
21 
22// Async version (non-blocking)
23await Application.Current.Dispatcher.InvokeAsync(() =>
24{
25    StatusText.Text = "Complete";
26});
27```
28 
29### Dispatcher Priority
30- Use `DispatcherPriority.Background` for non-urgent updates
31- Use `DispatcherPriority.Normal` (default) for standard updates
32- Use `DispatcherPriority.Send` only when absolutely necessary
33 
34```csharp
35Dispatcher.Invoke(() =>
36{
37    // Update UI
38}, DispatcherPriority.Background);
39```
40 
41## Async Service Methods
42 
43### Translation Services
44All translation services implement async methods:
45 
46```csharp
47public interface ITranslationService
48{
49    Task<TranslationResult?> TranslateAsync(
50        string sourceText,
51        string targetLanguage,
52        string context);
53}
54```
55 
56### Implementation Pattern
57```csharp
58public async Task<TranslationResult?> TranslateAsync(string text, string lang, string context)
59{
60    try
61    {
62        using var httpClient = new HttpClient();
63        var response = await httpClient.PostAsync(url, content);
64        
65        if (response.IsSuccessStatusCode)
66        {
67            var result = await response.Content.ReadAsStringAsync();
68            return ParseResult(result);
69        }
70        
71        return null;
72    }
73    catch (Exception ex)
74    {
75        Console.WriteLine($"Translation error: {ex.Message}");
76        return null;
77    }
78}
79```
80 
81## Background Operations
82 
83### Screen Capture
84Screen capture runs on background thread/timer:
85 
86```csharp
87private void Timer_Tick(object sender, EventArgs e)
88{
89    // Capture runs on timer thread
90    var bitmap = CaptureScreen(x, y, width, height);
91    
92    // Process on background thread
93    Task.Run(async () =>
94    {
95        var result = await ProcessImageAsync(bitmap);
96        
97        // Update UI on UI thread
98        Application.Current.Dispatcher.Invoke(() =>
99        {
100            UpdateDisplay(result);
101        });
102    });
103}
104```
105 
106### OCR Processing
107OCR operations should be async and non-blocking:
108 
109```csharp
110private async Task<List<TextObject>> ProcessOCRAsync(Bitmap bitmap)
111{
112    // Run OCR on background thread
113    return await Task.Run(() =>
114    {
115        // OCR processing
116        return ocrService.Process(bitmap);
117    });
118}
119```
120 
121## HttpClient Usage
122 
123### Best Practices
124- **DO NOT** create new HttpClient instances for each request
125- Create HttpClient once and reuse (or use HttpClientFactory)
126- Dispose properly with `using` statement
127 
128```csharp
129// Good: Reuse HttpClient
130private static readonly HttpClient _httpClient = new HttpClient();
131 
132public async Task<string> GetDataAsync()
133{
134    var response = await _httpClient.GetAsync(url);
135    return await response.Content.ReadAsStringAsync();
136}
137 
138// Or use using for one-off requests
139public async Task<string> GetDataAsync()
140{
141    using var client = new HttpClient();
142    var response = await client.GetAsync(url);
143    return await response.Content.ReadAsStringAsync();
144}
145```
146 
147## Task Cancellation
148 
149### Cancellation Tokens
150Use `CancellationToken` for long-running operations:
151 
152```csharp
153public async Task ProcessAsync(CancellationToken cancellationToken)
154{
155    while (!cancellationToken.IsCancellationRequested)
156    {
157        await DoWorkAsync();
158        await Task.Delay(1000, cancellationToken);
159    }
160}
161```
162 
163## Thread Safety
164 
165### Singleton Thread Safety
166Simple null-check pattern is sufficient for this application:
167 
168```csharp
169private static ConfigManager? _instance;
170private static readonly object _lock = new object();
171 
172public static ConfigManager Instance
173{
174    get
175    {
176        if (_instance == null)
177        {
178            lock (_lock)
179            {
180                if (_instance == null)
181                {
182                    _instance = new ConfigManager();
183                }
184            }
185        }
186        return _instance;
187    }
188}
189```
190 
191### Dictionary Access
192- Use `TryGetValue` for safe dictionary access
193- Check for null before using values
194 
195```csharp
196if (_configValues.TryGetValue(key, out var value))
197{
198    return value;
199}
200return defaultValue;
201```
202 
203## Blocking vs Non-Blocking
204 
205### Avoid Blocking UI Thread
206- **NEVER** use `.Result` or `.Wait()` on async methods in UI code
207- Always use `await` for async operations
208- Use `Task.Run()` to move CPU-intensive work off UI thread
209 
210```csharp
211// BAD: Blocks UI thread
212var result = httpClient.GetAsync(url).Result;
213 
214// GOOD: Non-blocking
215var result = await httpClient.GetAsync(url);
216 
217// GOOD: Move work off UI thread
218var result = await Task.Run(() => ExpensiveOperation());
219```
220 
221## Exception Handling in Async
222 
223### Async Exception Handling
224Exceptions in async methods should be caught and logged:
225 
226```csharp
227public async Task<Result?> ProcessAsync()
228{
229    try
230    {
231        var result = await DoWorkAsync();
232        return result;
233    }
234    catch (Exception ex)
235    {
236        Console.WriteLine($"Error: {ex.Message}");
237        LogManager.Instance.LogError("Process failed", ex);
238        return null;
239    }
240}
241```
242 
243## Timer Usage
244 
245### WPF DispatcherTimer
246Use `DispatcherTimer` for UI-related timers:
247 
248```csharp
249private DispatcherTimer _timer;
250 
251private void InitializeTimer()
252{
253    _timer = new DispatcherTimer();
254    _timer.Interval = TimeSpan.FromMilliseconds(100);
255    _timer.Tick += Timer_Tick;
256    _timer.Start();
257}
258 
259private void Timer_Tick(object sender, EventArgs e)
260{
261    // Runs on UI thread
262    UpdateUI();
263}
264```
265 
266### System.Timers.Timer
267Use `System.Timers.Timer` for background operations:
268 
269```csharp
270private System.Timers.Timer _backgroundTimer;
271 
272private void InitializeBackgroundTimer()
273{
274    _backgroundTimer = new System.Timers.Timer(1000);
275    _backgroundTimer.Elapsed += BackgroundTimer_Elapsed;
276    _backgroundTimer.AutoReset = true;
277    _backgroundTimer.Start();
278}
279 
280private void BackgroundTimer_Elapsed(object sender, System.Timers.ElapsedEventArgs e)
281{
282    // Runs on background thread - use Dispatcher for UI updates
283    Task.Run(async () => await ProcessBackgroundWorkAsync());
284}
285```
286 
287## Progress Reporting
288 
289### Progress Updates
290Report progress from background threads:
291 
292```csharp
293private async Task ProcessWithProgressAsync(IProgress<int> progress)
294{
295    for (int i = 0; i < 100; i++)
296    {
297        await DoWorkAsync();
298        progress.Report(i);
299    }
300}
301 
302// Usage
303var progress = new Progress<int>(percent =>
304{
305    Application.Current.Dispatcher.Invoke(() =>
306    {
307        ProgressBar.Value = percent;
308    });
309});
310 
311await ProcessWithProgressAsync(progress);
312```
313