microsoft/teams.net
Publicmirrored fromhttps://github.com/microsoft/teams.netAvailable
core/src/Microsoft.Teams.Bot.Apps/Api/MembersApi.cs
266lines · modecode
| 1 | // Copyright (c) Microsoft Corporation. |
| 2 | // Licensed under the MIT License. |
| 3 | |
| 4 | using Microsoft.Teams.Bot.Apps.Schema; |
| 5 | using Microsoft.Teams.Bot.Core; |
| 6 | using Microsoft.Teams.Bot.Core.Schema; |
| 7 | |
| 8 | namespace Microsoft.Teams.Bot.Apps.Api; |
| 9 | |
| 10 | using CustomHeaders = Dictionary<string, string>; |
| 11 | |
| 12 | /// <summary> |
| 13 | /// Provides member operations for managing conversation members. |
| 14 | /// </summary> |
| 15 | public class MembersApi |
| 16 | { |
| 17 | private readonly ConversationClient _client; |
| 18 | |
| 19 | /// <summary> |
| 20 | /// Initializes a new instance of the <see cref="MembersApi"/> class. |
| 21 | /// </summary> |
| 22 | /// <param name="conversationClient">The conversation client for member operations.</param> |
| 23 | internal MembersApi(ConversationClient conversationClient) |
| 24 | { |
| 25 | _client = conversationClient; |
| 26 | } |
| 27 | |
| 28 | /// <summary> |
| 29 | /// Gets all members of a conversation. |
| 30 | /// </summary> |
| 31 | /// <param name="conversationId">The ID of the conversation.</param> |
| 32 | /// <param name="serviceUrl">The service URL for the conversation.</param> |
| 33 | /// <param name="agenticIdentity">Optional agentic identity for authentication.</param> |
| 34 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 35 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 36 | /// <returns>A task that represents the asynchronous operation. The task result contains a list of conversation members.</returns> |
| 37 | public Task<IList<ConversationAccount>> GetAllAsync( |
| 38 | string conversationId, |
| 39 | Uri serviceUrl, |
| 40 | AgenticIdentity? agenticIdentity = null, |
| 41 | CustomHeaders? customHeaders = null, |
| 42 | CancellationToken cancellationToken = default) |
| 43 | => _client.GetConversationMembersAsync(conversationId, serviceUrl, agenticIdentity, customHeaders, cancellationToken); |
| 44 | |
| 45 | /// <summary> |
| 46 | /// Gets all members of a conversation using activity context. |
| 47 | /// </summary> |
| 48 | /// <param name="activity">The activity providing conversation context. Must contain valid Conversation.Id and ServiceUrl.</param> |
| 49 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 50 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 51 | /// <returns>A task that represents the asynchronous operation. The task result contains a list of conversation members.</returns> |
| 52 | public Task<IList<ConversationAccount>> GetAllAsync( |
| 53 | TeamsActivity activity, |
| 54 | CustomHeaders? customHeaders = null, |
| 55 | CancellationToken cancellationToken = default) |
| 56 | { |
| 57 | ArgumentNullException.ThrowIfNull(activity); |
| 58 | ArgumentNullException.ThrowIfNull(activity.ServiceUrl); |
| 59 | ArgumentNullException.ThrowIfNull(activity.Conversation); |
| 60 | ArgumentException.ThrowIfNullOrWhiteSpace(activity.Conversation.Id); |
| 61 | |
| 62 | return _client.GetConversationMembersAsync( |
| 63 | activity.Conversation.Id, |
| 64 | activity.ServiceUrl, |
| 65 | activity.From?.GetAgenticIdentity(), |
| 66 | customHeaders, |
| 67 | cancellationToken); |
| 68 | } |
| 69 | |
| 70 | /// <summary> |
| 71 | /// Gets a specific member of a conversation. |
| 72 | /// </summary> |
| 73 | /// <typeparam name="T">The type of conversation account to return. Must inherit from <see cref="ConversationAccount"/>.</typeparam> |
| 74 | /// <param name="conversationId">The ID of the conversation.</param> |
| 75 | /// <param name="userId">The ID of the user to retrieve.</param> |
| 76 | /// <param name="serviceUrl">The service URL for the conversation.</param> |
| 77 | /// <param name="agenticIdentity">Optional agentic identity for authentication.</param> |
| 78 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 79 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 80 | /// <returns>A task that represents the asynchronous operation. The task result contains the conversation member.</returns> |
| 81 | public Task<T> GetByIdAsync<T>( |
| 82 | string conversationId, |
| 83 | string userId, |
| 84 | Uri serviceUrl, |
| 85 | AgenticIdentity? agenticIdentity = null, |
| 86 | CustomHeaders? customHeaders = null, |
| 87 | CancellationToken cancellationToken = default) where T : ConversationAccount |
| 88 | => _client.GetConversationMemberAsync<T>(conversationId, userId, serviceUrl, agenticIdentity, customHeaders, cancellationToken); |
| 89 | |
| 90 | /// <summary> |
| 91 | /// Gets a specific member of a conversation using activity context. |
| 92 | /// </summary> |
| 93 | /// <typeparam name="T">The type of conversation account to return. Must inherit from <see cref="ConversationAccount"/>.</typeparam> |
| 94 | /// <param name="activity">The activity providing conversation context. Must contain valid Conversation.Id and ServiceUrl.</param> |
| 95 | /// <param name="userId">The ID of the user to retrieve.</param> |
| 96 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 97 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 98 | /// <returns>A task that represents the asynchronous operation. The task result contains the conversation member.</returns> |
| 99 | public Task<T> GetByIdAsync<T>( |
| 100 | TeamsActivity activity, |
| 101 | string userId, |
| 102 | CustomHeaders? customHeaders = null, |
| 103 | CancellationToken cancellationToken = default) where T : ConversationAccount |
| 104 | { |
| 105 | ArgumentNullException.ThrowIfNull(activity); |
| 106 | ArgumentNullException.ThrowIfNull(activity.Conversation); |
| 107 | ArgumentException.ThrowIfNullOrWhiteSpace(activity.Conversation.Id); |
| 108 | ArgumentNullException.ThrowIfNull(activity.ServiceUrl); |
| 109 | |
| 110 | return _client.GetConversationMemberAsync<T>( |
| 111 | activity.Conversation.Id, |
| 112 | userId, |
| 113 | activity.ServiceUrl, |
| 114 | activity.From?.GetAgenticIdentity(), |
| 115 | customHeaders, |
| 116 | cancellationToken); |
| 117 | } |
| 118 | |
| 119 | /// <summary> |
| 120 | /// Gets a specific member of a conversation. |
| 121 | /// </summary> |
| 122 | /// <param name="conversationId">The ID of the conversation.</param> |
| 123 | /// <param name="userId">The ID of the user to retrieve.</param> |
| 124 | /// <param name="serviceUrl">The service URL for the conversation.</param> |
| 125 | /// <param name="agenticIdentity">Optional agentic identity for authentication.</param> |
| 126 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 127 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 128 | /// <returns>A task that represents the asynchronous operation. The task result contains the conversation member.</returns> |
| 129 | public Task<TeamsConversationAccount> GetByIdAsync( |
| 130 | string conversationId, |
| 131 | string userId, |
| 132 | Uri serviceUrl, |
| 133 | AgenticIdentity? agenticIdentity = null, |
| 134 | CustomHeaders? customHeaders = null, |
| 135 | CancellationToken cancellationToken = default) |
| 136 | => _client.GetConversationMemberAsync<TeamsConversationAccount>(conversationId, userId, serviceUrl, agenticIdentity, customHeaders, cancellationToken); |
| 137 | |
| 138 | /// <summary> |
| 139 | /// Gets a specific member of a conversation using activity context. |
| 140 | /// </summary> |
| 141 | /// <param name="activity">The activity providing conversation context. Must contain valid Conversation.Id and ServiceUrl.</param> |
| 142 | /// <param name="userId">The ID of the user to retrieve.</param> |
| 143 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 144 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 145 | /// <returns>A task that represents the asynchronous operation. The task result contains the conversation member.</returns> |
| 146 | public Task<ConversationAccount> GetByIdAsync( |
| 147 | TeamsActivity activity, |
| 148 | string userId, |
| 149 | CustomHeaders? customHeaders = null, |
| 150 | CancellationToken cancellationToken = default) |
| 151 | { |
| 152 | ArgumentNullException.ThrowIfNull(activity); |
| 153 | ArgumentNullException.ThrowIfNull(activity.Conversation); |
| 154 | ArgumentException.ThrowIfNullOrWhiteSpace(activity.Conversation.Id); |
| 155 | ArgumentNullException.ThrowIfNull(activity.ServiceUrl); |
| 156 | |
| 157 | return _client.GetConversationMemberAsync<ConversationAccount>( |
| 158 | activity.Conversation.Id, |
| 159 | userId, |
| 160 | activity.ServiceUrl, |
| 161 | activity.From?.GetAgenticIdentity(), |
| 162 | customHeaders, |
| 163 | cancellationToken); |
| 164 | } |
| 165 | |
| 166 | /// <summary> |
| 167 | /// Gets members of a conversation one page at a time. |
| 168 | /// </summary> |
| 169 | /// <param name="conversationId">The ID of the conversation.</param> |
| 170 | /// <param name="serviceUrl">The service URL for the conversation.</param> |
| 171 | /// <param name="pageSize">Optional page size for the number of members to retrieve.</param> |
| 172 | /// <param name="continuationToken">Optional continuation token for pagination.</param> |
| 173 | /// <param name="agenticIdentity">Optional agentic identity for authentication.</param> |
| 174 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 175 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 176 | /// <returns>A task that represents the asynchronous operation. The task result contains a page of members and an optional continuation token.</returns> |
| 177 | public Task<PagedMembersResult> GetPagedAsync( |
| 178 | string conversationId, |
| 179 | Uri serviceUrl, |
| 180 | int? pageSize = null, |
| 181 | string? continuationToken = null, |
| 182 | AgenticIdentity? agenticIdentity = null, |
| 183 | CustomHeaders? customHeaders = null, |
| 184 | CancellationToken cancellationToken = default) |
| 185 | => _client.GetConversationPagedMembersAsync(conversationId, serviceUrl, pageSize, continuationToken, agenticIdentity, customHeaders, cancellationToken); |
| 186 | |
| 187 | /// <summary> |
| 188 | /// Gets members of a conversation one page at a time using activity context. |
| 189 | /// </summary> |
| 190 | /// <param name="activity">The activity providing conversation context. Must contain valid Conversation.Id and ServiceUrl.</param> |
| 191 | /// <param name="pageSize">Optional page size for the number of members to retrieve.</param> |
| 192 | /// <param name="continuationToken">Optional continuation token for pagination.</param> |
| 193 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 194 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 195 | /// <returns>A task that represents the asynchronous operation. The task result contains a page of members and an optional continuation token.</returns> |
| 196 | public Task<PagedMembersResult> GetPagedAsync( |
| 197 | TeamsActivity activity, |
| 198 | int? pageSize = null, |
| 199 | string? continuationToken = null, |
| 200 | CustomHeaders? customHeaders = null, |
| 201 | CancellationToken cancellationToken = default) |
| 202 | { |
| 203 | ArgumentNullException.ThrowIfNull(activity); |
| 204 | ArgumentNullException.ThrowIfNull(activity.Conversation); |
| 205 | ArgumentNullException.ThrowIfNull(activity.Conversation.Id); |
| 206 | ArgumentNullException.ThrowIfNull(activity.ServiceUrl); |
| 207 | |
| 208 | return _client.GetConversationPagedMembersAsync( |
| 209 | activity.Conversation.Id, |
| 210 | activity.ServiceUrl, |
| 211 | pageSize, |
| 212 | continuationToken, |
| 213 | activity.From?.GetAgenticIdentity(), |
| 214 | customHeaders, |
| 215 | cancellationToken); |
| 216 | } |
| 217 | |
| 218 | /// <summary> |
| 219 | /// Deletes a member from a conversation. |
| 220 | /// </summary> |
| 221 | /// <param name="conversationId">The ID of the conversation.</param> |
| 222 | /// <param name="memberId">The ID of the member to delete.</param> |
| 223 | /// <param name="serviceUrl">The service URL for the conversation.</param> |
| 224 | /// <param name="agenticIdentity">Optional agentic identity for authentication.</param> |
| 225 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 226 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 227 | /// <returns>A task that represents the asynchronous operation.</returns> |
| 228 | /// <remarks>If the deleted member was the last member of the conversation, the conversation is also deleted.</remarks> |
| 229 | public Task DeleteAsync( |
| 230 | string conversationId, |
| 231 | string memberId, |
| 232 | Uri serviceUrl, |
| 233 | AgenticIdentity? agenticIdentity = null, |
| 234 | CustomHeaders? customHeaders = null, |
| 235 | CancellationToken cancellationToken = default) |
| 236 | => _client.DeleteConversationMemberAsync(conversationId, memberId, serviceUrl, agenticIdentity, customHeaders, cancellationToken); |
| 237 | |
| 238 | /// <summary> |
| 239 | /// Deletes a member from a conversation using activity context. |
| 240 | /// </summary> |
| 241 | /// <param name="activity">The activity providing conversation context. Must contain valid Conversation.Id and ServiceUrl.</param> |
| 242 | /// <param name="memberId">The ID of the member to delete.</param> |
| 243 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 244 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 245 | /// <returns>A task that represents the asynchronous operation.</returns> |
| 246 | /// <remarks>If the deleted member was the last member of the conversation, the conversation is also deleted.</remarks> |
| 247 | public Task DeleteAsync( |
| 248 | TeamsActivity activity, |
| 249 | string memberId, |
| 250 | CustomHeaders? customHeaders = null, |
| 251 | CancellationToken cancellationToken = default) |
| 252 | { |
| 253 | ArgumentNullException.ThrowIfNull(activity); |
| 254 | ArgumentNullException.ThrowIfNull(activity.Conversation); |
| 255 | ArgumentNullException.ThrowIfNull(activity.Conversation.Id); |
| 256 | ArgumentNullException.ThrowIfNull(activity.ServiceUrl); |
| 257 | |
| 258 | return _client.DeleteConversationMemberAsync( |
| 259 | activity.Conversation.Id, |
| 260 | memberId, |
| 261 | activity.ServiceUrl, |
| 262 | activity.From?.GetAgenticIdentity(), |
| 263 | customHeaders, |
| 264 | cancellationToken); |
| 265 | } |
| 266 | } |
| 267 | |