Document ordering guarantee for X509Chain.ChainElements collection

[Copilot]

Summary

This PR clarifies the ordering of certificates in the X509Chain.ChainElements collection, which was previously undocumented and caused confusion for developers working with certificate chains across different platforms.

Changes Made

Updated the documentation for the ChainElements property in X509Chain.xml to include:

1. Explicit Ordering Guarantee

Added clear statement that the collection is ordered from end-entity (leaf) certificate at index 0 to trust anchor (root certificate) at the final index.

2. Cross-Platform Consistency References

• Windows: References CERT_CHAIN_CONTEXT structure behavior where rgpChain[0] is the end certificate
• Linux/macOS: References OpenSSL's X509_STORE_CTX_get0_chain() which returns certificates ordered from leaf to root

3. Practical Code Example

Added demonstration showing how to reliably access certificates by their position in the chain:

using var chain = new X509Chain();
chain.Build(serverCertificate);

// chain.ChainElements[0] is the leaf (end-entity) certificate
// chain.ChainElements[^1] is the root (trust anchor) certificate

Console.WriteLine("Certificate chain from leaf to root:");
for (int i = 0; i < chain.ChainElements.Count; i++)
{
    var cert = chain.ChainElements[i].Certificate;
    var role = i == 0 ? "Leaf" : 
               i == chain.ChainElements.Count - 1 ? "Root" : "Intermediate";
    Console.WriteLine($"[{i}] {role}: {cert.Subject}");
}

Impact

This documentation enhancement:

• Eliminates ambiguity around certificate chain ordering
• Enables reliable cross-platform code that depends on certificate position
• Provides confidence for developers implementing certificate validation logic
• Maintains backward compatibility (documentation-only change)

The changes are minimal (22 lines added) and focused solely on clarifying existing behavior without modifying any implementation.

Fixes #11359.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.