Skip to content

Commit b6fb6d5

Browse files
ebmarquezliunick-msftCopilot
authored
Add initial project structure and enhance testing framework (#5)
* added csproj and base files. * add 'Out' directory to .gitignore * updated Get-CidrFromSubnetMask to validate a proper subnetmask. updated Get-SubnetMaskFromCidr to thow on invalid cidr * updated required pester version * unit-test file * unit test helper * Enhance Get-CidrFromSubnetMask to count bits in subnet mask and improve Test-SubnetMask validation * Add Convert-Network cmdlet to module export list * Add tests for Convert-Network cmdlet and enhance setup for Pester configuration * Add PSScriptAnalyzer workflow for code quality checks * Enhance CI workflow by adding .NET setup and Pester test execution * Add issue templates for bug reports and feature requests * Update README.md to enhance project overview, features, installation, usage examples, and contribution guidelines * Remove outdated support instructions and streamline issue reporting in SUPPORT.md * Fix installation instructions in README.md to correctly reference module path * Update README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Nick Liu <105009141+liunick-msft@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent 202d26d commit b6fb6d5

12 files changed

Lines changed: 1277 additions & 33 deletions

‎.github/ISSUES_TEMPLATE/bug_report.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
name: Bug Report
3+
about: Report a bug or unexpected behavior in the PowerShell module.
4+
title: "[BUG] <Short description>"
5+
labels: bug
6+
assignees: ''
7+
---
8+
9+
## Describe the Bug
10+
11+
Provide a clear and concise description of the bug. Include any relevant details about what you were trying to accomplish.
12+
13+
## Steps to Reproduce
14+
15+
Steps to reproduce the behavior:
16+
1. Run the following command:
17+
```powershell
18+
<Insert PowerShell command here>
19+
```
20+
21+
2. Observe the behavior.
22+
Expected Behavior What you expected to happen.
23+
24+
Actual Behavior What actually happened.
25+
26+
## Environment
27+
28+
Module Version: <e.g., 1.0.0>
29+
PowerShell Version: <e.g., 7.3.0>
30+
OS: <e.g., Windows 10>

‎.github/ISSUES_TEMPLATE/feature_report.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
name: Feature Request
3+
about: Suggest a new feature or enhancement.
4+
title: "[FEATURE] <Short description>"
5+
labels: enhancement
6+
assignees: ''
7+
---
8+
9+
## Summary
10+
Provide a clear and concise summary of the feature or enhancement you are requesting.
11+
12+
## Problem Statement
13+
What problem does this feature solve? Why is it needed?
14+
15+
## Proposed Solution
16+
Describe how the feature should work. Include examples or pseudocode if applicable.
17+
18+
## Alternatives Considered
19+
Have you considered any alternative solutions or workarounds? If so, describe them.
20+
21+
## Additional Context
22+
Add any other context, screenshots, or references that might help explain your request.
23+
24+
## Environment (Optional)
25+
If this feature is related to a specific environment, provide details:
26+
- Module Version: <e.g., 1.0.0>
27+
- PowerShell Version: <e.g., 7.3.0>
28+
- OS: <e.g., Windows 10>

‎.github/copilot-instructions.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
- @azure Rule - Use Azure Best Practices: When generating code for Azure, running terminal commands for Azure, or performing operations related to Azure, invoke your `get_azure_best_practices` tool if available.

‎.github/workflow/powershell-psscriptanalyzer.yml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# This workflow uses actions that are not certified by GitHub.
2+
# They are provided by a third-party and are governed by
3+
# separate terms of service, privacy policy, and support
4+
# documentation.
5+
#
6+
# https://github.com/microsoft/action-psscriptanalyzer
7+
# For more information on PSScriptAnalyzer in general, see
8+
# https://github.com/PowerShell/PSScriptAnalyzer
9+
10+
name: PSScriptAnalyzer
11+
12+
on:
13+
push:
14+
branches: [ "main" ]
15+
pull_request:
16+
branches: [ "main" ]
17+
18+
permissions:
19+
contents: read
20+
21+
jobs:
22+
build:
23+
permissions:
24+
contents: read # for actions/checkout to fetch code
25+
security-events: write # for github/codeql-action/upload-sarif to upload SARIF results
26+
actions: read # only required for a private repository by github/codeql-action/upload-sarif to get the Action run status
27+
name: PSScriptAnalyzer
28+
runs-on: ubuntu-latest
29+
steps:
30+
- uses: actions/checkout@v4
31+
- name: Setup .NET
32+
uses: actions/setup-dotnet@v4
33+
with:
34+
dotnet-version: 8.0.x
35+
36+
- name: Run PSScriptAnalyzer
37+
uses: microsoft/psscriptanalyzer-action@6b2948b1944407914a58661c49941824d149734f
38+
with:
39+
# Check https://github.com/microsoft/action-psscriptanalyzer for more info about the options.
40+
# The below set up runs PSScriptAnalyzer to your entire repository and runs some basic security rules.
41+
path: .\src
42+
recurse: true
43+
# Include your own basic security rules. Removing this option will run all the rules
44+
includeRule: '"PSAvoidGlobalAliases", "PSAvoidUsingConvertToSecureStringWithPlainText"'
45+
output: results.sarif
46+
47+
# Upload the SARIF file generated in the previous step
48+
- name: Upload SARIF results file
49+
uses: github/codeql-action/upload-sarif@v3
50+
with:
51+
sarif_file: results.sarif
52+
53+
- name: Restore dependencies
54+
run: dotnet restore
55+
- name: Build
56+
run: dotnet build --no-restore
57+
58+
# run powershell script /tests/setupTest.ps1 to run pester unit-testing
59+
- name: Run Pester tests
60+
shell: pwsh
61+
run: |
62+
$ErrorActionPreference = "Stop"
63+
$PSScriptRoot = (Get-Item -Path $MyInvocation.MyCommand.Path).DirectoryName
64+
. "$PSScriptRoot/tests/setupTest.ps1"

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ bld/
2222
[Oo]bj/
2323
[Ll]og/
2424
[Ll]ogs/
25+
[Oo]ut/
2526

2627
# .NET Core
2728
project.lock.json

‎Microsoft.AzureStack.Util.ConvertNetwork.csproj‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<Project Sdk="Microsoft.Build.NoTargets/3.0.0">
2+
3+
<PropertyGroup>
4+
<ProjectName>Microsoft.AzureStack.Util.ConvertNetwork</ProjectName>
5+
<TargetFramework>net8.0</TargetFramework>
6+
<Platform>x64</Platform>
7+
<Version Condition="'$(Version)'==''">1.0.0</Version>
8+
<Configuration Condition="'$(Configuration)'==''">Debug</Configuration>
9+
<BinariesBuildDirectory>$(MSBuildProjectDirectory)\out</BinariesBuildDirectory>
10+
<Package>$(MSBuildProjectDirectory)\out\packages</Package>
11+
<PesterVersion>5.2.0</PesterVersion>
12+
<!-- Set the custom NuGet packages directory -->
13+
<RestorePackagesPath>$(MSBuildProjectDirectory)\out\packages</RestorePackagesPath>
14+
</PropertyGroup>
15+
16+
<ItemGroup>
17+
<PackageReference Include="Pester" Version="$(PesterVersion)" />
18+
</ItemGroup>
19+
20+
<Target Name="PlaceFiles" AfterTargets="Build">
21+
<Copy SourceFiles="$(MSBuildProjectDirectory)\src\Microsoft.AzureStack.Util.ConvertNetwork.psd1" DestinationFolder="$(BinariesBuildDirectory)\$(ProjectName)" />
22+
<Copy SourceFiles="$(MSBuildProjectDirectory)\src\Microsoft.AzureStack.Util.ConvertNetwork.psm1" DestinationFolder="$(BinariesBuildDirectory)\$(ProjectName)" />
23+
</Target>
24+
25+
<Target Name="CopyPester" AfterTargets="PlaceFiles">
26+
<!-- Include all files recursively from the Pester package directory -->
27+
<ItemGroup>
28+
<PesterFiles Include="$(RestorePackagesPath)\pester\$(PesterVersion)\tools\**\*" Exclude="*.nupkg;*.nuspec" />
29+
</ItemGroup>
30+
<Copy SourceFiles="@(PesterFiles)" DestinationFolder="$(BinariesBuildDirectory)\PowerShell\Modules\Pester\$(PesterVersion)\%(RecursiveDir)" />
31+
</Target>
32+
33+
</Project>

‎README.md‎

Lines changed: 188 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,188 @@
1-
# Project
1+
# Microsoft.AzureStack.Util.ConvertNetwork
22

3-
> This repo has been populated by an initial template to help get you started. Please
4-
> make sure to update the content to build a great experience for community-building.
3+
[![Build Status](https://img.shields.io/github/actions/workflow/status/microsoft/Microsoft.AzureStack.Util.ConvertNetwork/powershell-psscriptanalyzer.yml?branch=main)](https://github.com/microsoft/Microsoft.AzureStack.Util.ConvertNetwork/actions)
4+
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
55

6-
As the maintainer of this project, please make a few updates:
6+
## Overview
77

8-
- Improving this README.MD file to provide a great experience
9-
- Updating SUPPORT.MD with content about this project's support experience
10-
- Understanding the security reporting process in SECURITY.MD
11-
- Remove this section from the README
8+
`Microsoft.AzureStack.Util.ConvertNetwork` is a PowerShell module that provides utilities for working with IPv4 networks. It includes functions to calculate subnet masks, CIDR values, broadcast addresses, and more. This project is designed to simplify network-related operations for developers and IT professionals.
9+
10+
## Features
11+
12+
- Convert CIDR to subnet masks and vice versa.
13+
- Calculate network and broadcast addresses.
14+
- Validate subnet masks and IP addresses.
15+
- Generate subnets from a given network.
16+
- Perform IP address calculations with ease.
17+
18+
## Table of Contents
19+
20+
- [Installation](#installation)
21+
- [Usage](#usage)
22+
- [Contributing](#contributing)
23+
- [License](#license)
24+
- [Support](#support)
25+
- [Code of Conduct](#code-of-conduct)
26+
27+
## Installation
28+
29+
To install the module, clone this repository and import the module into your PowerShell session:
30+
31+
```powershell
32+
git clone https://github.com/microsoft/Microsoft.AzureStack.Util.ConvertNetwork.git
33+
Import-Module .\src\Microsoft.AzureStack.Util.ConvertNetwork.psm1
34+
```
35+
36+
## Usage
37+
38+
Here are some examples of how to use the module:
39+
40+
Convert CIDR to Subnet Mask
41+
42+
```powershell
43+
Get-SubnetMaskFromCidr -Cidr 24
44+
45+
AddressFamily : InterNetwork
46+
ScopeId :
47+
IsIPv6Multicast : False
48+
IsIPv6LinkLocal : False
49+
IsIPv6SiteLocal : False
50+
IsIPv6Teredo : False
51+
IsIPv6UniqueLocal : False
52+
IsIPv4MappedToIPv6 : False
53+
Address : 16777215
54+
IPAddressToString : 255.255.255.0
55+
```
56+
57+
Calculate Network Address
58+
59+
```powershell
60+
Get-NetworkAddressFromIP -IPv4Address 192.168.1.40 -CIDR 27
61+
62+
AddressFamily : InterNetwork
63+
ScopeId :
64+
IsIPv6Multicast : False
65+
IsIPv6LinkLocal : False
66+
IsIPv6SiteLocal : False
67+
IsIPv6Teredo : False
68+
IsIPv6UniqueLocal : False
69+
IsIPv4MappedToIPv6 : False
70+
Address : 536979648
71+
IPAddressToString : 192.168.1.32
72+
```
73+
74+
#### Convert-Network object
75+
76+
Used to describe a subnet attributes.
77+
78+
```powershell
79+
Convert-Network -IPv4Address 192.168.1.0 -CIDR 25
80+
IPv4Address : 192.168.1.0
81+
Network : 192.168.1.0
82+
Cidr : 25
83+
Mask : 255.255.255.128
84+
InverseMask : 0.0.0.127
85+
Broadcast : 192.168.1.127
86+
```
87+
88+
####Members from Convert-Network
89+
90+
```powershell
91+
Convert-Network -IPv4Address 192.168.1.0 -CIDR 25 | Get-Member
92+
93+
TypeName: Microsoft.AzureStack.Util.ConvertNetwork
94+
95+
Name MemberType Definition
96+
---- ---------- ----------
97+
Equals Method bool Equals(System.Object obj)
98+
GetHashCode Method int GetHashCode()
99+
GetType Method type GetType()
100+
ToString Method string ToString()
101+
Cidr NoteProperty int Cidr=25
102+
IPv4Address NoteProperty System.String IPv4Address=192.168.1.0
103+
GetBroadcast ScriptMethod System.Object GetBroadcast();
104+
GetInverseMask ScriptMethod System.Object GetInverseMask();
105+
GetIPInSubnet ScriptMethod System.Object GetIPInSubnet();
106+
GetMask ScriptMethod System.Object GetMask();
107+
GetNetwork ScriptMethod System.Object GetNetwork();
108+
IpIsInSubnet ScriptMethod System.Object IpIsInSubnet();
109+
NewSubnet ScriptMethod System.Object NewSubnet();
110+
Broadcast ScriptProperty System.Object Broadcast {get=…
111+
InverseMask ScriptProperty System.Object InverseMask {get=…
112+
Mask ScriptProperty System.Object Mask {get=…
113+
Network ScriptProperty System.Object Network {get=…
114+
```
115+
116+
#### ConvertNetwork - GetIPInSubnet()
117+
118+
```powershell
119+
(Convert-Network -IPv4Address 192.168.1.0 -CIDR 25).GetIPInSubnet()
120+
128
121+
```
122+
123+
#### ConvertNetwork - GetMask()
124+
125+
```powershell
126+
(Convert-Network -IPv4Address 192.168.1.0 -CIDR 25).GetMask().ToString()
127+
255.255.255.128
128+
```
129+
130+
#### ConvertNetwork - GetNetwork()
131+
132+
```powershell
133+
(Convert-Network -IPv4Address 192.168.1.0 -CIDR 25).GetNetwork().ToString()
134+
192.168.1.0
135+
```
136+
137+
#### ConvertNetwork - IpIsInSubnet()
138+
139+
```powershell
140+
(Convert-Network -IPv4Address 192.168.1.0 -CIDR 25).IpIsInSubnet("192.168.2.1")
141+
False
142+
```
143+
144+
#### ConvertNetwork - NewSubnet()
145+
146+
```powershell
147+
(Convert-Network -IPv4Address 192.168.1.0 -CIDR 25).NewSubnet(29)
148+
Position Network Cidr Supernet
149+
-------- ------- ---- --------
150+
0 192.168.1.0 29 192.168.1.0/25
151+
1 192.168.1.8 29 192.168.1.0/25
152+
2 192.168.1.16 29 192.168.1.0/25
153+
3 192.168.1.24 29 192.168.1.0/25
154+
4 192.168.1.32 29 192.168.1.0/25
155+
5 192.168.1.40 29 192.168.1.0/25
156+
6 192.168.1.48 29 192.168.1.0/25
157+
7 192.168.1.56 29 192.168.1.0/25
158+
8 192.168.1.64 29 192.168.1.0/25
159+
9 192.168.1.72 29 192.168.1.0/25
160+
10 192.168.1.80 29 192.168.1.0/25
161+
11 192.168.1.88 29 192.168.1.0/25
162+
12 192.168.1.96 29 192.168.1.0/25
163+
13 192.168.1.104 29 192.168.1.0/25
164+
14 192.168.1.112 29 192.168.1.0/25
165+
15 192.168.1.120 29 192.168.1.0/25
166+
```
167+
168+
For more examples, see the [tests](tests/ConvertNetwork.Tests.ps1).
169+
170+
## License
171+
172+
This project is licensed under the [MIT License](LICENSE).
173+
174+
## Support
175+
176+
If you encounter any issues or have questions, please file an issue in the [GitHub Issues](https://github.com/microsoft/Microsoft.AzureStack.Util.ConvertNetwork/issues) section.
12177

13178
## Contributing
14179

180+
We welcome contributions! To get started, follow these steps:
181+
182+
1. Fork the repository.
183+
2. Create a new branch for your feature or bug fix.
184+
3. Commit your changes and submit a pull request.
185+
15186
This project welcomes contributions and suggestions. Most contributions require you to agree to a
16187
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
17188
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
@@ -24,6 +195,15 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
24195
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
25196
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
26197

198+
## Code of Conduct
199+
200+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or concerns.
201+
202+
## Acknowledgments
203+
204+
- [Pester](https://github.com/pester/Pester) for unit testing.
205+
- Microsoft for supporting this open-source initiative.
206+
27207
## Trademarks
28208

29209
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft

0 commit comments

Comments
 (0)