Skip to content
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.

Sign up for GitHub

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

Update root readme file #12430

Merged
merged 8 commits into from
Jun 2, 2020
Merged

Update root readme file #12430

Changes from 5 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
56c818d
Update root readme file
azabbasi Jun 2, 2020
b7930ff
minor casing update
azabbasi Jun 2, 2020
de20ed4
linter done
azabbasi Jun 2, 2020
3b336b8
fix link
azabbasi Jun 2, 2020
8fe8515
one final lint warning
azabbasi Jun 2, 2020
8ecce32
digital twinSSSSS
azabbasi Jun 2, 2020
a6faf8e
address commments
azabbasi Jun 2, 2020
e8688c9
Fix analyze in ci
azabbasi Jun 2, 2020
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
88 changes: 72 additions & 16 deletions sdk/digitaltwins/Azure.DigitalTwins.Core/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,78 +1,134 @@
# Azure IoT Digital Twin client library for .NET
azabbasi marked this conversation as resolved.
Show resolved Hide resolved

This library provides access to the Azure Digital Twins service for managing twins, models, relationships, etc.

[Source code][source] | [Package (nuget)][package]

## Getting started
azabbasi marked this conversation as resolved.
Show resolved Hide resolved

### Authenticate the Client
The complete Microsoft Azure SDK can be downloaded from the [Microsoft Azure Downloads][microsoft_sdk_download] Page and ships with support for building deployment packages, integrating with tooling, rich command line tooling, and more.

For the best development experience, developers should use the official Microsoft NuGet packages for libraries. NuGet packages are regularly updated with new functionality and hotfixes.

## Prerequisites

### Install the package
- Microsoft Azure Subscription: To call Microsoft Azure services, you need to create an [Azure subscription][azure_sub]
- Azure Digital Twin instance: In order to use the Azure Digital Twins SDK, you need to first create a Digital Twin instance using one of many options:
- Using [Azure portal][azure_portal]
- Using [Azure Management APIs][azure_rest_api]
- Using [Azure CLI][azure_cli]: You will need to install azure cli and the [Azure IoT extension][iot_cli_extension] for Azure CLI. Refer to [IoT CLI Documentation][iot_cli_doc] for more information on how to create and interact with your Digital Twin instance.

## Install the package

Install the Azure Digital Twins client library for .NET with [NuGet][nuget]:

```PowerShell
Install-Package Azure.DigitalTwins.Core
```
### Prerequisites

* An [Azure subscription][azure_sub].
## Authenticate the Client

In order to interact with the Azure Digital Twins service, you will need to create an instance of a [TokenCredential class][token_credential] and pass it to the constructor of your [DigitalTwinsClient][digital_twins_client].

## Key concepts

Azure Digital Twins Preview is an Azure IoT service that creates comprehensive models of the physical environment. It can create spatial intelligence graphs to model the relationships and interactions between people, spaces, and devices.

You can learn more about Azure Digital Twins by visiting [Azure Digital Twins Documentation][digital_twins_documentation]

## Examples

## Developer guide
You can familiarize yourself with different APIs using [samples for Digital Twins](./samples/).

### Source code folder structure
## Source code folder structure

### /src
The digital twins public client `DigitalTwinsClient` and the additional configuration options that can be sent to the digital twins service `DigitalTwinsClientOptions`.

The Digital Twins public client `DigitalTwinsClient` and the additional configuration options that can be sent to the Digital Twins service `DigitalTwinsClientOptions`.

### /src/swagger
The swagger file that defines the structure of the REST APIs used by the digital twins client library.

The swagger file that defines the structure of the REST APIs used by the Digital Twins client library.

To generate the code, run the powershell script present [here](./src/generate.ps1).

### /src/Generated
The code generated by autorest using the swagger file defined under /src/swagger.

The code generated by autorest using the swagger file defined under /src/swagger.

### /src/Customized

The customzied code written to override the following behavior of auto-generated code:

- Rename some of the generated types, eg. [GetModelsOptions](./src/Customized/Models/GetModelsOptions.cs)
- Declare some of the generated types as **internal**, instead of the autorest default of **public**.
- Declare some methods to accept input parameters as **strings** instead of **objects**.
- Declare some methods to return the response as **strings** instead of **objects**.

### /src/Models
Constants useful for use with the digital twins client.

Constants useful for use with the Digital Twins client.

### /src/Properties

Assembly properties required for running unit tests against signed assemblies in Debug mode.

### /src/Serialization
Serialization helpers provided to help serialize/deseralize commonly used types within the digital twins service.

Any time the client library code is updated, you will need to run the script [here](./../Export-AdtApis.ps1), which will update the corresponding API surface.
Serialization helpers provided to help serialize/deseralize commonly used types within the Digital Twins service.
azabbasi marked this conversation as resolved.
Show resolved Hide resolved

Any time the client library code is updated, you will need to run the following scripts

- [Export-AdtApis](./../Export-AdtApis.ps1), which will update the corresponding API surface.
- [Ipdate-Snippents](./../Update-AdtSnippets.ps1), which will update all the code snippets in the readme files.

## Troubleshooting

All Azure Digital Twins service operations will throw a RequestFailedException on failure with helpful ErrorCodes.

For example, if you use the `GetModelAsync` operation and the model you are looking for doesn't exist, you can catch that specific [HttpStatusCode][http_status_code] to decide the operation that follows in that case.

```csharp
drwill-ms marked this conversation as resolved.
Show resolved Hide resolved
try
{
Response<ModelData> sampleModel = await DigitalTwinsClient.GetModelAsync(sampleModelId).ConfigureAwait(false);
}
catch (RequestFailedException ex) when (ex.Status == (int)HttpStatusCode.NotFound)
{
// Model does not exist.
// Create the model
}

```

## Next steps

Get started with our [Azure Digital Twins samples](./samples)

## Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit <https://cla.microsoft.com.>

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct]. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

<!-- LINKS -->
[microsoft_sdk_download]: https://azure.microsoft.com/en-us/downloads/?sdk=net
[azure_sdk_target_frameworks]: https://github.com/azure/azure-sdk-for-net#target-frameworks
[azure_cli]: https://docs.microsoft.com/cli/azure
[azure_sub]: https://azure.microsoft.com/free/
[source]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/iot/adt
[package]: https://www.nuget.org/packages/Azure.IoT.DigitalTwins
[source]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/digitaltwins
[package]: https://www.nuget.org/packages/Azure.DigitalTwins.Core
[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
[nuget]: https://www.nuget.org/
[azure_portal]: https://portal.azure.com/
[azure_rest_api]: https://docs.microsoft.com/en-us/rest/api/azure/
[azure_core_library]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/core/Azure.Core
[token_credential]: https://docs.microsoft.com/en-us/dotnet/api/azure.core.tokencredential?view=azure-dotnet
[digital_twins_client]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/digitaltwins/Azure.DigitalTwins.Core/src/DigitalTwinsClient.cs
[digital_twins_documentation]: https://docs.microsoft.com/en-us/azure/digital-twins/
[azure_cli]: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest
[iot_cli_extension]: https://docs.microsoft.com/en-us/azure/iot-pnp/howto-install-pnp-cli#:~:text=The%20Azure%20CLI%20lets%20you,Plug%20and%20Play%20Preview%20devices.
[iot_cli_doc]: https://docs.microsoft.com/en-us/cli/azure/ext/azure-iot/iot?view=azure-cli-latest
[http_status_code]: https://docs.microsoft.com/en-us/dotnet/api/system.net.httpstatuscode?view=netcore-3.1