Update Dependency management section in the Azure Functions PowerShell developer guide

[Francisco-Gamino]

Please update the Dependency management section at https://learn.microsoft.com/en-us/azure/azure-functions/functions-reference-powershell?tabs=portal#dependency-management.

For dependency management, there are two options: 1) Managed dependencies (via requirements.psd1 and host.json) -- these are managed by the Functions service 2) Include function app dependencies (PowerShell modules) with the function app content. These dependencies can be placed in the Modules folder at the function app root. This information is currently under the Function app-level modules folder section.

[AnatoliB]

The current doc structure is outdated, mixes important concepts, and does not give enough guidance to users who do not need the Managed Dependencies feature:

• Dependency management
  • Target specific versions
    • Many users don't immediately understand that both steps (requrements.psd1 and profile.ps1) are required, so they discover it the hard way, when something breaks. We need to make this guidance more prominent somehow.
  • Dependency management considerations
  • Dependency management app settings
• Custom modules
  • Function app-level modules folder
    • It's surprising to see this section under Custom modules. This approach works with any modules, including those available on the PS Gallery
    • Not enough guidance on how
  • Language worker level modules folder
    • This section doesn't seem actionable or helpful to the user. There are indeed modules available out-of-the-box, like with a regular PS installation, but this should be intuitively clear. The fact that this is implemented via a worker-level folder is just an implementation detail that the user cannot do anything about. I propose removing this entire section from the doc. This information is more appropriate for the design doc on the GitHub repo.
• ...
• Considerations for PowerShell functions
  • Bundle modules instead of using Install-Module
    • Bundling modules is not the only alternative to Install-Module.

I propose revamping the Dependency management section to make it very clear that there are two recommended methods to manage modules, each method has its own advantages, and each method has separate instructions. Here is the proposed structure with more comments:

• Module management ("Dependency management" is too ambitious - we are really talking only about modules here; it is also easy to confuse it with the Managed Dependencies as a feature)
  • Give a very quick comparison of two methods (using the Managed Dependencies feature vs. including modules into the app content), help the customer choose.
    • Reasons to use the Managed Dependencies feature:
      • Simplified initial installation
      • Auto-upgrades on a running app, including urgent security fixes
    • Reasons to include modules into the app content:
      • No dependency on the PowerShell Gallery
      • More control: no auto-upgrade regression risk
      • Works on Flex Consumption, recommended on other Linux SKUs
  • Managed Dependencies feature
    • Target specific versions - Let's make sure it's very clear that both steps are mandatory
    • Dependency management considerations
    • Dependency management app settings
  • Including modules into the app content
    • Function app-level modules folder
    • We provide a Copy-Item sample, which is useful in situations when the module content is already available locally. We need two more samples:
      • Using Save-Module to retrieve modules from the PowerShell Gallery
      • Using Save-PSResource from the PSResourceGet module to retrieve modules from the PowerShell Gallery or many other sources
• …
• Considerations for PowerShell functions
  • Bundle modules instead of using Install-Module
    • Rename this section to something like "Avoid using Install-Module"
    • Replace "Instead use Save-Module" with a reference to the Module management section

[andystaples]

Also consider:

• Dependency Management
  • Target specific versions
  • The doc could be read (especially if skipping the section above) to imply that the Az module is bundled with every function app by default. It is not, we should adjust phrasing to clarify this
  • Dependency management app settings
  • This entire section implies that we automatically upgrade modules installed with managed dependencies, but nowhere in the doc is this specifically called out. Add a sentence or two in the description of the managed dependencies feature that this is one of its capabilities
  • Also mention that if on an unsupported version (e.g. PS 7.0 today and 7.2 in November) we block automatic upgrades for managed dependencies by default, but you can override this behavior by setting the MDEnableAutomaticUpgrades env var to "true". This might not be worth calling out in the documentation, but worth discussion