GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/teams.net

Public

mirrored from https://github.com/microsoft/teams.netAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
devtools-port-no-auth

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

teams.net/core/docs

core/docs/CompatTeamsInfo-API-Mapping.md

199lines · modecode

RawDownload
Latest commit unavailable.
1# CompatTeamsInfo API Mapping
2
3This document provides a comprehensive mapping of Bot Framework TeamsInfo static methods to their corresponding REST API endpoints and the Teams Bot Core SDK client implementations.
4
5## Overview
6
7The `CompatTeamsInfo` class provides a compatibility layer that adapts the Bot Framework v4 SDK TeamsInfo API to use the Teams Bot Core SDK. It implements 19 static methods organized into four functional categories.
8
9## API Method Mappings
10
11### Member & Participant Methods
12
13| Method | REST Endpoint | Client | Description |
14|--------|--------------|--------|-------------|
15| `GetMemberAsync` | `GET /v3/conversations/{conversationId}/members/{userId}` | ConversationClient | Gets a single conversation member by user ID |
16| `GetMembersAsync` ⚠️ | `GET /v3/conversations/{conversationId}/members` | ConversationClient | Gets all conversation members (deprecated - use paged version) |
17| `GetPagedMembersAsync` | `GET /v3/conversations/{conversationId}/pagedmembers?pageSize={pageSize}&continuationToken={token}` | ConversationClient | Gets paginated list of conversation members |
18| `GetTeamMemberAsync` | `GET /v3/conversations/{teamId}/members/{userId}` | ConversationClient | Gets a single team member by user ID |
19| `GetTeamMembersAsync` ⚠️ | `GET /v3/conversations/{teamId}/members` | ConversationClient | Gets all team members (deprecated - use paged version) |
20| `GetPagedTeamMembersAsync` | `GET /v3/conversations/{teamId}/pagedmembers?pageSize={pageSize}&continuationToken={token}` | ConversationClient | Gets paginated list of team members |
21
22⚠️ *Deprecated by Microsoft Teams - use paged versions instead*
23
24### Meeting Methods
25
26| Method | REST Endpoint | Client | Description |
27|--------|--------------|--------|-------------|
28| `GetMeetingInfoAsync` | `GET /v1/meetings/{meetingId}` | TeamsApiClient | Gets meeting information by meeting ID |
29| `GetMeetingParticipantAsync` | `GET /v1/meetings/{meetingId}/participants/{participantId}?tenantId={tenantId}` | TeamsApiClient | Gets a specific meeting participant's information |
30| `SendMeetingNotificationAsync` | `POST /v1/meetings/{meetingId}/notification` | TeamsApiClient | Sends an in-meeting notification to participants |
31
32### Team & Channel Methods
33
34| Method | REST Endpoint | Client | Description |
35|--------|--------------|--------|-------------|
36| `GetTeamDetailsAsync` | `GET /v3/teams/{teamId}` | TeamsApiClient | Gets detailed information about a team |
37| `GetTeamChannelsAsync` | `GET /v3/teams/{teamId}/channels` | TeamsApiClient | Gets list of channels in a team |
38
39### Batch Messaging Methods
40
41| Method | REST Endpoint | Client | Description |
42|--------|--------------|--------|-------------|
43| `SendMessageToListOfUsersAsync` | `POST /v3/batch/conversation/users/` | TeamsApiClient | Sends a message to a list of users |
44| `SendMessageToListOfChannelsAsync` | `POST /v3/batch/conversation/channels/` | TeamsApiClient | Sends a message to a list of channels |
45| `SendMessageToAllUsersInTeamAsync` | `POST /v3/batch/conversation/team/` | TeamsApiClient | Sends a message to all users in a team |
46| `SendMessageToAllUsersInTenantAsync` | `POST /v3/batch/conversation/tenant/` | TeamsApiClient | Sends a message to all users in a tenant |
47| `SendMessageToTeamsChannelAsync` | Uses Bot Framework Adapter | BotAdapter.CreateConversationAsync | Creates a conversation in a Teams channel and sends a message |
48
49### Batch Operation Management Methods
50
51| Method | REST Endpoint | Client | Description |
52|--------|--------------|--------|-------------|
53| `GetOperationStateAsync` | `GET /v3/batch/conversation/{operationId}` | TeamsApiClient | Gets the state of a batch operation |
54| `GetPagedFailedEntriesAsync` | `GET /v3/batch/conversation/failedentries/{operationId}?continuationToken={token}` | TeamsApiClient | Gets failed entries from a batch operation |
55| `CancelOperationAsync` | `DELETE /v3/batch/conversation/{operationId}` | TeamsApiClient | Cancels a batch operation |
56
57## Client Distribution
58
59The implementation uses two primary clients from the Teams Bot Core SDK:
60
61### ConversationClient (6 methods)
62Used for member and participant operations in conversations and teams. Accessed via the `IConnectorClient` in TurnState.
63
64**Methods:**
65- GetMemberAsync
66- GetMembersAsync
67- GetPagedMembersAsync
68- GetTeamMemberAsync
69- GetTeamMembersAsync
70- GetPagedTeamMembersAsync
71
72### TeamsApiClient (12 methods)
73Used for Teams-specific operations including meetings, team details, channels, and batch messaging. Added to TurnState by the CompatAdapter.
74
75**Methods:**
76- GetMeetingInfoAsync
77- GetMeetingParticipantAsync
78- SendMeetingNotificationAsync
79- GetTeamDetailsAsync
80- GetTeamChannelsAsync
81- SendMessageToListOfUsersAsync
82- SendMessageToListOfChannelsAsync
83- SendMessageToAllUsersInTeamAsync
84- SendMessageToAllUsersInTenantAsync
85- GetOperationStateAsync
86- GetPagedFailedEntriesAsync
87- CancelOperationAsync
88
89### Bot Framework Adapter (1 method)
90One method uses the Bot Framework adapter directly for backward compatibility.
91
92**Methods:**
93- SendMessageToTeamsChannelAsync
94
95## Implementation Details
96
97### Model Conversion Strategy
98
99The implementation uses two strategies for converting between Bot Framework and Core SDK models:
100
1011. **Direct Property Mapping**: For simple models like `TeamsChannelAccount`, `ChannelInfo`, etc.
1022. **JSON Round-Trip**: For complex models like `TeamDetails`, `MeetingNotificationResponse`, `BatchOperationState`, etc.
103
104### Type Conversions
105
106Key extension methods in `CompatActivity.cs`:
107
108| Extension Method | Source Type | Target Type | Strategy |
109|------------------|-------------|-------------|----------|
110| `ToCompatTeamsChannelAccount` | Core TeamsConversationAccount | BF TeamsChannelAccount | Direct mapping |
111| `ToCompatMeetingInfo` | Core MeetingInfo | BF MeetingInfo | Direct mapping |
112| `ToCompatTeamsMeetingParticipant` | Core MeetingParticipant | BF TeamsMeetingParticipant | Direct mapping |
113| `ToCompatChannelInfo` | Core Channel | BF ChannelInfo | Direct mapping |
114| `ToCompatTeamsPagedMembersResult` | Core PagedMembersResult | BF TeamsPagedMembersResult | Direct mapping |
115| `ToCompatTeamDetails` | Core TeamDetails | BF TeamDetails | JSON round-trip |
116| `ToCompatMeetingNotificationResponse` | Core MeetingNotificationResponse | BF MeetingNotificationResponse | JSON round-trip |
117| `ToCompatBatchOperationState` | Core BatchOperationState | BF BatchOperationState | JSON round-trip |
118| `ToCompatBatchFailedEntriesResponse` | Core BatchFailedEntriesResponse | BF BatchFailedEntriesResponse | JSON round-trip |
119| `FromCompatTeamMember` | BF TeamMember | Core TeamMember | JSON round-trip |
120
121### Authentication
122
123All methods use `AgenticIdentity` extracted from the turn context activity properties for authentication with the Teams services.
124
125### Service URL
126
127All API calls use the service URL from the turn context activity (`turnContext.Activity.ServiceUrl`), which points to the appropriate Teams channel service endpoint.
128
129## Usage Examples
130
131### Getting a Team Member
132
133```csharp
134var member = await TeamsInfo.GetMemberAsync(turnContext, userId, cancellationToken);
135Console.WriteLine($"Member: {member.Name} ({member.Email})");
136```
137
138### Getting Meeting Information
139
140```csharp
141var meetingInfo = await TeamsInfo.GetMeetingInfoAsync(turnContext, meetingId, cancellationToken);
142Console.WriteLine($"Meeting: {meetingInfo.Details.Title}");
143```
144
145### Sending a Batch Message
146
147```csharp
148var activity = MessageFactory.Text("Hello from bot!");
149var members = new List<TeamMember> { new TeamMember(userId1), new TeamMember(userId2) };
150var operationId = await TeamsInfo.SendMessageToListOfUsersAsync(
151 turnContext, activity, members, tenantId, cancellationToken);
152
153// Check operation status
154var state = await TeamsInfo.GetOperationStateAsync(turnContext, operationId, cancellationToken);
155Console.WriteLine($"Operation state: {state.State}");
156```
157
158### Getting Team Channels
159
160```csharp
161var channels = await TeamsInfo.GetTeamChannelsAsync(turnContext, teamId, cancellationToken);
162foreach (var channel in channels)
163{
164 Console.WriteLine($"Channel: {channel.Name} ({channel.Id})");
165}
166```
167
168## Testing
169
170Comprehensive integration tests are available in `test/Microsoft.Teams.Bot.Core.Tests/CompatTeamsInfoTests.cs`. All tests are marked with `[Fact(Skip = "Requires live service credentials")]` and require environment variables to be set for live testing:
171
172- `TEST_USER_ID`
173- `TEST_CONVERSATIONID`
174- `TEST_TEAMID`
175- `TEST_CHANNELID`
176- `TEST_MEETINGID`
177- `TEST_TENANTID`
178
179## Modified Core Models
180
181To support full compatibility, the following Core SDK models were enhanced:
182
183### TeamsConversationAccount
184Added properties to match Bot Framework `TeamsChannelAccount`:
185- `GivenName`
186- `Surname`
187- `Email`
188- `UserPrincipalName`
189- `UserRole`
190- `TenantId`
191
192### MeetingInfo
193Changed `Organizer` property type from `ConversationAccount` to `TeamsConversationAccount` to match Bot Framework schema.
194
195## References
196
197- [Bot Framework TeamsInfo Source](https://github.com/microsoft/botbuilder-dotnet/blob/main/libraries/Microsoft.Bot.Builder/Teams/TeamsInfo.cs)
198- [Teams REST API Documentation](https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-connector-api-reference)
199- [Teams Meeting Notifications](https://docs.microsoft.com/en-us/microsoftteams/platform/apps-in-teams-meetings/meeting-apps-apis)
200