From 77f6e11bba91a32476034ae1ddabc4665ae6cdec Mon Sep 17 00:00:00 2001 From: Sindhu Nagesh Date: Wed, 3 Jun 2020 13:30:10 -0700 Subject: [PATCH] feat(adt): Add exception tag to comments --- .../src/DigitalTwinsClient.cs | 273 +++++++++++++++++- 1 file changed, 267 insertions(+), 6 deletions(-) diff --git a/sdk/digitaltwins/Azure.DigitalTwins.Core/src/DigitalTwinsClient.cs b/sdk/digitaltwins/Azure.DigitalTwins.Core/src/DigitalTwinsClient.cs index bd1be4fdb3ec4..2714358679f7f 100644 --- a/sdk/digitaltwins/Azure.DigitalTwins.Core/src/DigitalTwinsClient.cs +++ b/sdk/digitaltwins/Azure.DigitalTwins.Core/src/DigitalTwinsClient.cs @@ -126,6 +126,12 @@ protected DigitalTwinsClient() /// The Id of the digital twin. /// The cancellation token. /// The application/json digital twin and the http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// /// /// This sample demonstrates getting and deserializing a digital twin into a custom data type. /// @@ -156,6 +162,12 @@ public virtual Task> GetDigitalTwinAsync(string digitalTwinId, /// The Id of the digital twin. /// The cancellation token. /// The application/json digital twin and the http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// public virtual Response GetDigitalTwin(string digitalTwinId, CancellationToken cancellationToken = default) { return _dtRestClient.GetById(digitalTwinId, cancellationToken); @@ -168,6 +180,12 @@ public virtual Response GetDigitalTwin(string digitalTwinId, Cancellatio /// The application/json digital twin to create. /// The cancellation token. /// The created application/json digital twin and the http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when or is null. + /// /// /// /// string customDtId = await GetUniqueTwinIdAsync(SamplesConstants.TemporaryTwinPrefix, DigitalTwinsClient).ConfigureAwait(false); @@ -202,6 +220,12 @@ public virtual Task> CreateDigitalTwinAsync(string digitalTwinI /// The application/json digital twin to create. /// The cancellation token. /// The created application/json digital twin and the http response. + /// + /// + /// The exception is thrown when or is null. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// public virtual Response CreateDigitalTwin(string digitalTwinId, string digitalTwin, CancellationToken cancellationToken = default) { return _dtRestClient.Add(digitalTwinId, digitalTwin, cancellationToken); @@ -214,6 +238,12 @@ public virtual Response CreateDigitalTwin(string digitalTwinId, string d /// The optional settings for this request. /// The cancellation token. /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// /// /// To delete a digital twin, any relationships referencing it must be deleted first. /// @@ -234,6 +264,12 @@ public virtual Task DeleteDigitalTwinAsync(string digitalTwinId, Reque /// The optional settings for this request. /// The cancellation token. /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// /// /// To delete a digital twin, any relationships referencing it must be deleted first. /// @@ -248,9 +284,14 @@ public virtual Response DeleteDigitalTwin(string digitalTwinId, RequestOptions r /// The Id of the digital twin to update. /// The application/json-patch+json operations to be performed on the specified digital twin. /// The optional settings for this request. - /// The http response. /// The cancellationToken. /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when or is null. + /// public virtual Task> UpdateDigitalTwinAsync(string digitalTwinId, string digitalTwinUpdateOperations, RequestOptions requestOptions = default, CancellationToken cancellationToken = default) { return _dtRestClient.UpdateAsync(digitalTwinId, digitalTwinUpdateOperations, requestOptions?.IfMatchEtag, cancellationToken); @@ -262,8 +303,14 @@ public virtual Task> UpdateDigitalTwinAsync(string digitalTwinI /// The Id of the digital twin to update. /// The application/json-patch+json operations to be performed on the specified digital twin. /// The optional settings for this request. - /// The http response. /// The cancellationToken. + /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when or is null. + /// /// /// See the asynchronous version of this method for examples. /// @@ -279,6 +326,12 @@ public virtual Response UpdateDigitalTwin(string digitalTwinId, string d /// The component being retrieved. /// The cancellation token. /// Json string representation of the component corresponding to the provided componentPath and the HTTP response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when or is null. + /// /// /// /// response = await DigitalTwinsClient.GetComponentAsync(basicDtId, SamplesConstants.ComponentPath).ConfigureAwait(false); @@ -298,6 +351,12 @@ 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. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when or is null. + /// /// /// See the asynchronous version of this method for examples. /// @@ -315,7 +374,13 @@ public virtual Response GetComponent(string digitalTwinId, string compon /// The optional settings for this request. /// The cancellation token. /// The HTTP response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// /// + /// + /// The exception is thrown when or is null. + /// /// /// // Update Component1 by replacing the property ComponentProp1 value /// var componentUpdateUtility = new UpdateOperationsUtility(); @@ -342,6 +407,12 @@ public virtual Task> UpdateComponentAsync(string digitalTwinId, /// The optional settings for this request. /// The cancellation token. /// The HTTP response. + /// + /// + /// The exception is thrown when or is null. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// /// /// See the asynchronous version of this method for examples. /// @@ -357,6 +428,12 @@ public virtual Response UpdateComponent(string digitalTwinId, string com /// 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. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// /// /// /// AsyncPageable<string> relationships = DigitalTwinsClient.GetRelationshipsAsync(twin.Key); @@ -411,6 +488,12 @@ 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. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// /// /// See the asynchronous version of this method for examples. /// @@ -462,6 +545,12 @@ Page NextPageFunc(string nextLink, int? pageSizeHint) /// 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. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// /// /// /// AsyncPageable<IncomingRelationship> incomingRelationships = DigitalTwinsClient.GetIncomingRelationshipsAsync(twin.Key); @@ -510,6 +599,12 @@ 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. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// /// /// See the asynchronous version of this method for examples. /// @@ -557,7 +652,12 @@ Page NextPageFunc(string nextLink, int? pageSizeHint) /// The Id of the relationship to retrieve. /// 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. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when or is null. + /// public virtual Task> GetRelationshipAsync(string digitalTwinId, string relationshipId, CancellationToken cancellationToken = default) { return _dtRestClient.GetRelationshipByIdAsync(digitalTwinId, relationshipId, cancellationToken); @@ -570,7 +670,12 @@ public virtual Task> GetRelationshipAsync(string digitalTwinId, /// The Id of the relationship to retrieve. /// 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. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when or is null. + /// /// /// See the asynchronous version of this method for examples. /// @@ -587,6 +692,12 @@ public virtual Response GetRelationship(string digitalTwinId, string rel /// The optional settings for this request. /// The cancellation token. /// The http response. + /// + /// + /// The exception is thrown when or is null. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// public virtual Task DeleteRelationshipAsync(string digitalTwinId, string relationshipId, RequestOptions requestOptions = default, CancellationToken cancellationToken = default) { return _dtRestClient.DeleteRelationshipAsync(digitalTwinId, relationshipId, requestOptions?.IfMatchEtag, cancellationToken); @@ -600,6 +711,12 @@ public virtual Task DeleteRelationshipAsync(string digitalTwinId, stri /// The optional settings for this request. /// The cancellation token. /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when or is null. + /// /// /// See the asynchronous version of this method for examples. /// @@ -616,9 +733,14 @@ public virtual Response DeleteRelationship(string digitalTwinId, string relation /// The application/json relationship to be created. /// The cancellation token. /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when or is null. + /// /// /// 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. /// /// /// @@ -645,9 +767,14 @@ public virtual Task> CreateRelationshipAsync(string digitalTwin /// The application/json relationship to be created. /// The cancellation token. /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when or is null. + /// /// /// 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. @@ -666,6 +793,12 @@ public virtual Response CreateRelationship(string digitalTwinId, string /// The optional settings for this request. /// The cancellation token. /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when or is null. + /// public virtual Task UpdateRelationshipAsync(string digitalTwinId, string relationshipId, string relationshipUpdateOperations, RequestOptions requestOptions = default, CancellationToken cancellationToken = default) { // TODO how can we make this patch easier to construct? @@ -681,6 +814,12 @@ public virtual Task UpdateRelationshipAsync(string digitalTwinId, stri /// The optional settings for this request. /// The cancellation token. /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when or is null. + /// /// /// See the asynchronous version of this method for examples. /// @@ -697,6 +836,9 @@ public virtual Response UpdateRelationship(string digitalTwinId, string relation /// 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. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// /// /// /// AsyncPageable<ModelData> allModels = DigitalTwinsClient.GetModelsAsync(); @@ -751,6 +893,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. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// /// /// See the asynchronous version of this method for examples. /// @@ -797,6 +942,12 @@ Page NextPageFunc(string nextLink, int? pageSizeHint) /// The Id of the model. /// The cancellation token. /// The application/json model and the http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// /// /// /// Response<ModelData> sampleModel = await DigitalTwinsClient.GetModelAsync(sampleModelId).ConfigureAwait(false); @@ -814,6 +965,12 @@ public virtual Task> GetModelAsync(string modelId, Cancellat /// The Id of the model. /// The cancellation token. /// The application/json model and the http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// /// /// See the asynchronous version of this method for examples. /// @@ -829,6 +986,12 @@ public virtual Response GetModel(string modelId, CancellationToken ca /// The Id of the model to decommission. /// The cancellation token. /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// /// /// When a model is decomissioned, new digital twins will no longer be able to be defined by this model. /// However, existing digital twins may continue to use this model. @@ -859,6 +1022,12 @@ public virtual Task DecommissionModelAsync(string modelId, Cancellatio /// The Id of the model to decommission. /// The cancellation token. /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// /// /// When a model is decomissioned, new digital twins will no longer be able to be defined by this model. /// However, existing digital twins may continue to use this model. @@ -878,6 +1047,9 @@ public virtual Response DecommissionModel(string modelId, CancellationToken canc /// The set of models to create. Each string corresponds to exactly one model. /// The cancellation token. /// The created models and the http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// /// /// Bulk model creation is useful when several models have references to each other. /// It simplifies creation for the client because otherwise the models would have to be created in a very specific order. @@ -901,6 +1073,9 @@ public virtual Task>> CreateModelsAsync(IEnume /// The set of models to create. Each string corresponds to exactly one model. /// The cancellation token. /// The created models and the http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// /// /// Bulk model creation is useful when several models have references to each other. /// It simplifies creation for the client because otherwise the models would have to be created in a very specific order. @@ -920,6 +1095,13 @@ public virtual Response> CreateModels(IEnumerable /// The id for the model. The id is globally unique and case sensitive. /// The cancellation token to use. + /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// /// /// A model can only be deleted if no other models reference it. /// Status codes: @@ -952,6 +1134,13 @@ public virtual Task DeleteModelAsync(string modelId, CancellationToken /// /// The id for the model. The id is globally unique and case sensitive. /// The cancellation token to use. + /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// /// /// A model can only be deleted if no other models reference it. /// Status codes: @@ -974,6 +1163,9 @@ public virtual Response DeleteModel(string modelId, CancellationToken cancellati /// The query string, in SQL-like syntax. /// The cancellation token. /// The pageable list of query results. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// /// /// /// // This code snippet demonstrates the simplest way to iterate over the digital twin results, where paging @@ -1043,6 +1235,9 @@ async Task> NextPageFunc(string nextLink, int? pageSizeHint) /// The query string, in SQL-like syntax. /// The cancellation token. /// The pageable list of query results. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// /// /// A basic query for all digital twins: SELECT * FROM digitalTwins. /// @@ -1102,6 +1297,9 @@ Page 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. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// /// /// /// AsyncPageable<EventRoute> response = DigitalTwinsClient.GetEventRoutesAsync(); @@ -1154,6 +1352,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. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// /// /// See the asynchronous version of this method for examples. /// @@ -1200,6 +1401,12 @@ Page NextPageFunc(string nextLink, int? pageSizeHint) /// The Id of the event route. /// The cancellation token. /// The application/json event routes and the http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// public virtual Task> GetEventRouteAsync(string eventRouteId, CancellationToken cancellationToken = default) { return _eventRoutesRestClient.GetByIdAsync(eventRouteId, cancellationToken); @@ -1211,6 +1418,12 @@ public virtual Task> GetEventRouteAsync(string eventRouteId /// The Id of the event route. /// The cancellation token. /// The application/json event routes and the http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// /// /// See the asynchronous version of this method for examples. /// @@ -1226,6 +1439,12 @@ public virtual Response GetEventRoute(string eventRouteId, Cancellat /// The event route data containing the endpoint and optional filter. /// The cancellation token. /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// /// /// /// string eventFilter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'"; @@ -1249,6 +1468,12 @@ public virtual Task CreateEventRouteAsync(string eventRouteId, EventRo /// The event route data containing the endpoint and optional filter. /// The cancellation token. /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// /// /// See the asynchronous version of this method for examples. /// @@ -1263,6 +1488,12 @@ public virtual Response CreateEventRoute(string eventRouteId, EventRoute eventRo /// The Id of the event route to delete. /// The cancellation token. /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// /// /// /// Response response = await DigitalTwinsClient.DeleteEventRouteAsync(_eventRouteId).ConfigureAwait(false); @@ -1279,6 +1510,12 @@ public virtual Task DeleteEventRouteAsync(string eventRouteId, Cancell /// The Id of the event route to delete. /// The cancellation token. /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when is null. + /// /// /// See the asynchronous version of this method for examples. /// @@ -1297,6 +1534,12 @@ public virtual Response DeleteEventRoute(string eventRouteId, CancellationToken /// The additional information to be used when processing a telemetry request. /// The cancellation token. /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when or is null. + /// /// /// /// // construct your json telemetry payload by hand. @@ -1323,6 +1566,12 @@ public virtual Task PublishTelemetryAsync(string digitalTwinId, string /// The additional information to be used when processing a telemetry request. /// The cancellation token. /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when or is null. + /// /// /// See the asynchronous version of this method for examples. /// @@ -1345,6 +1594,12 @@ public virtual Response PublishTelemetry(string digitalTwinId, string payload, T /// The additional information to be used when processing a telemetry request. /// The cancellation token. /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when or or is null. + /// /// /// /// // construct your json telemetry payload by serializing a dictionary. @@ -1376,6 +1631,12 @@ public virtual Task PublishComponentTelemetryAsync(string digitalTwinI /// The additional information to be used when processing a telemetry request. /// The cancellation token. /// The http response. + /// + /// The exception that captures the errors from the service. Check the and properties for more details. + /// + /// + /// The exception is thrown when or or is null. + /// /// /// See the asynchronous version of this method for examples. ///