diff --git a/doc/DataPlaneCodeGeneration/Autorest_DataPlane_Quickstart.md b/doc/DataPlaneCodeGeneration/Autorest_DataPlane_Quickstart.md index a1b09ce38bb5..02675d7353a2 100644 --- a/doc/DataPlaneCodeGeneration/Autorest_DataPlane_Quickstart.md +++ b/doc/DataPlaneCodeGeneration/Autorest_DataPlane_Quickstart.md @@ -10,7 +10,7 @@ This tutorial has following sections: - [Azure SDK Code Generation Quickstart Tutorial (Data Plane)](#azure-sdk-code-generation-quickstart-tutorial-data-plane) - [Prerequisites](#prerequisites) - - [Setup your repo](#setup-your-repo) + - [Setup your repository](#setup-your-repository) - [Create starter package](#create-starter-package) - [Add package ship requirements](#add-package-ship-requirements) - [Tests](#tests) @@ -31,7 +31,7 @@ This tutorial has following sections: ## Prerequisites -- Install VS 2022 (Community or higher) and make sure you have the [latest updates](https://www.visualstudio.com/). +- Install Visual Studio 2022 (Community or higher) and make sure you have the [latest updates](https://www.visualstudio.com/). - Need at least .NET Framework 4.6.1 and 4.7 development tools - Install the **.NET Core cross-platform development** workloads in VisualStudio - Install **.NET 6.0 SDK** for your specific platform. (or a higher version) @@ -150,7 +150,7 @@ Adding convenience APIs is not required for Azure SDK data plane generated libra You can add convienice APIs by adding a customization layer on top of the generated code. Please see the [autorest.csharp README](https://github.com/Azure/autorest.csharp#setup) for the details of adding the customization layer. This is the preferred method for adding convenience APIs to your generated client. -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. Details for various transforms can be found in [Customizing the generated code](https://github.com/Azure/autorest.csharp#customizing-the-generated-code). +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. [autorest.md](https://github.com/Azure/azure-sdk-for-net/blob/main/doc/sampleFiles/autorest-with-directive.md) shows and example of how this can be accomplished. Details for various transforms can be found in [Customizing the generated code](https://github.com/Azure/autorest.csharp#customizing-the-generated-code). 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). diff --git a/doc/DataPlaneCodeGeneration/AzureSDKCodeGeneration_DataPlane_Quickstart.md b/doc/DataPlaneCodeGeneration/AzureSDKCodeGeneration_DataPlane_Quickstart.md index a71f012412dd..8766c6806d39 100644 --- a/doc/DataPlaneCodeGeneration/AzureSDKCodeGeneration_DataPlane_Quickstart.md +++ b/doc/DataPlaneCodeGeneration/AzureSDKCodeGeneration_DataPlane_Quickstart.md @@ -10,14 +10,11 @@ This tutorial has following sections: - [Azure SDK Code Generation Quickstart Tutorial (Data Plane)](#azure-sdk-code-generation-quickstart-tutorial-data-plane) - [Prerequisites](#prerequisites) - - [Setup your repo](#setup-your-repo) + - [Setup your repository](#setup-your-repository) - [Create starter package](#create-starter-package) - [Use Cadl as Input](#use-cadl-as-input) - [Create Cadl project](#create-cadl-project) - - [Create a sdk project folder](#create-a-sdk-project-folder) - - [Generate the library source code](#generate-the-library-source-code) - - [Build the library project](#build-the-library-project) - - [Export the library's public API](#export-the-librarys-public-api) + - [Create sdk starter package](#create-sdk-starter-package) - [Use swagger as Input](#use-swagger-as-input) - [Add package ship requirements](#add-package-ship-requirements) - [Tests](#tests) @@ -32,16 +29,15 @@ This tutorial has following sections: ## Prerequisites -- Install VS 2020 (Community or higher) and make sure you have the [latest updates](https://www.visualstudio.com/). +- Install Visual Studio 2022 (Community or higher) and make sure you have the [latest updates](https://www.visualstudio.com/). - Need at least .NET Framework 4.6.1 and 4.7 development tools - - Install the **.NET Core cross-platform development** workloads in VisualStudio + - Install the **.NET Core cross-platform development** workloads in Visual Studio - Install **.NET 6.0 SDK** for your specific platform. (or a higher version) -- Install **.NET core 3.1** for your specific platform. - Install the latest version of [git](https://git-scm.com/downloads) - Install [PowerShell](https://docs.microsoft.com/powershell/scripting/install/installing-powershell), version 7 or higher. - Install [NodeJS](https://nodejs.org/) (16.x.x or above). -## Setup your repo +## Setup your repository - Fork and clone an [azure-sdk-for-net](https://github.com/Azure/azure-sdk-for-net) repo. Follow the instructions in the [.NET CONTRIBUTING.md](https://github.com/Azure/azure-sdk-for-net/issues/12903) to fork and clone the `azure-sdk-for-net` repo. - Create a branch to work in. @@ -123,60 +119,50 @@ emitters: - `clear-output-folder` indicate if you want to clear up the output folder. -#### Create a sdk project folder +#### Create sdk starter package -You can manually create the project folder. Please refer to [Azure.Template](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template) as an example. +We will use dotnet project template [Azure.Template](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template) to automatically create the project. -**Note**: +You can run `eng\scripts\automation\Invoke-CadlDataPlaneGenerateSDKPackage.ps1` to generate the starting SDK client library package directly as following: -- Please refer to [sdk-directory-layout](https://github.com/Azure/azure-sdk/blob/main/docs/policies/repostructure.md#sdk-directory-layout) for detail information. -- remove `autorest.md` from sdk\\\src -- add `cadl-location.yaml` under sdk\\\src - - Modify `cadl-location.yaml` to add some project meta data if needed, Otherwise just add an empty file. - - e.g. if you want specify cadl project folder in azure-rest-api-spec repo, you can define (directory, commit, repo) to specify the cadl project. - - ```yml - directory: specification/cognitiveservices/data-plane/AnomalyDetector/stable/v1.1/cadl - commit: 8804b10cf61267b81e06ebccbd1dd46677a54425 - repo: Azure/azure-rest-api-specs - cleanup: false - ``` - -#### Generate the library source code - -Generate the library source code files to the directory `/sdk///src/Generated` +```powershell +eng/scripts/automation/Invoke-CadlDataPlaneGenerateSDKPackage.ps1 -service -namespace Azure.. -sdkPath -cadlRelativeFolder [-commit ] [-repo ] [-specRoot ] [-additionalSubDirectories ] +``` - Enter `Cadl Project Folder`, run +e.g. +Use git url - ```shell - npm install - npx cadl compile --emit @azure-tools/cadl-csharp --output-path - ``` - - e.g. +```powershell +pwsh /home/azure-sdk-for-net/eng/scripts/automation/Invoke-CadlDataPlaneGenerateSDKPackage.ps1 -service anomalydetector -namespace Azure.AI.AnomalyDetector -sdkPath /home/azure-sdk-for-net -cadlRelativeFolder specification/cognitiveservices/AnomalyDetector -commit ac8e06a2ed0fc1c54663c98f12c8a073f8026b90 -repo Azure/azure-rest-api-specs +``` +or +Use local Cadl project - ```shell - npx cadl compile --emit @azure-tools/cadl-csharp --output-path /home/azure-sdk-for-net/sdk/deviceupdate/Azure.IoT.DeviceUpdate/src main.cadl - ``` +```powershell +pwsh /home/azure-sdk-for-net/eng/scripts/automation/Invoke-CadlDataPlaneGenerateSDKPackage.ps1 -service anomalydetector -namespace Azure.AI.AnomalyDetector -sdkPath /home/azure-sdk-for-net -cadlRelativeFolder specification/cognitiveservices/AnomalyDetector -specRoot /home/azure-rest-api-specs +``` **Note**: -- `` - Should be the entrypoint cadl file of the cadl project. e.g. When you define `client.cadl` to customize the client, the `client.cadl` will be the entrypoint cadl file, and you should specify the path to the `client.cadl`. - -#### Build the library project +- `-service` takes Azure client service directory name. ie. purview. It equals to the name of the directory in the specification folder of the azure-rest-api-specs repo that contains the REST API definition file. +- For `- namespace`, please use one of the pre-approved namespace groups on the [.NET Azure SDK Guidelines Approved Namespaces list](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-namespaces-approved-list). This value will also provide the name for the shipped package, and should be of the form `Azure..`. +- `-sdkPath` takes the address of the root directory of sdk repo. e.g. /home/azure-sdk-for-net +- `cadlRelativeFolder` takes the relative path of the cadl project folder in spec repo. e.g. specification/cognitiveservices/AnomalyDetector +- `-additionalSubDirectories` takes the relative paths of the additional directories needed by the cadl project, such as share library folder, separated by semicolon if there is more than one folder. +- `-commit` takes the commit of the github hash, e.g. ac8e06a2ed0fc1c54663c98f12c8a073f8026b90 +- `-repo` takes the `/` of the spec repo. e.g. Azure/azure-rest-api-specs +- `-specRoot` takes the file system path of the spec repo. e.g. /home/azure-rest-api-specs +- You need to provide one of (`-commit`, `-repo`) pair to refer to an URL path of the cadl project and `-specRoot` parameters. If you provide both, `-specRoot` will be ignored. -Run `dotnet build` under project folder ``/sdk//` to build the project to create the starter package binary. +When you run the `eng\scripts\automation\Invoke-CadlDataPlaneGenerateSDKPackage.ps1` script, it will: -#### Export the library's public API +- Create a project folder, install template files from `sdk/template/Azure.Template`, and create `.csproj` and `.sln` files for your new library. -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 `/sdk///api` 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). + 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). -e.g. Running the script for a project in `sdk\deviceupdate` would look like this: +- Generate the library source code files to the directory `/sdk///src/Generated` +- Build the library project to create the starter package binary. +- Export the library's public API to the directory `/sdk///api` -```powershell -eng\scripts\Export-API.ps1 deviceupdate -``` ### Use swagger as Input @@ -237,7 +223,8 @@ Adding convenience APIs is not required for Azure SDK data plane generated libra You can add convienice APIs by adding a customization layer on top of the generated code. Please see the [autorest.csharp README](https://github.com/Azure/autorest.csharp#setup) for the details of adding the customization layer. This is the preferred method for adding convenience APIs to your generated client. -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. + +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. [autorest.md](https://github.com/Azure/azure-sdk-for-net/blob/main/doc/sampleFiles/autorest-with-directive.md) shows and example of how this can be accomplished. Details for various transforms can be found in [Customizing the generated code](https://github.com/Azure/autorest.csharp#customizing-the-generated-code). 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). diff --git a/doc/sampleFiles/autorest-with-directive.md b/doc/sampleFiles/autorest-with-directive.md new file mode 100644 index 000000000000..bf0bb7768aa7 --- /dev/null +++ b/doc/sampleFiles/autorest-with-directive.md @@ -0,0 +1,54 @@ +# Azure.IoT.DeviceUpdate + +Run `generate.ps1` or `dotnet msbuild /t:GenerateCode` to generate code. + +### AutoRest Configuration +> see https://aka.ms/autorest + +``` yaml +public-clients: true +title: DeviceUpdate + +input-file: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d7c9be23749467be1aea18f02ba2f4948a39db6a/specification/deviceupdate/data-plane/Microsoft.DeviceUpdate/stable/2022-10-01/deviceupdate.json + +namespace: Azure.IoT.DeviceUpdate +security: AADToken +security-scopes: https://api.adu.microsoft.com/.default +# disable renaming pagination parameter "top" since the SDK is GAed +disable-pagination-top-renaming: true +``` + +### Add StartImportUpdate method with no final response body +```yaml +directive: +- from: swagger-document + where: $.paths + transform: > + const o = $["/deviceUpdate/{instanceId}/updates:import"]; + const r = Object.assign({}, o.post.responses); + delete r["200"]; + $["/deviceUpdate/{instanceId}/updates:import?"] = { // Add ? to avoid stomping + post: { + tags: o.post.tags.slice(), + operationId: "DeviceUpdate_StartImportUpdate", + "x-ms-long-running-operation": true, + description: o.post.description, + parameters: o.post.parameters.slice(), + responses: r, + } + }; + return $; +``` + +### Remove duplicate ImportUpdate LRO for now +This can be deleted when https://github.com/Azure/autorest.csharp/issues/2672 is +fixed and it'll generate a correct `ImportUpdate` method next to the workaround +`StartImportUpdate` method. +```yaml +directive: +- from: swagger-document + where: $.paths + transform: > + delete $["/deviceUpdate/{instanceId}/updates:import"]; + return $; +``` \ No newline at end of file diff --git a/eng/scripts/Cadl-Project-Generate.ps1 b/eng/scripts/Cadl-Project-Generate.ps1 index 550540a559a6..a5dd23271053 100644 --- a/eng/scripts/Cadl-Project-Generate.ps1 +++ b/eng/scripts/Cadl-Project-Generate.ps1 @@ -42,20 +42,27 @@ $npmWorkingDir = Resolve-Path $tempFolder/$innerFolder $mainCadlFile = If (Test-Path "$npmWorkingDir/client.cadl") { Resolve-Path "$npmWorkingDir/client.cadl" } Else { Resolve-Path "$npmWorkingDir/main.cadl"} $resolvedProjectDirectory = Resolve-Path "$ProjectDirectory/src" +$HasEmitterOutputDir = $false; if (Test-Path "$npmWorkingDir/cadl-project.yaml") { $cadlProjectYaml = Get-Content -Path "$npmWorkingDir/cadl-project.yaml" -Raw $yml = ConvertFrom-YAML $cadlProjectYaml - if ( $yml["emitters"]["@azure-tools/cadl-csharp"]["sdk-folder"]) { - $yml["emitters"]["@azure-tools/cadl-csharp"]["sdk-folder"] = "" + if ($yml -And $yml["options"] -And $yml["options"]["@azure-tools/cadl-csharp"] -And $yml["options"]["@azure-tools/cadl-csharp"]["emitter-output-dir"]) { + $HasEmitterOutputDir = $true } - (ConvertTo-Yaml $yml) | Out-File "$npmWorkingDir/cadl-project.yaml" } try { Push-Location $npmWorkingDir NpmInstallForProject $npmWorkingDir - Write-Host("npx cadl compile $mainCadlFile --emit `"`@azure-tools/cadl-csharp`" --output-path `"$resolvedProjectDirectory`"") - npx cadl compile $mainCadlFile --emit "@azure-tools/cadl-csharp" --output-path "$resolvedProjectDirectory" + if ($HasEmitterOutputDir) { + $csharpSdkFolder = (Join-Path $ProjectDirectory ".." ".." "..") + $csharpSdkFolder = Resolve-Path $csharpSdkFolder + Write-Host("npx cadl compile $mainCadlFile --emit `"`@azure-tools/cadl-csharp`" --arg `"csharp-sdk-folder=$csharpSdkFolder`"") + npx cadl compile $mainCadlFile --emit "@azure-tools/cadl-csharp" --arg "csharp-sdk-folder=$csharpSdkFolder" + } else { + Write-Host("npx cadl compile $mainCadlFile --emit `"`@azure-tools/cadl-csharp`" --option `"@azure-tools/cadl-csharp.emitter-output-dir=$resolvedProjectDirectory`"") + npx cadl compile $mainCadlFile --emit "@azure-tools/cadl-csharp" --option @azure-tools/cadl-csharp.emitter-output-dir=$resolvedProjectDirectory + } } finally { Pop-Location diff --git a/eng/scripts/Invoke-GenerateAndBuildV2.ps1 b/eng/scripts/Invoke-GenerateAndBuildV2.ps1 index 56938fa441e3..68fceeed806a 100644 --- a/eng/scripts/Invoke-GenerateAndBuildV2.ps1 +++ b/eng/scripts/Invoke-GenerateAndBuildV2.ps1 @@ -119,16 +119,20 @@ if ($relatedCadlProjectFolder) { Install-ModuleIfNotInstalled "powershell-yaml" "0.4.1" | Import-Module $yml = ConvertFrom-YAML $cadlProjectYaml - $sdkFolder = $yml["emitters"]["@azure-tools/cadl-csharp"]["sdk-folder"] - $projectFolder = (Join-Path $sdkPath $sdkFolder) - # $projectFolder = $projectFolder -replace "\\", "/" - if ($projectFolder) { - $directories = $projectFolder -split "/|\\" - $count = $directories.Count - $projectFolder = $directories[0 .. ($count-2)] -join "/" - $service = $directories[-3]; - $namespace = $directories[-2]; + $service = "" + $namespace = "" + if ($yml) { + if ($yml["parameters"] -And $yml["parameters"]["service-directory-name"]) { + $service = $yml["parameters"]["service-directory-name"]["default"]; + } + if ($yml["options"] -And $yml["options"]["@azure-tools/cadl-csharp"] -And $yml["options"]["@azure-tools/cadl-csharp"]["namespace"]) { + $namespace = $yml["options"]["@azure-tools/cadl-csharp"]["namespace"] + } } + if (!$service || !$namespace) { + throw "Not provide service name or namespace." + } + $projectFolder = (Join-Path $sdkPath "sdk" $service $namespace) New-CADLPackageFolder ` -service $service ` -namespace $namespace ` diff --git a/eng/scripts/automation/GenerateAndBuildLib.ps1 b/eng/scripts/automation/GenerateAndBuildLib.ps1 index 42cbc97fe86b..983a8d77a0f6 100644 --- a/eng/scripts/automation/GenerateAndBuildLib.ps1 +++ b/eng/scripts/automation/GenerateAndBuildLib.ps1 @@ -366,15 +366,18 @@ function CreateOrUpdateCadlConfigFile() { [string]$directory, [string]$commit = "", [string]$repo = "", - [string]$specRoot = "" + [string]$specRoot = "", + [string]$additionalSubDirectories="" #additional directories needed, separated by semicolon if more than one + ) if (!(Test-Path -Path $cadlConfigurationFile)) { New-Item -Path $cadlConfigurationFile } + Install-ModuleIfNotInstalled "powershell-yaml" "0.4.1" | Import-Module $configuration = Get-Content -Path $cadlConfigurationFile -Raw | ConvertFrom-Yaml if ( !$configuration) { - $configuration = [System.Collections.Generic.Dictionary[string,string]](New-Object 'System.Collections.Generic.Dictionary[string,string]') + $configuration = @{} } $configuration["directory"] = $directory if ($commit) { @@ -394,14 +397,14 @@ function CreateOrUpdateCadlConfigFile() { $configuration.Remove("spec-root-dir") } - $fileContent = "" - foreach ( $key in $configuration.keys) { - if ($configuration[$key]) { - $fileContent += ( $key + ": " + $configuration[$key] + [Environment]::NewLine) - } + if ($additionalSubDirectories) { + $directoryArray = [string[]]$additionalSubDirectories.Split(";") + $configuration["additionalDirectories"] = [Collections.Generic.List[string]]$directoryArray; + } else { + $configuration.Remove("additionalDirectories") } - $fileContent | Out-File $cadlConfigurationFile + $configuration |ConvertTo-Yaml | Out-File $cadlConfigurationFile } function New-CADLPackageFolder() { @@ -413,6 +416,7 @@ function New-CADLPackageFolder() { [string]$commit = "", [string]$repo = "", [string]$specRoot = "", + [string]$additionalSubDirectories="", #additional directories needed, separated by semicolon if more than one [string]$outputJsonFile = "$PWD/output.json" ) $serviceFolder = (Join-Path $sdkPath "sdk" $service) @@ -435,7 +439,8 @@ function New-CADLPackageFolder() { -directory $relatedCadlProjectFolder ` -commit $commit ` -repo $repo ` - -specRoot $specRoot + -specRoot $specRoot ` + -additionalSubDirectories $additionalSubDirectories Update-CIYmlFile -ciFilePath $ciymlFilePath -artifact $namespace } else { @@ -484,7 +489,8 @@ function New-CADLPackageFolder() { -directory $relatedCadlProjectFolder ` -commit $commit ` -repo $repo ` - -specRoot $specRoot + -specRoot $specRoot ` + -additionalSubDirectories $additionalSubDirectories dotnet sln remove src/$namespace.csproj dotnet sln add src/$namespace.csproj diff --git a/eng/scripts/automation/Invoke-CadlDataPlaneGenerateSDKPackage.ps1 b/eng/scripts/automation/Invoke-CadlDataPlaneGenerateSDKPackage.ps1 new file mode 100644 index 000000000000..10cb8e7785c6 --- /dev/null +++ b/eng/scripts/automation/Invoke-CadlDataPlaneGenerateSDKPackage.ps1 @@ -0,0 +1,100 @@ +#Requires -Version 7.0 +<# +.SYNOPSIS +script for creating a getting started project in a branch of `azure-sdk-for-net` repo. + +.PARAMETER service +The Azure client service directory name. ie. purview. It is the same as the name of the directory in the specification folder of the azure-rest-api-specs repo that contains the REST API definition file. + +.PARAMETER namespace +The SDK package namespace. This value will also provide the name for the shipped package, and should be of the form `Azure..`. + +.PARAMETER sdkPath +The address of the root directory of sdk repo. e.g. `/home/azure-sdk-for-net` + +.PARAMETER cadlRelativeFolder +The relative path of the cadl project folder in spec repo. e.g. `specification/cognitiveservices/AnomalyDetector` + + .PARAMETER specRoot +The file system path of the spec repo. e.g. `/home/azure-rest-api-specs` + + .PARAMETER repo +The `/` of the spec repo. e.g. `Azure/azure-rest-api-specs` + +.PARAMETER commit +The commit of the github hash, e.g. ac8e06a2ed0fc1c54663c98f12c8a073f8026b90 + +.PARAMETER additionalSubDirectories +The relative paths of the additional directories needed by the cadl project, such as share library folder, separated by semicolon if there is more than one folder. + +.EXAMPLE +Run script with default parameters. + +Invoke-CadlDataPlaneGenerateSDKPackage.ps1 -service -namespace Azure.. -sdkPath -cadlRelativeFolder [-commit ] [-repo ] [-specRoot ] [-additionalSubDirectories ] + +e.g. + +Use git url + +Invoke-CadlDataPlaneGenerateSDKPackage.ps1 -service anomalydetector -namespace Azure.AI.AnomalyDetector -sdkPath /home/azure-sdk-for-net -cadlRelativeFolder specification/cognitiveservices/AnomalyDetector -commit ac8e06a2ed0fc1c54663c98f12c8a073f8026b90 -repo Azure/azure-rest-api-specs + +or +Use local Cadl project + +Invoke-CadlDataPlaneGenerateSDKPackage.ps1 -service anomalydetector -namespace Azure.AI.AnomalyDetector -sdkPath /home/azure-sdk-for-net -cadlRelativeFolder specification/cognitiveservices/AnomalyDetector -specRoot /home/azure-rest-api-specs + +#> +param ( + [string]$service, + [string]$namespace, + [string]$sdkPath, + [string]$cadlRelativeFolder, + [string]$specRoot = "", + [string]$repo="", + [string]$commit="", + [string]$additionalSubDirectories="" #additional directories needed, separated by semicolon if more than one +) +. (Join-Path $PSScriptRoot GenerateAndBuildLib.ps1) +$sdkPath = Resolve-Path $sdkPath +# Generate dataplane library +$outputJsonFile = "newpackageoutput.json" +New-CADLPackageFolder ` + -service $service ` + -namespace $namespace ` + -sdkPath $sdkPath ` + -relatedCadlProjectFolder $cadlRelativeFolder ` + -specRoot $specRoot ` + -commit $commit ` + -repo $repo ` + -additionalSubDirectories $additionalSubDirectories ` + -outputJsonFile $outputJsonFile + +if ( $LASTEXITCODE ) { + Write-Error "Failed to create sdk project folder. exit code: $LASTEXITCODE" + exit $LASTEXITCODE +} +$outputJson = Get-Content $outputJsonFile | Out-String | ConvertFrom-Json +$projectFolder = $outputJson.projectFolder +$projectFolder = $projectFolder -replace "\\", "/" + +Write-Host "projectFolder:$projectFolder" +Remove-Item $outputJsonFile +# Generate Code +$srcPath = Join-Path $projectFolder 'src' +dotnet build /t:GenerateCode $srcPath +if ($LASTEXITCODE) { + Write-Error "Failed to generate sdk." + exit $LASTEXITCODE +} +# Build +dotnet build $projectFolder +if ($LASTEXITCODE) { + Write-Error "Failed to build sdk. exit code: $LASTEXITCODE" + exit $LASTEXITCODE +} +# Generate APIs +$repoRoot = (Join-Path $PSScriptRoot .. .. ..) +Push-Location $repoRoot +pwsh eng/scripts/Export-API.ps1 $service +Pop-Location +exit 0 \ No newline at end of file diff --git a/eng/scripts/automation/Invoke-GenerateAndBuild.ps1 b/eng/scripts/automation/Invoke-GenerateAndBuild.ps1 index 11a099ec6a31..53b601c7f05f 100644 --- a/eng/scripts/automation/Invoke-GenerateAndBuild.ps1 +++ b/eng/scripts/automation/Invoke-GenerateAndBuild.ps1 @@ -73,16 +73,20 @@ if ($relatedCadlProjectFolder) { Install-ModuleIfNotInstalled "powershell-yaml" "0.4.1" | Import-Module $yml = ConvertFrom-YAML $cadlProjectYaml - $sdkFolder = $yml["emitters"]["@azure-tools/cadl-csharp"]["sdk-folder"] - $projectFolder = (Join-Path $sdkPath $sdkFolder) - # $projectFolder = $projectFolder -replace "\\", "/" - if ($projectFolder) { - $directories = $projectFolder -split "/|\\" - $count = $directories.Count - $projectFolder = $directories[0 .. ($count-2)] -join "/" - $service = $directories[-3]; - $namespace = $directories[-2]; + $service = "" + $namespace = "" + if ($yml) { + if ($yml["parameters"] -And $yml["parameters"]["service-directory-name"]) { + $service = $yml["parameters"]["service-directory-name"]["default"]; + } + if ($yml["options"] -And $yml["options"]["@azure-tools/cadl-csharp"] -And $yml["options"]["@azure-tools/cadl-csharp"]["namespace"]) { + $namespace = $yml["options"]["@azure-tools/cadl-csharp"]["namespace"] + } } + if (!$service || !$namespace) { + throw "Not provide service name or namespace." + } + $projectFolder = (Join-Path $sdkPath "sdk" $service $namespace) New-CADLPackageFolder ` -service $service ` -namespace $namespace ` diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/Azure.Contoso.Widgetmanager.sln b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/Azure.Contoso.Widgetmanager.sln new file mode 100644 index 000000000000..46f0d9340ab1 --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/Azure.Contoso.Widgetmanager.sln @@ -0,0 +1,69 @@ + +Microsoft Visual Studio Solution File, Format Version 12.00 +# Visual Studio Version 16 +VisualStudioVersion = 16.0.29709.97 +MinimumVisualStudioVersion = 10.0.40219.1 +Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Azure.Core.TestFramework", "..\..\core\Azure.Core.TestFramework\src\Azure.Core.TestFramework.csproj", "{ECC730C1-4AEA-420C-916A-66B19B79E4DC}" +EndProject +Project("{3BB3D4CD-B76A-4C30-B048-697FBA7691BE}") = "Azure.Contoso.Widgetmanager.Perf", "perf\Azure.Contoso.Widgetmanager.Perf.csproj", "{30C5FF85-655A-49FC-A324-16438130FF3F}" +EndProject +Project("{3BB3D4CD-B76A-4C30-B048-697FBA7691BE}") = "Azure.Contoso.Widgetmanager.Stress", "stress\Azure.Contoso.Widgetmanager.Stress.csproj", "{47E3BC66-5C4F-47CD-A37B-A973E54BCBA9}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Azure.Contoso.Widgetmanager", "src\Azure.Contoso.Widgetmanager.csproj", "{0910D911-A707-404A-8D94-1B4B26A0ED70}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Azure.Contoso.Widgetmanager.Tests", "tests\Azure.Contoso.Widgetmanager.Tests.csproj", "{FF1CFA2D-69A7-43AB-AC3A-F7D84A25D19C}" +EndProject +Global + GlobalSection(SolutionConfigurationPlatforms) = preSolution + Debug|Any CPU = Debug|Any CPU + Release|Any CPU = Release|Any CPU + EndGlobalSection + GlobalSection(ProjectConfigurationPlatforms) = postSolution + {B0C276D1-2930-4887-B29A-D1A33E7009A2}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {B0C276D1-2930-4887-B29A-D1A33E7009A2}.Debug|Any CPU.Build.0 = Debug|Any CPU + {B0C276D1-2930-4887-B29A-D1A33E7009A2}.Release|Any CPU.ActiveCfg = Release|Any CPU + {B0C276D1-2930-4887-B29A-D1A33E7009A2}.Release|Any CPU.Build.0 = Release|Any CPU + {8E9A77AC-792A-4432-8320-ACFD46730401}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {8E9A77AC-792A-4432-8320-ACFD46730401}.Debug|Any CPU.Build.0 = Debug|Any CPU + {8E9A77AC-792A-4432-8320-ACFD46730401}.Release|Any CPU.ActiveCfg = Release|Any CPU + {8E9A77AC-792A-4432-8320-ACFD46730401}.Release|Any CPU.Build.0 = Release|Any CPU + {ECC730C1-4AEA-420C-916A-66B19B79E4DC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {ECC730C1-4AEA-420C-916A-66B19B79E4DC}.Debug|Any CPU.Build.0 = Debug|Any CPU + {ECC730C1-4AEA-420C-916A-66B19B79E4DC}.Release|Any CPU.ActiveCfg = Release|Any CPU + {ECC730C1-4AEA-420C-916A-66B19B79E4DC}.Release|Any CPU.Build.0 = Release|Any CPU + {A4241C1F-A53D-474C-9E4E-075054407E74}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {A4241C1F-A53D-474C-9E4E-075054407E74}.Debug|Any CPU.Build.0 = Debug|Any CPU + {A4241C1F-A53D-474C-9E4E-075054407E74}.Release|Any CPU.ActiveCfg = Release|Any CPU + {A4241C1F-A53D-474C-9E4E-075054407E74}.Release|Any CPU.Build.0 = Release|Any CPU + {FA8BD3F1-8616-47B6-974C-7576CDF4717E}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {FA8BD3F1-8616-47B6-974C-7576CDF4717E}.Debug|Any CPU.Build.0 = Debug|Any CPU + {FA8BD3F1-8616-47B6-974C-7576CDF4717E}.Release|Any CPU.ActiveCfg = Release|Any CPU + {FA8BD3F1-8616-47B6-974C-7576CDF4717E}.Release|Any CPU.Build.0 = Release|Any CPU + {85677AD3-C214-42FA-AE6E-49B956CAC8DC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {85677AD3-C214-42FA-AE6E-49B956CAC8DC}.Debug|Any CPU.Build.0 = Debug|Any CPU + {85677AD3-C214-42FA-AE6E-49B956CAC8DC}.Release|Any CPU.ActiveCfg = Release|Any CPU + {85677AD3-C214-42FA-AE6E-49B956CAC8DC}.Release|Any CPU.Build.0 = Release|Any CPU + {30C5FF85-655A-49FC-A324-16438130FF3F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {30C5FF85-655A-49FC-A324-16438130FF3F}.Debug|Any CPU.Build.0 = Debug|Any CPU + {30C5FF85-655A-49FC-A324-16438130FF3F}.Release|Any CPU.ActiveCfg = Release|Any CPU + {30C5FF85-655A-49FC-A324-16438130FF3F}.Release|Any CPU.Build.0 = Release|Any CPU + {47E3BC66-5C4F-47CD-A37B-A973E54BCBA9}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {47E3BC66-5C4F-47CD-A37B-A973E54BCBA9}.Debug|Any CPU.Build.0 = Debug|Any CPU + {47E3BC66-5C4F-47CD-A37B-A973E54BCBA9}.Release|Any CPU.ActiveCfg = Release|Any CPU + {47E3BC66-5C4F-47CD-A37B-A973E54BCBA9}.Release|Any CPU.Build.0 = Release|Any CPU + {0910D911-A707-404A-8D94-1B4B26A0ED70}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {0910D911-A707-404A-8D94-1B4B26A0ED70}.Debug|Any CPU.Build.0 = Debug|Any CPU + {0910D911-A707-404A-8D94-1B4B26A0ED70}.Release|Any CPU.ActiveCfg = Release|Any CPU + {0910D911-A707-404A-8D94-1B4B26A0ED70}.Release|Any CPU.Build.0 = Release|Any CPU + {FF1CFA2D-69A7-43AB-AC3A-F7D84A25D19C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {FF1CFA2D-69A7-43AB-AC3A-F7D84A25D19C}.Debug|Any CPU.Build.0 = Debug|Any CPU + {FF1CFA2D-69A7-43AB-AC3A-F7D84A25D19C}.Release|Any CPU.ActiveCfg = Release|Any CPU + {FF1CFA2D-69A7-43AB-AC3A-F7D84A25D19C}.Release|Any CPU.Build.0 = Release|Any CPU + EndGlobalSection + GlobalSection(SolutionProperties) = preSolution + HideSolutionNode = FALSE + EndGlobalSection + GlobalSection(ExtensibilityGlobals) = postSolution + SolutionGuid = {A97F4B90-2591-4689-B1F8-5F21FE6D6CAE} + EndGlobalSection +EndGlobal diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/CHANGELOG.md b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/CHANGELOG.md new file mode 100644 index 000000000000..13dd08af78ab --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/CHANGELOG.md @@ -0,0 +1,11 @@ +# Release History + +## 1.0.0-beta.1 (Unreleased) + +### Features Added + +### Breaking Changes + +### Bugs Fixed + +### Other Changes diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/Directory.Build.props b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/Directory.Build.props new file mode 100644 index 000000000000..1a9611bd4924 --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/Directory.Build.props @@ -0,0 +1,6 @@ + + + + diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/README.md b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/README.md new file mode 100644 index 000000000000..79340bd66069 --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/README.md @@ -0,0 +1,90 @@ +# Azure Widgetmanager client library for .NET + +This section should give out brief introduction of the client library. + +* 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. + + [Source code](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/src) | [Package (NuGet)](https://www.nuget.org/packages/Azure.Contoso.Widgetmanager) | [API reference documentation](https://azure.github.io/azure-sdk-for-net) | [Product documentation](https://docs.microsoft.com/azure) + +## 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. + +Install the client library for .NET with [NuGet](https://www.nuget.org/ ): + +```dotnetcli +dotnet add package Azure.Contoso.Widgetmanager --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/) 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/contosowidgetmanager/Azure.Contoso.Widgetmanager/samples). + +### + +You can create a client and call the client's `` method. + +```C# Snippet:Azure_Contoso_Widgetmanager_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/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/README.png) \ No newline at end of file diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/api/Azure.Contoso.Widgetmanager.netstandard2.0.cs b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/api/Azure.Contoso.Widgetmanager.netstandard2.0.cs new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/perf/Azure.Contoso.Widgetmanager.Perf.csproj b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/perf/Azure.Contoso.Widgetmanager.Perf.csproj new file mode 100644 index 000000000000..4cac0d76b1bf --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/perf/Azure.Contoso.Widgetmanager.Perf.csproj @@ -0,0 +1,16 @@ + + + + Exe + + + + + + + + + + + + diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/perf/Program.cs b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/perf/Program.cs new file mode 100644 index 000000000000..78a52ddce190 --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/perf/Program.cs @@ -0,0 +1,7 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. +// Licensed under the MIT License. + +using System.Reflection; +using Azure.Test.Perf; + + await PerfProgram.Main(Assembly.GetEntryAssembly(), args); diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/perf/WidgetmanagerClientTest.cs b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/perf/WidgetmanagerClientTest.cs new file mode 100644 index 000000000000..9881475fa3f6 --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/perf/WidgetmanagerClientTest.cs @@ -0,0 +1,36 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. +// Licensed under the MIT License. + +using System; +using System.Threading; +using System.Threading.Tasks; +using Azure.Identity; +using Azure.Test.Perf; +using CommandLine; + +namespace Azure.Contoso.Widgetmanager.Perf +{ + public class WidgetmanagerClientTest : PerfTest + { + /* please refer to https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/perf/TemplateClientTest.cs to write perf test. */ + + public WidgetmanagerClientTest(WidgetmanagerClientPerfOptions options) : base(options) + { + } + public class WidgetmanagerClientPerfOptions : PerfOptions + { + } + + public override void Run(CancellationToken cancellationToken) + { + } + + public override async Task RunAsync(CancellationToken cancellationToken) + { + await Task.Run(() => + { + Console.WriteLine("exec some async operation"); + }); + } + } +} diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/samples/README.md b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/samples/README.md new file mode 100644 index 000000000000..c3ea8b4d8c42 --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/samples/README.md @@ -0,0 +1,14 @@ +--- +page_type: sample +languages: +- csharp +products: +# Including relevant stubs from https://review.docs.microsoft.com/help/contribute/metadata-taxonomies#product +- azure +name: Azure.Contoso.Widgetmanager samples for .NET +description: Samples for the Azure.Contoso.Widgetmanager client library. +--- + +# Azure.Contoso.Widgetmanager Samples + + diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/samples/Sample1_HelloWorld.md b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/samples/Sample1_HelloWorld.md new file mode 100644 index 000000000000..e17d9b7f03dc --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/samples/Sample1_HelloWorld.md @@ -0,0 +1,15 @@ +# + +To use these samples, you'll first need to set up resources. See [getting started](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/README.md#getting-started) for details. + +## + +You can create a client and call the client's `` method + +```C# Snippet:Azure_Contoso_Widgetmanager_Scenario +``` + +To see the full example source files, see: +* [HelloWorld](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/Samples/Sample1_HelloWorld.cs)) + + \ No newline at end of file diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/samples/Sample1_HelloWorldAsync.md b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/samples/Sample1_HelloWorldAsync.md new file mode 100644 index 000000000000..f132bb20b249 --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/samples/Sample1_HelloWorldAsync.md @@ -0,0 +1,15 @@ +# + +To use these samples, you'll first need to set up resources. See [getting started](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/README.md#getting-started) for details. + +## asynchronously + +You can create a client and call the client's `` method + +```C# Snippet:Azure_Contoso_Widgetmanager_ScenarioAsync +``` + +To see the full example source files, see: +* [HelloWorld](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/Samples/Sample1_HelloWorldAsync.cs)) + + \ No newline at end of file diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/src/Azure.Contoso.Widgetmanager.csproj b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/src/Azure.Contoso.Widgetmanager.csproj new file mode 100644 index 000000000000..731a79b748d7 --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/src/Azure.Contoso.Widgetmanager.csproj @@ -0,0 +1,22 @@ + + + This is the Widgetmanager client library for developing .NET applications with rich experience. + Azure SDK Code Generation Widgetmanager for Azure Data Plane + 1.0.0-beta.1 + Azure Widgetmanager + $(RequiredTargetFrameworks) + true + + + + + + + + + + + + + + diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/src/Generated/Docs/WidgetmanagerClient.xml b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/src/Generated/Docs/WidgetmanagerClient.xml new file mode 100644 index 000000000000..f281e6371282 --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/src/Generated/Docs/WidgetmanagerClient.xml @@ -0,0 +1,81 @@ + + + + + +This sample shows how to call GetSecretAsync with required parameters and parse the result. +", credential); + +Response response = await client.GetSecretAsync(""); + +JsonElement result = JsonDocument.Parse(response.ContentStream).RootElement; +Console.WriteLine(result.GetProperty("value").ToString()); +Console.WriteLine(result.GetProperty("id").ToString()); +Console.WriteLine(result.GetProperty("contentType").ToString()); +Console.WriteLine(result.GetProperty("tags").GetProperty("").ToString()); +Console.WriteLine(result.GetProperty("kid").ToString()); +Console.WriteLine(result.GetProperty("managed").ToString()); +]]> + + +The GET operation is applicable to any secret stored in Azure Key Vault. This operation requires the secrets/get permission. + +Below is the JSON schema for the response payload. + +Response Body: + +Schema for SecretBundle: +{ + value: string, # Optional. The secret value. + id: string, # Optional. The secret id. + contentType: string, # Optional. The content type of the secret. + tags: Dictionary<string, string>, # Optional. Application specific metadata in the form of key-value pairs. + kid: string, # Optional. If this is a secret backing a KV certificate, then this field specifies the corresponding key backing the KV certificate. + managed: boolean, # Optional. True if the secret's lifetime is managed by key vault. If this is a secret backing a certificate, then managed will be true. +} + + + + + + +This sample shows how to call GetSecret with required parameters and parse the result. +", credential); + +Response response = client.GetSecret(""); + +JsonElement result = JsonDocument.Parse(response.ContentStream).RootElement; +Console.WriteLine(result.GetProperty("value").ToString()); +Console.WriteLine(result.GetProperty("id").ToString()); +Console.WriteLine(result.GetProperty("contentType").ToString()); +Console.WriteLine(result.GetProperty("tags").GetProperty("").ToString()); +Console.WriteLine(result.GetProperty("kid").ToString()); +Console.WriteLine(result.GetProperty("managed").ToString()); +]]> + + +The GET operation is applicable to any secret stored in Azure Key Vault. This operation requires the secrets/get permission. + +Below is the JSON schema for the response payload. + +Response Body: + +Schema for SecretBundle: +{ + value: string, # Optional. The secret value. + id: string, # Optional. The secret id. + contentType: string, # Optional. The content type of the secret. + tags: Dictionary<string, string>, # Optional. Application specific metadata in the form of key-value pairs. + kid: string, # Optional. If this is a secret backing a KV certificate, then this field specifies the corresponding key backing the KV certificate. + managed: boolean, # Optional. True if the secret's lifetime is managed by key vault. If this is a secret backing a certificate, then managed will be true. +} + + + + + + \ No newline at end of file diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/src/GlobalSuppressions.cs b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/src/GlobalSuppressions.cs new file mode 100644 index 000000000000..9b3803f9838c --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/src/GlobalSuppressions.cs @@ -0,0 +1,6 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. +// Licensed under the MIT License. + +using System.Diagnostics.CodeAnalysis; + +[assembly: SuppressMessage("Usage", "AZC0002:DO ensure all service methods, both asynchronous and synchronous, take an optional CancellationToken parameter called cancellationToken.", Justification = "CancellationToken can be passed through RequestOptions")] \ No newline at end of file diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/src/cadl-location.yaml b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/src/cadl-location.yaml new file mode 100644 index 000000000000..2913da7ad32b --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/src/cadl-location.yaml @@ -0,0 +1,3 @@ +directory: specification/contosowidgetmanager/Contoso.WidgetManager +spec-root-dir: /mnt/vss/_work/1/s/azure-rest-api-specs + diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/src/properties/AssemblyInfo.cs b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/src/properties/AssemblyInfo.cs new file mode 100644 index 000000000000..f3358526713a --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/src/properties/AssemblyInfo.cs @@ -0,0 +1,13 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. +// Licensed under the MIT License. + +using System.Runtime.CompilerServices; + +// Replace with test project/test project public key and uncomment to make internal members visible to +// your test project. If not needed, this can be deleted. +// [assembly: InternalsVisibleTo("Azure.Contoso.Widgetmanager.Generated.Tests, PublicKey=0024000004800000940000000602000000240000525341310004000001000100d15ddcb29688295338af4b7686603fe614abd555e09efba8fb88ee09e1f7b1ccaeed2e8f823fa9eef3fdd60217fc012ea67d2479751a0b8c087a4185541b851bd8b16f8d91b840e51b1cb0ba6fe647997e57429265e85ef62d565db50a69ae1647d54d7bd855e4db3d8a91510e5bcbd0edfbbecaa20a7bd9ae74593daa7b11b4")] + +// Replace Microsoft.Test with the correct resource provider namepace for your service and uncomment. +// See https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/azure-services-resource-providers +// for the list of possible values. +[assembly: Azure.Core.AzureResourceProviderNamespace("Microsoft.Contosowidgetmanager")] diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/stress/Azure.Contoso.Widgetmanager.Stress.csproj b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/stress/Azure.Contoso.Widgetmanager.Stress.csproj new file mode 100644 index 000000000000..c9e5ebd5c4da --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/stress/Azure.Contoso.Widgetmanager.Stress.csproj @@ -0,0 +1,16 @@ + + + + Exe + + + + + + + + + + + + diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/stress/Program.cs b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/stress/Program.cs new file mode 100644 index 000000000000..d25a1b56e291 --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/stress/Program.cs @@ -0,0 +1,7 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. +// Licensed under the MIT License. + +using System.Reflection; +using Azure.Test.Stress; + +await StressProgram.Main(Assembly.GetEntryAssembly(), args); diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/stress/WidgetmanagerClientTest.cs b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/stress/WidgetmanagerClientTest.cs new file mode 100644 index 000000000000..47a5ee11200d --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/stress/WidgetmanagerClientTest.cs @@ -0,0 +1,36 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. +// Licensed under the MIT License. + +using System; +using System.Threading; +using System.Threading.Tasks; +using Azure.Identity; +using Azure.Test.Stress; +using CommandLine; + +namespace Azure.Contoso.Widgetmanager.Stress +{ + public class WidgetmanagerClientTest : StressTest + { + public WidgetmanagerClientTest(WidgetmanagerClientStressOptions options, WidgetmanagerClientStressMetrics metrics) : base(options, metrics) + { + } + + /* please refer to https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/stress/TemplateClientTest.cs to write stress tests. */ + + public override async Task RunAsync(CancellationToken cancellationToken) + { + await Task.Run(() => + { + Console.WriteLine("exec some async operation"); + }); + } + public class WidgetmanagerClientStressMetrics : StressMetrics + { + } + + public class WidgetmanagerClientStressOptions : StressOptions + { + } + } +} diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/Azure.Contoso.Widgetmanager.Tests.csproj b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/Azure.Contoso.Widgetmanager.Tests.csproj new file mode 100644 index 000000000000..8553861a8b58 --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/Azure.Contoso.Widgetmanager.Tests.csproj @@ -0,0 +1,25 @@ + + + $(RequiredTargetFrameworks) + + + $(NoWarn);CS1591 + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/Samples/README.md b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/Samples/README.md new file mode 100644 index 000000000000..5c3a7a611afe --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/Samples/README.md @@ -0,0 +1,3 @@ +Source files in this directory are written as tests from which samples are extracted. +They are not intended to be viewed directly and help ensure our samples compile and work correctly. +See our [list of samples](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/samples) for more explanation about how to use this client library. diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/Samples/Sample1_HelloWorld.cs b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/Samples/Sample1_HelloWorld.cs new file mode 100644 index 000000000000..a54831d6b486 --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/Samples/Sample1_HelloWorld.cs @@ -0,0 +1,21 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. +// Licensed under the MIT License. + +using System; +using System.Linq; +using System.Text.Json; +using System.Threading.Tasks; +using Azure.Core; +using Azure.Core.TestFramework; +using NUnit.Framework; + +namespace Azure.Contoso.Widgetmanager.Tests.Samples +{ + public partial class WidgetmanagerSamples: SamplesBase + { + /* please refer to https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/tests/Samples/Sample1.HelloWorld.cs to write samples. */ + #region Snippet:Azure_Contoso_Widgetmanager_Scenario + + #endregion + } +} diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/Samples/Sample1_HelloWorldAsync.cs b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/Samples/Sample1_HelloWorldAsync.cs new file mode 100644 index 000000000000..89ffda710860 --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/Samples/Sample1_HelloWorldAsync.cs @@ -0,0 +1,21 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. +// Licensed under the MIT License. + +using System; +using System.Linq; +using System.Text.Json; +using System.Threading.Tasks; +using Azure.Core; +using Azure.Core.TestFramework; +using NUnit.Framework; + +namespace Azure.Contoso.Widgetmanager.Tests.Samples +{ + public partial class WidgetmanagerSamples: SamplesBase + { + /* please refer to https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/tests/Samples/Sample1.HelloWorldAsync.cs to write samples. */ + #region Snippet:Azure_Contoso_Widgetmanager_ScenarioAsync + + #endregion + } +} diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/WidgetmanagerClientTest.cs b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/WidgetmanagerClientTest.cs new file mode 100644 index 000000000000..73a5d51422ad --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/WidgetmanagerClientTest.cs @@ -0,0 +1,42 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. +// Licensed under the MIT License. + +using System; +using System.IO; +using System.Net.Http; +using System.Text.Json; +using System.Threading.Tasks; +using Azure.Core.Pipeline; +using Azure.Core.TestFramework; +using NUnit.Framework; + +namespace Azure.Contoso.Widgetmanager.Tests +{ + public class WidgetmanagerClientTest: RecordedTestBase + { + public WidgetmanagerClientTest(bool isAsync) : base(isAsync) + { + } + + /* please refer to https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/tests/TemplateClientLiveTests.cs to write tests. */ + + [RecordedTest] + public void TestOperation() + { + Assert.IsTrue(true); + } + + #region Helpers + + private static BinaryData GetContentFromResponse(Response r) + { + // Workaround azure/azure-sdk-for-net#21048, which prevents .Content from working when dealing with responses + // from the playback system. + + MemoryStream ms = new MemoryStream(); + r.ContentStream.CopyTo(ms); + return new BinaryData(ms.ToArray()); + } + #endregion + } +} diff --git a/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/WidgetmanagerClientTestEnvironment.cs b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/WidgetmanagerClientTestEnvironment.cs new file mode 100644 index 000000000000..ccd193dc05d8 --- /dev/null +++ b/sdk/contosowidgetmanager/Azure.Contoso.Widgetmanager/tests/WidgetmanagerClientTestEnvironment.cs @@ -0,0 +1,14 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. +// Licensed under the MIT License. + +using Azure.Core.TestFramework; + +namespace Azure.Contoso.Widgetmanager.Tests +{ + public class WidgetmanagerClientTestEnvironment : TestEnvironment + { + public string Endpoint => GetRecordedVariable("Widgetmanager_ENDPOINT"); + + // Add other client paramters here as above. + } +} diff --git a/sdk/contosowidgetmanager/ci.yml b/sdk/contosowidgetmanager/ci.yml new file mode 100644 index 000000000000..6e9194ae70b8 --- /dev/null +++ b/sdk/contosowidgetmanager/ci.yml @@ -0,0 +1,31 @@ +# NOTE: Please refer to https://aka.ms/azsdk/engsys/ci-yaml before editing this file. + +trigger: + branches: + include: + - main + - hotfix/* + - release/* + paths: + include: + - sdk/contosowidgetmanager/ + +pr: + branches: + include: + - main + - feature/* + - hotfix/* + - release/* + paths: + include: + - sdk/contosowidgetmanager/ + +extends: + template: /eng/pipelines/templates/stages/archetype-sdk-client.yml + parameters: + ServiceDirectory: contosowidgetmanager + ArtifactName: packages + Artifacts: + - name: Azure.Contoso.Widgetmanager + safeName: AzureContosoWidgetmanager