Initial commit
This commit is contained in:
Microsoft GitHub User
Wes Haggard
Коммит
3d726f4413
|
|
@ -0,0 +1,330 @@
|
|||
## Ignore Visual Studio temporary files, build results, and
|
||||
## files generated by popular Visual Studio add-ons.
|
||||
##
|
||||
## Get latest from https://github.com/github/gitignore/blob/master/VisualStudio.gitignore
|
||||
|
||||
# User-specific files
|
||||
*.suo
|
||||
*.user
|
||||
*.userosscache
|
||||
*.sln.docstates
|
||||
|
||||
# User-specific files (MonoDevelop/Xamarin Studio)
|
||||
*.userprefs
|
||||
|
||||
# Build results
|
||||
[Dd]ebug/
|
||||
[Dd]ebugPublic/
|
||||
[Rr]elease/
|
||||
[Rr]eleases/
|
||||
x64/
|
||||
x86/
|
||||
bld/
|
||||
[Bb]in/
|
||||
[Oo]bj/
|
||||
[Ll]og/
|
||||
|
||||
# Visual Studio 2015/2017 cache/options directory
|
||||
.vs/
|
||||
# Uncomment if you have tasks that create the project's static files in wwwroot
|
||||
#wwwroot/
|
||||
|
||||
# Visual Studio 2017 auto generated files
|
||||
Generated\ Files/
|
||||
|
||||
# MSTest test Results
|
||||
[Tt]est[Rr]esult*/
|
||||
[Bb]uild[Ll]og.*
|
||||
|
||||
# NUNIT
|
||||
*.VisualState.xml
|
||||
TestResult.xml
|
||||
|
||||
# Build Results of an ATL Project
|
||||
[Dd]ebugPS/
|
||||
[Rr]eleasePS/
|
||||
dlldata.c
|
||||
|
||||
# Benchmark Results
|
||||
BenchmarkDotNet.Artifacts/
|
||||
|
||||
# .NET Core
|
||||
project.lock.json
|
||||
project.fragment.lock.json
|
||||
artifacts/
|
||||
**/Properties/launchSettings.json
|
||||
|
||||
# StyleCop
|
||||
StyleCopReport.xml
|
||||
|
||||
# Files built by Visual Studio
|
||||
*_i.c
|
||||
*_p.c
|
||||
*_i.h
|
||||
*.ilk
|
||||
*.meta
|
||||
*.obj
|
||||
*.iobj
|
||||
*.pch
|
||||
*.pdb
|
||||
*.ipdb
|
||||
*.pgc
|
||||
*.pgd
|
||||
*.rsp
|
||||
*.sbr
|
||||
*.tlb
|
||||
*.tli
|
||||
*.tlh
|
||||
*.tmp
|
||||
*.tmp_proj
|
||||
*.log
|
||||
*.vspscc
|
||||
*.vssscc
|
||||
.builds
|
||||
*.pidb
|
||||
*.svclog
|
||||
*.scc
|
||||
|
||||
# Chutzpah Test files
|
||||
_Chutzpah*
|
||||
|
||||
# Visual C++ cache files
|
||||
ipch/
|
||||
*.aps
|
||||
*.ncb
|
||||
*.opendb
|
||||
*.opensdf
|
||||
*.sdf
|
||||
*.cachefile
|
||||
*.VC.db
|
||||
*.VC.VC.opendb
|
||||
|
||||
# Visual Studio profiler
|
||||
*.psess
|
||||
*.vsp
|
||||
*.vspx
|
||||
*.sap
|
||||
|
||||
# Visual Studio Trace Files
|
||||
*.e2e
|
||||
|
||||
# TFS 2012 Local Workspace
|
||||
$tf/
|
||||
|
||||
# Guidance Automation Toolkit
|
||||
*.gpState
|
||||
|
||||
# ReSharper is a .NET coding add-in
|
||||
_ReSharper*/
|
||||
*.[Rr]e[Ss]harper
|
||||
*.DotSettings.user
|
||||
|
||||
# JustCode is a .NET coding add-in
|
||||
.JustCode
|
||||
|
||||
# TeamCity is a build add-in
|
||||
_TeamCity*
|
||||
|
||||
# DotCover is a Code Coverage Tool
|
||||
*.dotCover
|
||||
|
||||
# AxoCover is a Code Coverage Tool
|
||||
.axoCover/*
|
||||
!.axoCover/settings.json
|
||||
|
||||
# Visual Studio code coverage results
|
||||
*.coverage
|
||||
*.coveragexml
|
||||
|
||||
# NCrunch
|
||||
_NCrunch_*
|
||||
.*crunch*.local.xml
|
||||
nCrunchTemp_*
|
||||
|
||||
# MightyMoose
|
||||
*.mm.*
|
||||
AutoTest.Net/
|
||||
|
||||
# Web workbench (sass)
|
||||
.sass-cache/
|
||||
|
||||
# Installshield output folder
|
||||
[Ee]xpress/
|
||||
|
||||
# DocProject is a documentation generator add-in
|
||||
DocProject/buildhelp/
|
||||
DocProject/Help/*.HxT
|
||||
DocProject/Help/*.HxC
|
||||
DocProject/Help/*.hhc
|
||||
DocProject/Help/*.hhk
|
||||
DocProject/Help/*.hhp
|
||||
DocProject/Help/Html2
|
||||
DocProject/Help/html
|
||||
|
||||
# Click-Once directory
|
||||
publish/
|
||||
|
||||
# Publish Web Output
|
||||
*.[Pp]ublish.xml
|
||||
*.azurePubxml
|
||||
# Note: Comment the next line if you want to checkin your web deploy settings,
|
||||
# but database connection strings (with potential passwords) will be unencrypted
|
||||
*.pubxml
|
||||
*.publishproj
|
||||
|
||||
# Microsoft Azure Web App publish settings. Comment the next line if you want to
|
||||
# checkin your Azure Web App publish settings, but sensitive information contained
|
||||
# in these scripts will be unencrypted
|
||||
PublishScripts/
|
||||
|
||||
# NuGet Packages
|
||||
*.nupkg
|
||||
# The packages folder can be ignored because of Package Restore
|
||||
**/[Pp]ackages/*
|
||||
# except build/, which is used as an MSBuild target.
|
||||
!**/[Pp]ackages/build/
|
||||
# Uncomment if necessary however generally it will be regenerated when needed
|
||||
#!**/[Pp]ackages/repositories.config
|
||||
# NuGet v3's project.json files produces more ignorable files
|
||||
*.nuget.props
|
||||
*.nuget.targets
|
||||
|
||||
# Microsoft Azure Build Output
|
||||
csx/
|
||||
*.build.csdef
|
||||
|
||||
# Microsoft Azure Emulator
|
||||
ecf/
|
||||
rcf/
|
||||
|
||||
# Windows Store app package directories and files
|
||||
AppPackages/
|
||||
BundleArtifacts/
|
||||
Package.StoreAssociation.xml
|
||||
_pkginfo.txt
|
||||
*.appx
|
||||
|
||||
# Visual Studio cache files
|
||||
# files ending in .cache can be ignored
|
||||
*.[Cc]ache
|
||||
# but keep track of directories ending in .cache
|
||||
!*.[Cc]ache/
|
||||
|
||||
# Others
|
||||
ClientBin/
|
||||
~$*
|
||||
*~
|
||||
*.dbmdl
|
||||
*.dbproj.schemaview
|
||||
*.jfm
|
||||
*.pfx
|
||||
*.publishsettings
|
||||
orleans.codegen.cs
|
||||
|
||||
# Including strong name files can present a security risk
|
||||
# (https://github.com/github/gitignore/pull/2483#issue-259490424)
|
||||
#*.snk
|
||||
|
||||
# Since there are multiple workflows, uncomment next line to ignore bower_components
|
||||
# (https://github.com/github/gitignore/pull/1529#issuecomment-104372622)
|
||||
#bower_components/
|
||||
|
||||
# RIA/Silverlight projects
|
||||
Generated_Code/
|
||||
|
||||
# Backup & report files from converting an old project file
|
||||
# to a newer Visual Studio version. Backup files are not needed,
|
||||
# because we have git ;-)
|
||||
_UpgradeReport_Files/
|
||||
Backup*/
|
||||
UpgradeLog*.XML
|
||||
UpgradeLog*.htm
|
||||
ServiceFabricBackup/
|
||||
*.rptproj.bak
|
||||
|
||||
# SQL Server files
|
||||
*.mdf
|
||||
*.ldf
|
||||
*.ndf
|
||||
|
||||
# Business Intelligence projects
|
||||
*.rdl.data
|
||||
*.bim.layout
|
||||
*.bim_*.settings
|
||||
*.rptproj.rsuser
|
||||
|
||||
# Microsoft Fakes
|
||||
FakesAssemblies/
|
||||
|
||||
# GhostDoc plugin setting file
|
||||
*.GhostDoc.xml
|
||||
|
||||
# Node.js Tools for Visual Studio
|
||||
.ntvs_analysis.dat
|
||||
node_modules/
|
||||
|
||||
# Visual Studio 6 build log
|
||||
*.plg
|
||||
|
||||
# Visual Studio 6 workspace options file
|
||||
*.opt
|
||||
|
||||
# Visual Studio 6 auto-generated workspace file (contains which files were open etc.)
|
||||
*.vbw
|
||||
|
||||
# Visual Studio LightSwitch build output
|
||||
**/*.HTMLClient/GeneratedArtifacts
|
||||
**/*.DesktopClient/GeneratedArtifacts
|
||||
**/*.DesktopClient/ModelManifest.xml
|
||||
**/*.Server/GeneratedArtifacts
|
||||
**/*.Server/ModelManifest.xml
|
||||
_Pvt_Extensions
|
||||
|
||||
# Paket dependency manager
|
||||
.paket/paket.exe
|
||||
paket-files/
|
||||
|
||||
# FAKE - F# Make
|
||||
.fake/
|
||||
|
||||
# JetBrains Rider
|
||||
.idea/
|
||||
*.sln.iml
|
||||
|
||||
# CodeRush
|
||||
.cr/
|
||||
|
||||
# Python Tools for Visual Studio (PTVS)
|
||||
__pycache__/
|
||||
*.pyc
|
||||
|
||||
# Cake - Uncomment if you are using it
|
||||
# tools/**
|
||||
# !tools/packages.config
|
||||
|
||||
# Tabs Studio
|
||||
*.tss
|
||||
|
||||
# Telerik's JustMock configuration file
|
||||
*.jmconfig
|
||||
|
||||
# BizTalk build output
|
||||
*.btp.cs
|
||||
*.btm.cs
|
||||
*.odx.cs
|
||||
*.xsd.cs
|
||||
|
||||
# OpenCover UI analysis results
|
||||
OpenCover/
|
||||
|
||||
# Azure Stream Analytics local run output
|
||||
ASALocalRun/
|
||||
|
||||
# MSBuild Binary and Structured Log
|
||||
*.binlog
|
||||
|
||||
# NVidia Nsight GPU debugger configuration file
|
||||
*.nvuser
|
||||
|
||||
# MFractors (Xamarin productivity tool) working folder
|
||||
.mfractor/
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
MIT License
|
||||
|
||||
Copyright (c) Microsoft Corporation. All rights reserved.
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE
|
||||
|
|
@ -0,0 +1,52 @@
|
|||
# Azure SDK
|
||||
|
||||
The Azure SDK delivers a platform for developers to leverage the wide variety of Azure services in their language of choice. The source for the libraries exists for the most part in repositories for each language. This repository is meant to be a jumping off point into those language specific repositories. Issues related to a specific language should be opened in the corresponding repository but cross cutting issues can be opened in this repository.
|
||||
|
||||
| [.NET](https://github.com/Azure/azure-sdk-for-net) | [Java](https://github.com/Azure/azure-sdk-for-java) | [Python](https://github.com/Azure/azure-sdk-for-python) | [JavaScript](https://github.com/Azure/azure-sdk-for-js) | [Go](https://github.com/Azure/azure-sdk-for-go) |
|
||||
|
||||
# Azure Service Libraries
|
||||
|
||||
The following is a list of Azure services and links to their open source code:
|
||||
|
||||
## Client Libraries
|
||||
|
||||
| Service Name | .NET | Java | Python | JavaScript | Go |
|
||||
| ------------ | ------ | ----- | ------ | ------- | -------- |
|
||||
| Azure Storage | [code](https://github.com/Azure/azure-storage-net) | [code](https://github.com/Azure/azure-storage-java) | [code](https://github.com/Azure/azure-storage-python) | [code](https://github.com/Azure/azure-storage-node) | [code](https://github.com/Azure/azure-storage-go) |
|
||||
| CosmosDB | | [code](https://github.com/Azure/azure-cosmosdb-java) | [code](https://github.com/Azure/azure-cosmos-python) | [code](https://github.com/Azure/azure-cosmos-js) |
|
||||
| Keyvault | [code](https://github.com/Azure/azure-sdk-for-net/tree/psSdkJson6/src/SDKs/KeyVault/dataPlane) | [code](https://github.com/Azure/azure-keyvault-java) | [code](https://github.com/Azure/azure-sdk-for-python/tree/master/azure-keyvault) | [code](https://github.com/Azure/azure-sdk-for-node/tree/master/lib/services/keyVault)|
|
||||
| Service Bus | [code](https://github.com/Azure/azure-service-bus-dotnet) | [code](https://github.com/Azure/azure-service-bus-java) | [code](https://github.com/Azure/azure-service-bus-python) | [code](https://github.com/Azure/azure-service-bus-node) |
|
||||
| Event Hubs | [code](https://github.com/Azure/azure-event-hubs-dotnet) | [code](https://github.com/Azure/azure-event-hubs-java) | [code](https://github.com/Azure/azure-event-hubs-python) | [code](https://github.com/Azure/azure-event-hubs-node) |
|
||||
| IotHub, Iot Devices, IotHub Provisioning Service, IotHub Provisioning Device | [code](https://github.com/Azure/azure-iot-sdk-csharp) | [code](https://github.com/Azure/azure-iot-sdk-java) | [code](https://github.com/Azure/azure-iot-sdk-python) | [code](https://github.com/Azure/azure-iot-sdk-node) |
|
||||
| Event Grid | [code](https://github.com/Azure/azure-sdk-for-net/tree/psSdkJson6/src/SDKs/EventGrid/DataPlane) | [code](https://github.com/Azure/azure-sdk-for-java/tree/master/eventgrid/data-plane) | [code](https://github.com/Azure/azure-sdk-for-python/tree/master/azure-eventgrid) | [code](https://github.com/Azure/azure-sdk-for-node/tree/master/lib/services/eventgrid) |
|
||||
| Batch | [code](https://github.com/Azure/azure-sdk-for-net/tree/psSdkJson6/src/SDKs/Batch/DataPlane) | [code](https://github.com/Azure/azure-batch-sdk-for-java) | [code](https://github.com/Azure/azure-sdk-for-python/tree/master/azure-batch) | [code](https://github.com/Azure/azure-sdk-for-node/tree/master/lib/services/batch) |
|
||||
| HDInsight | | | | |
|
||||
| Notification Hubs | | | | |
|
||||
| Application Insights Ingestion | [code](https://github.com/Microsoft/ApplicationInsights-dotnet) | [code](https://github.com/Microsoft/ApplicationInsights-java)| [code](https://github.com/Microsoft/ApplicationInsights-python) | [code](https://github.com/Microsoft/ApplicationInsights-node.js) |
|
||||
| Application Insights Query | [code](https://github.com/Azure/azure-sdk-for-net/tree/psSdkJson6/src/SDKs/ApplicationInsights/DataPlane)| [code](https://github.com/Azure/azure-sdk-for-java/tree/master/applicationinsights/data-plane) | [code](https://github.com/Azure/azure-sdk-for-python/tree/master/azure-applicationinsights)| [code](https://github.com/Azure/azure-sdk-for-node/tree/master/lib/services/applicationinsights-query) |
|
||||
| Log Analytics Ingestion | | | | |
|
||||
| Log Analytics Query | [code](https://github.com/Azure/azure-sdk-for-net/tree/psSdkJson6/src/SDKs/OperationalInsights/DataPlane) | [code](https://github.com/Azure/azure-sdk-for-java/tree/master/loganalytics/data-plane) | [code](https://github.com/Azure/azure-sdk-for-python/tree/master/azure-loganalytics) | [code](https://github.com/Azure/azure-sdk-for-node/tree/master/lib/services/loganalytics) |
|
||||
| Service Fabric | | | | |
|
||||
| DataLake Analytics | [code](https://github.com/Azure/azure-sdk-for-net/tree/psSdkJson6/src/SDKs/DataLake.Analytics)| [code](https://github.com/Azure/azure-libraries-for-java/tree/master/azure-mgmt-datalake-analytics) | [code](https://github.com/Azure/azure-sdk-for-python/tree/master/azure-mgmt-datalake-analytics)| [code](https://github.com/Azure/azure-sdk-for-node/tree/master/lib/services/dataLake.Analytics)|
|
||||
| Datalake Store | [code](https://github.com/Azure/azure-data-lake-store-net) | [code](https://github.com/Azure/azure-data-lake-store-java) | [code](https://github.com/Azure/azure-data-lake-store-python) | |
|
||||
| Azure Search | [code](https://github.com/Azure/azure-sdk-for-net/tree/psSdkJson6/src/SDKs/Search) | | | |
|
||||
| Relay | [code](https://github.com/Azure/azure-relay-dotnet) | | | [code](https://github.com/Azure/azure-relay-node)|
|
||||
| Cognitive Services | [code](https://github.com/Azure/azure-sdk-for-net/tree/psSdkJson6/src/SDKs/CognitiveServices/dataPlane) | [code](https://github.com/Azure/azure-sdk-for-java/tree/master/cognitiveservices/data-plane) | [code](https://github.com/Azure/azure-sdk-for-python) | [code](https://github.com/Azure/azure-sdk-for-node/tree/master/lib/services) |
|
||||
| SQL | | | | |
|
||||
| MySQL | | | | |
|
||||
| PostgreSQL | | | | |
|
||||
| Redis | | | | |
|
||||
|
||||
# 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.
|
||||
|
||||
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](https://opensource.microsoft.com/codeofconduct/).
|
||||
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
|
||||
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
|
||||
# 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.
|
||||
|
||||
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](https://opensource.microsoft.com/codeofconduct/).
|
||||
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
|
||||
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
|
||||
|
|
@ -0,0 +1,68 @@
|
|||
# Azure SDK Design Guidelines
|
||||
|
||||
This document will describe architectural and API design guidelines for Azure SDKs.
|
||||
|
||||
Currently, the document id mainly as a list of topics that we want to cover in more detail, i.e. there is not much useful inforamtion in it yet.
|
||||
|
||||
## 1.0 Language Independent Guidelines
|
||||
|
||||
### 1.0.0 General Guidelines
|
||||
|
||||
1.0.1 :warning: **NOTE** language-specific gudelines (sections 2.0 - 6.0) overrule language independent guidelines
|
||||
|
||||
1.0.2 :white_check_mark: **DO** provide SDKs for the following languages: C#, Java, Python, JavaScript
|
||||
|
||||
1.0.3 :ballot_box_with_check: **CONSIDER** providing SDKs for the following languages: Go, C++
|
||||
|
||||
<font size="2" color="gray">TODO: This will result in partial coverage for optional languages. Is that OK?</font>
|
||||
|
||||
1.0.4 :white_check_mark: **DO** support cancellations.
|
||||
|
||||
1.0.5 :white_check_mark: **DO** support retries
|
||||
|
||||
1.0.6 :no_entry: **DO NOT** depend on concrete logging, dependency injection, or configuration technologies.
|
||||
|
||||
The SDKs will be used in applications that might be using ther logging, DI, and configuration technologies of their choice.
|
||||
|
||||
## 1.1.0 Telemetry
|
||||
Telemetry is used by service teams (not customers) to monitor what SDK a client is using to call into their service. Specifically, the service team can detect client OS, language, language version, and service SDK version. Some clients can prepend additional information indicating the name and version of the client application.
|
||||
|
||||
1.1.1 :white_check_mark: **DO** send telemetry information in the User-Agent header, with the header value in the the following format:
|
||||
|
||||
[<application_id>/<SPACE\>]<sdk_name>/<sdk_version>/<SPACE\><platform_information>
|
||||
|
||||
* <application_id> ::= optional application-specific string. The string is supplied by the user of the SDK, e.g. "AzCopy/10.0.4-Preview"
|
||||
* <sdk_name> ::= name of the SDK, e.g. "Azure-Storage-Blob"
|
||||
* <sdk_version> ::= the version of the SDK. Note: this is not the version of the service
|
||||
* <platform_information> ::= information about the currently-executing OS and runtime, e.g. "(NODE-VERSION v4.5.0; Windows_NT 10.0.14393)"
|
||||
|
||||
For example, the following two are fully formatter User-Agent header values:
|
||||
|
||||
* "Azure-Storage/1.4.0 (NODE-VERSION v4.5.0; Windows_NT 10.0.14393)"
|
||||
* "AzCopy/10.0.4-Preview Azure-Storage/1.4.0 (NODE-VERSION v4.5.0; Windows_NT 10.0.14393)"
|
||||
|
||||
For details on the User-Agent header, see https://tools.ietf.org/html/rfc7231#section-5.5.3
|
||||
|
||||
NOTE: today, the <sdk_name> for all storage SDKs/packages (Blob, File, etc.) is simply "Azure-Storage". The guideline above proposes that we standardize on full SDK names, e.g. "Azure-Storage-Blob".
|
||||
|
||||
TODO: provide the full list of SDK names.
|
||||
|
||||
TODO: provide language-specific guidelines (and possibly shared library) for generating <platform_information>
|
||||
|
||||
TODO: provide shared library API for injecting telemetry information
|
||||
|
||||
## 2.0 C# Specific Guidelines
|
||||
|
||||
2.0.1 :white_check_mark: **DO** follow the official [Framework Design Guidelines](https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/)
|
||||
|
||||
2.0.2 :warning: **NOTE** additional gudelines in this section overrule the Framework Design Guidelines
|
||||
|
||||
<font size="2" color="gray">TODO: describe guidance for logging, configuration, and dependency injection</font>
|
||||
|
||||
## 3.0 Java Specific Guidelines
|
||||
|
||||
## 4.0 Python Specific Guidelines
|
||||
|
||||
## 5.0 JavaScript Specific Guidelines
|
||||
|
||||
## 6.0 Go Specific Guidelines
|
||||
|
|
@ -0,0 +1,44 @@
|
|||
# Cloud Native Azure SDK Features
|
||||
|
||||
## All Cloud Native SDKs should support these features:
|
||||
- Customization of the HTTP stack (allowing proxies, changing concurrent connections, keep-alives, TLS, expect continue, etc.)
|
||||
|
||||
- Logging (with levels [debug, info, warning, error] and possible too-much-time threshold)
|
||||
- Retries (With exponential/fixed policy, max # of retries, per-try timeout, retry delay, max retry delay). Also, deserialization of service payloads should be retryable should connection fail while downloading. Some services may support additional retry features such as retrying an operation from an alternate datacenter. Also note that the service and/or client may need to do some additonal work to guarantee idempotency.
|
||||
- Telemetry
|
||||
- Credentials (Anonymous, OAuth, and possibly custom [like shared key for Azure Storage])
|
||||
- Unique request ID generation (possibly overwritten by customer)
|
||||
- Progress reporting when transferring large amounts of data
|
||||
- Manual & timed cancellation (ideally, a single cancellation object could be usable across multiple SDKs; for example, imagine a single 5-second cancellation object that can be passed to keyvault, CosmosDB, and Azure Storage APIs ensuring that all operations complete within 5 seconds)
|
||||
|
||||
|
||||
## Some other potential features are:
|
||||
- Circuit breakers
|
||||
- Client-side caching
|
||||
- Pacing of requests
|
||||
- Fault injection
|
||||
- Bandwidth monitoring
|
||||
- Mocking/testing support (recordings)
|
||||
|
||||
## Here are some other SDK thoughts:
|
||||
- SDK design should be centered around leading customer into "pit of success". For example, customers should be able to diagnose problems themselves and fix them without having to get any kind of support. This, by necessaity, requires NOT abstracting network calls and communcation endpoints so that when communication fails, the customer can determine what was trying to be communcatted with in an effort to diagnose the failure.
|
||||
|
||||
- SDKs should be pay for play. That is, customers should only have to take what they need.
|
||||
|
||||
- Each SDK major version is tied to a specific service version. Minor version updates are for compatible bug fixes/perf improvements/non-breaking features. We're allowed to make breaking changes between major versions. However, breaks should NOT be gratuitous; they should be a very good reason for breaking customer code.
|
||||
|
||||
- If possible (usually depending on the programming language), customers should be able to load multiple versions of the SDK in their application; old code can run against the old version and new code can run against the new version. There MUST be a way for customer code to interop between the versions. For example, the customer can grab a URL from an old library object and construct a new library object using the same URL - this allows the user to use both old & new libraries at will within their application to leverage new feratures while not forcing them to upgrade old code to a new library version.
|
||||
|
||||
- SDKs should ideally depend on the language's core platform only and NOT depend on any other packages. Depending on other packages prevents customers from using other SDKs that depend on different versions of those same packages. This could even prevent multiple Azure SDKs from being used within a single app if the SDKs depend on different versions of the same package. To solve this, it is best for each SDK to not depend on any other packages.
|
||||
|
||||
- SDKs should stick with simple data types (strings, numbers, booleans, and simple structures consisting of these data types) as these are available in all languages allowing for greater consistency across languages which simplifies user's learning curve.
|
||||
|
||||
- Of course, the SDK should be up-to-date with the idioms used by the SDK's programming language. Here are some examples:
|
||||
- .NET I/O APIs should all be of the XxxAsync form; synchronous and BeginXxx/EndXxx APIs should not be exposed.
|
||||
- Go I/O APIs should all take a context.Context object as their first parameter.
|
||||
- Java I/O APIs should use RxJava and not expose synchronous APIs.
|
||||
- Node I/O APIs should return promises.
|
||||
|
||||
- All APIs must be threadsafe. Ideally, all data structures returned from a service call are immutable.
|
||||
|
||||
- SDKs should avoid allocating memory/buffers as much as possible. Customers should own their own memory consumption including buffer sizes, number of buffers, and their lifetime.
|
||||
|
|
@ -0,0 +1,67 @@
|
|||
# Engineering System
|
||||
|
||||
## Requirements
|
||||
- Dashboard
|
||||
- Tracking status of all SDKs in all languages
|
||||
- Repositories
|
||||
- One per language, or one per SDK per language?
|
||||
- Public and private versions of all repos
|
||||
- New service features under embargo
|
||||
- Publishing
|
||||
- Nightly / per-checkin builds to publicly-available pre-release package stores
|
||||
- Official builds to package stores on-demand
|
||||
- Fast and easy to publish a subset of packages (down to a single package)
|
||||
- Servicing
|
||||
- Branching
|
||||
- Toolset management
|
||||
- Testing
|
||||
- Unit, Functional, Scenario
|
||||
- Performance
|
||||
- Stress
|
||||
- All tests can be run without connecting to Azure (or in a private fork)
|
||||
- Distributed runner to decrease test time
|
||||
- Test multiple SDK versions agains latest version of service
|
||||
- Integrate with other engineering systems (CDP/CDPx/healthstore)
|
||||
- Detect if service deployments break SDK
|
||||
- Run tests frequently against live services (prod, canary, deployment pipeline)
|
||||
- Automatically open ICM incidents
|
||||
- Support different cloud instances
|
||||
- Public
|
||||
- National
|
||||
- Stack
|
||||
- Service virtualization
|
||||
- Record and replay service responses, so tests can run much faster and without connecting to Azure
|
||||
- Fault injection (simulate service error cases)
|
||||
- Code coverage
|
||||
- Breaking change detection
|
||||
- Service breaks SDK within ApiVersion
|
||||
- Service upgrades ApiVersion
|
||||
- Client API breaking change
|
||||
- Documentation
|
||||
- Build and publish
|
||||
- Changelog generation
|
||||
- Installers(?) for global package installs (e.g. apt-get)
|
||||
- Issue Management
|
||||
- Report issues not getting traction
|
||||
- Route issues from client to service teams
|
||||
- Dependency management
|
||||
- Between components we own
|
||||
- Third-party libraries (e.g. JSON.NET)
|
||||
- New (e.g. Python 3.8, Java9) or out-of-support runtimes (Python 2.7)
|
||||
- Notification when newer third-party library is available
|
||||
- Notification for issues and security vulnerabilities in third-party libraries
|
||||
- Standardization
|
||||
- Test frameworks
|
||||
- Dependencies
|
||||
- Versioning
|
||||
|
||||
## Infrastructure
|
||||
- Azure DevOps
|
||||
- Travis
|
||||
|
||||
## Support Policy
|
||||
> Microsoft Azure Cloud Services will support no fewer than the latest two SDK versions for deploying new Cloud Services. Microsoft will provide notification 12 months before retiring a SDK in order to smooth the transition to a supported version.
|
||||
|
||||
The Microsoft Azure SDK policy covers Microsoft Azure SDK authoring tools, REST APIs, client libraries, command-line utilities, compute & storage emulators, and Azure Tools for Microsoft Visual Studio.
|
||||
|
||||
https://support.microsoft.com/en-gb/help/18486/lifecycle-faq-azure
|
||||
Загрузка…
Ссылка в новой задаче