Update Container API documentation with best practices and modernize external links

[Copilot]

This PR comprehensively updates the Container API documentation to include best practices guidance and removes stale/outdated content as requested in the issue.

Changes Made

📚 Updated External Links (12 instances)

• Modernized all docs.microsoft.com links to learn.microsoft.com across Container API files
• Updated Request Units documentation references
• Fixed REST API documentation links
• Updated LINQ provider and transaction scope documentation links

🚀 Enhanced Documentation with Best Practices

Container Class (Container.cs):

• Added comprehensive performance optimization guidance
• Included resource management best practices
• Added consistency level recommendations
• Enhanced error handling examples with proper exception patterns

Key Method Improvements:

• CreateItemAsync: Added partition key guidance, conflict resolution, and error handling
• ReadItemAsync: Enhanced with performance tips, metadata explanation, and exception handling
• UpsertItemAsync: Added usage guidance, status code interpretation, and concurrency best practices
• Query Methods: Added parameterized query best practices, performance optimization, and indexing guidance
• LINQ Provider: Added async execution recommendations and limitations awareness

Additional Files:

• ContainerProperties.cs: Added container design best practices for partition keys, indexing, and throughput
• ContainerBuilder.cs: Updated fluent API documentation with modern links

💻 Code Examples Improvements

• Modernized all code examples with current C# patterns
• Added comprehensive error handling with try-catch blocks
• Included realistic scenarios with meaningful variable names
• Added RU consumption monitoring examples
• Improved resource management patterns

🔧 Documentation Structure

• Standardized formatting with consistent bullet points and structure
• Removed duplicate/redundant documentation sections
• Fixed StyleCop compliance issues
• Added clear section headers for better readability

Example of Enhanced Documentation

Before:

// Basic example without error handling
ItemResponse item = await container.CreateItemAsync<ToDoActivity>(test, new PartitionKey(test.status));

After:

// Comprehensive example with best practices
try
{
    ToDoActivity newTask = new ToDoActivity()
    {
        id = Guid.NewGuid().ToString(),
        status = "InProgress"
    };

    ItemResponse<ToDoActivity> response = await container.CreateItemAsync<ToDoActivity>(
        newTask, 
        new PartitionKey(newTask.status));
    
    Console.WriteLine($"Created item with id: {response.Resource.id}");
}
catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.Conflict)
{
    // Item with this id already exists
    Console.WriteLine("Item already exists");
}

Quality Assurance

• ✅ All changes build successfully without errors or warnings
• ✅ StyleCop compliance maintained throughout
• ✅ No breaking changes to public API
• ✅ Comprehensive testing of documentation examples

The Container API documentation now provides developers with actionable guidance for building performant, secure, and maintainable Azure Cosmos DB applications.

Fixes #5296.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.