Rename IncomingFile.WebUrl to ContentUrl

[Corina (corinagum)]

Renames the public IncomingFile.WebUrl property to ContentUrl.

This is not a breaking change

The property has never been published, despite this repo having shipped a stable 2.1.0. Verified rather than assumed:

• I downloaded Microsoft.Teams.Apps 2.1.0 (the current stable) from NuGet and inspected it. It contains zero occurrences of IncomingFile and zero occurrences of WebUrl, in both the assembly and its generated XML doc surface.
• The files feature landed after that package was cut, so nothing consuming a released build can reference this property.

So there are no consumers to break. This is also the last cheap moment: once the files feature ships, the name is locked.

Why

The value arrives on the wire as the attachment's ContentUrl, and Attachment.ContentUrl already exposes it publicly in this same SDK. That left the same value reachable under two different public names depending on which door you came through:

activity.Attachments[0].ContentUrl   // public
ctx.Files[0].WebUrl                  // public, same value, different name

Upstream doesn't call it a "web URL" either. APX sources it from fileInfo.ObjectUrl and writes it into the Bot Framework attachment's ContentUrl slot, so WebUrl was a name this SDK invented at the boundary. The mapping comment in FilesAccessor.cs was the only thing holding the two vocabularies together, and it's now unnecessary: the value is a straight pass-through.

The one real objection, and how it's handled

ContentUrl sits next to the download URL, and it is the one that does not return content. That's a genuine footgun, but it already exists on Attachment.ContentUrl regardless of what we do here, and it's a docs problem rather than a design problem. Two public names for one value is the design problem. So the doc comment now states the trap directly:

Browsable URL to the file in OneDrive/SharePoint, as sent on the attachment's contentUrl. Not fetchable for bytes despite the name.

Scope note

Microsoft.Teams.Cards has an unrelated WebUrl (Adaptive Card Loop metadata). It is deliberately untouched; the rename is scoped to the Files namespace. The build succeeding is itself proof of completeness, since any stale reference would fail to compile.

Cross-SDK

Companion to microsoft/teams.ts#773 and microsoft/teams.py#580. The feature is unreleased in all three, so all three can move together. Published docs in teams-sdk are updated separately.

Validation

Build clean (0 errors). 528 unit tests pass on net10.0, including all 32 Files tests.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Pull request overview

Renames the Files SDK surface for the browsable attachment link from IncomingFile.WebUrl to IncomingFile.ContentUrl, aligning the Files API with the Bot Framework attachment wire name (contentUrl) and the existing Attachment.ContentUrl naming.

Changes:

• Renamed IncomingFile.WebUrl to IncomingFile.ContentUrl and updated its XML documentation.
• Updated FilesAccessor mapping to populate IncomingFile.ContentUrl from TeamsAttachment.ContentUrl.
• Updated Files unit tests to assert against ContentUrl and ensure percent-encoding behavior remains intact.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
test/Microsoft.Teams.Apps.UnitTests/Files/FilesAccessorWireShapeTests.cs	Updates wire-shape mapping assertions to use ContentUrl.
test/Microsoft.Teams.Apps.UnitTests/Files/FilesAccessorTests.cs	Updates unit test expectations to use ContentUrl.
src/Microsoft.Teams.Apps/Files/IncomingFile.cs	Renames the public property to ContentUrl and refreshes its XML doc.
src/Microsoft.Teams.Apps/Files/FilesAccessor.cs	Renames the mapped initializer property to ContentUrl.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.