feat(adt): Adding see-also section for sync methods (#12470)

sdk/digitaltwins/Azure.DigitalTwins.Core/src/DigitalTwinsClient.cs

@@ -266,6 +266,9 @@ public virtual Task<Response<string>> UpdateDigitalTwinAsync(string digitalTwinI
         /// <param name="requestOptions">The optional settings for this request.</param>
         /// <returns>The http response.</returns>
         /// <param name="cancellationToken">The cancellationToken.</param>
+        /// <seealso cref="UpdateDigitalTwinAsync(string, string, RequestOptions, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Response<string> UpdateDigitalTwin(string digitalTwinId, string digitalTwinUpdateOperations, RequestOptions requestOptions = default, CancellationToken cancellationToken = default)
         {
             return _dtRestClient.Update(digitalTwinId, digitalTwinUpdateOperations, requestOptions?.IfMatchEtag, cancellationToken);
@@ -297,6 +300,9 @@ public virtual Task<Response<string>> GetComponentAsync(string digitalTwinId, st
         /// <param name="componentPath">The component being retrieved.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
         /// <returns>Json string representation of the component corresponding to the provided componentPath and the HTTP response.</returns>
+        /// <seealso cref="GetComponentAsync(string, string, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Response<string> GetComponent(string digitalTwinId, string componentPath, CancellationToken cancellationToken = default)
         {
             return _dtRestClient.GetComponent(digitalTwinId, componentPath, cancellationToken);
@@ -338,6 +344,9 @@ public virtual Task<Response<string>> UpdateComponentAsync(string digitalTwinId,
         /// <param name="requestOptions">The optional settings for this request.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
         /// <returns>The HTTP response.</returns>
+        /// <seealso cref="UpdateComponentAsync(string, string, string, RequestOptions, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Response<string> UpdateComponent(string digitalTwinId, string componentPath, string componentUpdateOperations, RequestOptions requestOptions = default, CancellationToken cancellationToken = default)
         {
             return _dtRestClient.UpdateComponent(digitalTwinId, componentPath, componentUpdateOperations, requestOptions?.IfMatchEtag, cancellationToken);
@@ -404,6 +413,9 @@ async Task<Page<string>> NextPageFunc(string nextLink, int? pageSizeHint)
         /// <param name="relationshipName">The name of a relationship to filter to. If null, all relationships for the digital twin will be returned.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
         /// <returns>The pageable list of application/json relationships belonging to the specified digital twin and the http response.</returns>
+        /// <seealso cref="GetRelationshipsAsync(string, string, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Pageable<string> GetRelationships(string digitalTwinId, string relationshipName = null, CancellationToken cancellationToken = default)
         {
             if (digitalTwinId == null)
@@ -500,6 +512,9 @@ async Task<Page<IncomingRelationship>> NextPageFunc(string nextLink, int? pageSi
         /// <param name="digitalTwinId">The Id of the target digital twin.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
         /// <returns>The pageable list of application/json relationships directed towards the specified digital twin and the http response.</returns>
+        /// <seealso cref="GetIncomingRelationshipsAsync(string, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Pageable<IncomingRelationship> GetIncomingRelationships(string digitalTwinId, CancellationToken cancellationToken = default)
         {
             Page<IncomingRelationship> FirstPageFunc(int? pageSizeHint)
@@ -558,6 +573,9 @@ public virtual Task<Response<string>> GetRelationshipAsync(string digitalTwinId,
         /// <param name="cancellationToken">The cancellation token.</param>
         /// <returns>The application/json relationship corresponding to the provided relationshipId and the http response.</returns>
         /// <remarks>This returned application/json string can always be serialized into an instance of <see cref="Azure.DigitalTwins.Core.Serialization.BasicRelationship"/> or into an extension of that type.</remarks>
+        /// <seealso cref="GetRelationshipAsync(string, string, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Response<string> GetRelationship(string digitalTwinId, string relationshipId, CancellationToken cancellationToken = default)
         {
             return _dtRestClient.GetRelationshipById(digitalTwinId, relationshipId, cancellationToken);
@@ -584,6 +602,9 @@ public virtual Task<Response> DeleteRelationshipAsync(string digitalTwinId, stri
         /// <param name="requestOptions">The optional settings for this request.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
         /// <returns>The http response.</returns>
+        /// <seealso cref="DeleteRelationshipAsync(string, string, RequestOptions, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Response DeleteRelationship(string digitalTwinId, string relationshipId, RequestOptions requestOptions = default, CancellationToken cancellationToken = default)
         {
             return _dtRestClient.DeleteRelationship(digitalTwinId, relationshipId, requestOptions?.IfMatchEtag, cancellationToken);
@@ -630,6 +651,9 @@ public virtual Task<Response<string>> CreateRelationshipAsync(string digitalTwin
         /// <para>Relationships are a one-way link from a source digital twin to another, as described at creation time of the assigned model of the digital twin.</para>
         /// <para>This argument must be the serialization of an instance of <see cref="Azure.DigitalTwins.Core.Serialization.BasicRelationship"/> or the serialization of an extension of that type.</para>
         /// </remarks>
+        /// <seealso cref="CreateRelationshipAsync(string, string, string, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Response<string> CreateRelationship(string digitalTwinId, string relationshipId, string relationship, CancellationToken cancellationToken = default)
         {
             return _dtRestClient.AddRelationship(digitalTwinId, relationshipId, relationship, cancellationToken);
@@ -659,6 +683,9 @@ public virtual Task<Response> UpdateRelationshipAsync(string digitalTwinId, stri
         /// <param name="requestOptions">The optional settings for this request.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
         /// <returns>The http response.</returns>
+        /// <seealso cref="UpdateRelationshipAsync(string, string, string, RequestOptions, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Response UpdateRelationship(string digitalTwinId, string relationshipId, string relationshipUpdateOperations, RequestOptions requestOptions = default, CancellationToken cancellationToken = default)
         {
             return _dtRestClient.UpdateRelationship(digitalTwinId, relationshipId, relationshipUpdateOperations, requestOptions?.IfMatchEtag, cancellationToken);
@@ -726,6 +753,9 @@ async Task<Page<ModelData>> NextPageFunc(string nextLink, int? pageSizeHint)
         /// <param name="options">The options to follow when listing the models. For example, the page size hint can be specified.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
         /// <returns>A pageable set of application/json models and the http response.</returns>
+        /// <seealso cref="GetModelsAsync(IEnumerable{string}, bool, GetModelsOptions, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Pageable<ModelData> GetModels(IEnumerable<string> dependenciesFor = default, bool includeModelDefinition = false, GetModelsOptions options = default, CancellationToken cancellationToken = default)
         {
             Page<ModelData> FirstPageFunc(int? pageSizeHint)
@@ -786,6 +816,9 @@ public virtual Task<Response<ModelData>> GetModelAsync(string modelId, Cancellat
         /// <param name="modelId">The Id of the model.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
         /// <returns>The application/json model and the http response.</returns>
+        /// <seealso cref="GetModelAsync(string, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Response<ModelData> GetModel(string modelId, CancellationToken cancellationToken = default)
         {
             // The GetModel API will include the model definition in its response by default.
@@ -833,6 +866,9 @@ public virtual Task<Response> DecommissionModelAsync(string modelId, Cancellatio
         /// However, existing digital twins may continue to use this model.
         /// Once a model is decomissioned, it may not be recommissioned.
         /// </remarks>
+        /// <seealso cref="DecommissionModelAsync(string, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Response DecommissionModel(string modelId, CancellationToken cancellationToken = default)
         {
             return _dtModelsRestClient.Update(modelId, ModelsConstants.DecommissionModelOperationList, cancellationToken);
@@ -873,6 +909,9 @@ public virtual Task<Response<IReadOnlyList<ModelData>>> CreateModelsAsync(IEnume
         /// The service evaluates all models to ensure all references are satisfied, and then accepts or rejects the set.
         /// So using this method, model creation is transactional.
         /// </remarks>
+        /// <seealso cref="CreateModelsAsync(IEnumerable{string}, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Response<IReadOnlyList<ModelData>> CreateModels(IEnumerable<string> models, CancellationToken cancellationToken = default)
         {
             return _dtModelsRestClient.Add(models, cancellationToken);
@@ -923,6 +962,9 @@ public virtual Task<Response> DeleteModelAsync(string modelId, CancellationToken
         /// 404 (Not Found): There is no model with the provided id.
         /// 409 (Conflict): There are dependencies on the model that prevent it from being deleted.
         /// </remarks>
+        /// <seealso cref="DeleteModelAsync(string, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Response DeleteModel(string modelId, CancellationToken cancellationToken = default)
         {
             return _dtModelsRestClient.Delete(modelId, cancellationToken);
@@ -1006,6 +1048,9 @@ async Task<Page<string>> NextPageFunc(string nextLink, int? pageSizeHint)
         /// <example>
         /// A basic query for all digital twins: SELECT * FROM digitalTwins.
         /// </example>
+        /// <seealso cref="QueryAsync(string, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Pageable<string> Query(string query, CancellationToken cancellationToken = default)
         {
             // Note: pageSizeHint is not supported as a parameter in the service for query API, so ignoring it.
@@ -1111,6 +1156,9 @@ async Task<Page<EventRoute>> NextPageFunc(string nextLink, int? pageSizeHint)
         /// <param name="options">The options to use when listing the event routes. One can set the maximum number of items to retrieve per request, however the service may return less than requested.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
         /// <returns>A pageable set of application/json event routes and the http response.</returns>
+        /// <seealso cref="GetEventRoutesAsync(EventRoutesListOptions, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Pageable<EventRoute> GetEventRoutes(EventRoutesListOptions options = default, CancellationToken cancellationToken = default)
         {
             Page<EventRoute> FirstPageFunc(int? pageSizeHint)
@@ -1165,6 +1213,9 @@ public virtual Task<Response<EventRoute>> GetEventRouteAsync(string eventRouteId
         /// <param name="eventRouteId">The Id of the event route.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
         /// <returns>The application/json event routes and the http response.</returns>
+        /// <seealso cref="GetEventRouteAsync(string, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Response<EventRoute> GetEventRoute(string eventRouteId, CancellationToken cancellationToken = default)
         {
             return _eventRoutesRestClient.GetById(eventRouteId, cancellationToken);
@@ -1200,6 +1251,9 @@ public virtual Task<Response> CreateEventRouteAsync(string eventRouteId, EventRo
         /// <param name="eventRoute">The event route data containing the endpoint and optional filter.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
         /// <returns>The http response.</returns>
+        /// <seealso cref="CreateEventRouteAsync(string, EventRoute, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Response CreateEventRoute(string eventRouteId, EventRoute eventRoute, CancellationToken cancellationToken = default)
         {
             return _eventRoutesRestClient.Add(eventRouteId, eventRoute, cancellationToken);
@@ -1227,6 +1281,9 @@ public virtual Task<Response> DeleteEventRouteAsync(string eventRouteId, Cancell
         /// <param name="eventRouteId">The Id of the event route to delete.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
         /// <returns>The http response.</returns>
+        /// <seealso cref="DeleteEventRouteAsync(string, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Response DeleteEventRoute(string eventRouteId, CancellationToken cancellationToken = default)
         {
             return _eventRoutesRestClient.Delete(eventRouteId, cancellationToken);
@@ -1268,6 +1325,9 @@ public virtual Task<Response> PublishTelemetryAsync(string digitalTwinId, string
         /// <param name="options">The additional information to be used when processing a telemetry request.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
         /// <returns>The http response.</returns>
+        /// <seealso cref="PublishTelemetryAsync(string, string, TelemetryOptions, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Response PublishTelemetry(string digitalTwinId, string payload, TelemetryOptions options = default, CancellationToken cancellationToken = default)
         {
             TelemetryOptions telemetryOptions = options ?? new TelemetryOptions();
@@ -1318,6 +1378,9 @@ public virtual Task<Response> PublishComponentTelemetryAsync(string digitalTwinI
         /// <param name="options">The additional information to be used when processing a telemetry request.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
         /// <returns>The http response.</returns>
+        /// <seealso cref="PublishComponentTelemetryAsync(string, string, string, TelemetryOptions, CancellationToken)">
+        /// See the asynchronous version of this method for examples.
+        /// </seealso>
         public virtual Response PublishComponentTelemetry(string digitalTwinId, string componentName, string payload, TelemetryOptions options = default, CancellationToken cancellationToken = default)
         {
             TelemetryOptions telemetryOptions = options ?? new TelemetryOptions();

sdk/digitaltwins/Azure.DigitalTwins.Core/src/RequestOptions.cs

@@ -17,6 +17,9 @@ public class RequestOptions
         /// only if this ETag matches the value maintained by the server, indicating that the entity has not been modified since it was last retrieved.
         /// To force the operation to execute only if the entity exists, set the ETag to the wildcard character '*'. To force the operation to execute unconditionally, leave this value null.
         /// </summary>
+        /// <remarks>
+        /// If this value is not set, it defaults to null, and the ifMatch header will not be sent with the request. This means that update and delete will be unconditional and the operation will execute regardless of the existence of the resource.
+        /// </remarks>
         public string IfMatchEtag { get; set; } = null;
     }
 }