From 27d924c5d85316e68dc5c41b69830eeab9787ce1 Mon Sep 17 00:00:00 2001 From: Sindhu Nagesh Date: Wed, 3 Jun 2020 10:53:45 -0700 Subject: [PATCH] feat(adt): Adding see-also section for sync methods --- .../src/DigitalTwinsClient.cs | 63 +++++++++++++++++++ .../src/RequestOptions.cs | 3 + 2 files changed, 66 insertions(+) diff --git a/sdk/digitaltwins/Azure.DigitalTwins.Core/src/DigitalTwinsClient.cs b/sdk/digitaltwins/Azure.DigitalTwins.Core/src/DigitalTwinsClient.cs index 128a67bf9f5b8..125b2d80407f7 100644 --- a/sdk/digitaltwins/Azure.DigitalTwins.Core/src/DigitalTwinsClient.cs +++ b/sdk/digitaltwins/Azure.DigitalTwins.Core/src/DigitalTwinsClient.cs @@ -254,6 +254,9 @@ public virtual Task> UpdateDigitalTwinAsync(string digitalTwinI /// The optional settings for this request. /// The http response. /// The cancellationToken. + /// + /// See the asynchronous version of this method for examples. + /// public virtual Response UpdateDigitalTwin(string digitalTwinId, string digitalTwinUpdateOperations, RequestOptions requestOptions = default, CancellationToken cancellationToken = default) { return _dtRestClient.Update(digitalTwinId, digitalTwinUpdateOperations, requestOptions?.IfMatchEtag, cancellationToken); @@ -285,6 +288,9 @@ public virtual Task> GetComponentAsync(string digitalTwinId, st /// The component being retrieved. /// The cancellation token. /// Json string representation of the component corresponding to the provided componentPath and the HTTP response. + /// + /// See the asynchronous version of this method for examples. + /// public virtual Response GetComponent(string digitalTwinId, string componentPath, CancellationToken cancellationToken = default) { return _dtRestClient.GetComponent(digitalTwinId, componentPath, cancellationToken); @@ -326,6 +332,9 @@ public virtual Task> UpdateComponentAsync(string digitalTwinId, /// The optional settings for this request. /// The cancellation token. /// The HTTP response. + /// + /// See the asynchronous version of this method for examples. + /// public virtual Response UpdateComponent(string digitalTwinId, string componentPath, string componentUpdateOperations, RequestOptions requestOptions = default, CancellationToken cancellationToken = default) { return _dtRestClient.UpdateComponent(digitalTwinId, componentPath, componentUpdateOperations, requestOptions?.IfMatchEtag, cancellationToken); @@ -392,6 +401,9 @@ async Task> NextPageFunc(string nextLink, int? pageSizeHint) /// The name of a relationship to filter to. If null, all relationships for the digital twin will be returned. /// The cancellation token. /// The pageable list of application/json relationships belonging to the specified digital twin and the http response. + /// + /// See the asynchronous version of this method for examples. + /// public virtual Pageable GetRelationships(string digitalTwinId, string relationshipName = null, CancellationToken cancellationToken = default) { if (digitalTwinId == null) @@ -488,6 +500,9 @@ async Task> NextPageFunc(string nextLink, int? pageSi /// The Id of the target digital twin. /// The cancellation token. /// The pageable list of application/json relationships directed towards the specified digital twin and the http response. + /// + /// See the asynchronous version of this method for examples. + /// public virtual Pageable GetIncomingRelationships(string digitalTwinId, CancellationToken cancellationToken = default) { Page FirstPageFunc(int? pageSizeHint) @@ -546,6 +561,9 @@ public virtual Task> GetRelationshipAsync(string digitalTwinId, /// The cancellation token. /// The application/json relationship corresponding to the provided relationshipId and the http response. /// This returned application/json string can always be serialized into an instance of or into an extension of that type. + /// + /// See the asynchronous version of this method for examples. + /// public virtual Response GetRelationship(string digitalTwinId, string relationshipId, CancellationToken cancellationToken = default) { return _dtRestClient.GetRelationshipById(digitalTwinId, relationshipId, cancellationToken); @@ -572,6 +590,9 @@ public virtual Task DeleteRelationshipAsync(string digitalTwinId, stri /// The optional settings for this request. /// The cancellation token. /// The http response. + /// + /// See the asynchronous version of this method for examples. + /// public virtual Response DeleteRelationship(string digitalTwinId, string relationshipId, RequestOptions requestOptions = default, CancellationToken cancellationToken = default) { return _dtRestClient.DeleteRelationship(digitalTwinId, relationshipId, requestOptions?.IfMatchEtag, cancellationToken); @@ -618,6 +639,9 @@ public virtual Task> CreateRelationshipAsync(string digitalTwin /// 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. /// This argument must be the serialization of an instance of or the serialization of an extension of that type. /// + /// + /// See the asynchronous version of this method for examples. + /// public virtual Response CreateRelationship(string digitalTwinId, string relationshipId, string relationship, CancellationToken cancellationToken = default) { return _dtRestClient.AddRelationship(digitalTwinId, relationshipId, relationship, cancellationToken); @@ -647,6 +671,9 @@ public virtual Task UpdateRelationshipAsync(string digitalTwinId, stri /// The optional settings for this request. /// The cancellation token. /// The http response. + /// + /// See the asynchronous version of this method for examples. + /// 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); @@ -714,6 +741,9 @@ async Task> NextPageFunc(string nextLink, int? pageSizeHint) /// The options to follow when listing the models. For example, the page size hint can be specified. /// The cancellation token. /// A pageable set of application/json models and the http response. + /// + /// See the asynchronous version of this method for examples. + /// public virtual Pageable GetModels(IEnumerable dependenciesFor = default, bool includeModelDefinition = false, GetModelsOptions options = default, CancellationToken cancellationToken = default) { Page FirstPageFunc(int? pageSizeHint) @@ -774,6 +804,9 @@ public virtual Task> GetModelAsync(string modelId, Cancellat /// The Id of the model. /// The cancellation token. /// The application/json model and the http response. + /// + /// See the asynchronous version of this method for examples. + /// public virtual Response GetModel(string modelId, CancellationToken cancellationToken = default) { // The GetModel API will include the model definition in its response by default. @@ -821,6 +854,9 @@ public virtual Task DecommissionModelAsync(string modelId, Cancellatio /// However, existing digital twins may continue to use this model. /// Once a model is decomissioned, it may not be recommissioned. /// + /// + /// See the asynchronous version of this method for examples. + /// public virtual Response DecommissionModel(string modelId, CancellationToken cancellationToken = default) { return _dtModelsRestClient.Update(modelId, ModelsConstants.DecommissionModelOperationList, cancellationToken); @@ -861,6 +897,9 @@ public virtual Task>> 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. /// + /// + /// See the asynchronous version of this method for examples. + /// public virtual Response> CreateModels(IEnumerable models, CancellationToken cancellationToken = default) { return _dtModelsRestClient.Add(models, cancellationToken); @@ -911,6 +950,9 @@ public virtual Task 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. /// + /// + /// See the asynchronous version of this method for examples. + /// public virtual Response DeleteModel(string modelId, CancellationToken cancellationToken = default) { return _dtModelsRestClient.Delete(modelId, cancellationToken); @@ -994,6 +1036,9 @@ async Task> NextPageFunc(string nextLink, int? pageSizeHint) /// /// A basic query for all digital twins: SELECT * FROM digitalTwins. /// + /// + /// See the asynchronous version of this method for examples. + /// public virtual Pageable Query(string query, CancellationToken cancellationToken = default) { // Note: pageSizeHint is not supported as a parameter in the service for query API, so ignoring it. @@ -1099,6 +1144,9 @@ async Task> NextPageFunc(string nextLink, int? pageSizeHint) /// 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. /// The cancellation token. /// A pageable set of application/json event routes and the http response. + /// + /// See the asynchronous version of this method for examples. + /// public virtual Pageable GetEventRoutes(EventRoutesListOptions options = default, CancellationToken cancellationToken = default) { Page FirstPageFunc(int? pageSizeHint) @@ -1153,6 +1201,9 @@ public virtual Task> GetEventRouteAsync(string eventRouteId /// The Id of the event route. /// The cancellation token. /// The application/json event routes and the http response. + /// + /// See the asynchronous version of this method for examples. + /// public virtual Response GetEventRoute(string eventRouteId, CancellationToken cancellationToken = default) { return _eventRoutesRestClient.GetById(eventRouteId, cancellationToken); @@ -1188,6 +1239,9 @@ public virtual Task CreateEventRouteAsync(string eventRouteId, EventRo /// The event route data containing the endpoint and optional filter. /// The cancellation token. /// The http response. + /// + /// See the asynchronous version of this method for examples. + /// public virtual Response CreateEventRoute(string eventRouteId, EventRoute eventRoute, CancellationToken cancellationToken = default) { return _eventRoutesRestClient.Add(eventRouteId, eventRoute, cancellationToken); @@ -1215,6 +1269,9 @@ public virtual Task DeleteEventRouteAsync(string eventRouteId, Cancell /// The Id of the event route to delete. /// The cancellation token. /// The http response. + /// + /// See the asynchronous version of this method for examples. + /// public virtual Response DeleteEventRoute(string eventRouteId, CancellationToken cancellationToken = default) { return _eventRoutesRestClient.Delete(eventRouteId, cancellationToken); @@ -1256,6 +1313,9 @@ public virtual Task PublishTelemetryAsync(string digitalTwinId, string /// The additional information to be used when processing a telemetry request. /// The cancellation token. /// The http response. + /// + /// See the asynchronous version of this method for examples. + /// public virtual Response PublishTelemetry(string digitalTwinId, string payload, TelemetryOptions options = default, CancellationToken cancellationToken = default) { TelemetryOptions telemetryOptions = options ?? new TelemetryOptions(); @@ -1306,6 +1366,9 @@ public virtual Task PublishComponentTelemetryAsync(string digitalTwinI /// The additional information to be used when processing a telemetry request. /// The cancellation token. /// The http response. + /// + /// See the asynchronous version of this method for examples. + /// public virtual Response PublishComponentTelemetry(string digitalTwinId, string componentName, string payload, TelemetryOptions options = default, CancellationToken cancellationToken = default) { TelemetryOptions telemetryOptions = options ?? new TelemetryOptions(); diff --git a/sdk/digitaltwins/Azure.DigitalTwins.Core/src/RequestOptions.cs b/sdk/digitaltwins/Azure.DigitalTwins.Core/src/RequestOptions.cs index 93ad0b04fee33..b9243a1bb4271 100644 --- a/sdk/digitaltwins/Azure.DigitalTwins.Core/src/RequestOptions.cs +++ b/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. /// + /// + /// 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. + /// public string IfMatchEtag { get; set; } = null; } }