Skip to content

Commit 2611925

Browse files
isra-felisra-fel
committed
readme
1 parent 24de864 commit 2611925

File tree

1 file changed

+113
-77
lines changed

1 file changed

+113
-77
lines changed

‎tools/AzDev/README.md‎

Lines changed: 113 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,115 @@
1-
Can't resolve this error. Will put on hold for now.
1+
# AzDev - developer module for Azure PowerShell
22

3+
This module is designed to help developers of Azure PowerShell modules. It provides tools to assist development, troubleshooting issues, etc.
4+
5+
All the cmdlets in this module are prefixed with `Dev-` to avoid conflicts with other modules.
6+
7+
Like many other tools, this module targets `net8.0` so always run it in PowerShell 7.2 or later.
8+
9+
- [Quick start](#quick-start)
10+
- [Features](#features)
11+
- [Repo inventory](#repo-inventory)
12+
- [Connect azure-powershell and azure-powershell-common](#connect-azure-powershell-and-azure-powershell-common)
13+
- [Autorest helper](#autorest-helper)
14+
- [Open swagger online](#open-swagger-online)
15+
- [Development](#development)
16+
- [Design](#design)
17+
- [Testing](#testing)
18+
19+
## Quick start
20+
21+
```powershell
22+
# build the module
23+
./tools/AzDev/build.ps1
24+
# import the module
25+
Import-Module ./artifacts/AzDev/AzDev.psd1
26+
# set up the context (only once)
27+
Set-DevContext -RepoRoot 'C:\repos\azure-powershell'
28+
```
29+
30+
## Features
31+
32+
### Repo inventory
33+
34+
`Get-DevModule` and `Get-DevProject` are the main cmdlets to get the inventory of the repo.
35+
36+
```powershell
37+
PS /> Get-DevModule | Select-Object -First 10
38+
39+
Name Type Path
40+
---- ---- ----
41+
Maps AutoRestBased /Users/azps/workspace/azure-powershell/src/Maps
42+
Kusto AutoRestBased /Users/azps/workspace/azure-powershell/src/Kusto
43+
StorageMover AutoRestBased /Users/azps/workspace/azure-powershell/src/StorageMover
44+
ResourceGraph Hybrid /Users/azps/workspace/azure-powershell/src/ResourceGraph
45+
Terraform AutoRestBased /Users/azps/workspace/azure-powershell/src/Terraform
46+
PostgreSql AutoRestBased /Users/azps/workspace/azure-powershell/src/PostgreSql
47+
SpringCloud AutoRestBased /Users/azps/workspace/azure-powershell/src/SpringCloud
48+
ManagedNetworkFabric AutoRestBased /Users/azps/workspace/azure-powershell/src/ManagedNetworkFabric
49+
ServiceBus Hybrid /Users/azps/workspace/azure-powershell/src/ServiceBus
50+
Mdp AutoRestBased /Users/azps/workspace/azure-powershell/src/Mdp
51+
52+
PS /> Get-DevProject | Group-Object -Property Type | Select-Object -Property Name,Count | Sort-Object -Property Count -Descending
53+
54+
Name Count
55+
---- -----
56+
AutoRestBased 163
57+
Wrapper 127
58+
SdkBased 76
59+
Test 70
60+
Track1Sdk 48
61+
Other 8
62+
LegacyHelper 4
63+
```
64+
65+
### Connect azure-powershell and azure-powershell-common
66+
67+
Help you connect the azure-powershell and azure-powershell-common repositories for developing or debugging.
68+
69+
```powershell
70+
# Connect
71+
Connect-DevCommonRepo
72+
73+
# Disconnect
74+
Disconnect-DevCommonRepo
75+
```
76+
77+
### Autorest helper
78+
79+
#### Open swagger online
80+
81+
`Open-DevSwagger` opens the online version of the specified swagger file. It's useful when you want to quickly check the structure of a swagger file.
82+
83+
```powershell
84+
PS /> Open-DevSwagger workloads
85+
Multiple projects matching [workloads]
86+
1: SapVirtualInstance.Autorest
87+
2: Monitors.Autorest
88+
Enter the number corresponding to your selection
89+
1
90+
Multiple swagger references found in [SapVirtualInstance.Autorest]
91+
1: $(repo)/specification/workloads/resource-manager/Microsoft.Workloads/SAPVirtualInstance/readme.md
92+
2: $(repo)/specification/workloads/resource-manager/readme.powershell.md
93+
Enter the number corresponding to your selection
94+
1
95+
Opening https://github.com/Azure/azure-rest-api-specs/blob/202321f386ea5b0c103b46902d43b3d3c50e029c/specification/workloads/resource-manager/Microsoft.Workloads/SAPVirtualInstance/readme.md in default browser...
396
```
4-
PS C:\Users\yeliu\code\azure-powershell [0.23s]> get-error
5-
6-
Exception :
7-
Type : System.IO.FileLoadException
8-
Message : Could not load file or assembly 'Microsoft.Bcl.AsyncInterfaces, Version=9.0.0.3, Culture=neutral,
9-
PublicKeyToken=cc7b13ffcd2ddd51'. The located assembly's manifest definition does not match the assembly reference. (0x80131040)
10-
FileName : Microsoft.Bcl.AsyncInterfaces, Version=9.0.0.3, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51
11-
TargetSite :
12-
Name : Initialize
13-
DeclaringType : [AzDev.Services.AzDevModule]
14-
MemberType : Method
15-
Module : AzDev.dll
16-
InnerException :
17-
Type : System.IO.FileLoadException
18-
Message : Could not load file or assembly 'C:\Users\yeliu\code\azure-powershell\artifacts\AzDev\bin\Microsoft.Bcl.AsyncInterfaces.dll'.
19-
The located assembly's manifest definition does not match the assembly reference. (0x80131040)
20-
FileName : C:\Users\yeliu\code\azure-powershell\artifacts\AzDev\bin\Microsoft.Bcl.AsyncInterfaces.dll
21-
TargetSite :
22-
Name : LoadFromAssemblyPath
23-
DeclaringType : [System.Runtime.Loader.AssemblyLoadContext]
24-
MemberType : Method
25-
Module : System.Private.CoreLib.dll
26-
Source : System.Private.CoreLib
27-
HResult : -2146234304
28-
StackTrace :
29-
at System.Runtime.Loader.AssemblyLoadContext.LoadFromAssemblyPath(String assemblyPath)
30-
at System.Reflection.Assembly.LoadFrom(String assemblyFile)
31-
at System.Reflection.Assembly.LoadFromResolveHandler(Object sender, ResolveEventArgs args)
32-
at System.Runtime.Loader.AssemblyLoadContext.InvokeResolveEvent(ResolveEventHandler eventHandler, RuntimeAssembly assembly, String name)
33-
Source : AzDev
34-
HResult : -2146234304
35-
StackTrace :
36-
at AzDev.Services.AzDevModule.Initialize()
37-
at AzDev.Cmdlets.DevCmdletBase.OnImport() in C:\Users\yeliu\code\azure-powershell\tools\AzDev\src\Cmdlets\DevCmdletBase.cs:line 76
38-
at System.Management.Automation.Runspaces.PSSnapInHelpers.ExecuteModuleInitializer(Assembly assembly, IEnumerable`1 assemblyTypes)
39-
at System.Management.Automation.Runspaces.PSSnapInHelpers.AnalyzeModuleAssemblyWithReflection(Assembly assembly, String name, PSSnapInInfo
40-
psSnapInInfo, PSModuleInfo moduleInfo, String helpFile, Dictionary`2& cmdlets, Dictionary`2& aliases, Dictionary`2& providers)
41-
at System.Management.Automation.Runspaces.PSSnapInHelpers.AnalyzePSSnapInAssembly(Assembly assembly, String name, PSSnapInInfo psSnapInInfo,
42-
PSModuleInfo moduleInfo, Dictionary`2& cmdlets, Dictionary`2& aliases, Dictionary`2& providers, String& helpFile)
43-
at System.Management.Automation.Runspaces.InitialSessionState.ImportCmdletsFromAssembly(Assembly assembly, PSModuleInfo module)
44-
at Microsoft.PowerShell.Commands.ModuleCmdletBase.LoadBinaryModule(PSModuleInfo parentModule, String moduleName, String fileName, Assembly
45-
assemblyToLoad, String moduleBase, SessionState ss, ImportModuleOptions options, ManifestProcessingFlags manifestProcessingFlags, String prefix,
46-
Boolean& found, String shortModuleName, Boolean disableFormatUpdates)
47-
at Microsoft.PowerShell.Commands.ModuleCmdletBase.LoadModule(PSModuleInfo parentModule, String fileName, String moduleBase, String prefix,
48-
SessionState ss, Object privateData, ImportModuleOptions& options, ManifestProcessingFlags manifestProcessingFlags, Boolean& found, Boolean&
49-
moduleFileFound)
50-
at Microsoft.PowerShell.Commands.ModuleCmdletBase.LoadModuleNamedInManifest(PSModuleInfo parentModule, ModuleSpecification moduleSpecification,
51-
String moduleBase, Boolean searchModulePath, String prefix, SessionState ss, ImportModuleOptions options, ManifestProcessingFlags
52-
manifestProcessingFlags, Object privateData, Boolean& found, String shortModuleName, Nullable`1 manifestLanguageMode)
53-
at Microsoft.PowerShell.Commands.ModuleCmdletBase.LoadModuleManifest(String moduleManifestPath, ExternalScriptInfo manifestScriptInfo,
54-
Hashtable data, Hashtable localizedData, ManifestProcessingFlags manifestProcessingFlags, Version minimumVersion, Version maximumVersion, Version
55-
requiredVersion, Nullable`1 requiredModuleGuid, ImportModuleOptions& options, Boolean& containedErrors)
56-
at Microsoft.PowerShell.Commands.ModuleCmdletBase.LoadModule(PSModuleInfo parentModule, String fileName, String moduleBase, String prefix,
57-
SessionState ss, Object privateData, ImportModuleOptions& options, ManifestProcessingFlags manifestProcessingFlags, Boolean& found, Boolean&
58-
moduleFileFound)
59-
at Microsoft.PowerShell.Commands.ImportModuleCommand.ImportModule_LocallyViaName(ImportModuleOptions importModuleOptions, String name)
60-
at Microsoft.PowerShell.Commands.ImportModuleCommand.ImportModule_LocallyViaName_WithTelemetry(ImportModuleOptions importModuleOptions, String
61-
name)
62-
at Microsoft.PowerShell.Commands.ImportModuleCommand.ProcessRecord()
63-
at System.Management.Automation.CommandProcessor.ProcessRecord()
64-
CategoryInfo : NotSpecified: (:) [Import-Module], FileLoadException
65-
FullyQualifiedErrorId : System.IO.FileLoadException,Microsoft.PowerShell.Commands.ImportModuleCommand
66-
InvocationInfo :
67-
MyCommand : Import-Module
68-
ScriptLineNumber : 1
69-
OffsetInLine : 1
70-
HistoryId : 2
71-
Line : ipmo .\artifacts\AzDev\AzDev.psd1
72-
Statement : ipmo .\artifacts\AzDev\AzDev.psd1
73-
PositionMessage : At line:1 char:1
74-
+ ipmo .\artifacts\AzDev\AzDev.psd1
75-
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
76-
InvocationName : ipmo
77-
CommandOrigin : Internal
78-
ScriptStackTrace : at <ScriptBlock>, <No file>: line 1
79-
```
97+
98+
## Development
99+
100+
### Design
101+
102+
`AzDev` supports both C# based and script based cmdlets.
103+
104+
The script based cmdlets are located in the `AzDev` folder. Take a look at `AzDev/CommonRepo.psm1` for example. Update `NestedModules` in `AzDev.psd1` when you add new scripts.
105+
106+
The C# based cmdlets are located in the `src` folder. It's quite similar to developing a SDK-based module in Azure PowerShell.
107+
108+
Either way, make sure
109+
110+
1. All cmdlets are prefixed with `Dev-`.
111+
2. Add your new cmdlets to `FunctionsToExport` or `CmdletsToExport` in `AzDev.psd1`.
112+
113+
### Testing
114+
115+
Use `dotnet test` to run the unit tests. `Invoke-Pester` to run the E2E tests located in `Tests/PSTests`.

0 commit comments

Comments
 (0)