Summary

Implement a Roslyn Analyzer + Code Fix package to help users migrate from Microsoft.Identity.Web v3.x to v4.0.0, focused on:

• Breaking changes (removed types, methods)
• Newly obsolete types (e.g., TokenAcquirerTokenCredential, TokenAcquirerAppTokenCredential)
• Async-first migration (replace sync APIs)
• Downstream API surface migration
• Configuration modernization

Analyzer Scope

• Detect usages of removed/obsolete symbols
  • TokenAcquirerTokenCredential (IDW4001)
  • TokenAcquirerAppTokenCredential (IDW4002)
  • AddDownstreamWebApi (IDW4003)
  • IDownstreamWebApi interface/fields/params (IDW4004)
  • Legacy generic helpers (PostForUserAsync, PutForUserAsync, etc.) (IDW4005)
  • WithClientCredentials (sync) (IDW4006)
  • IMsalTokenCacheProvider.InitializeAsync (IDW4007)
  • DownstreamWebApiOptions.Scopes as string instead of string[] (IDW4008)
  • _certificatesObserver (IDW4009, optional)

Analyzer Implementation

• Create a new package Microsoft.Identity.Web.Analyzers targeting netstandard2.0
• Each rule should:
  • Use semantic analysis to avoid false positives
  • Attach a code fixer where migration can be automated (see below)
  • Link to https://aka.ms/ms-id-web/v3-to-v4 in diagnostic message
  • Include sample .editorconfig for teams to escalate severity
• Provide Roslyn unit tests for each rule and code fix
• Document analyzer rules, diagnostics, and .editorconfig usage in repo

Code Fix Provider Scope

• IDW4001/4002: Replace TokenAcquirer*Credential with MicrosoftIdentityTokenCredential. For app credential, add Options.RequestAppToken = true.
• IDW4003: Replace AddDownstreamWebApi with AddDownstreamApi.
• IDW4004: Replace field/param/property/constructor types from IDownstreamWebApi to IDownstreamApi.
• IDW4005: Replace legacy generic helpers with new strongly typed methods (mapping table to be provided).
• IDW4006: Replace sync WithClientCredentials with async/await version. Offer fix to convert calling method to async (if safe).
• IDW4007: Replace InitializeAsync with Initialize, remove await/async.
• IDW4008: Suggest conversion from scopes string to string[] in config or options.
• IDW4009: Point to use _certificatesObservers collection.

Documentation & Adoption

• Document each rule, code fix, and migration scenario in MIGRATION_GUIDE_V4.md and analyzer README.
• Provide a sample .editorconfig to escalate warnings to errors.
• Link analyzer package from migration guide and main README.
• Encourage teams to run analyzer pre-migration and in CI.

Testing & Validation

• Roslyn unit tests per rule (positive/negative/fix verification).
• Integration tests for migration scenarios.

Future Considerations

• Expand analyzer to cover future breaking changes in v5/v6.
• Provide optional rules to block usage of any [Obsolete] symbol.

References

• Migration guide

Labels

breaking change, static analysis, code cleanup, enhancement, API-breaking-change, code fix

Please review, iterate, and confirm design before implementation. Suggest batching initial rules: IDW4001, IDW4002, IDW4003, IDW4004, IDW4006.