The Tools.Common project is a collection of classes that are used by other tooling applications in the Azure PowerShell repository, such as static analysis and the versioning tool.
The Models folder contains classes representing the metadata for different pieces of a module that are used by static analysis and the versioning tool.
The ModuleMetadata class contains information about the content exposed by a module.
The following public serializable properties are found in this class:
Cmdlets- This is the list of cmdlets exposed by the module, represented as
CmdletMetadataobjects
- This is the list of cmdlets exposed by the module, represented as
TypeDictionary- This is a dictionary of types exposed by the module, mapping the fully name of the type to its
TypeMetadataobject representation
- This is a dictionary of types exposed by the module, mapping the fully name of the type to its
The TypeMetadata class contains information about the content of a .NET type.
The following public serializable properties are found in this class:
Namespace- This is the namespace of the type (e.g.,
Systemis the namespace forSystem.DateTime)
- This is the namespace of the type (e.g.,
Name- This is the full name of the type (e.g.,
System.DateTime)
- This is the full name of the type (e.g.,
AssemblyQualifiedName- This is the assembly qualified name of the type (e.g.,
System.DateTime, System.Private.CoreLib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798eis the assembly qualified name forSystem.DateTime)
- This is the assembly qualified name of the type (e.g.,
Properties- This is a dictionary that maps the type's property names' to their corresponding full type name (e.g.,
Name-->System.String,Enabled-->System.Boolean)
- This is a dictionary that maps the type's property names' to their corresponding full type name (e.g.,
ElementType- If the type is a collection of elements (e.g., array), then this is the type of the element (e.g.,
System.Byteis the element type for the typeSystem.Byte[])
- If the type is a collection of elements (e.g., array), then this is the type of the element (e.g.,
GenericTypeArguments- If the type is a generic (e.g., list, dictionary), then this is the type of the arguments of the generic (e.g.,
System.Stringis the generic type argument forIList<System.String>)
- If the type is a generic (e.g., list, dictionary), then this is the type of the arguments of the generic (e.g.,
Methods- This is the
MethodSignaturerepresentation of the public methods exposed by this type (e.g.,ToString(),Equals(),GetHashCode())
- This is the
Constructors- This is the
MethodSignaturerepresentation of the public constructors exposed by this type
- This is the
The CmdletMetadata class contains information about the content of a cmdlet.
The following public serializable properties are found in this class:
VerbName- This is the verb component of the cmdlet name
NounName- This is the noun component of the cmdlet name
Name- This is the name of the cmdlet
ClassName- This is the name of the class that the cmdlet is defined in
SupportsShouldProcess- This signals whether or not the cmdlet implements
SupportsShouldProcess
- This signals whether or not the cmdlet implements
ConfirmImpact- This is impact level of the operation
SupportsPaging- This signals whether or not the cmdlet implements
SupportsPaging
- This signals whether or not the cmdlet implements
DefaultParameterSetName- The name of the default parameter set of the cmdlet
OutputTypes- A list of the output types of the cmdlet, represented as
OutputMetadataobjects
- A list of the output types of the cmdlet, represented as
Parameters- A list of parameters found in the cmdlet, represented as
ParameterMetadataobjects
- A list of parameters found in the cmdlet, represented as
ParameterSets- A list of parameter sets found in the cmdlet, represented as
ParameterSetMetadataobjects
- A list of parameter sets found in the cmdlet, represented as
AliasList- A list of aliases that the cmdlet has
The OutputMetadata class contains information about the output type of a cmdlet.
The following public serializable properties are found in this class:
Type- The type of the output, represented as a
TypeMetadataobject
- The type of the output, represented as a
ParameterSets- The list of parameter sets that the output type is returned in
The ParameterMetadata class contains information about the content of a parameter.
The following public serializable properties are found in this class:
Name- The name of the parameter
AliasList- The list of aliases that the parameter has
Type- The type of the parameter, represented as a
TypeMetadataobject
- The type of the parameter, represented as a
ValidateSet- The list of values that are defined in the
ValidateSetattribute for the parameter
- The list of values that are defined in the
ValidateRangeMin- The minimum value specified in the
ValidateRangeattribute for the parameter
- The minimum value specified in the
ValidateRangeMax- The maximum value specified in the
ValidateRangeattribute for the parameter
- The maximum value specified in the
ValidateNotNullOrEmpty- This signals whether or not the parameter has the
ValidateNotNullOrEmptyattribute
- This signals whether or not the parameter has the
The ParameterSetMetadata class contains information about the content of a parameter set.
The following public serializable properties are found in this class:
Name- The name of the parameter set
Parameters- The list of parameters found in the parameter set, represented as
Parameterobjects
- The list of parameters found in the parameter set, represented as
The following public serializable properties are found in the Parameter class:
ParameterMetadata- The global information about a parameter, represented as a
ParameterMetadataobject
- The global information about a parameter, represented as a
Mandatory- This signals whether or not the parameter is mandatory in the given parameter set
Position- The position of the parameter in the given parameter set
ValueFromPipeline- This signals whether or not the parameter has
ValueFromPipeline = truein the given parameter set
- This signals whether or not the parameter has
ValueFromPipelineByPropertyName- This signals whether or not the parameter has
ValueFromPipelineByPropertyName = truein the given parameter set
- This signals whether or not the parameter has
The AssemblyMetadata class contains information about the content of an assembly. The constructor for this class takes a System.Reflection.Assembly object.
The following public serializable properties are found in this class:
Location- The path to the assembly on disk
The following methods are used as well:
GetName()- Returns the name of the assembly
GetReferencedAssemblies()- Returns the list of assemblies that are referenced by the assembly
This folder contains classes that introduce various extension methods used to help inside of the Tools.Common project.
The ReflectionExtensions class contains extension methods used to help reflect over attributes in a given assembly.
The following extension methods are found in this class:
GetAttribute<T>(this Type type)- Returns the attribute of type
Tfound in thetypeobject
- Returns the attribute of type
GetAttribute<T>(this PropertyInfo propertyInfo)- Returns the attribute of type
Tfound in thepropertyInfoobject
- Returns the attribute of type
GetAttributes<T>(this Type type)- Returns a list of attributes of type
Tfound in thetypeobject
- Returns a list of attributes of type
GetAttributes<T>(this PropertyInfo propertyInfo)- Returns a list of attributes of type
Tfound in thepropertyInfoobject
- Returns a list of attributes of type
HasAttribute<T>(this Type type)- Returns whether or not the
typeobject contains an attribute of typeT
- Returns whether or not the
HasAttribute<T>(this PropertyInfo propertyInfo)- Returns whether or not the
propertyInfoobject contains an attribute of typeT
- Returns whether or not the
GetParameters(this Type type)- Using a call to
HasAttribute<ParameterAttribute>(), returns the list ofPropertyInfoobjects with aParameterAttribute
- Using a call to
GetCmdletTypes(this Assembly assembly)- Using a call to
HasAttribute<CmdletAttribute>(), returns the list ofTypeobjects with theCmdletAttribute
- Using a call to
This folder contains classes that load assemblies into the current session and reflect over them to create various metadata objects found in the Models folder.
The AssemblyLoader class contains the logic to load assemblies, reflect over them and convert them to AssemblyMetadata objects.
This class is used by the dependency analyzer that runs as a part of static analysis.
The CmdletLoader class contains the logic to load assemblies, reflect over them and convert them to ModuleMetadata objects.
This class is used by the breaking change analyzer, help analyzer and signature verifier, which all run as a part of static analysis, as well as the version controller.
This folder contains .json files that are the serialization of the ModuleMetadata object constructed for each module. During each release, if a module has been updated, its .json file will be re-serialized using the latest ModuleMetadata object constructed. As a result, a module's .json file should be viewed as a snapshot of the module the last time that it was released.
The breaking change analyzer that runs as a part of static analysis uses the .json files to check for any breaking changes from the last release to the changes being made in a user's pull request.
The versioning tool that runs as a part of each release uses the .json files to check for any public API changes from the last release to the current release, and decides what type of bump to make to the module's version:
| Bump | Description | Example |
|---|---|---|
| Major | A breaking change was introduced into the module | 1.2.3 --> 2.0.0 |
| Minor | Additions were made to the module (e.g., new cmdlets, new parameters) | 1.2.3 --> 1.3.0 |
| Patch | Bug fixes in the backend of a module or documentation updates | 1.2.3 --> 1.2.4 |
Version bumping bases on installed version and changes of APIs. But it cannot handle below scenarios:
- Module will be GAed from
0.n.n-->1.0.0. The tool cannot detect this change because preview release module doesn't has.jsonfile, or there is no breaking changes in current release. - Module has a preview release but new bumped version has the same semantic version just without
previewlabel. This new version cannot be published to PSGallery. The tool needs a patch version increase.
Above scenarios can be supported by configurations MinimalVersion.csv. Each line contains module name and expected minimal version. If bumped version is lower than expected minital version, the tool will use minimal version for new release.
The Issues folder contains classes that represent the records that are created by the different analyzers found in static analysis. Each analyzer is responsible for implement a specific record for their analyzer that defines the following methods:
PrintHeaders()- Returns the string representation of the headers found in the resulting
.csvrecord file
- Returns the string representation of the headers found in the resulting
FormatRecord()- Returns the string representationg of a single record (or row) found in the resulting
.csvrecord file
- Returns the string representationg of a single record (or row) found in the resulting
Match(IReportRecord other)- Defines how to compare two records, specifically to see if the incoming record is already found in the existing
.csvcontaining the suppressed records
- Defines how to compare two records, specifically to see if the incoming record is already found in the existing
Parse(string line)- Defines how to parse a line in the
.csvfile and assign the values to properties of the record
- Defines how to parse a line in the
The AnalysisLogger classes contains methods to create new loggers, retrieve existing loggers, write reports, check for issues within a certain severity threshold and log errors, warnings and messages using the Log4Net package.
The ConsoleLogger class contains methods used for logging errors and warnings to the console and writing reports to the file system.
The ReportLogger abstract class that acts as an abstraction over typed loggers, deferring to the parent logger to define how to log errors, warnings and messages.
An implementation of the ReportLogger abstraction can be found in this class as well, ReportLogger<T>, which knows how to use the exceptions files for the different analyzers in static analysis and log records against them.
For example, if a new breaking change exception is found in its analyzer, the ReportLogger knows to how to compare the new breaking change record created and compare it to the existing breaking change exceptions that are found in the Exceptions folder of Tools.Common to see if the new record can be ignored.