diff --git a/doc/DataPlaneCodeGeneration/AzureSDKCodeGeneration_DataPlane_Quickstart.md b/doc/DataPlaneCodeGeneration/AzureSDKCodeGeneration_DataPlane_Quickstart.md index bfe5e01576a2d..e8a54d4b10b58 100644 --- a/doc/DataPlaneCodeGeneration/AzureSDKCodeGeneration_DataPlane_Quickstart.md +++ b/doc/DataPlaneCodeGeneration/AzureSDKCodeGeneration_DataPlane_Quickstart.md @@ -85,7 +85,7 @@ pwsh /home/azure-sdk-for-net/eng/scripts/automation/Invoke-DataPlaneGenerateSDKP When you run the `eng\scripts\automation\Invoke-DataPlaneGenerateSDKPackage.ps1` script, it will: -- Create a project folder, install template files from `eng/templates/Azure.ServiceTemplate.Template`, and create `.csproj` and `.sln` files for your new library. +- Create a project folder, install template files from `sdk/template/Azure.Template`, and create `.csproj` and `.sln` files for your new library. These files are created following the guidance for the [Azure SDK Repo Structure](https://github.com/Azure/azure-sdk/blob/master/docs/policies/repostructure.md). @@ -130,13 +130,13 @@ You will update all the `Sample_.md` and README.md file ### Snippets -Snippets are the great way to reuse the sample code. Snippets allow us to verify that the code in our samples and READMEs is always up to date, and passes unit tests. We have added the snippet [here](https://github.com/Azure/azure-sdk-for-net/blob/3ac301ac6435c818ad7a9946ab1c4023cee236ff/eng/templates/Azure.ServiceTemplate.Template/tests/Samples/Sample1_CreateResource.cs#L32) in a sample and used it in the [README](https://github.com/Azure/azure-sdk-for-net/blob/3ac301ac6435c818ad7a9946ab1c4023cee236ff/eng/templates/Azure.ServiceTemplate.Template/README.md#create-resource). Please refer to [Updating Sample Snippets](https://github.com/Azure/azure-sdk-for-net/blob/main/CONTRIBUTING.md#updating-sample-snippets) to add snippets in your samples. +Snippets are the great way to reuse the sample code. Snippets allow us to verify that the code in our samples and READMEs is always up to date, and passes unit tests. We have added the snippet [here](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/tests/Samples/Sample1_HelloWorld.cs#L21) in a sample and used it in the [README](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/README.md#get-secret). Please refer to [Updating Sample Snippets](https://github.com/Azure/azure-sdk-for-net/blob/main/CONTRIBUTING.md#updating-sample-snippets) to add snippets in your samples. ### README README.md file instructions are listed in `Azure../README.md` file. Please add/update the README.md file as per your library. -**Learn more:** to understand more about README, see the [README.md](https://github.com/Azure/azure-sdk-for-net/blob/3ac301ac6435c818ad7a9946ab1c4023cee236ff/eng/templates/Azure.ServiceTemplate.Template/README.md). Based on that [here](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Keys/README.md) is an example. +**Learn more:** to understand more about README, see the [README.md](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/README.md). Based on that [here](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Keys/README.md) is an example. ### Changelog @@ -150,7 +150,7 @@ You can add convienice APIs by adding a customization layer on top of the genera If other modifications are needed to the generated API, you can consider making them directly to the Open API specification, which will have the benefit of making the changes to the library in all languages you generate the library in. As a last resort, you can add modifications with swagger transforms in the `autorest.md` file. [AnomalyDetector autorest.md](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/anomalydetector/Azure.AI.AnomalyDetector/src/autorest.md) shows and example of how this can be accomplished. -Once you've made changes to the public API, you will need to run the `eng\scripts\Export-API.ps1` script to update the public API listing. This will generate a file in the library's directory similar to the example found in [eng\templates\Azure.ServiceTemplate.Template\api\Azure.ServiceTemplate.Template.netstandard2.0.cs](https://github.com/Azure/azure-sdk-for-net/blob/bb0fbccfc33dd27d1ec6f0870022824d47181e61/sdk/template-dpg/Azure.ServiceTemplate.Template/api/Azure.ServiceTemplate.Template.netstandard2.0.cs). +Once you've made changes to the public API, you will need to run the `eng\scripts\Export-API.ps1` script to update the public API listing. This will generate a file in the library's directory similar to the example found in [sdk\template\Azure.Template\api\Azure.Template.netstandard2.0.cs](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/api/Azure.Template.netstandard2.0.cs). e.g. Running the script for a project in `sdk\deviceupdate` would look like this: diff --git a/eng/scripts/automation/GenerateAndBuildLib.ps1 b/eng/scripts/automation/GenerateAndBuildLib.ps1 index 731596ed2f5a3..bba03db010555 100644 --- a/eng/scripts/automation/GenerateAndBuildLib.ps1 +++ b/eng/scripts/automation/GenerateAndBuildLib.ps1 @@ -127,7 +127,6 @@ function New-DataPlanePackageFolder() { $inputfile = "" $fileArray = $inputfiles.Split(";") if (($inputfiles -ne "") -And ($fileArray.Length -gt 0)) { - # $inputfile = "- " + $fileArray[0]; for ($i = 0; $i -lt $fileArray.Count ; $i++) { $inputfile = $inputfile + [Environment]::NewLine + "- " + $fileArray[$i] } @@ -161,7 +160,7 @@ function New-DataPlanePackageFolder() { $libraryName = $namespaceArray[-1] $groupName = $namespaceArray[1] - $dotnetNewCmd = "dotnet new dpg --libraryName $libraryName --groupName $groupName --force" + $dotnetNewCmd = "dotnet new azsdkdpg --libraryName $libraryName --groupName $groupName --force" if ($inputfile -ne "") { $dotnetNewCmd = $dotnetNewCmd + " --swagger '$inputfile'" } @@ -180,7 +179,7 @@ function New-DataPlanePackageFolder() { $dotnetNewCmd = $dotnetNewCmd + " --includeCI true" } - # dotnet new dpg --libraryName $libraryName --swagger $inputfile --securityScopes $securityScope --securityHeaderName $securityHeaderName --includeCI true --force + # dotnet new azsdkdpg --libraryName $libraryName --swagger $inputfile --securityScopes $securityScope --securityHeaderName $securityHeaderName --includeCI true --force Write-Host "Invote dotnet new command: $dotnetNewCmd" Invoke-Expression $dotnetNewCmd @@ -192,7 +191,6 @@ function New-DataPlanePackageFolder() { dotnet sln remove tests\$namespace.Tests.csproj dotnet sln add tests\$namespace.Tests.csproj Pop-Location - dotnet new -u $sdkPath/sdk/template/Azure.Template } Push-Location $sdkPath @@ -278,6 +276,11 @@ function Invoke-Generate() { $sdkfolder = $sdkfolder -replace "\\", "/" Push-Location $sdkfolder/src dotnet build /t:GenerateCode + if ( !$? ) { + Write-Error "Failed to create generate sdk." + Pop-Location + exit 1 + } Pop-Location } @@ -288,6 +291,11 @@ function Invoke-Build() { $sdkfolder = $sdkfolder -replace "\\", "/" Push-Location $sdkfolder dotnet build + if ( !$? ) { + Write-Error "Failed to build sdk. exit code: $?" + Pop-Location + exit 1 + } Pop-Location } @@ -298,6 +306,11 @@ function Invoke-Pack() { $sdkfolder = $sdkfolder -replace "\\", "/" Push-Location $sdkfolder dotnet pack + if ( !$? ) { + Write-Error "Failed to build sdk package. exit code: $?" + Pop-Location + exit 1 + } Pop-Location } function Get-ResourceProviderFromReadme($readmeFile) { diff --git a/eng/scripts/automation/Invoke-DataPlaneGenerateSDKPackage.ps1 b/eng/scripts/automation/Invoke-DataPlaneGenerateSDKPackage.ps1 index 44b03f247f104..ac9510f481f32 100644 --- a/eng/scripts/automation/Invoke-DataPlaneGenerateSDKPackage.ps1 +++ b/eng/scripts/automation/Invoke-DataPlaneGenerateSDKPackage.ps1 @@ -22,17 +22,10 @@ $outputJson = Get-Content $outputJsonFile | Out-String | ConvertFrom-Json $projectFolder = $outputJson.projectFolder Write-Host "projectFolder:$projectFolder" Remove-Item $outputJsonFile +# Generate Code Invoke-Generate -sdkfolder $projectFolder -if ( $? -ne $True) { - Write-Error "Failed to create generate sdk." - exit 1 -} - +# Build Invoke-Build -sdkfolder $projectFolder -if ( $? -ne $True) { - Write-Error "Failed to build sdk. exit code: $?" - exit 1 -} # Generate APIs $repoRoot = (Join-Path $PSScriptRoot .. .. ..) diff --git a/eng/scripts/automation/Invoke-GenerateAndBuild.ps1 b/eng/scripts/automation/Invoke-GenerateAndBuild.ps1 index 47994f1f289bf..fec3cf5215d92 100644 --- a/eng/scripts/automation/Invoke-GenerateAndBuild.ps1 +++ b/eng/scripts/automation/Invoke-GenerateAndBuild.ps1 @@ -30,7 +30,7 @@ if ( $serviceType -eq "resource-manager" ) { Write-Host "Data-plane SDK Generation is not implemented currently." exit 1 } -if ( $? -ne $True) { +if ( !$? ) { Write-Error "Failed to create sdk project folder. exit code: $?" exit 1 } @@ -39,18 +39,11 @@ $projectFolder = $newpackageoutputJson.projectFolder $path = $newpackageoutputJson.path Write-Host "projectFolder:$projectFolder" Remove-Item $newpackageoutput - +# Generate Code Invoke-Generate -sdkfolder $projectFolder -if ( $? -ne $True) { - Write-Error "Failed to generate sdk. exit code: $?" - exit 1 -} - +# Build Invoke-Build -sdkfolder $projectFolder -if ( $? -ne $True) { - Write-Error "Failed to build sdk. exit code: $?" - exit 1 -} + $outputJson = [PSCustomObject]@{ packages = @([pscustomobject]@{packageName="$packageName"; result='succeeded'; path=@("$path");packageFolder="$path"}) } diff --git a/sdk/template/Azure.Template/.content/api/Azure.Template.netstandard2.0.cs b/sdk/template/Azure.Template/.content/api/Azure.Template.netstandard2.0.cs index e69de29bb2d1d..73c55888aad6a 100644 --- a/sdk/template/Azure.Template/.content/api/Azure.Template.netstandard2.0.cs +++ b/sdk/template/Azure.Template/.content/api/Azure.Template.netstandard2.0.cs @@ -0,0 +1,17 @@ +namespace Azure.Template +{ + public partial class TemplateClient + { + protected TemplateClient() { } + public TemplateClient(string endpoint, Azure.Core.TokenCredential credential, Azure.Template.TemplateClientOptions options = null) { } + public virtual Azure.Core.Pipeline.HttpPipeline Pipeline { get { throw null; } } + } + public partial class TemplateClientOptions : Azure.Core.ClientOptions + { + public TemplateClientOptions(Azure.Template.Generated.TemplateServiceClientOptions.ServiceVersion version = Azure.Template.Generated.TemplateServiceClientOptions.ServiceVersion.V1_0_0) { } + public enum ServiceVersion + { + V1_0_0 = 1, + } + } +} \ No newline at end of file diff --git a/sdk/template/Azure.Template/.content/CHANGELOG.md b/sdk/template/Azure.Template/.content/packageResource/CHANGELOG.md similarity index 100% rename from sdk/template/Azure.Template/.content/CHANGELOG.md rename to sdk/template/Azure.Template/.content/packageResource/CHANGELOG.md diff --git a/sdk/template/Azure.Template/.content/packageResource/README.md b/sdk/template/Azure.Template/.content/packageResource/README.md new file mode 100644 index 0000000000000..830f13e14c77a --- /dev/null +++ b/sdk/template/Azure.Template/.content/packageResource/README.md @@ -0,0 +1,97 @@ +# README.md template + +Use the guidelines in each section of this template to ensure consistency and readability of your README. The README resides in your package's GitHub repository at the root of its directory within the repo. It's also used as the package distribution page (NuGet, PyPi, npm, etc.) and as a Quickstart on docs.microsoft.com. See [Azure.Template/README.md](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/README.md) for an example following this template. + +**Title**: The H1 of your README should be in the format: `# [Product Name] client library for [Language]` + +* All headings, including the H1, should use **sentence-style capitalization**. Refer to the [Microsoft Style Guide][style-guide-msft] and [Microsoft Cloud Style Guide][style-guide-cloud] for more information. +* Example: `# Azure Batch client library for .NET` + +# Azure Template client library for .NET + +**Introduction**: The introduction appears directly under the title (H1) of your README. + +* **DO NOT** use an "Introduction" or "Overview" heading (H2) for this section. +* First sentence: **Describe the service** briefly. You can usually use the first line of the service's docs landing page for this (Example: [Cosmos DB docs landing page](https://docs.microsoft.com/azure/cosmos-db/)). +* Next, add a **bulleted list** of the **most common tasks** supported by the package or library, prefaced with "Use the client library for [Product Name] to:". Then, provide code snippets for these tasks in the [Examples](#examples) section later in the document. Keep the task list short but include those tasks most developers need to perform with your package. +* Include this single line of links targeting your product's content at the bottom of the introduction, making any adjustments as necessary (for example, NuGet instead of PyPi): + + [Source code](https://github.com/Azure/azure-sdk-for-net/tree/bb0fbccfc33dd27d1ec6f0870022824d47181e61/sdk/template-dpg/Azure.ServiceTemplate.Template/src) | [Package (NuGet)](https://www.nuget.org/packages/Azure.AI.AnomalyDetector) | [API reference documentation](https://azure.github.io/azure-sdk-for-net/anomalydetector.html) | [Product documentation](https://docs.microsoft.com/azure/cognitive-services/anomaly-detector/) + +> TIP: Your README should be as **brief** as possible but **no more brief** than necessary to get a developer new to Azure, the service, or the package up and running quickly. Keep it brief, but include everything a developer needs to make their first API call successfully. + +## Getting started + +This section should include everything a developer needs to do to install and create their first client connection *very quickly*. + +### Install the package + +First, provide instruction for obtaining and installing the package or library. This section might include only a single line of code, like `dotnet add package package-name`, but should enable a developer to successfully install the package from NuGet, npm, or even cloning a GitHub repository. + +### Prerequisites + +Include a section after the install command that details any requirements that must be satisfied before a developer can [authenticate](#authenticate-the-client) and test all of the snippets in the [Examples](#examples) section. For example, for Cosmos DB: + +> You must have an [Azure subscription](https://azure.microsoft.com/free/dotnet/) and [Cosmos DB account](https://docs.microsoft.com/azure/cosmos-db/account-overview) (SQL API). In order to take advantage of the C# 8.0 syntax, it is recommended that you compile using the [.NET Core SDK](https://dotnet.microsoft.com/download) 3.0 or higher with a [language version](https://docs.microsoft.com/dotnet/csharp/language-reference/configure-language-version#override-a-default) of `latest`. It is also possible to compile with the .NET Core SDK 2.1.x using a language version of `preview`. + +### Authenticate the client + +If your library requires authentication for use, such as for Azure services, include instructions and example code needed for initializing and authenticating. + +For example, include details on obtaining an account key and endpoint URI, setting environment variables for each, and initializing the client object. + +## Key concepts + +The *Key concepts* section should describe the functionality of the main classes. Point out the most important and useful classes in the package (with links to their reference pages) and explain how those classes work together. Feel free to use bulleted lists, tables, code blocks, or even diagrams for clarity. + +Include the *Thread safety* and *Additional concepts* sections below at the end of your *Key concepts* section. You may remove or add links depending on what your library makes use of: + +### Thread safety + +We guarantee that all client instance methods are thread-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-service-methods-thread-safety)). This ensures that the recommendation of reusing client instances is always safe, even across threads. + +### Additional concepts + +[Client options](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#configuring-service-clients-using-clientoptions) | +[Accessing the response](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#accessing-http-response-details-using-responset) | +[Long-running operations](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#consuming-long-running-operations-using-operationt) | +[Handling failures](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#reporting-errors-requestfailedexception) | +[Diagnostics](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Diagnostics.md) | +[Mocking](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#mocking) | +[Client lifetime](https://devblogs.microsoft.com/azure-sdk/lifetime-management-and-thread-safety-guarantees-of-azure-sdk-net-clients/) + + +## Examples + +You can familiarize yourself with different APIs using [Samples](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/template/Azure.Template/samples). + +### + +You can create a client and call the client's `` method. + +```C# Snippet:Azure_Template_Scenario +``` + +## Troubleshooting + +Describe common errors and exceptions, how to "unpack" them if necessary, and include guidance for graceful handling and recovery. + +Provide information to help developers avoid throttling or other service-enforced errors they might encounter. For example, provide guidance and examples for using retry or connection policies in the API. + +If the package or a related package supports it, include tips for logging or enabling instrumentation to help them debug their code. + +## Next steps + +* Provide a link to additional code examples, ideally to those sitting alongside the README in the package's `/samples` directory. +* If appropriate, point users to other packages that might be useful. +* If you think there's a good chance that developers might stumble across your package in error (because they're searching for specific functionality and mistakenly think the package provides that functionality), point them to the packages they might be looking for. + +## Contributing + +This is a template, but your SDK readme should include details on how to contribute code to the repo/package. + + +[style-guide-msft]: https://docs.microsoft.com/style-guide/capitalization +[style-guide-cloud]: https://aka.ms/azsdk/cloud-style-guide + +![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Ftemplate%2FAzure.Template%2FREADME.png) \ No newline at end of file diff --git a/sdk/template/Azure.Template/.content/samples/README.md b/sdk/template/Azure.Template/.content/samples/README.md index 5b8338f64a1f5..ec5edcbf0252f 100644 --- a/sdk/template/Azure.Template/.content/samples/README.md +++ b/sdk/template/Azure.Template/.content/samples/README.md @@ -9,6 +9,6 @@ name: Azure.Template samples for .NET description: Samples for the Azure.Template client library. --- -# Azure.ServiceTemplate.Template Samples +# Azure.Template Samples - + diff --git a/sdk/template/Azure.Template/.content/samples/Sample1_HelloWorld.md b/sdk/template/Azure.Template/.content/samples/Sample1_HelloWorld.md index 98fc01df66886..31d46e0c573e8 100644 --- a/sdk/template/Azure.Template/.content/samples/Sample1_HelloWorld.md +++ b/sdk/template/Azure.Template/.content/samples/Sample1_HelloWorld.md @@ -14,6 +14,6 @@ You can create a client and call the client's `` method ``` To see the full example source files, see: -* [HelloWorld](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/tests/Samples/Sample1_HelloWorld.cs) +* [HelloWorld](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/tests/Samples/Sample1_HelloWorld.cs)) - \ No newline at end of file + \ No newline at end of file diff --git a/sdk/template/Azure.Template/.content/samples/Sample1_HelloWorldAsync.md b/sdk/template/Azure.Template/.content/samples/Sample1_HelloWorldAsync.md index c409c0a657321..5eefdba0de566 100644 --- a/sdk/template/Azure.Template/.content/samples/Sample1_HelloWorldAsync.md +++ b/sdk/template/Azure.Template/.content/samples/Sample1_HelloWorldAsync.md @@ -14,6 +14,6 @@ You can create a client and call the client's `` method ``` To see the full example source files, see: -* [HelloWorld](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/tests/Samples/Sample1_HelloWorldAsync.cs) +* [HelloWorld](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/tests/Samples/Sample1_HelloWorldAsync.cs)) - \ No newline at end of file + \ No newline at end of file diff --git a/sdk/template/Azure.Template/.content/testResource/tests.yml b/sdk/template/Azure.Template/.content/testResource/tests.yml new file mode 100644 index 0000000000000..7f4825e231c97 --- /dev/null +++ b/sdk/template/Azure.Template/.content/testResource/tests.yml @@ -0,0 +1,7 @@ +trigger: none + +extends: + template: /eng/pipelines/templates/stages/archetype-sdk-tests.yml + parameters: + ServiceDirectory: ServiceNameLowercase + SupportedClouds: 'Public' diff --git a/sdk/template/Azure.Template/.template.config/template.json b/sdk/template/Azure.Template/.template.config/template.json index 0e32ea7cf51cb..b804f01d18d8d 100644 --- a/sdk/template/Azure.Template/.template.config/template.json +++ b/sdk/template/Azure.Template/.template.config/template.json @@ -3,7 +3,7 @@ "classifications": [ "Azure", "ClassLibrary" ], "identity": "Azure.Template", "name": "Azure DataPlane SDK template: client project", - "shortName": "dpg", + "shortName": "azsdkdpg", "tags": { "language": "C#", "type": "project" @@ -49,6 +49,10 @@ "source": ".content/perf", "target": "./perf" }, + { + "source": ".content/samples", + "target": "./samples" + }, { "source": ".content/stress", "target": "./stress" @@ -60,6 +64,10 @@ { "source": ".content/src", "target": "./src" + }, + { + "source": ".content/packageResource", + "target": "./" } ], "symbols": { @@ -150,6 +158,27 @@ "defaultValue": "https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/tests/Samples/Sample1.HelloWorldAsync.cs", "replaces": "AsyncSamplesLink" }, + "readmeLink": { + "type": "parameter", + "datatype": "text", + "isRequired": false, + "defaultValue": "https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/samples/README.md", + "replaces": "ReadmeLink" + }, + "sampleReadmeLink": { + "type": "parameter", + "datatype": "text", + "isRequired": false, + "defaultValue": "https://github.com/Azure/azure-sdk-for-net/main/sdk/template/Azure.Template/samples/Sample1_HelloWorld.md", + "replaces": "SampleReadmeLink" + }, + "asyncSampleReadmeLink": { + "type": "parameter", + "datatype": "text", + "isRequired": false, + "defaultValue": "https://github.com/Azure/azure-sdk-for-net/main/sdk/template/Azure.Template/samples/Sample1_HelloWorldAsync.md", + "replaces": "AsyncSampleReadmeLink" + }, "ServiceName": { "type": "derived", "datatype": "text", diff --git a/sdk/template/Azure.Template/CHANGELOG.md b/sdk/template/Azure.Template/CHANGELOG.md index cc54ec4c0b815..0e50c409dcfae 100644 --- a/sdk/template/Azure.Template/CHANGELOG.md +++ b/sdk/template/Azure.Template/CHANGELOG.md @@ -1,7 +1,112 @@ # Release History -## 1.0.0-beta.1 (2022-04-13) +## 1.0.3-beta.20 (2022-04-26) -### Features Added +### Other Changes +- Release DPG library +- Add Grow-up story + +## 1.0.3-beta.19 (2020-09-24) +- Test Submit-PR -- Get secret +## 1.0.3-beta.18 (2020-09-24) +- Test Submit-PR + +## 1.0.3-beta.17 (2020-09-16) +- Package Artifacts directory restructure, attempt 7 + +## 1.0.3-beta.16 (2020-09-15) +- Package Artifacts directory restructure, attempt 6 + +## 1.0.3-beta.15 (2020-09-15) +- Package Artifacts directory restructure, attempt 5 + +## 1.0.3-beta.14 (2020-09-14) +- Package Artifacts directory restructure, attempt 4 + +## 1.0.3-beta.13 (2020-09-14) +- Package Artifacts directory restructure, attempt 3 + +## 1.0.3-beta.12 (2020-09-11) +- Package Artifacts directory restructure, attempt 2 + +## 1.0.3-beta.11 (2020-09-10) +- Package Artifacts directory restructure + +## 1.0.3-beta.10 (2020-09-09) +- Enable the master link replacement feature, attempt 3 + +## 1.0.3-beta.9 (2020-09-09) +- Enable the master link replacement feature, attempt 2 + +## 1.0.3-beta.8 (2020-09-09) +- Enable the master link replacement feature, attempt 1 + +## 1.0.3-beta.7 (2020-09-04) +- Test release tag replacement + +## 1.0.3-beta.6 (2020-09-03) +- Test new alpha beta versioning + +## 1.0.3-beta.5 (2020-09-03) +- Test new alpha beta versioning + +## 1.0.3-beta.4 (2020-09-01) +- Test new alpha beta versioning + +## 1.0.3-beta.3 (2020-08-31) +- Test new alpha beta versioning + +## 1.0.3-beta.2 (2020-08-30) +- Test new alpha beta versioning + +## 1.0.3-beta.1 (2020-08-27) +- Test new alpha beta versioning + +## 1.0.2-preview.17 (2020-07-24) +- Test release pipeline + +## 1.0.2-preview.15 (2020-06-29) +- Test release pipeline + +## 1.0.2-preview.14 (2020-06-02) +- Test release pipeline + +## 1.0.2-preview.13 (2020-03-23) +- Test release pipeline + +## 1.0.2-preview.12 (2020-03-23) +- Test release pipeline + +## 1.0.2-preview.11 (2020-03-23) +- Test release pipeline + +## 1.0.2-preview.10 (2020-03-23) +- Test release pipeline + +## 1.0.2-preview.9 (2020-03-17) +- Test release pipeline + +## 1.0.2-preview.8 (2020-03-10) +- Testing out release pipeline + +## 1.0.2-preview.7 (2020-03-06) +- Testing out release pipeline + +## 1.0.2-preview.6 (2020-02-24) +### Added +- Testing Changelog added section +- Testing Links [Project Site](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/README.md) +- Test `Highlighted Code` + +## 1.0.2-preview.5 (2020-02-24) +### Added +- Testing Changelog added section +- Testing Links [Project Site](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/README.md) +- Test `Highlighted Code` + +## 1.0.2-preview.4 (2019-12-17) +- Version Bump + +## 1.0.2-preview.3 (2019-12-17) +- Started changelog to capture release notes. \ No newline at end of file diff --git a/sdk/template/Azure.Template/README.md b/sdk/template/Azure.Template/README.md index 39ed2e0e8bc99..e31e2d7bd8702 100644 --- a/sdk/template/Azure.Template/README.md +++ b/sdk/template/Azure.Template/README.md @@ -5,7 +5,7 @@ Use the guidelines in each section of this template to ensure consistency and re **Title**: The H1 of your README should be in the format: `# [Product Name] client library for [Language]` * All headings, including the H1, should use **sentence-style capitalization**. Refer to the [Microsoft Style Guide][style-guide-msft] and [Microsoft Cloud Style Guide][style-guide-cloud] for more information. -* Example: `# Azure Batch client library for Python` +* Example: `# Azure Batch client library for .NET` # Azure Template client library for .NET @@ -16,7 +16,7 @@ Use the guidelines in each section of this template to ensure consistency and re * Next, add a **bulleted list** of the **most common tasks** supported by the package or library, prefaced with "Use the client library for [Product Name] to:". Then, provide code snippets for these tasks in the [Examples](#examples) section later in the document. Keep the task list short but include those tasks most developers need to perform with your package. * Include this single line of links targeting your product's content at the bottom of the introduction, making any adjustments as necessary (for example, NuGet instead of PyPi): - [Source code](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/batch/azure-batch) | [Package (PyPi)](https://pypi.org/project/azure-batch/) | [API reference documentation](https://docs.microsoft.com/python/api/overview/azure/batch?view=azure-python) | [Product documentation](https://docs.microsoft.com/azure/batch/) + [Source code](https://github.com/Azure/azure-sdk-for-net/tree/bb0fbccfc33dd27d1ec6f0870022824d47181e61/sdk/template-dpg/Azure.ServiceTemplate.Template/src) | [Package (NuGet)](https://www.nuget.org/packages/Azure.AI.AnomalyDetector) | [API reference documentation](https://azure.github.io/azure-sdk-for-net/anomalydetector.html) | [Product documentation](https://docs.microsoft.com/azure/cognitive-services/anomaly-detector/) > TIP: Your README should be as **brief** as possible but **no more brief** than necessary to get a developer new to Azure, the service, or the package up and running quickly. Keep it brief, but include everything a developer needs to make their first API call successfully. @@ -26,13 +26,19 @@ This section should include everything a developer needs to do to install and cr ### Install the package -First, provide instruction for obtaining and installing the package or library. This section might include only a single line of code, like `pip install package-name`, but should enable a developer to successfully install the package from NuGet, pip, npm, Maven, or even cloning a GitHub repository. +First, provide instruction for obtaining and installing the package or library. This section might include only a single line of code, like `dotnet add package package-name`, but should enable a developer to successfully install the package from NuGet, npm, or even cloning a GitHub repository. + +Install the client library for .NET with [NuGet](https://www.nuget.org/ ): + +```dotnetcli +dotnet add package Azure.Template --prerelease +``` ### Prerequisites Include a section after the install command that details any requirements that must be satisfied before a developer can [authenticate](#authenticate-the-client) and test all of the snippets in the [Examples](#examples) section. For example, for Cosmos DB: -> You must have an [Azure subscription](https://azure.microsoft.com/free/dotnet/), [Cosmos DB account](https://docs.microsoft.com/azure/cosmos-db/account-overview) (SQL API), and [Python 3.6+](https://www.python.org/downloads/) to use this package. +> You must have an [Azure subscription](https://azure.microsoft.com/free/dotnet/) and [Cosmos DB account](https://docs.microsoft.com/azure/cosmos-db/account-overview) (SQL API). In order to take advantage of the C# 8.0 syntax, it is recommended that you compile using the [.NET Core SDK](https://dotnet.microsoft.com/download) 3.0 or higher with a [language version](https://docs.microsoft.com/dotnet/csharp/language-reference/configure-language-version#override-a-default) of `latest`. It is also possible to compile with the .NET Core SDK 2.1.x using a language version of `preview`. ### Authenticate the client @@ -63,23 +69,15 @@ We guarantee that all client instance methods are thread-safe and independent of ## Examples -Include code snippets and short descriptions for each task you listed in the [Introduction](#introduction) (the bulleted list). Briefly explain each operation, but include enough clarity to explain complex or otherwise tricky operations. - -If possible, use the same example snippets that your in-code documentation uses. For example, use the snippets in your `examples.py` that Sphinx ingests via its [literalinclude](https://www.sphinx-doc.org/en/1.5/markup/code.html?highlight=code%20examples#includes) directive. The `examples.py` file containing the snippets should reside alongside your package's code, and should be tested in an automated fashion. - -Each example in the *Examples* section starts with an H3 that describes the example. At the top of this section, just under the *Examples* H2, add a bulleted list linking to each example H3. Each example should deep-link to the types and/or members used in the example. - -* [Create the thing](#create-the-thing) -* [Get the thing](#get-the-thing) -* [List the things](#list-the-things) +You can familiarize yourself with different APIs using [Samples](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/template/Azure.Template/samples). -### Get a secret +### Get secret The `GetSecret` method retrieves a secret from the service. ```C# Snippet:Azure_Template_GetSecret -endpoint = "https://myvault.vault.azure.net"; -TemplateClient client = new TemplateClient(endpoint, new DefaultAzureCredential()); +string endpoint = "https://myvault.vault.azure.net"; +var client = new TemplateClient(endpoint, new DefaultAzureCredential()); SecretBundle secret = client.GetSecretValue("TestSecret"); diff --git a/sdk/template/Azure.Template/samples/Sample1.HelloWorldAsync.md b/sdk/template/Azure.Template/samples/Sample1.HelloWorldAsync.md index e537f0215fa0d..f09dbf761d1dd 100644 --- a/sdk/template/Azure.Template/samples/Sample1.HelloWorldAsync.md +++ b/sdk/template/Azure.Template/samples/Sample1.HelloWorldAsync.md @@ -13,8 +13,8 @@ using Azure.Template.Models; You can also get secrets asynchronously: ```C# Snippet:Azure_Template_GetSecretAsync -endpoint = "https://myvault.vault.azure.net"; -TemplateClient client = new TemplateClient(endpoint, new DefaultAzureCredential()); +string endpoint = "https://myvault.vault.azure.net"; +var client = new TemplateClient(endpoint, new DefaultAzureCredential()); SecretBundle secret = await client.GetSecretValueAsync("TestSecret"); diff --git a/sdk/template/Azure.Template/samples/Sample1_HelloWorld.md b/sdk/template/Azure.Template/samples/Sample1_HelloWorld.md index 2480d51550208..bc9f9ba641967 100644 --- a/sdk/template/Azure.Template/samples/Sample1_HelloWorld.md +++ b/sdk/template/Azure.Template/samples/Sample1_HelloWorld.md @@ -13,8 +13,8 @@ using Azure.Template.Models; You can create a client and get secrets synchronously: ```C# Snippet:Azure_Template_GetSecret -endpoint = "https://myvault.vault.azure.net"; -TemplateClient client = new TemplateClient(endpoint, new DefaultAzureCredential()); +string endpoint = "https://myvault.vault.azure.net"; +var client = new TemplateClient(endpoint, new DefaultAzureCredential()); SecretBundle secret = client.GetSecretValue("TestSecret"); diff --git a/sdk/template/Azure.Template/src/Azure.Template.csproj b/sdk/template/Azure.Template/src/Azure.Template.csproj index 3bbeba05588f5..3862cda4a07b0 100644 --- a/sdk/template/Azure.Template/src/Azure.Template.csproj +++ b/sdk/template/Azure.Template/src/Azure.Template.csproj @@ -2,7 +2,7 @@ This is the Template client library for developing .NET applications with rich experience. Azure SDK Code Generation Template for Azure Data Plane - 1.0.0-beta.1 + 1.0.3-beta.20 Azure Template $(RequiredTargetFrameworks) true diff --git a/sdk/template/Azure.Template/tests/Azure.Template.Tests.csproj b/sdk/template/Azure.Template/tests/Azure.Template.Tests.csproj index fd78ef0995fcc..8f392bf811633 100644 --- a/sdk/template/Azure.Template/tests/Azure.Template.Tests.csproj +++ b/sdk/template/Azure.Template/tests/Azure.Template.Tests.csproj @@ -23,10 +23,6 @@ - - - - diff --git a/sdk/template/Azure.Template/tests/Samples/Sample1_HelloWorld.cs b/sdk/template/Azure.Template/tests/Samples/Sample1_HelloWorld.cs index ddadda367ceb5..0375a7ca841c9 100644 --- a/sdk/template/Azure.Template/tests/Samples/Sample1_HelloWorld.cs +++ b/sdk/template/Azure.Template/tests/Samples/Sample1_HelloWorld.cs @@ -18,13 +18,12 @@ public partial class TemplateSamples: SamplesBase [SyncOnly] public void GettingASecret() { - string endpoint = TestEnvironment.KeyVaultUri; - #region Snippet:Azure_Template_GetSecret -#if SNIPPET - endpoint = "https://myvault.vault.azure.net"; + string endpoint = "https://myvault.vault.azure.net"; +#if !SNIPPET + endpoint = TestEnvironment.KeyVaultUri; #endif - TemplateClient client = new TemplateClient(endpoint, new DefaultAzureCredential()); + var client = new TemplateClient(endpoint, new DefaultAzureCredential()); SecretBundle secret = client.GetSecretValue("TestSecret"); diff --git a/sdk/template/Azure.Template/tests/Samples/Sample1_HelloWorldAsync.cs b/sdk/template/Azure.Template/tests/Samples/Sample1_HelloWorldAsync.cs index 2bbb4eeab3c2e..b0f10fb15c940 100644 --- a/sdk/template/Azure.Template/tests/Samples/Sample1_HelloWorldAsync.cs +++ b/sdk/template/Azure.Template/tests/Samples/Sample1_HelloWorldAsync.cs @@ -16,13 +16,12 @@ public partial class TemplateSamples: SamplesBase [AsyncOnly] public async Task GettingASecretAsync() { - string endpoint = TestEnvironment.KeyVaultUri; - #region Snippet:Azure_Template_GetSecretAsync -#if SNIPPET - endpoint = "https://myvault.vault.azure.net"; + string endpoint = "https://myvault.vault.azure.net"; +#if !SNIPPET + endpoint = TestEnvironment.KeyVaultUri; #endif - TemplateClient client = new TemplateClient(endpoint, new DefaultAzureCredential()); + var client = new TemplateClient(endpoint, new DefaultAzureCredential()); SecretBundle secret = await client.GetSecretValueAsync("TestSecret");