Skip to content

Add API descriptions #301

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ public ConnectionSettings(IConfigurationSection msalConfigurationSection) : base
/// <summary>
/// Validates required properties are present in the configuration for the requested authentication type.
/// </summary>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="System.ArgumentNullException"></exception>
public void ValidateConfiguration()
{
switch (AuthType)
Expand Down
11 changes: 6 additions & 5 deletions src/libraries/Authentication/Authentication.Msal/MsalAuth.cs
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ public class MsalAuth : IAccessTokenProvider, IOBOExchange, IMSALProvider
/// </summary>
/// <param name="systemServiceProvider">Should contain the following objects: a httpClient factory called "MSALClientFactory" and a instance of the MsalAuthConfigurationOptions object</param>
/// <param name="msalConfigurationSection"></param>
public MsalAuth(IServiceProvider systemServiceProvider, IConfigurationSection msalConfigurationSection)
public MsalAuth(IServiceProvider systemServiceProvider, IConfigurationSection msalConfigurationSection)
: this(systemServiceProvider, new ConnectionSettings(msalConfigurationSection))
{
}
Expand Down Expand Up @@ -110,10 +110,11 @@ public async Task<string> GetAccessTokenAsync(string resourceUrl, IList<string>
object msalAuthClient = InnerCreateClientApplication();

// setup the result payload.
ExecuteAuthenticationResults authResultPayload = null;
ExecuteAuthenticationResults authResultPayload = null;
if (msalAuthClient is IConfidentialClientApplication msalConfidentialClient)
{
if (localScopes.Length == 0) {
if (localScopes.Length == 0)
{
throw new ArgumentException("At least one Scope is required for Client Authentication.");
}

Expand Down Expand Up @@ -252,7 +253,7 @@ async Task<String> FetchExternalTokenAsync()
/// <param name="instanceUrl"></param>
/// <param name="scopes">scopes list to create the token for</param>
/// <returns></returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="System.ArgumentNullException"></exception>
private string[] ResolveScopesList(Uri instanceUrl, IList<string> scopes = null)
{
IList<string> _localScopesResolver = new List<string>();
Expand All @@ -264,7 +265,7 @@ private string[] ResolveScopesList(Uri instanceUrl, IList<string> scopes = null)
else
{
var templist = new List<string>();

if (_connectionSettings.Scopes != null)
{
foreach (var scope in _connectionSettings.Scopes)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -420,7 +420,7 @@ public async Task<DialogTurnResult> CancelAllDialogsAsync(bool cancelParents, st
}

// End the active dialog
await dialogContext.EndActiveDialogAsync(DialogReason.CancelCalled,cancellationToken: cancellationToken).ConfigureAwait(false);
await dialogContext.EndActiveDialogAsync(DialogReason.CancelCalled, cancellationToken: cancellationToken).ConfigureAwait(false);
}
else
{
Expand Down Expand Up @@ -544,7 +544,7 @@ public Dialog FindDialog(string dialogId)
if (this.Parent != null)
{
var dialog = Parent.FindDialog(dialogId);

if (dialog != null)
{
return dialog;
Expand Down Expand Up @@ -636,7 +636,7 @@ public async Task<bool> EmitEventAsync(string name, object value = null, bool bu
/// Obtain the CultureInfo in DialogContext.
/// </summary>
/// <returns>A string representing the current locale.</returns>
/// <exception cref="CultureNotFoundException">Thrown when no locale is resolved and no default value factory is provided.</exception>
/// <exception cref="System.CultureNotFoundException">Thrown when no locale is resolved and no default value factory is provided.</exception>
public string GetLocale()
{
string locale;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -165,7 +165,7 @@ public async Task<string> ExchangeTurnTokenAsync(ITurnContext turnContext, strin
/// <param name="exchangeConnection"></param>
/// <param name="exchangeScopes"></param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <exception cref="InvalidOperationException">If a flow is already active.</exception>
/// <exception cref="System.InvalidOperationException">If a flow is already active.</exception>
public async Task SignInUserAsync(ITurnContext turnContext, ITurnState turnState, string handlerName, string exchangeConnection = null, IList<string> exchangeScopes = null, CancellationToken cancellationToken = default)
{
AssertionHelpers.ThrowIfNull(turnContext, nameof(turnContext));
Expand Down Expand Up @@ -316,8 +316,8 @@ internal async Task<bool> StartOrContinueSignInUserAsync(ITurnContext turnContex

// Get token or start flow for specified flow.
SignInResponse response = await _dispatcher.SignUserInAsync(
turnContext,
activeFlowName,
turnContext,
activeFlowName,
forceSignIn: !flowContinuation,
exchangeConnection: signInState.RuntimeOBOConnectionName,
exchangeScopes: signInState.RuntimeOBOScopes,
Expand Down Expand Up @@ -376,7 +376,7 @@ internal async Task<bool> StartOrContinueSignInUserAsync(ITurnContext turnContex
}

await turnContext.SendActivitiesAsync(
_options.SignInFailedMessage == null ? [MessageFactory.Text("SignIn Failed")] : _options.SignInFailedMessage(activeFlowName, response),
_options.SignInFailedMessage == null ? [MessageFactory.Text("SignIn Failed")] : _options.SignInFailedMessage(activeFlowName, response),
cancellationToken).ConfigureAwait(false);
return false;
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ public virtual Task DeleteActivityAsync(ITurnContext turnContext, ConversationRe
/// <param name="cancellationToken">A cancellation token that can be used by other objects
/// or threads to receive notice of cancellation.</param>
/// <returns>A task that represents the work queued to execute.</returns>
/// <exception cref="ArgumentNullException">
/// <exception cref="System.ArgumentNullException">
/// <paramref name="turnContext"/> is null.</exception>
/// <remarks>The adapter calls middleware in the order in which you added it.
/// The adapter passes in the context object for the turn and a next delegate,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -378,17 +378,17 @@ private static InvokeResponse ProcessTurnResults(TurnContext turnContext)
/// A connector client is required if the activity's delivery mode is not "ExpectReplies" or "Stream"
/// and the service URL is not null or empty.
/// </returns>
/// <exception cref="ArgumentNullException">Thrown if the <paramref name="activity"/> is null.</exception>
/// <exception cref="System.ArgumentNullException">Thrown if the <paramref name="activity"/> is null.</exception>
private static bool ResolveIfConnectorClientIsNeeded(IActivity activity)
{
Microsoft.Agents.Core.AssertionHelpers.ThrowIfNull(activity, nameof(activity));
switch (activity.DeliveryMode)
{
case DeliveryModes.ExpectReplies:
case DeliveryModes.Stream:
case DeliveryModes.Stream:
if (string.IsNullOrEmpty(activity.ServiceUrl))
return false;
break;
break;
default:
break;
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ public interface IStreamingResponse
/// before sending the final Message.
/// </remarks>
/// <returns>A Task representing the async operation</returns>
/// <exception cref="InvalidOperationException">Throws if the stream has already ended.</exception>
/// <exception cref="System.InvalidOperationException">Throws if the stream has already ended.</exception>
Task EndStreamAsync(CancellationToken cancellationToken = default);

bool IsStreamStarted();
Expand All @@ -84,15 +84,15 @@ public interface IStreamingResponse
/// </summary>
/// <param name="text">Text of the update to send.</param>
/// <param name="cancellationToken"></param>
/// <exception cref="InvalidOperationException">Throws if the stream has already ended.</exception>
/// <exception cref="System.InvalidOperationException">Throws if the stream has already ended.</exception>
Task QueueInformativeUpdateAsync(string text, CancellationToken cancellationToken = default);

/// <summary>
/// Queues a chunk of partial message text to be sent to the client.
/// </summary>
/// <param name="text">Partial text of the message to send.</param>
/// <param name="citations">Citations to include in the message.</param>
/// <exception cref="InvalidOperationException">Throws if the stream has already ended.</exception>
/// <exception cref="System.InvalidOperationException">Throws if the stream has already ended.</exception>
void QueueTextChunk(string text);

/// <summary>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -265,7 +265,7 @@ public interface ITurnContext
/// </summary>
/// <param name="handler">The handler to add to the context object.</param>
/// <returns>The updated context object.</returns>
/// <exception cref="ArgumentNullException"><paramref name="handler"/> is <c>null</c>.</exception>
/// <exception cref="System.ArgumentNullException"><paramref name="handler"/> is <c>null</c>.</exception>
/// <remarks>When the context's <see cref="DeleteActivityAsync(string, CancellationToken)"/> is called,
/// the adapter calls the registered handlers in the order in which they were
/// added to the context object.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ public LocalArrayBufferWriter()
/// with an initial capacity specified.
/// </summary>
/// <param name="initialCapacity">The minimum capacity with which to initialize the underlying buffer.</param>
/// <exception cref="ArgumentException">
/// <exception cref="System.ArgumentException">
/// Thrown when <paramref name="initialCapacity"/> is not positive (i.e. less than or equal to 0).
Copy link
Preview

Copilot AI May 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Include a description of the invalid condition, e.g., 'Thrown when initialCapacity is less than or equal to zero.'

Suggested change
/// Thrown when <paramref name="initialCapacity"/> is not positive (i.e. less than or equal to 0).
/// Thrown when <paramref name="initialCapacity"/> is less than or equal to zero.

Copilot uses AI. Check for mistakes.

/// </exception>
public LocalArrayBufferWriter(int initialCapacity)
Expand Down Expand Up @@ -111,10 +111,10 @@ public void Clear()
/// <summary>
/// Notifies <see cref="IBufferWriter{T}"/> that <paramref name="count"/> amount of data was written to the output <see cref="Span{T}"/>/<see cref="Memory{T}"/>
/// </summary>
/// <exception cref="ArgumentException">
/// <exception cref="System.ArgumentException">
/// Thrown when <paramref name="count"/> is negative.
/// </exception>
/// <exception cref="InvalidOperationException">
/// <exception cref="System.InvalidOperationException">
/// Thrown when attempting to advance past the end of the underlying buffer.
/// </exception>
/// <remarks>
Expand All @@ -135,7 +135,7 @@ public void Advance(int count)
/// Returns a <see cref="Memory{T}"/> to write to that is at least the requested length (specified by <paramref name="sizeHint"/>).
/// If no <paramref name="sizeHint"/> is provided (or it's equal to <code>0</code>), some non-empty buffer is returned.
/// </summary>
/// <exception cref="ArgumentException">
/// <exception cref="System.ArgumentException">
/// Thrown when <paramref name="sizeHint"/> is negative.
/// </exception>
/// <remarks>
Expand Down Expand Up @@ -166,7 +166,7 @@ public Memory<T> GetMemory(int sizeHint = 0)
/// Returns a <see cref="Span{T}"/> to write to that is at least the requested length (specified by <paramref name="sizeHint"/>).
/// If no <paramref name="sizeHint"/> is provided (or it's equal to <code>0</code>), some non-empty buffer is returned.
/// </summary>
/// <exception cref="ArgumentException">
/// <exception cref="System.ArgumentException">
/// Thrown when <paramref name="sizeHint"/> is negative.
/// </exception>
/// <remarks>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@ namespace Microsoft.Agents.Builder
/// <remarks>
/// Connector and UserToken client factory.
/// </remarks>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentException"></exception>
/// <exception cref="InvalidOperationException">Thrown when an instance of <see cref="IAccessTokenProvider"/> is not found via <see cref="IConnections"/>.</exception>
/// <exception cref="System.ArgumentNullException"></exception>
/// <exception cref="System.ArgumentException"></exception>
Comment on lines +26 to +27
Copy link
Preview

Copilot AI May 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add context to this exception tag, e.g., 'Thrown when a required parameter is null.'

Suggested change
/// <exception cref="System.ArgumentNullException"></exception>
/// <exception cref="System.ArgumentException"></exception>
/// <exception cref="System.ArgumentNullException">Thrown when a required parameter, such as <paramref name="connections"/> or <paramref name="httpClientFactory"/>, is null.</exception>
/// <exception cref="System.ArgumentException">Thrown when an argument provided to the constructor is invalid.</exception>

Copilot uses AI. Check for mistakes.

/// <exception cref="System.InvalidOperationException">Thrown when an instance of <see cref="IAccessTokenProvider"/> is not found via <see cref="IConnections"/>.</exception>
public class RestChannelServiceClientFactory : IChannelServiceClientFactory
{
private readonly string _tokenServiceEndpoint;
Expand Down Expand Up @@ -111,7 +111,7 @@ public Task<IUserTokenClient> CreateUserTokenClientAsync(ClaimsIdentity claimsId
var tokenAccess = _connections.GetTokenProvider(claimsIdentity, _tokenServiceEndpoint);
return tokenAccess.GetAccessTokenAsync(_tokenServiceAudience, null);
}
catch(Exception ex)
catch (Exception ex)
{
// have to do it this way b/c of the lambda expression.
throw Microsoft.Agents.Core.Errors.ExceptionHelper.GenerateException<OperationCanceledException>(
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ public abstract class AgentState : IPropertyManager, IAgentState
/// The object uses <paramref name="storage"/> to persist state property values.
/// The object uses the <paramref name="stateName"/> to cache state within the context for each turn.
/// </remarks>
/// <exception cref="ArgumentNullException"><paramref name="storage"/> or <paramref name="stateName"/>
/// <exception cref="System.ArgumentNullException"><paramref name="storage"/> or <paramref name="stateName"/>
/// is <c>null</c>.</exception>
/// <seealso cref="ITurnContext"/>
public AgentState(IStorage storage, string stateName)
Expand All @@ -51,7 +51,7 @@ public AgentState(IStorage storage, string stateName)
/// <typeparam name="T">The value type of the property.</typeparam>
/// <param name="name">The name of the property.</param>
/// <returns>An accessor for the property.</returns>
/// <exception cref="ArgumentNullException"><paramref name="name"/> is <c>null</c>.</exception>
/// <exception cref="System.ArgumentNullException"><paramref name="name"/> is <c>null</c>.</exception>
[Obsolete("Use AgentState.GetValue and AgentsState.SetValue")]
public IStatePropertyAccessor<T> CreateProperty<T>(string name)
{
Expand Down Expand Up @@ -199,7 +199,7 @@ private bool ShouldLoad(ITurnContext turnContext, string storageKey, bool force)
public virtual async Task SaveChangesAsync(ITurnContext turnContext, bool force = false, CancellationToken cancellationToken = default)
{
AssertionHelpers.ThrowIfNull(turnContext, nameof(turnContext));

var cachedState = GetCachedState();
if (cachedState != null && (force || cachedState.IsChanged()))
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ public interface IAgentState
/// <param name="cancellationToken">A cancellation token that can be used by other objects
/// or threads to receive notice of cancellation.</param>
/// <returns>A task that represents the work queued to execute.</returns>
/// <exception cref="ArgumentNullException"><paramref name="turnContext"/> is <c>null</c>.</exception>
/// <exception cref="System.ArgumentNullException"><paramref name="turnContext"/> is <c>null</c>.</exception>
Task LoadAsync(ITurnContext turnContext, bool force = false, CancellationToken cancellationToken = default);

/// <summary>
Expand All @@ -95,7 +95,7 @@ public interface IAgentState
/// <param name="cancellationToken">A cancellation token that can be used by other objects
/// or threads to receive notice of cancellation.</param>
/// <returns>A task that represents the work queued to execute.</returns>
/// <exception cref="ArgumentNullException"><paramref name="turnContext"/> is <c>null</c>.</exception>
/// <exception cref="System.ArgumentNullException"><paramref name="turnContext"/> is <c>null</c>.</exception>
Task SaveChangesAsync(ITurnContext turnContext, bool force = false, CancellationToken cancellationToken = default);

/// <summary>
Expand All @@ -105,7 +105,7 @@ public interface IAgentState
/// <param name="cancellationToken">A cancellation token that can be used by other objects
/// or threads to receive notice of cancellation.</param>
/// <returns>A task that represents the work queued to execute.</returns>
/// <exception cref="ArgumentNullException"><paramref name="turnContext"/> is <c>null</c>.</exception>
/// <exception cref="System.ArgumentNullException"><paramref name="turnContext"/> is <c>null</c>.</exception>
Task DeleteStateAsync(ITurnContext turnContext, CancellationToken cancellationToken = default);
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ public interface ITurnState
/// <param name="cancellationToken">A cancellation token that can be used by other objects
/// or threads to receive notice of cancellation.</param>
/// <returns>A task that represents the work queued to execute.</returns>
/// <exception cref="ArgumentNullException"><paramref name="turnContext"/> is <c>null</c>.</exception>
/// <exception cref="System.ArgumentNullException"><paramref name="turnContext"/> is <c>null</c>.</exception>
Task LoadStateAsync(ITurnContext turnContext, bool force = false, CancellationToken cancellationToken = default);

/// <summary>
Expand All @@ -98,7 +98,7 @@ public interface ITurnState
/// <param name="cancellationToken">A cancellation token that can be used by other objects
/// or threads to receive notice of cancellation.</param>
/// <returns>A task that represents the work queued to execute.</returns>
/// <exception cref="ArgumentNullException"><paramref name="turnContext"/> is <c>null</c>.</exception>
/// <exception cref="System.ArgumentNullException"><paramref name="turnContext"/> is <c>null</c>.</exception>
Task SaveStateAsync(ITurnContext turnContext, bool force = false, CancellationToken cancellationToken = default);
}
}
Loading
Loading