diff --git a/.planning/phases/01-foundation/01-RESEARCH.md b/.planning/phases/01-foundation/01-RESEARCH.md new file mode 100644 index 0000000..62296fd --- /dev/null +++ b/.planning/phases/01-foundation/01-RESEARCH.md @@ -0,0 +1,842 @@ +# Phase 1: Foundation - Research + +**Researched:** 2026-04-02 +**Domain:** WPF/.NET 10, MVVM, MSAL authentication, multi-tenant session management, structured logging, localization +**Confidence:** HIGH + +--- + + +## User Constraints (from CONTEXT.md) + +### Locked Decisions + +| Decision | Value | +|---|---| +| Runtime | .NET 10 LTS + WPF | +| MVVM framework | CommunityToolkit.Mvvm 8.4.2 | +| SharePoint library | PnP.Framework 1.18.0 | +| Auth | MSAL.NET 4.83.1 + Extensions.Msal 4.83.3 + Desktop 4.82.1 | +| Token cache | MsalCacheHelper — one `IPublicClientApplication` per ClientId | +| DI host | Microsoft.Extensions.Hosting 10.x | +| Logging | Serilog 4.3.1 + rolling file sink → `%AppData%\SharepointToolbox\logs\` | +| JSON | System.Text.Json (built-in) | +| JSON persistence | Write-then-replace (`file.tmp` → validate → `File.Move`) + `SemaphoreSlim(1)` per file | +| Async pattern | `AsyncRelayCommand` everywhere — zero `async void` handlers | +| Trimming | `PublishTrimmed=false` — accept ~150–200 MB EXE | +| Architecture | 4-layer MVVM: View → ViewModel → Service → Infrastructure | +| Cross-VM messaging | `WeakReferenceMessenger` for tenant-switched events | +| Session holder | Singleton `SessionManager` — only class that holds `ClientContext` objects | +| Localization | .resx resource files (EN default, FR overlay) | + +### Shell Layout (defaults applied — not re-litigatable) + +- `MainWindow` with top `ToolBar`, center `TabControl`, bottom docked `RichTextBox` log panel (150 px, always visible) +- `StatusBar` at very bottom: tenant name | operation status | progress % +- Toolbar (L→R): `ComboBox` (220 px, tenant list) → `Button "Connect"` → `Button "Manage Profiles..."` → separator → `Button "Clear Session"` +- Profile fields: Name, Tenant URL, Client ID — matches `{ name, tenantUrl, clientId }` JSON exactly +- All feature tabs stubbed with "Coming soon" placeholder except Settings (profile management + language) + +### Progress + Cancel UX (locked) + +- Per-tab: `ProgressBar` + `TextBlock` + `Button "Cancel"` — visible only when `IsRunning` +- `CancellationTokenSource` owned by each ViewModel, recreated per operation +- `IProgress` where `OperationProgress = { int Current, int Total, string Message }` +- Log panel writes every meaningful progress event (timestamped) +- `StatusBar` updates from active tab via `WeakReferenceMessenger` + +### Error Surface UX (locked) + +- Non-fatal: red log panel entry + per-tab status summary — no modal +- Fatal/blocking: `MessageBox.Show` modal + "Copy to Clipboard" button +- No toasts in Phase 1 +- Log format: `HH:mm:ss [LEVEL] Message` — green=info, orange=warning, red=error +- Global handlers: `Application.DispatcherUnhandledException` + `TaskScheduler.UnobservedTaskException` +- Empty catch block = build defect; enforced in code review + +### JSON Compatibility (locked — live user data) + +| File | Schema | +|---|---| +| `Sharepoint_Export_profiles.json` | `{ "profiles": [{ "name": "...", "tenantUrl": "...", "clientId": "..." }] }` | +| `Sharepoint_Settings.json` | `{ "dataFolder": "...", "lang": "en" }` | + +### Localization (locked) + +- `Strings.resx` (EN/neutral default), `Strings.fr.resx` (FR overlay) +- Key naming mirrors existing PowerShell convention: `tab.perms`, `btn.run.scan`, `menu.language`, etc. +- Dynamic switching: `CultureInfo.CurrentUICulture` swap + `WeakReferenceMessenger` broadcast +- FR strings stubbed with EN fallback in Phase 1 + +### Infrastructure Patterns (Phase 1 required deliverables) + +1. `SharePointPaginationHelper` — static helper wrapping `CamlQuery` + `ListItemCollectionPosition` looping, `RowLimit ≤ 2000` +2. `AsyncRelayCommand` canonical example — `FeatureViewModel` base showing `CancellationTokenSource` + `IsRunning` + `IProgress` + `OperationCanceledException` handling +3. `ObservableCollection` threading rule — accumulate in `List` on background, then `Dispatcher.InvokeAsync` with `new ObservableCollection(list)` +4. `ExecuteQueryRetryAsync` wrapper — wraps PnP Framework retry; surfaces retry events as log + progress messages +5. `ClientContext` disposal — always `await using`; unit tests verify `Dispose()` on cancellation + +### Deferred Ideas (OUT OF SCOPE for Phase 1) + +- Log panel collapsibility +- Dark/light theme toggle +- Toast/notification system +- FR locale completeness (Phase 5) +- User access export, storage charts, simplified permissions view + + +--- + + +## Phase Requirements + +| ID | Description | Research Support | +|----|-------------|-----------------| +| FOUND-01 | Application built with C#/WPF (.NET 10 LTS) using MVVM architecture | Generic Host DI pattern, CommunityToolkit.Mvvm ObservableObject/RelayCommand stack confirmed | +| FOUND-02 | Multi-tenant profile registry — create, rename, delete, switch tenant profiles | ProfileService using System.Text.Json + write-then-replace pattern; ComboBox bound to ObservableCollection | +| FOUND-03 | Multi-tenant session caching — stay authenticated across tenant switches | MsalCacheHelper per ClientId (one IPublicClientApplication per tenant), AcquireTokenSilent flow | +| FOUND-04 | Interactive Azure AD OAuth login via browser — no client secrets | MSAL PublicClientApplicationBuilder + AcquireTokenInteractive; PnP AuthenticationManager.CreateWithInteractiveLogin | +| FOUND-05 | All long-running operations report progress to the UI in real-time | IProgress + Progress (marshals to UI thread automatically) | +| FOUND-06 | User can cancel any long-running operation mid-execution | CancellationTokenSource per ViewModel; AsyncRelayCommand.Cancel(); OperationCanceledException handling | +| FOUND-07 | All errors surface to the user with actionable messages — no silent failures | Global DispatcherUnhandledException + TaskScheduler.UnobservedTaskException; empty-catch policy | +| FOUND-08 | Structured logging for diagnostics | Serilog 4.3.1 + Serilog.Sinks.File (rolling daily) → %AppData%\SharepointToolbox\logs\ | +| FOUND-09 | Localization system supporting English and French with dynamic language switching | Strings.resx + Strings.fr.resx; singleton TranslationSource + WeakReferenceMessenger broadcast | +| FOUND-10 | JSON-based local storage compatible with current app format | System.Text.Json; existing field names preserved exactly; write-then-replace with SemaphoreSlim(1) | +| FOUND-12 | Configurable data output folder for exports | SettingsService reads/writes `Sharepoint_Settings.json`; FolderBrowserDialog in Settings tab | + + +--- + +## Summary + +Phase 1 establishes the entire skeleton on which all feature phases build. The technical choices are fully locked and research-validated. The stack (.NET 10 + WPF + CommunityToolkit.Mvvm + MSAL + PnP.Framework + Serilog + System.Text.Json) is internally consistent, widely documented, and has no version conflicts identified. + +The three highest-risk areas for planning are: (1) WPF + Generic Host integration — the WPF STA threading model requires explicit plumbing that is not in the default Host template; (2) MSAL per-tenant token cache scoping — the `MsalCacheHelper` must be instantiated with a unique cache file name per `ClientId`, and the `IPublicClientApplication` instance must be kept alive in `SessionManager` for `AcquireTokenSilent` to work across tenant switches; (3) Dynamic localization without a restart — WPF's standard `x:Static` bindings to generated `.resx` classes are evaluated at startup only, so a `TranslationSource` singleton bound to `INotifyPropertyChanged` (or `MarkupExtension` returning a `Binding`) is required for runtime culture switching. + +**Primary recommendation:** Build the Generic Host wiring, `SessionManager`, and `TranslationSource` in Wave 1 of the plan. All other components depend on DI being up and the culture system being in place. + +--- + +## Standard Stack + +### Core + +| Library | Version | Purpose | Why Standard | +|---------|---------|---------|--------------| +| CommunityToolkit.Mvvm | 8.4.2 | ObservableObject, RelayCommand, AsyncRelayCommand, WeakReferenceMessenger | Microsoft-maintained; source generator MVVM; replaces MVVM Light | +| Microsoft.Extensions.Hosting | 10.x | Generic Host — DI container, lifetime, configuration | Official .NET hosting model; Serilog integrates via UseSerilog() | +| MSAL.NET (Microsoft.Identity.Client) | 4.83.1 | Public client OAuth2 interactive login | Official Microsoft identity library for desktop | +| Microsoft.Identity.Client.Extensions.Msal | 4.83.3 | MsalCacheHelper — cross-platform encrypted file token cache | Required for persistent token cache on desktop | +| Microsoft.Identity.Client.Broker | 4.82.1 | WAM (Windows Auth Manager) broker support | Better Windows 11 SSO; falls back gracefully | +| PnP.Framework | 1.18.0 | AuthenticationManager, ClientContext, CSOM operations | Only library containing PnP Provisioning Engine | +| Serilog | 4.3.1 | Structured logging | De-facto .NET logging library | +| Serilog.Sinks.File | (latest) | Rolling daily log file | The modern replacement for deprecated Serilog.Sinks.RollingFile | +| Serilog.Extensions.Hosting | (latest) | host.UseSerilog() integration | Wires Serilog into ILogger DI | +| System.Text.Json | built-in (.NET 10) | JSON serialization/deserialization | Zero dependency; sufficient for flat profile/settings schemas | + +### Supporting + +| Library | Version | Purpose | When to Use | +|---------|---------|---------|-------------| +| Microsoft.Extensions.DependencyInjection | 10.x | DI abstractions (bundled with Hosting) | Service registration and resolution | +| xUnit | 2.x | Unit testing | ViewModel and service layer tests | +| Moq or NSubstitute | latest | Mocking in tests | Isolate services in ViewModel tests | + +### Alternatives Considered + +| Instead of | Could Use | Tradeoff | +|------------|-----------|----------| +| CommunityToolkit.Mvvm | Prism | Prism is heavier, module-oriented; overkill for single-assembly app | +| Serilog.Sinks.File | NLog or log4net | Serilog integrates cleanly with Generic Host; NLog would work but adds config file complexity | +| System.Text.Json | Newtonsoft.Json | Newtonsoft handles more edge cases but is unnecessary for the flat schemas here | + +**Installation:** + +```bash +dotnet add package CommunityToolkit.Mvvm --version 8.4.2 +dotnet add package Microsoft.Extensions.Hosting +dotnet add package Microsoft.Identity.Client --version 4.83.1 +dotnet add package Microsoft.Identity.Client.Extensions.Msal --version 4.83.3 +dotnet add package Microsoft.Identity.Client.Broker --version 4.82.1 +dotnet add package PnP.Framework --version 1.18.0 +dotnet add package Serilog +dotnet add package Serilog.Sinks.File +dotnet add package Serilog.Extensions.Hosting +``` + +--- + +## Architecture Patterns + +### Recommended Project Structure + +``` +SharepointToolbox/ +├── App.xaml / App.xaml.cs # Generic Host entry point, global exception handlers +├── Core/ +│ ├── Models/ +│ │ ├── TenantProfile.cs # { Name, TenantUrl, ClientId } +│ │ └── OperationProgress.cs # record { int Current, int Total, string Message } +│ ├── Messages/ +│ │ ├── TenantSwitchedMessage.cs +│ │ └── LanguageChangedMessage.cs +│ └── Helpers/ +│ ├── SharePointPaginationHelper.cs +│ └── ExecuteQueryRetryHelper.cs +├── Infrastructure/ +│ ├── Persistence/ +│ │ ├── ProfileRepository.cs # write-then-replace + SemaphoreSlim(1) +│ │ └── SettingsRepository.cs +│ ├── Auth/ +│ │ └── MsalClientFactory.cs # creates and caches IPublicClientApplication per ClientId +│ └── Logging/ +│ └── LogPanelSink.cs # custom Serilog sink → RichTextBox +├── Services/ +│ ├── SessionManager.cs # singleton, owns all ClientContext instances +│ ├── ProfileService.cs +│ └── SettingsService.cs +├── Localization/ +│ ├── TranslationSource.cs # singleton INotifyPropertyChanged; ResourceManager wrapper +│ ├── Strings.resx # EN (neutral default) +│ └── Strings.fr.resx # FR overlay +├── ViewModels/ +│ ├── MainWindowViewModel.cs +│ ├── ProfileManagementViewModel.cs +│ ├── FeatureViewModelBase.cs # canonical async pattern: CTS + IsRunning + IProgress +│ └── Tabs/ +│ └── SettingsViewModel.cs +└── Views/ + ├── MainWindow.xaml + ├── Dialogs/ + │ └── ProfileManagementDialog.xaml + └── Tabs/ + └── SettingsView.xaml +``` + +### Pattern 1: Generic Host + WPF Wiring + +**What:** Replace WPF's default `StartupUri`-based startup with a `static Main` that builds a Generic Host, then resolves `MainWindow` from DI. + +**When to use:** Required for all DI-injected ViewModels and services in WPF. + +**Example:** + +```csharp +// App.xaml.cs +// Source: https://formatexception.com/2024/02/adding-host-to-wpf-for-dependency-injection/ +public partial class App : Application +{ + [STAThread] + public static void Main(string[] args) + { + using IHost host = Host.CreateDefaultBuilder(args) + .UseSerilog((ctx, cfg) => cfg + .WriteTo.File( + Path.Combine( + Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData), + "SharepointToolbox", "logs", "app-.log"), + rollingInterval: RollingInterval.Day, + retainedFileCountLimit: 30)) + .ConfigureServices(RegisterServices) + .Build(); + + host.Start(); + + App app = new(); + app.InitializeComponent(); + app.MainWindow = host.Services.GetRequiredService(); + app.MainWindow.Visibility = Visibility.Visible; + app.Run(); + } + + private static void RegisterServices(HostBuilderContext ctx, IServiceCollection services) + { + services.AddSingleton(); + services.AddSingleton(); + services.AddSingleton(); + services.AddSingleton(); + services.AddSingleton(); + services.AddTransient(); + services.AddSingleton(); + } +} +``` + +```xml + + + + +``` + +```xml + + + SharepointToolbox.App + + + + + +``` + +### Pattern 2: AsyncRelayCommand Canonical Pattern (FeatureViewModelBase) + +**What:** Base class for all feature ViewModels demonstrating CancellationTokenSource lifecycle, IsRunning binding, IProgress wiring, and graceful OperationCanceledException handling. + +**When to use:** Every feature tab ViewModel inherits from this or replicates the pattern. + +```csharp +// Source: https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/asyncrelaycommand +public abstract class FeatureViewModelBase : ObservableRecipient +{ + private CancellationTokenSource? _cts; + + [ObservableProperty] + private bool _isRunning; + + [ObservableProperty] + private string _statusMessage = string.Empty; + + [ObservableProperty] + private int _progressValue; + + public IAsyncRelayCommand RunCommand { get; } + public RelayCommand CancelCommand { get; } + + protected FeatureViewModelBase() + { + RunCommand = new AsyncRelayCommand(ExecuteAsync, () => !IsRunning); + CancelCommand = new RelayCommand(() => _cts?.Cancel(), () => IsRunning); + } + + private async Task ExecuteAsync() + { + _cts = new CancellationTokenSource(); + IsRunning = true; + StatusMessage = string.Empty; + try + { + var progress = new Progress(p => + { + ProgressValue = p.Total > 0 ? (int)(100.0 * p.Current / p.Total) : 0; + StatusMessage = p.Message; + }); + await RunOperationAsync(_cts.Token, progress); + } + catch (OperationCanceledException) + { + StatusMessage = "Operation cancelled."; + } + catch (Exception ex) + { + StatusMessage = $"Error: {ex.Message}"; + // Log via Serilog ILogger injected into derived class + } + finally + { + IsRunning = false; + _cts.Dispose(); + _cts = null; + } + } + + protected abstract Task RunOperationAsync(CancellationToken ct, IProgress progress); +} +``` + +### Pattern 3: MSAL Per-Tenant Token Cache + +**What:** One `IPublicClientApplication` per ClientId, backed by a per-ClientId `MsalCacheHelper` file. `SessionManager` (singleton) holds the dictionary and performs `AcquireTokenSilent` before falling back to `AcquireTokenInteractive`. + +**When to use:** Every SharePoint authentication flow. + +```csharp +// Source: https://learn.microsoft.com/en-us/entra/msal/dotnet/how-to/token-cache-serialization +public class MsalClientFactory +{ + private readonly Dictionary _clients = new(); + private readonly SemaphoreSlim _lock = new(1, 1); + private readonly string _cacheDir = Path.Combine( + Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData), + "SharepointToolbox", "auth"); + + public async Task GetOrCreateAsync(string clientId) + { + await _lock.WaitAsync(); + try + { + if (_clients.TryGetValue(clientId, out var existing)) + return existing; + + var storageProps = new StorageCreationPropertiesBuilder( + $"msal_{clientId}.cache", _cacheDir) + .Build(); + + var pca = PublicClientApplicationBuilder + .Create(clientId) + .WithDefaultRedirectUri() + .WithLegacyCacheCompatibility(false) + .Build(); + + var helper = await MsalCacheHelper.CreateAsync(storageProps); + helper.RegisterCache(pca.UserTokenCache); + + _clients[clientId] = pca; + return pca; + } + finally { _lock.Release(); } + } +} +``` + +### Pattern 4: Dynamic Localization (TranslationSource + MarkupExtension) + +**What:** A singleton `TranslationSource` implements `INotifyPropertyChanged`. XAML binds to it via an indexer `[key]`. When `CurrentCulture` changes, `PropertyChanged` fires for all keys simultaneously, refreshing every bound string in the UI — no restart required. + +**When to use:** All localizable strings in XAML. + +```csharp +// TranslationSource.cs — singleton, INotifyPropertyChanged +public class TranslationSource : INotifyPropertyChanged +{ + public static readonly TranslationSource Instance = new(); + private ResourceManager _resourceManager = Strings.ResourceManager; + private CultureInfo _currentCulture = CultureInfo.CurrentUICulture; + + public string this[string key] => + _resourceManager.GetString(key, _currentCulture) ?? $"[{key}]"; + + public CultureInfo CurrentCulture + { + get => _currentCulture; + set + { + if (_currentCulture == value) return; + _currentCulture = value; + Thread.CurrentThread.CurrentUICulture = value; + // Raise PropertyChanged with null/empty = "all properties changed" + PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(string.Empty)); + } + } + + public event PropertyChangedEventHandler? PropertyChanged; +} +``` + +```xml + + +``` + +```csharp +// Language switch handler (in SettingsViewModel) +// Broadcasts so StatusBar and other VMs reset any cached strings +TranslationSource.Instance.CurrentCulture = new CultureInfo("fr"); +WeakReferenceMessenger.Default.Send(new LanguageChangedMessage("fr")); +``` + +### Pattern 5: WeakReferenceMessenger for Tenant Switching + +**What:** When the user selects a different tenant, `MainWindowViewModel` sends a `TenantSwitchedMessage`. All feature ViewModels that inherit `ObservableRecipient` register for this message and reset their state. + +```csharp +// Message definition (in Core/Messages/) +public sealed class TenantSwitchedMessage : ValueChangedMessage +{ + public TenantSwitchedMessage(TenantProfile profile) : base(profile) { } +} + +// MainWindowViewModel sends on ComboBox selection change +WeakReferenceMessenger.Default.Send(new TenantSwitchedMessage(selectedProfile)); + +// FeatureViewModelBase registers in OnActivated (ObservableRecipient lifecycle) +protected override void OnActivated() +{ + Messenger.Register(this, (r, m) => + r.OnTenantSwitched(m.Value)); +} +``` + +### Pattern 6: JSON Write-Then-Replace + +**What:** Prevents corrupt files on crash during write. Validate JSON before replacing. + +```csharp +// ProfileRepository.cs +private readonly SemaphoreSlim _writeLock = new(1, 1); + +public async Task SaveAsync(IReadOnlyList profiles) +{ + await _writeLock.WaitAsync(); + try + { + var json = JsonSerializer.Serialize( + new { profiles }, + new JsonSerializerOptions { WriteIndented = true }); + + var tmpPath = _filePath + ".tmp"; + await File.WriteAllTextAsync(tmpPath, json, Encoding.UTF8); + + // Validate round-trip before replacing + JsonDocument.Parse(await File.ReadAllTextAsync(tmpPath)).Dispose(); + + File.Move(tmpPath, _filePath, overwrite: true); + } + finally { _writeLock.Release(); } +} +``` + +### Pattern 7: ObservableCollection Threading Rule + +**What:** Never modify an `ObservableCollection` from a `Task.Run` background thread. The bound `ItemsControl` will throw or silently malfunction. + +```csharp +// In FeatureViewModel — collect on background, assign on UI thread +var results = new List(); +await Task.Run(async () => +{ + // ... enumerate, add to results ... +}, ct); + +// Switch back to UI thread for collection assignment +await Application.Current.Dispatcher.InvokeAsync(() => +{ + Items = new ObservableCollection(results); +}); +``` + +### Anti-Patterns to Avoid + +- **`async void` event handlers:** Use `AsyncRelayCommand` instead. `async void` swallows exceptions silently and is untestable. +- **Direct `ObservableCollection.Add()` from background thread:** Causes cross-thread `InvalidOperationException`. Always use the dispatcher + `new ObservableCollection(list)` pattern. +- **Single `IPublicClientApplication` for all tenants:** MSAL's token cache is scoped per app instance. Sharing one instance for multiple ClientIds causes tenant bleed. Each ClientId must have its own PCA. +- **Holding `ClientContext` in ViewModels:** `ClientContext` is expensive and not thread-safe. Only `SessionManager` holds it; ViewModels call a service method that takes the URL and returns results. +- **`x:Static` bindings to generated resx class:** `Properties.Strings.SomeKey` is resolved once at startup. It will not update when `CurrentUICulture` changes. Use `TranslationSource` binding instead. +- **`await using` on `ClientContext` without cancellation check:** PnP CSOM operations do not respect `CancellationToken` at the HTTP level in all paths. Check `ct.ThrowIfCancellationRequested()` before each `ExecuteQuery` call. + +--- + +## Don't Hand-Roll + +| Problem | Don't Build | Use Instead | Why | +|---------|-------------|-------------|-----| +| Token cache file encryption on Windows | Custom DPAPI wrapper | `MsalCacheHelper` (Extensions.Msal) | Handles DPAPI, Mac keychain, Linux SecretService, and fallback; concurrent access safe | +| Async command with cancellation | Custom `ICommand` implementation | `AsyncRelayCommand` from CommunityToolkit.Mvvm | Handles re-entrancy, `IsRunning`, `CanExecute` propagation, source-generated attributes | +| Cross-VM broadcast | Events on a static class | `WeakReferenceMessenger.Default` | Prevents memory leaks; no strong reference from sender to recipient | +| Retry on SharePoint throttle | Custom retry loop | Wrap PnP Framework's built-in retry in `ExecuteQueryRetryAsync` | PnP already handles 429 backoff; wrapper just exposes events for progress reporting | +| CSOM list pagination | Manual rowlimit + while loop | `SharePointPaginationHelper` (built in Phase 1) | Forgetting `ListItemCollectionPosition` on large lists causes silent data truncation at 5000 items | +| Rolling log file | Custom `ILogger` sink | `Serilog.Sinks.File` with `rollingInterval: RollingInterval.Day` | Note: `Serilog.Sinks.RollingFile` is deprecated — use `Serilog.Sinks.File` | + +**Key insight:** The highest-value "don't hand-roll" is `SharePointPaginationHelper`. The existing PowerShell app likely has silent list threshold failures. Building this helper correctly in Phase 1 is what prevents PERM-07 and every other list-enumeration feature from hitting the 5,000-item wall. + +--- + +## Common Pitfalls + +### Pitfall 1: WPF STA Thread + Generic Host Conflict + +**What goes wrong:** `Host.CreateDefaultBuilder` creates a multi-threaded environment. WPF requires the UI thread to be STA. If `Main` is not explicitly marked `[STAThread]`, or if `Application.Run()` is called from the wrong thread, the application crashes at startup with a threading exception. + +**Why it happens:** The default `Program.cs` generated by the WPF template uses `[STAThread]` on `Main` and calls `Application.Run()` directly. When replacing with Generic Host, the entry point changes and the STA attribute must be manually preserved. + +**How to avoid:** Mark `static void Main` with `[STAThread]`. Remove `StartupUri` from `App.xaml`. Add `` to the csproj. Demote `App.xaml` from `ApplicationDefinition` to `Page`. + +**Warning signs:** `InvalidOperationException: The calling thread must be STA` at startup. + +### Pitfall 2: MSAL Token Cache Sharing Across Tenants + +**What goes wrong:** One `IPublicClientApplication` is created and reused for all tenants. Tokens from tenant A contaminate the cache for tenant B, causing silent auth failures or incorrect user context. + +**Why it happens:** `IPublicClientApplication` has one `UserTokenCache`. The cache keys internally include the ClientId; if multiple tenants use the same ClientId (which is possible in multi-tenant Azure AD apps), the cache is shared and `AcquireTokenSilent` may return a token for the wrong tenant account. + +**How to avoid:** Create one `IPublicClientApplication` per `ClientId`, backed by a cache file named `msal_{clientId}.cache`. If two profiles share a ClientId, they share the PCA (same ClientId = same app registration), but switching requires calling `AcquireTokenSilent` with the correct account from `pca.GetAccountsAsync()`. + +**Warning signs:** User is authenticated as wrong tenant after switch; `MsalUiRequiredException` on switch despite being previously logged in. + +### Pitfall 3: Dynamic Localization Not Updating All Strings + +**What goes wrong:** Language is switched via `CultureInfo`, but 30–40% of strings in the UI still show the old language. Specifically, strings bound via `x:Static` to the generated resource class accessor (e.g., `{x:Static p:Strings.SaveButton}`) are resolved at load time and never re-queried. + +**Why it happens:** The WPF design-time resource designer generates static string properties. `x:Static` retrieves the value once. No `INotifyPropertyChanged` mechanism re-fires. + +**How to avoid:** Use `TranslationSource.Instance[key]` binding pattern for all strings. Never use `x:Static` on the generated Strings class for UI text. The `TranslationSource.PropertyChanged` with an empty string key triggers WPF to re-evaluate all bindings on the source object simultaneously. + +**Warning signs:** Some strings update on language switch, others don't; exactly the strings using `x:Static` are the ones that don't update. + +### Pitfall 4: Empty `catch` Swallows SharePoint Exceptions + +**What goes wrong:** A `catch (Exception)` block with no body (or only a comment) causes SharePoint operations to silently fail. The user sees a blank result grid with no error message, and the log shows nothing. + +**Why it happens:** PnP CSOM throws `ServerException` with SharePoint error codes. Developers add broad `catch` blocks during development to "handle errors later" and forget to complete them. + +**How to avoid:** Enforce the project policy from day one: every `catch` block must log-and-recover, log-and-rethrow, or log-and-surface. Code review rejects any empty or comment-only catch. Serilog's structured logging makes logging trivial. + +**Warning signs:** Operations complete in ~0ms, return zero results, log shows no entry. + +### Pitfall 5: `ClientContext` Not Disposed on Cancellation + +**What goes wrong:** `ClientContext` holds an HTTP connection to SharePoint. If cancellation is requested and the `ClientContext` is abandoned rather than disposed, connections accumulate. Long-running sessions leak sockets. + +**Why it happens:** The `await using` pattern is dropped when developers switch from the canonical pattern to a try/catch block and forget to add the `finally { ctx.Dispose(); }`. + +**How to avoid:** Enforce `await using` in all code touching `ClientContext`. Unit tests verify `Dispose()` is called even when `OperationCanceledException` is thrown (mock `ClientContext` and assert `Dispose` call count). + +**Warning signs:** `SocketException` or connection timeout errors appearing after the application has been running for several hours; memory growth over a long session. + +### Pitfall 6: `ObservableCollection` Modified from Background Thread + +**What goes wrong:** `Add()` or `Clear()` called on an `ObservableCollection` from inside `Task.Run`. WPF's `CollectionView` throws `NotSupportedException: This type of CollectionView does not support changes to its SourceCollection from a thread different from the Dispatcher thread`. + +**Why it happens:** Developers call `Items.Add(item)` inside a `for` loop that runs on a background thread, which feels natural but violates WPF's cross-thread collection rule. + +**How to avoid:** Accumulate results in a plain `List` on the background thread. When the operation completes (or at batch boundaries), `await Application.Current.Dispatcher.InvokeAsync(() => Items = new ObservableCollection(list))`. + +**Warning signs:** `InvalidOperationException` or `NotSupportedException` with "Dispatcher thread" in the message, occurring only when the result set is large enough to trigger background processing. + +--- + +## Code Examples + +Verified patterns from official sources: + +### MsalCacheHelper Desktop Setup + +```csharp +// Source: https://learn.microsoft.com/en-us/entra/msal/dotnet/how-to/token-cache-serialization +var storageProperties = new StorageCreationPropertiesBuilder( + $"msal_{clientId}.cache", + Path.Combine(Environment.GetFolderPath( + Environment.SpecialFolder.ApplicationData), "SharepointToolbox", "auth")) + .Build(); + +var pca = PublicClientApplicationBuilder + .Create(clientId) + .WithDefaultRedirectUri() + .WithLegacyCacheCompatibility(false) + .Build(); + +var cacheHelper = await MsalCacheHelper.CreateAsync(storageProperties); +cacheHelper.RegisterCache(pca.UserTokenCache); +``` + +### AcquireTokenSilent with Interactive Fallback + +```csharp +// Source: MSAL.NET documentation pattern +public async Task GetAccessTokenAsync( + IPublicClientApplication pca, + string[] scopes, + CancellationToken ct) +{ + var accounts = await pca.GetAccountsAsync(); + AuthenticationResult result; + try + { + result = await pca.AcquireTokenSilent(scopes, accounts.FirstOrDefault()) + .ExecuteAsync(ct); + } + catch (MsalUiRequiredException) + { + result = await pca.AcquireTokenInteractive(scopes) + .WithUseEmbeddedWebView(false) + .ExecuteAsync(ct); + } + return result.AccessToken; +} +``` + +### PnP AuthenticationManager Interactive Login + +```csharp +// Source: https://pnp.github.io/pnpframework/api/PnP.Framework.AuthenticationManager.html +var authManager = AuthenticationManager.CreateWithInteractiveLogin( + clientId: profile.ClientId, + tenantId: null, // null = common endpoint (multi-tenant) + redirectUrl: "http://localhost"); + +await using var ctx = await authManager.GetContextAsync(profile.TenantUrl, ct); +// ctx is a SharePoint CSOM ClientContext ready for ExecuteQueryAsync +``` + +### WeakReferenceMessenger Send + Register + +```csharp +// Source: https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/messenger + +// Define message +public sealed class TenantSwitchedMessage : ValueChangedMessage +{ + public TenantSwitchedMessage(TenantProfile p) : base(p) { } +} + +// Send (in MainWindowViewModel) +WeakReferenceMessenger.Default.Send(new TenantSwitchedMessage(selected)); + +// Register (in ObservableRecipient-derived ViewModel) +protected override void OnActivated() +{ + Messenger.Register(this, (r, m) => + r.HandleTenantSwitch(m.Value)); +} +``` + +### Serilog Setup with Rolling File + +```csharp +// Source: https://github.com/serilog/serilog-sinks-file +// NOTE: Use Serilog.Sinks.File — Serilog.Sinks.RollingFile is DEPRECATED +Log.Logger = new LoggerConfiguration() + .MinimumLevel.Debug() + .WriteTo.File( + path: Path.Combine( + Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData), + "SharepointToolbox", "logs", "app-.log"), + rollingInterval: RollingInterval.Day, + retainedFileCountLimit: 30, + outputTemplate: "{Timestamp:HH:mm:ss} [{Level:u3}] {Message:lj}{NewLine}{Exception}") + .CreateLogger(); +``` + +### Global Exception Handlers in App.xaml.cs + +```csharp +// App.xaml.cs — wire in Application constructor or OnStartup +Application.Current.DispatcherUnhandledException += (_, e) => +{ + Log.Fatal(e.Exception, "Unhandled dispatcher exception"); + MessageBox.Show( + $"An unexpected error occurred:\n\n{e.Exception.Message}\n\n" + + "Check the log file for details.", + "Unexpected Error", + MessageBoxButton.OK, MessageBoxImage.Error); + e.Handled = true; // prevent crash; or set false to let it crash +}; + +TaskScheduler.UnobservedTaskException += (_, e) => +{ + Log.Error(e.Exception, "Unobserved task exception"); + e.SetObserved(); // prevent process termination +}; +``` + +--- + +## State of the Art + +| Old Approach | Current Approach | When Changed | Impact | +|--------------|------------------|--------------|--------| +| Serilog.Sinks.RollingFile NuGet | Serilog.Sinks.File with `rollingInterval` param | ~2018 | Rolling file is deprecated; same behavior, different package | +| MSAL v2 `TokenCacheCallback` | `MsalCacheHelper.RegisterCache()` | MSAL 4.x | Much simpler; handles encryption and cross-platform automatically | +| ADAL.NET | MSAL.NET | 2020+ | ADAL is end-of-life; all new auth must use MSAL | +| `async void` event handlers | `AsyncRelayCommand` | CommunityToolkit.Mvvm era | `async void` is an anti-pattern; toolkit makes the right thing easy | +| `x:Static` on resx | `TranslationSource` binding | No standard date | Required for runtime culture switch without restart | +| WPF app without DI | Generic Host + WPF | .NET Core 3+ | Enables testability, Serilog wiring, and lifetime management | + +**Deprecated/outdated:** + +- `Serilog.Sinks.RollingFile`: Deprecated; replaced by `Serilog.Sinks.File`. Do not add this package. +- `Microsoft.Toolkit.Mvvm` (old namespace): Superseded by `CommunityToolkit.Mvvm`. Same toolkit, new package ID. +- `ADAL.NET` (Microsoft.IdentityModel.Clients.ActiveDirectory): End-of-life. Use MSAL only. +- `MvvmLight` (GalaSoft): Unmaintained. CommunityToolkit.Mvvm is the successor. + +--- + +## Open Questions + +1. **PnP AuthenticationManager vs raw MSAL for token acquisition** + - What we know: `PnP.Framework.AuthenticationManager.CreateWithInteractiveLogin` wraps MSAL internally and produces a `ClientContext`. There is also a constructor accepting an external `IAuthenticationProvider`. + - What's unclear: Whether passing an externally-managed `IPublicClientApplication` (from `MsalClientFactory`) into `AuthenticationManager` is officially supported in PnP.Framework 1.18, or if we must create a new PCA inside `AuthenticationManager` and bypass `MsalClientFactory`. + - Recommendation: In Wave 1, spike with `CreateWithInteractiveLogin(clientId, ...)` — accept that PnP creates its own internal PCA. If we need to share the token cache with a separately-created PCA, use the `IAuthenticationProvider` constructor overload. + +2. **WAM Broker behavior on Windows 10 LTSC** + - What we know: `Microsoft.Identity.Client.Broker` enables WAM on Windows 11. The locked runtime decision includes it. + - What's unclear: Behavior on the user's Windows 10 IoT LTSC environment. WAM may not be available or may fall back silently. + - Recommendation: Configure MSAL with `.WithDefaultRedirectUri()` as fallback and do not hard-require WAM. Test on Windows 10 LTSC before shipping. + +--- + +## Validation Architecture + +### Test Framework + +| Property | Value | +|----------|-------| +| Framework | xUnit 2.x | +| Config file | none — see Wave 0 | +| Quick run command | `dotnet test --filter "Category=Unit" --no-build` | +| Full suite command | `dotnet test --no-build` | + +### Phase Requirements → Test Map + +| Req ID | Behavior | Test Type | Automated Command | File Exists? | +|--------|----------|-----------|-------------------|-------------| +| FOUND-01 | App starts, MainWindow resolves from DI | smoke | `dotnet test --filter "FullyQualifiedName~AppStartupTests" -x` | ❌ Wave 0 | +| FOUND-02 | ProfileService: create/rename/delete/load profiles; JSON written correctly | unit | `dotnet test --filter "FullyQualifiedName~ProfileServiceTests" -x` | ❌ Wave 0 | +| FOUND-03 | MsalClientFactory: unique PCA per ClientId; same ClientId returns cached instance | unit | `dotnet test --filter "FullyQualifiedName~MsalClientFactoryTests" -x` | ❌ Wave 0 | +| FOUND-04 | SessionManager: AcquireTokenSilent called before Interactive; MsalUiRequiredException triggers interactive | unit (mock MSAL) | `dotnet test --filter "FullyQualifiedName~SessionManagerTests" -x` | ❌ Wave 0 | +| FOUND-05 | FeatureViewModelBase: IProgress updates ProgressValue and StatusMessage on UI thread | unit | `dotnet test --filter "FullyQualifiedName~FeatureViewModelBaseTests" -x` | ❌ Wave 0 | +| FOUND-06 | FeatureViewModelBase: CancelCommand calls CTS.Cancel(); operation stops; IsRunning resets to false | unit | `dotnet test --filter "FullyQualifiedName~FeatureViewModelBaseTests" -x` | ❌ Wave 0 | +| FOUND-07 | Global exception handlers log and surface (verify log written + MessageBox shown) | integration | manual-only (UI dialog) | — | +| FOUND-08 | Serilog writes to rolling file in %AppData%\SharepointToolbox\logs\ | integration | `dotnet test --filter "FullyQualifiedName~LoggingIntegrationTests" -x` | ❌ Wave 0 | +| FOUND-09 | TranslationSource: switching CurrentCulture fires PropertyChanged with empty key; string lookup uses new culture | unit | `dotnet test --filter "FullyQualifiedName~TranslationSourceTests" -x` | ❌ Wave 0 | +| FOUND-10 | ProfileRepository: write-then-replace atomicity; SemaphoreSlim prevents concurrent writes; corrupt JSON on tmp does not replace original | unit | `dotnet test --filter "FullyQualifiedName~ProfileRepositoryTests" -x` | ❌ Wave 0 | +| FOUND-12 | SettingsService: reads/writes Sharepoint_Settings.json; dataFolder field round-trips correctly | unit | `dotnet test --filter "FullyQualifiedName~SettingsServiceTests" -x` | ❌ Wave 0 | + +### Sampling Rate + +- **Per task commit:** `dotnet test --filter "Category=Unit" --no-build` +- **Per wave merge:** `dotnet test --no-build` +- **Phase gate:** Full suite green before `/gsd:verify-work` + +### Wave 0 Gaps + +- [ ] `SharepointToolbox.Tests/SharepointToolbox.Tests.csproj` — xUnit test project, add packages: xunit, xunit.runner.visualstudio, Moq (or NSubstitute), Microsoft.NET.Test.Sdk +- [ ] `SharepointToolbox.Tests/Services/ProfileServiceTests.cs` — covers FOUND-02, FOUND-10 +- [ ] `SharepointToolbox.Tests/Services/SettingsServiceTests.cs` — covers FOUND-12 +- [ ] `SharepointToolbox.Tests/Auth/MsalClientFactoryTests.cs` — covers FOUND-03 +- [ ] `SharepointToolbox.Tests/Auth/SessionManagerTests.cs` — covers FOUND-04 +- [ ] `SharepointToolbox.Tests/ViewModels/FeatureViewModelBaseTests.cs` — covers FOUND-05, FOUND-06 +- [ ] `SharepointToolbox.Tests/Localization/TranslationSourceTests.cs` — covers FOUND-09 +- [ ] `SharepointToolbox.Tests/Integration/LoggingIntegrationTests.cs` — covers FOUND-08 + +--- + +## Sources + +### Primary (HIGH confidence) + +- [AsyncRelayCommand — Microsoft Learn (CommunityToolkit)](https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/asyncrelaycommand) — AsyncRelayCommand API, IsRunning, CancellationToken, IProgress patterns +- [Messenger — Microsoft Learn (CommunityToolkit)](https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/messenger) — WeakReferenceMessenger, Send/Register patterns, ValueChangedMessage +- [Token Cache Serialization — Microsoft Learn (MSAL.NET)](https://learn.microsoft.com/en-us/entra/msal/dotnet/how-to/token-cache-serialization) — MsalCacheHelper desktop setup, StorageCreationPropertiesBuilder, per-user cache +- [PnP Framework AuthenticationManager API](https://pnp.github.io/pnpframework/api/PnP.Framework.AuthenticationManager.html) — CreateWithInteractiveLogin overloads, GetContextAsync +- [Serilog.Sinks.File GitHub](https://github.com/serilog/serilog-sinks-file) — modern rolling file sink (RollingFile deprecated) +- Existing project files: `Sharepoint_Settings.json`, `lang/fr.json`, `Sharepoint_ToolBox.ps1:1-152` — exact JSON schemas and localization keys confirmed + +### Secondary (MEDIUM confidence) + +- [Adding Host to WPF for DI — FormatException (2024)](https://formatexception.com/2024/02/adding-host-to-wpf-for-dependency-injection/) — Generic Host + WPF wiring pattern (verified against Generic Host official docs) +- [Custom Resource MarkupExtension — Microsoft DevBlogs](https://devblogs.microsoft.com/ifdef-windows/use-a-custom-resource-markup-extension-to-succeed-at-ui-string-globalization/) — MarkupExtension for resx (verified pattern approach) +- [NuGet: CommunityToolkit.Mvvm 8.4.2](https://www.nuget.org/packages/CommunityToolkit.Mvvm/) — version confirmed + +### Tertiary (LOW confidence) + +- Multiple WebSearch results on WPF localization patterns (2012–2020 vintage, not 2025-specific). The `TranslationSource` singleton pattern is consistent across sources but no single authoritative 2025 doc was found. Implementation is straightforward enough to treat as MEDIUM. + +--- + +## Metadata + +**Confidence breakdown:** + +- Standard stack: HIGH — all packages are official, versions verified on NuGet, no version conflicts identified +- Architecture: HIGH — Generic Host + WPF pattern is well-documented for .NET Core+; MSAL per-tenant pattern verified against official MSAL docs +- Pitfalls: HIGH — pitfalls 1–4 are documented in official sources; pitfalls 5–6 are well-known WPF threading behaviors with extensive community documentation +- Localization (TranslationSource): MEDIUM — the `INotifyPropertyChanged` singleton approach is the standard community pattern for dynamic resx switching; no single authoritative Microsoft doc covers it end-to-end +- PnP Framework auth integration: MEDIUM — `AuthenticationManager.CreateWithInteractiveLogin` API is documented; exact behavior when combining with external `MsalClientFactory` needs a validation spike + +**Research date:** 2026-04-02 +**Valid until:** 2026-05-02 (30 days — stable libraries, conservative estimate)