Using Rider’s Structural Search & Replace for Legacy API Migration

Why Structural Search & Replace Matters

When a .NET solution grows, the same API call can appear in dozens of files. Replacing a deprecated method manually is error‑prone and time‑consuming. Rider’s Structural Search & Replace (SSR) lets you describe a code pattern in terms of the language’s Abstract Syntax Tree (AST), then replace every match with a new pattern that can include variable placeholders.

Key SSR Concepts

• Template – the code pattern you search for. It can contain #var# placeholders that match any expression, type, or keyword.
• Replacement – the new code you want to inject. Placeholders from the template can be reused here.
• Scope – the set of projects or directories the search applies to.
• Preview – Rider shows a diff of every change before you commit.

Concrete Example: Migrating from HttpClient.GetAsync to HttpClient.GetStreamAsync

Suppose a legacy codebase uses HttpClient.GetAsync(string) everywhere, but you want to switch to the stream-based API for performance. The pattern to find is a method call with a string literal argument. The replacement will preserve the argument but change the method name.

Template:
HttpClient.GetAsync(#url#)

Replacement:
HttpClient.GetStreamAsync(#url#)

1. Open Tools > Find & Replace > Search by Pattern.
2. Paste the template in the Search template box.
3. Paste the replacement in the Replace template box.
4. Set the Scope to the entire solution.
5. Click Preview.
6. Review the diff – Rider will list each file, line number, and the proposed change.
7. If satisfied, click Replace All.

After the replace, Rider’s code analysis will automatically re‑resolve references. If any call was inside a try/catch that depended on the old method’s return type, the analysis will flag a mismatch, allowing you to fix it immediately.

Trade‑Offs and Limitations

• Static Analysis Only – SSR cannot handle dynamic string construction that resolves to a method name at runtime. If your code uses reflection or dynamic types, the tool may miss some calls.
• Resource Usage – On a solution with >5 M lines, a full‑solution SSR run can consume >2 GB RAM and several minutes of CPU time. It’s best to run SSR on a dedicated build agent or limit the scope to a subset of projects.
• False Positives – Because SSR matches AST nodes, it can occasionally match code that looks similar but semantically differs (e.g., a local method named GetAsync). Always review the preview before committing.

Verification Checklist

• Run SSR with the template and confirm the Preview list contains all expected files.
• Check the Code Analysis window for new warnings after the replace.
• Build the solution to ensure no compilation errors were introduced.
• Run unit tests that cover the affected API calls to catch runtime regressions.

Actionable Takeaway

Use Rider’s SSR for any large‑scale, pattern‑based refactor. Create a template, preview, validate, and replace. Keep the scope manageable, monitor resource usage, and always run the code analyzer afterward. With SSR, a migration that would take hours of manual edits can be completed in minutes, with a safety net of Rider’s real‑time analysis.