Metadata and screenshot updated, minor Acrolinx fixes to improve score

Author: DENKEN02MSFT

articles/digital-twins/how-to-manage-twin.md

@@ -5,7 +5,7 @@ titleSuffix: Azure Digital Twins
 description: See how to retrieve, update, and delete individual twins and relationships.
 author: baanders
 ms.author: baanders # Microsoft employees only
-ms.date: 2/13/2025
+ms.date: 03/04/2025
 ms.topic: how-to
 ms.service: azure-digital-twins
 
@@ -45,12 +45,12 @@ To create a digital twin, you need to provide:
 * The [model](concepts-models.md) you want to use
 * Any desired initialization of twin data, including...
     - Properties (initialization optional): You can set initial values for properties of the digital twin if you want. Properties are treated as optional and can be set later, but note that **they won't show up as part of a twin until they've been set**.
-    - Components (initialization required if they're present on a twin): If your twin contains any [components](concepts-models.md#model-attributes), these must be initialized when the twin is created. They can be empty objects, but the components themselves have to exist.
+    - Components (initialization required if they're present on a twin): If your twin contains any [components](concepts-models.md#model-attributes), these components must be initialized when the twin is created. They can be empty objects, but the components themselves have to exist.
 
 The model and any initial property values are provided through the `initData` parameter, which is a JSON string containing the relevant data. For more information on structuring this object, continue to the next section.
 
 > [!TIP]
-> After creating or updating a twin, there may be a latency of up to 10 seconds before the changes will be reflected in [queries](how-to-query-graph.md). The `GetDigitalTwin` API (described [later in this article](#get-data-for-a-digital-twin)) does not experience this delay, so if you need an instant response, use the API call instead of querying to see your newly-created twins. 
+> After you create or update a twin, there might be a latency of up to 10 seconds before the changes will be reflected in [queries](how-to-query-graph.md). The `GetDigitalTwin` API (described [later in this article](#get-data-for-a-digital-twin)) doesn't experience this delay, so if you need an instant response, use the API call instead of querying to see your newly created twins. 
 
 ### Initialize model and properties
 
@@ -86,7 +86,7 @@ You can use the [Import Jobs API](concepts-apis-sdks.md#bulk-import-with-the-imp
 >[!TIP]
 >The Import Jobs API also allows models and relationships to be imported in the same call, to create all parts of a graph at once. For more about this process, see [Upload models, twins, and relationships in bulk with the Import Jobs API](how-to-manage-graph.md#upload-models-twins-and-relationships-in-bulk-with-the-import-jobs-api).
 
-To import twins in bulk, you need to structure your twins (and any other resources included in the bulk import job) as an *NDJSON* file. The `Twins` section comes after the `Models` section (and before the `Relationships` section). Twins defined in the file can reference models that are either defined in this file or already present in the instance, and they can optionally include initialization of the twin's properties.
+To import twins in bulk, you need to structure your twins (and any other resources included in the bulk import job) as an *NDJSON* file. The `Twins` section comes after the `Models` section (and before the `Relationships` section). Twins defined in the file can reference models that are either defined in this file or already present in the instance. The twins defined in the file can optionally include initialization of the twin's properties.
 
 You can view an example import file and a sample project for creating these files in the [Import Jobs API introduction](concepts-apis-sdks.md#bulk-import-with-the-import-jobs-api).
 
@@ -100,7 +100,7 @@ You can access the details of any digital twin by calling the `GetDigitalTwin()`
 
 :::code language="csharp" source="~/digital-twins-docs-samples/sdks/csharp/twin_operations_sample.cs" id="GetTwinCall":::
 
-This call returns twin data as a strongly-typed object type such as `BasicDigitalTwin`. `BasicDigitalTwin` is a serialization helper class included with the SDK, which returns the core twin metadata and properties in preparsed form. You can always deserialize twin data using the JSON library of your choice, like `System.Text.Json` or `Newtonsoft.Json`. For basic access to a twin, however, the helper classes can make this more convenient.
+This call returns twin data as a strongly typed object type such as `BasicDigitalTwin`. `BasicDigitalTwin` is a serialization helper class included with the SDK, which returns the core twin metadata and properties in preparsed form. You can always deserialize twin data using the JSON library of your choice, like `System.Text.Json` or `Newtonsoft.Json`. For basic access to a twin, however, the helper classes can make deserializing twin data more convenient.
 
 > [!NOTE]
 > `BasicDigitalTwin` uses `System.Text.Json` attributes. In order to use `BasicDigitalTwin` with your [DigitalTwinsClient](/dotnet/api/azure.digitaltwins.core.digitaltwinsclient?view=azure-dotnet&preserve-view=true), you must either initialize the client with the default constructor, or, if you want to customize the serializer option, use the [JsonObjectSerializer](/dotnet/api/azure.core.serialization.jsonobjectserializer?view=azure-dotnet&preserve-view=true).
@@ -109,10 +109,10 @@ The `BasicDigitalTwin` helper class also gives you access to properties defined
 
 :::code language="csharp" source="~/digital-twins-docs-samples/sdks/csharp/twin_operations_sample.cs" id="GetTwin" highlight="2":::
 
-Only properties that have been set at least once are returned when you retrieve a twin with the `GetDigitalTwin()` method.
+Only properties that are set at least once are returned when you retrieve a twin with the `GetDigitalTwin()` method.
 
 >[!TIP]
->The `displayName` for a twin is part of its model metadata, so it will not show when getting data for the twin instance. To see this value, you can [retrieve it from the model](how-to-manage-model.md#retrieve-models).
+>The `displayName` for a twin is part of its model metadata, so it shows when getting data for the twin instance. To see this value, you can [retrieve it from the model](how-to-manage-model.md#retrieve-models).
 
 To retrieve multiple twins using a single API call, see the Query API examples in [Query the twin graph](how-to-query-graph.md).
 
@@ -142,11 +142,11 @@ The result of calling `object result = await client.GetDigitalTwinAsync("my-moon
 
 The defined properties of the digital twin are returned as top-level properties on the digital twin. Metadata or system information that isn't part of the DTDL definition is returned with a `$` prefix. Metadata properties include the following values:
 * `$dtId`: The ID of the digital twin in this Azure Digital Twins instance
-* `$etag`: A standard HTTP field assigned by the web server. This is updated to a new value every time the twin is updated, which can be useful to determine whether the twin's data has been updated on the server since a previous check. You can use `If-Match` to perform updates and deletes that only complete if the entity's etag matches the etag provided. For more information on these operations, see the documentation for [DigitalTwins Update](/rest/api/digital-twins/dataplane/twins/digital-twins-update) and [DigitalTwins Delete](/rest/api/digital-twins/dataplane/twins/digital-twins-delete).
-* `$metadata`: A set of metadata properties, which might include the following:
+* `$etag`: A standard HTTP field assigned by the web server. This property is updated to a new value every time the twin is updated, which can be useful to determine whether the twin's data updated on the server since a previous check. You can use `If-Match` to perform updates and deletes that only complete if the entity's etag matches the etag provided. For more information on these operations, see the documentation for [DigitalTwins Update](/rest/api/digital-twins/dataplane/twins/digital-twins-update) and [DigitalTwins Delete](/rest/api/digital-twins/dataplane/twins/digital-twins-delete).
+* `$metadata`: A set of metadata properties, which might include the following properties:
   - `$model`, the DTMI of the model of the digital twin.
-  - `lastUpdateTime` for twin properties. This is a timestamp indicating the date and time that Azure Digital Twins processed the property update message
-  - `sourceTime` for twin properties. This is an optional, writable property representing the timestamp when the property update was observed in the real world.
+  - `lastUpdateTime` for twin properties. This property is a timestamp indicating the date and time that Azure Digital Twins processed the property update message
+  - `sourceTime` for twin properties. This property is an optional, writable property representing the timestamp when the property update was observed in the real world.
 
 You can read more about the fields contained in a digital twin in [Digital twin JSON format](concepts-twins-graph.md#digital-twin-json-format). You can read more about the serialization helper classes like `BasicDigitalTwin` in [Azure Digital Twins APIs and SDKs](concepts-apis-sdks.md#serialization-helpers-in-the-net-c-sdk).
 
@@ -160,7 +160,7 @@ Here's the body of the basic query that returns a list of all digital twins in t
 
 ## Update a digital twin
 
-To update properties of a digital twin, write the information you want to replace in [JSON Patch](http://jsonpatch.com/) format. For a full list of JSON Patch operations that can be used, including `replace`, `add` and `remove`, see the [Operations for JSON Patch](http://jsonpatch.com/#operations).
+To update properties of a digital twin, write the information you want to replace in [JSON Patch](http://jsonpatch.com/) format. For a full list of JSON Patch operations that can be used, including `replace`, `add`, and `remove`, see the [Operations for JSON Patch](http://jsonpatch.com/#operations).
 
 After crafting the JSON Patch document containing update information, pass the document into the `UpdateDigitalTwin()` method:
 
@@ -169,9 +169,9 @@ After crafting the JSON Patch document containing update information, pass the d
 A single patch call can update as many properties on a single twin as you want (even all of them). If you need to update properties across multiple twins, you need a separate update call for each twin.
 
 > [!TIP]
-> After creating or updating a twin, there may be a latency of up to 10 seconds before the changes will be reflected in [queries](how-to-query-graph.md). The `GetDigitalTwin` API (described [earlier in this article](#get-data-for-a-digital-twin)) does not experience this delay, so use the API call instead of querying to see your newly-updated twins if you need an instant response. 
+> After you create or update a twin, there might be a latency of up to 10 seconds before the changes will be reflected in [queries](how-to-query-graph.md). The `GetDigitalTwin` API (described [earlier in this article](#get-data-for-a-digital-twin)) doesn't experience this delay, so use the API call instead of querying to see your newly updated twins if you need an instant response. 
 
-Here's an example of JSON Patch code. This document replaces the *mass* and *radius* property values of the digital twin it's applied to. This example shows the JSON Patch `replace` operation, which replaces the value of an existing property.
+Here's an example of JSON Patch code. This document replaces the *mass* and *radius* property values of the applicable digital twin. This example shows the JSON Patch `replace` operation, which replaces the value of an existing property.
 
 :::code language="json" source="~/digital-twins-docs-samples/models/patch.json":::
 
@@ -198,7 +198,7 @@ Consider a model with an object-type property, `ObjectProperty`. `ObjectProperty
 
 When a twin is created using this model, it's not necessary to instantiate the `ObjectProperty` at that time. If the object property isn't instantiated during twin creation, there's no default path created to access `ObjectProperty` and its `StringSubProperty` for a patch operation. You need to add the path to `ObjectProperty` yourself before you can update its properties.
 
-This can be done with a JSON Patch `add` operation, like this:
+This addition can be done with a JSON Patch `add` operation, like this:
 
 :::code language="json" source="~/digital-twins-docs-samples/models/patch-object-sub-property-1.json":::
 
@@ -209,11 +209,11 @@ This can be done with a JSON Patch `add` operation, like this:
 >```
 
 
-After this has been done once, a path to `StringSubProperty` exists, and it can be updated directly from now on with a typical `replace` operation:
+After this addition is done once, a path to `StringSubProperty` exists, and it can be updated directly from now on with a typical `replace` operation:
 
 :::code language="json" source="~/digital-twins-docs-samples/models/patch-object-sub-property-2.json":::
 
-Although the first step isn't necessary in cases where `ObjectProperty` was instantiated when the twin was created, it's recommended to use it every time you update a sub-property for the first time, since you might not always know with certainty whether the object property was initially instantiated or not.
+Although the first step isn't necessary in cases where `ObjectProperty` was instantiated when the twin was created, we recommend that you use it every time you update a sub-property for the first time, because you might not always know with certainty whether the object property was initially instantiated or not.
 
 ### Update a digital twin's model
 
@@ -223,7 +223,7 @@ For example, consider the following JSON Patch document that replaces the digita
 
 :::code language="json" source="~/digital-twins-docs-samples/models/patch-model-1.json":::
 
-This operation only succeeds if the digital twin being modified by the patch conforms with the new model. 
+This operation only succeeds if the digital twin modified by the patch conforms with the new model. 
 
 Consider the following example:
 1. Imagine a digital twin with a model of foo_old. foo_old defines a required property *mass*.
@@ -244,15 +244,15 @@ Here's an example of a JSON Patch document that updates both the value and the `
 
 :::code language="json" source="~/digital-twins-docs-samples/models/patch-sourcetime.json":::
 
-To update the `sourceTime` field on a property that's part of a component, include the component at the start of the path. In the example above, you would do this by changing the path value from `/$metadata/Temperature/sourceTime` to `myComponent/$metadata/Temperature/sourceTime`.
+To update the `sourceTime` field on a property that's part of a component, include the component at the start of the path. In the previous example, you would include the component by changing the path value from `/$metadata/Temperature/sourceTime` to `myComponent/$metadata/Temperature/sourceTime`.
 
 >[!NOTE]
-> If you update both the `sourceTime` and value on a property, and then later update only the property's value, the `sourceTime` timestamp from the first update will remain.
+> If you update both the `sourceTime` and value on a property, and then later update only the property's value, the `sourceTime` timestamp from the first update remains.
 
 
 ### Handle conflicting update calls
 
-Azure Digital Twins ensures that all incoming requests are processed one after the other. This means that even if multiple functions try to update the same property on a twin at the same time, there's **no need** for you to write explicit locking code to handle the conflict.
+Azure Digital Twins ensures that all incoming requests are processed sequentially, one after the other. This sequential processing means that even if multiple functions try to update the same property on a twin at the same time, there's **no need** for you to write explicit locking code to handle the conflict.
 
 This behavior is on a per-twin basis. 
 
@@ -273,13 +273,13 @@ Here's an example of the code to delete twins and their relationships. The `Dele
 
 ### Delete all digital twins
 
-For an example of how to delete all twins at once, download the sample app used in the [Explore the basics with a sample client app](tutorial-command-line-app.md). The *CommandLoop.cs* file does this in a `CommandDeleteAllTwins()` function.
+For an example of how to delete all twins at once, download the sample app used in the [Explore the basics with a sample client app](tutorial-command-line-app.md). The *CommandLoop.cs* file deletes all digital twins in a `CommandDeleteAllTwins()` function.
 
 [!INCLUDE [digital-twins-bulk-delete-note.md](../../includes/digital-twins-bulk-delete-note.md)]
 
 ## Runnable digital twin code sample
 
-You can use the runnable code sample below to create a twin, update its details, and delete the twin. 
+You can use the following runnable code sample to create a twin, update its details, and delete the twin. 
 
 ### Set up sample project files
 
@@ -305,14 +305,14 @@ Next, complete the following steps to configure your project code:
       dotnet add package Azure.Identity
       ```
 
-You also need to set up local credentials if you want to run the sample directly. The next section walks through this.
+You also need to set up local credentials if you want to run the sample directly. The next section walks through this prerequisite.
 [!INCLUDE [Azure Digital Twins: local credentials prereq (outer)](../../includes/digital-twins-local-credentials-outer.md)]
 
 ### Run the sample
 
 Now that setup is complete, you can run the sample code project.
 
-Here's the console output of the above program: 
+Here's the console output of the previous program: 
 
 :::image type="content" source="./media/how-to-manage-twin/console-output-manage-twins.png" alt-text="Screenshot of the console output showing that the twin is created, updated, and deleted." lightbox="./media/how-to-manage-twin/console-output-manage-twins.png":::