Azure / Azure/azure-powershell

[Doc]: AzApplicationGateway Tutorial

Open
#24,152 3 comments 0 reactions 0 assignees View on GitHub
act-quality-productivity-squad customer-reported Doc - Reference Network - Application Gateway Service Attention
Dominant language
C#
Stars
4.8k
Forks
4.3k
Avg merge
3d 14h
Merged PRs (30d)
54

Description

### Type of issue

Other (describe below)

### Feedback

I have been working with the AzApplicationGateway command recently but have found them incredibly confusing to understand and could find very little guidance on how to work them so I want to suggest there is either an improved tutorial on how the PowerShell cmdlets should be approached, or in an ideal world, the cmdlets better tailored for their purpose.

These are my main issues:

- The [Cmdlet Documentation](https://learn.microsoft.com/en-us/powershell/module/az.network/set-azapplicationgatewayhttplistener?view=azps-11.2.0) assumes you realise that this is only instantiating/modifying objects in local memory. Nothing is pushed to the cloud until the objects in memory are connected to an Application Gateway also in memory and then that Application Gateway is committed using `Set-AzApplicationGateway`
- It is not clear anywhere how the "New", "Set" and "Add" cmdlets differ - 'New' creates something (e.g. a Http Listener, Backend Probe) in memory and both 'Set'/'Add' seems to also create one and immediately associate it to local copy of an Application Gateway. **However, neither the `Add` or `Set` cmdlets seem to allow you to add something you have created with the related 'New' cmdlet. For example, the below is not valid:**
```powershell
$HttpListener = New-AzApplicationGatewayHttpListener @MyParams
Add-AzApplicationGatewayHttpListener -ApplicationGateway $AppGateway -HttpListener $HttpListener
# This is not valid! There is no parameter that accepts an existing Http Listener!
```
- Continuing from the last point, the only way I could find to use the `New` cmdlets was with `$ApplicationGateway.Add($MyObject)` but when I tried to use the `Set-AzApplicationGateway` cmdlet to push it to the cloud, I just received very ambiguous errors such as "Object reference not found" with no details to the object I am missing so I had to give up.
- Being forced to use the `Add` cmdlets also return the revised Application Gateway which sort of makes sense. However, since I couldn't get the `New` cmdlets to work it meant the only way I was able to connect a Probe to a Backend would be multiple steps which felt quite wasteful:
```powershell
Add-AzApplicationGatewayProbeConfig @MyParams
$Probe = Get-AzApplicationGatewayProbeConfig
```

Now I'll admit that I can be an idiot a lot of the time but in this situation I can't be the only person who's tripped up on this? I thought it would be maybe 5x New-Az.... cmdlets to add my new listener, probe and backend, it ended up taking me 10+ lines of code and more days than I'd like to admit! I can't be the only person to stumble with these?

Thanks!

### Page URL

https://learn.microsoft.com/en-us/azure/application-gateway/

### Content source URL

_No response_

### Author

_No response_

### Document Id

_No response_

Contributor guide

Open the contributing guide

Research direction

Start with the Azure Application Gateway page and the linked Set-AzApplicationGatewayHttpListener documentation, then compare the New-, Add-, and Set-AzApplicationGateway cmdlet examples mentioned in the report. Done means a tutorial clearly explains local in-memory objects, committing changes to Azure, and how to connect listeners, probes, and backends without ambiguous steps.

Written by the indexing model from the issue text.

Assessment

Tech stack
azure, powershell
Domain
cloud, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.