Clarify CertificateChainPolicy property supersession in SSL authentication options

[Copilot]

The documentation for CertificateChainPolicy stated that certain properties are "ignored" when set, but didn't explain what supersedes them or link to the relevant properties.

Changes

• Client and server authentication options: Replaced "ignored" language with explicit "superseded by" statements that link to the corresponding X509ChainPolicy properties

  • CertificateRevocationCheckMode → X509ChainPolicy.RevocationMode
  • Trust settings → X509ChainPolicy.TrustMode and X509ChainPolicy.CustomTrustStore

• Server-specific behavior: Preserved the note that the trust list is still transmitted in the handshake even when superseded

This makes the API behavior more discoverable and clarifies which properties developers should configure on the chain policy instead.

Original prompt

Repository: dotnet/dotnet-api-docs

Update XML API documentation to improve remarks for:

• System.Net.Security.SslClientAuthenticationOptions.CertificateChainPolicy
• System.Net.Security.SslServerAuthenticationOptions.CertificateChainPolicy

Goal:

• In the <remarks> section for each CertificateChainPolicy property, clarify that when the value is not null, the properties listed as "ignored" are superseded by relevant settings on the provided X509ChainPolicy.
• Use a conversational tone with contractions.
• Be concise.
• Break up long sentences.
• Use present tense.
• Avoid the word "may"; use "might" or "can".
• Use a comma before clauses that begin with "which".
• Use the Oxford comma.

Content requirements:

• Explicitly say that ignored properties are superseded by the corresponding properties on System.Security.Cryptography.X509Certificates.X509ChainPolicy.
• Include links (<xref:...>) to the superseding chain policy properties.
  • For CertificateRevocationCheckMode, link to X509ChainPolicy.RevocationMode.
  • For trust behavior, link to X509ChainPolicy.TrustMode and, when appropriate, X509ChainPolicy.CustomTrustStore.
  • If additional ignored properties exist for server options, map them to the relevant X509ChainPolicy properties and link them.

Files:

• Edit xml/System.Net.Security/SslClientAuthenticationOptions.xml.
• Find and edit the corresponding SslServerAuthenticationOptions.xml file under xml/System.Net.Security/.

Notes:

• Code comments (if any are added) must end with a period.
• Do not add inline ``` code blocks inside XML remarks.

Please open a pull request with these doc updates.

This pull request was created from Copilot chat.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

This pull request improves the documentation for the CertificateChainPolicy property in SSL authentication options by clarifying property supersession behavior. The changes replace vague "ignored" language with explicit "superseded by" statements that include xref links to the corresponding X509ChainPolicy properties, making the API behavior more discoverable for developers.

Changes:

• Updated remarks for SslClientAuthenticationOptions.CertificateChainPolicy to explicitly state which properties are superseded with links to X509ChainPolicy.RevocationMode, X509ChainPolicy.TrustMode, and X509ChainPolicy.CustomTrustStore
• Updated remarks for SslServerAuthenticationOptions.CertificateChainPolicy with the same supersession clarifications, plus a note that the trust list is still transmitted in the handshake

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
xml/System.Net.Security/SslServerAuthenticationOptions.xml	Updated CertificateChainPolicy remarks to clarify property supersession with xref links and preserve handshake behavior note
xml/System.Net.Security/SslClientAuthenticationOptions.xml	Updated CertificateChainPolicy remarks to clarify property supersession with xref links