Document MultipartContent zero-part serialization behavior

[Copilot]

Per RFC 1341 (MIME) 7.2, multipart messages must contain one or more body parts. MultipartContent with zero parts serializes as a single dummy empty part (no headers, no body) to satisfy this requirement, but other HTTP clients may not interpret this correctly.

Changes

• Added remarks to MultipartContent documenting the zero-part serialization behavior
• Clarified RFC compliance and backward compatibility rationale
• Added recommendation to include at least one part before serializing

Example

await new MultipartContent("mixed", "111").ReadAsStringAsync();
// Outputs:
// --111
// 
// --111--
// 
// (A single empty part between boundaries)

Addresses #11526

Original prompt

---

This section details on the original issue you should resolve

<issue_title>MultipartContent with zero parts writes itself as a dummy empty part</issue_title>
<issue_description>### Description

RFC 1341 (MIME) 7.2 and all its successors state that multipart messages must contain one or more body parts. A multipart message with no body parts, i.e. consisting of only the closing multipart delimiter, violates the standard. Probably for this reason, System.Net.Http.MultipartContent with zero parts added to it writes itself as a dummy empty part with no content headers or message body. This output follows the letter of the RFC, but may not be what users of MultipartContent without deep knowledge of the RFC expect to happen. Multipart reader implementation in HttpContentMultipartExtension from System.Net.Http.Formatting has a special check to read the resulting message as a multipart content with zero parts (it discards the dummy empty part).

However, (a) other HTTP clients may not interpret this message in the same way, potentially leading to unexpected results, and (b) the RFC does not appear to single out empty parts with no headers or content as being in any way special (chapter 7.2 specifically states that in body parts all headers are optional), so this looks like a backward compatibility. As such, it is almost certainly going to stay that way, although it would probably be more correct for a MultipartContent with zero parts added to it to throw an exception when written out.

Reproduction Steps

Console.WriteLine (await new MultipartContent ("mixed", "111").ReadAsStringAsync ());
prints

--111

--111--

Expected behavior

I suggest adding a sentence to the description of MultipartContent to document this behavior.

Actual behavior

A MultipartContent with zero parts added writes itself as a single dummy empty body part.

Regression?

No response

Known Workarounds

No response

Configuration

No response

Other information

No response</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes MultipartContent with zero parts writes itself as a dummy empty part runtime#115997

---

💡 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.

[Copilot]

Pull Request Overview

This pull request adds documentation to the MultipartContent class in the System.Net.Http namespace, specifically enhancing the <remarks> section which was previously a placeholder.

Key Changes

• Added detailed remarks explaining the behavior of MultipartContent when serialized with zero body parts
• Documented the workaround for servers that don't support empty multipart content