[dotnet] Annotate JavaScript strings within BiDi

[RenderMichael]

User description

Missed in #16616

🔗 Related Issues

💥 What does this PR do?

🔧 Implementation Notes

💡 Additional Considerations

🔄 Types of changes

• Cleanup (formatting, renaming)

---

PR Type

Enhancement

---

Description

• Add [StringSyntax(StringSyntaxConstants.JavaScript)] annotations to JavaScript string parameters

• Improve IDE support for JavaScript code completion and syntax highlighting

• Organize and add missing using statements across BiDi script files

• Enable better tooling integration for JavaScript expressions in BiDi API

---

Diagram Walkthrough

flowchart LR
  A["JavaScript String Parameters"] -->|Add StringSyntax Annotation| B["IDE Support Enhanced"]
  B -->|Code Completion| C["Better Developer Experience"]
  B -->|Syntax Highlighting| C
  D["Using Statements"] -->|Organize & Add| E["Code Quality Improved"]

Loading

File Walkthrough

Relevant files

Enhancement

BrowsingContextScriptModule.cs Annotate JavaScript parameters with StringSyntax                  dotnet/src/webdriver/BiDi/BrowsingContext/BrowsingContextScriptModule.cs Added [StringSyntax(StringSyntaxConstants.JavaScript)] annotation to four method parameters: functionDeclaration and expression parameters Added missing using statements: OpenQA.Selenium.Internal and System.Diagnostics.CodeAnalysis Reorganized using statements in alphabetical order +8/-6      AddPreloadScriptCommand.cs Annotate FunctionDeclaration with StringSyntax                      dotnet/src/webdriver/BiDi/Script/AddPreloadScriptCommand.cs Added [StringSyntax(StringSyntaxConstants.JavaScript)] annotation to FunctionDeclaration parameter in AddPreloadScriptParameters record Added missing using statements: OpenQA.Selenium.Internal and System.Diagnostics.CodeAnalysis +3/-1      CallFunctionCommand.cs Annotate FunctionDeclaration with StringSyntax                      dotnet/src/webdriver/BiDi/Script/CallFunctionCommand.cs Added [StringSyntax(StringSyntaxConstants.JavaScript)] annotation to FunctionDeclaration parameter in CallFunctionParameters record Added missing using statements: OpenQA.Selenium.Internal and System.Diagnostics.CodeAnalysis +3/-1      EvaluateCommand.cs Annotate Expression with StringSyntax                                        dotnet/src/webdriver/BiDi/Script/EvaluateCommand.cs Added [StringSyntax(StringSyntaxConstants.JavaScript)] annotation to Expression parameter in EvaluateParameters record Added missing using statements: OpenQA.Selenium.Internal and System.Diagnostics.CodeAnalysis +3/-1      ScriptModule.cs Annotate JavaScript parameters with StringSyntax                  dotnet/src/webdriver/BiDi/Script/ScriptModule.cs Added [StringSyntax(StringSyntaxConstants.JavaScript)] annotation to four method parameters across multiple overloads: expression and functionDeclaration Added missing using statement: System.Diagnostics.CodeAnalysis Methods annotated: EvaluateAsync, CallFunctionAsync, and AddPreloadScriptAsync +6/-5

---

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
⚪	Platform compatibility Description: The new use of StringSyntax attribute requires System.Diagnostics.CodeAnalysis; ensure targeting .NET version that defines StringSyntaxConstants.JavaScript to avoid missing-type runtime issues when consuming the library. BrowsingContextScriptModule.cs [29-31] Referred Code public async Task<AddPreloadScriptResult> AddPreloadScriptAsync([StringSyntax(StringSyntaxConstants.JavaScript)] string functionDeclaration, BrowsingContextAddPreloadScriptOptions? options = null) { AddPreloadScriptOptions addPreloadScriptOptions = new(options)
	Code injection risk Description: Annotating user-supplied JavaScript strings does not validate or sanitize code; if consumers pass untrusted input into Evaluate/CallFunction, it may enable script injection in the target browsing context. ScriptModule.cs [33-56] Referred Code public async Task<EvaluateResult> EvaluateAsync([StringSyntax(StringSyntaxConstants.JavaScript)] string expression, bool awaitPromise, Target target, EvaluateOptions? options = null) { var @params = new EvaluateParameters(expression, target, awaitPromise, options?.ResultOwnership, options?.SerializationOptions, options?.UserActivation); return await Broker.ExecuteCommandAsync(new EvaluateCommand(@params), options, _jsonContext.EvaluateCommand, _jsonContext.EvaluateResult).ConfigureAwait(false); } public async Task<TResult?> EvaluateAsync<TResult>([StringSyntax(StringSyntaxConstants.JavaScript)] string expression, bool awaitPromise, Target target, EvaluateOptions? options = null) { var result = await EvaluateAsync(expression, awaitPromise, target, options).ConfigureAwait(false); return result.AsSuccessResult().ConvertTo<TResult>(); } public async Task<EvaluateResult> CallFunctionAsync([StringSyntax(StringSyntaxConstants.JavaScript)] string functionDeclaration, bool awaitPromise, Target target, CallFunctionOptions? options = null) { var @params = new CallFunctionParameters(functionDeclaration, awaitPromise, target, options?.Arguments, options?.ResultOwnership, options?.SerializationOptions, options?.This, options?.UserActivation); return await Broker.ExecuteCommandAsync(new CallFunctionCommand(@params), options, _jsonContext.CallFunctionCommand, _jsonContext.EvaluateResult).ConfigureAwait(false); } ... (clipped 3 lines)
Ticket Compliance
🟡	🎫 #5678 🔴 Investigate and resolve ChromeDriver "Error: ConnectFailure (Connection refused)" occurring on subsequent ChromeDriver instantiations on Ubuntu 16.04.4 with Chrome 65/ChromeDriver 2.35 and Selenium 3.9.0. Provide a fix or guidance so that multiple ChromeDriver instances can be created without connection failures.
🟡	🎫 #1234 🔴 Ensure that WebDriver click() triggers JavaScript in link href (javascript:) as it did in 2.47.1, addressing regression observed in 2.48.x with Firefox 42. Provide compatibility or a fix specific to Firefox so JS hrefs execute on click.
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: No logging: The new annotations and method signatures add no audit logging for critical scripting actions, but this PR appears focused on annotations and may rely on existing logging elsewhere. Referred Code public async Task<AddPreloadScriptResult> AddPreloadScriptAsync([StringSyntax(StringSyntaxConstants.JavaScript)] string functionDeclaration, BrowsingContextAddPreloadScriptOptions? options = null) { AddPreloadScriptOptions addPreloadScriptOptions = new(options) { Contexts = [context] }; return await scriptModule.AddPreloadScriptAsync(functionDeclaration, addPreloadScriptOptions).ConfigureAwait(false); } public async Task<GetRealmsResult> GetRealmsAsync(GetRealmsOptions? options = null) { options ??= new(); options.Context = context; return await scriptModule.GetRealmsAsync(options).ConfigureAwait(false); } public Task<EvaluateResult> EvaluateAsync([StringSyntax(StringSyntaxConstants.JavaScript)] string expression, bool awaitPromise, EvaluateOptions? options = null, ContextTargetOptions? targetOptions = null) { ... (clipped 34 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: No error handling: Newly added parameter annotations and method overloads do not add null/empty validation or exception handling for JavaScript strings, but this may be intentionally delegated to lower layers. Referred Code public async Task<AddPreloadScriptResult> AddPreloadScriptAsync([StringSyntax(StringSyntaxConstants.JavaScript)] string functionDeclaration, BrowsingContextAddPreloadScriptOptions? options = null) { AddPreloadScriptOptions addPreloadScriptOptions = new(options) { Contexts = [context] }; return await scriptModule.AddPreloadScriptAsync(functionDeclaration, addPreloadScriptOptions).ConfigureAwait(false); } public async Task<GetRealmsResult> GetRealmsAsync(GetRealmsOptions? options = null) { options ??= new(); options.Context = context; return await scriptModule.GetRealmsAsync(options).ConfigureAwait(false); } public Task<EvaluateResult> EvaluateAsync([StringSyntax(StringSyntaxConstants.JavaScript)] string expression, bool awaitPromise, EvaluateOptions? options = null, ContextTargetOptions? targetOptions = null) { ... (clipped 34 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Input validation: JavaScript string inputs are annotated but not validated or sanitized in the new code, which could be acceptable if the BiDi protocol layer handles safety and serialization. Referred Code internal sealed record EvaluateParameters([StringSyntax(StringSyntaxConstants.JavaScript)] string Expression, Target Target, bool AwaitPromise, ResultOwnership? ResultOwnership, SerializationOptions? SerializationOptions, bool? UserActivation) : Parameters; public sealed class EvaluateOptions : CommandOptions Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Learned best practice	Factor duplicated target construction Extract the repeated ContextTarget building into a private helper to avoid duplication and keep behavior consistent. dotnet/src/webdriver/BiDi/BrowsingContext/BrowsingContextScriptModule.cs [48-77] +private ContextTarget BuildContextTarget(ContextTargetOptions? targetOptions) +{ + var target = new ContextTarget(context); + if (targetOptions is not null) + { + target.Sandbox = targetOptions.Sandbox; + } + return target; +} + public Task<EvaluateResult> EvaluateAsync([StringSyntax(StringSyntaxConstants.JavaScript)] string expression, bool awaitPromise, EvaluateOptions? options = null, ContextTargetOptions? targetOptions = null) { - var contextTarget = new ContextTarget(context); - - if (targetOptions is not null) - { - contextTarget.Sandbox = targetOptions.Sandbox; - } - - return scriptModule.EvaluateAsync(expression, awaitPromise, contextTarget, options); + return scriptModule.EvaluateAsync(expression, awaitPromise, BuildContextTarget(targetOptions), options); } public Task<EvaluateResult> CallFunctionAsync([StringSyntax(StringSyntaxConstants.JavaScript)] string functionDeclaration, bool awaitPromise, CallFunctionOptions? options = null, ContextTargetOptions? targetOptions = null) { - var contextTarget = new ContextTarget(context); - - if (targetOptions is not null) - { - contextTarget.Sandbox = targetOptions.Sandbox; - } - - return scriptModule.CallFunctionAsync(functionDeclaration, awaitPromise, contextTarget, options); + return scriptModule.CallFunctionAsync(functionDeclaration, awaitPromise, BuildContextTarget(targetOptions), options); } Apply / Chat Suggestion importance[1-10]: 6 __ Why: Relevant best practice - Replace ad-hoc duplication with shared helpers/utilities to centralize repeated target construction logic.	Low
Update

[RenderMichael]

No functional changes, only IDE attributes. Merging.