Azure portal extension development documentation

This is the home page for all documentation related to onboarding, designing, developing, operating, and anything else to do with owning an Azure portal extension.

Couldn't find what you needed? Ask about the docs on StackOverflow.

Announcements

• Docs in this github are moved to Engineering Hub Azure Portal Framework (IbizaFx) Documentation. If you are the owner of any docs in this github, move it to Engineering Hub. If you view a docs in this github, use the link in Engineering Hub.

• Access to the Portal Dogfood environment will be restricted after April 15, 2023.

Get started with Default Experiences

If your resource types have public Azure Rest API specs, we likely have generated UX for your resource types already.

You can discover default experiences for your resource type in MS Portal through global search. By default, you can expect to see a browse, overview with commands and resource menu to manage the resource instances of your resource types- without any upfront development. If your resource types have public API specs, but you do not see a default experience for these resource instances or if you have additional questions please reach out to: dxportalteam@microsoft.com

If you want to customize this experience, you must own a portal extension. However, you can save development time by making use of auto-generated artifacts. In the AzureUX-GeneratedExtension repo, you can find the generated asset and views that power the default experience for the resource type.

Learn more about Default Experiences & generated UX

Onboarding a new extension

• Overview / Get started

• Steps that do not involve the Ibiza team

• Managing cloud/environment specific configuration

• Production-ready metrics

• Partner feature request process

Kickoff the onboarding experience by sending a mail to Azure Onboarding Team.

Azure portal architecture

Learn how the framework is structured and how it is designed to run in multiple clouds / environments.

• Architecture overview

• Authentication flow

• Authentication procedures

Design guide

Design patterns provide solutions for common Azure scenarios. By leveraging these patterns, Azure teams will accelerate extension development and provide users with a familiar experience so that users can easily adopt new Azure services. The design guide covers design toolkits, style guidance, common page layouts and the resource management pattern.

• Design guide

Development guide

Getting started

If you are building a new extension, consider building a declarative extension. A declarative extension is easier to build and cheaper to maintain. Learn more here.

Azure portal extension development is supported on Windows Server 2012 R2, and Windows 10.

• Downloads

• Release notes

• Breaking changes

• Install the CLI

• Get started

• Updating the SDK or Ask an SDK setup question on StackOverflow

• Running your extension locally (a.k.a. sideloading)

• Add auto-generated views & asset definitions into your extension

Azure Portal Extension Developer CLI

The Azure portal extension developer CLI, namely ap, is the foundational tool used for all inner dev/test loop actions during extension development and includes commands such as new, restore, build, serve, start, release, lint, run test, watch and update.

• CLI Overview

• Setup and Installation

• Basic Workflows

• Command Reference

• Linting directly within VS Code

• Customizing Lint Rules

• Extending the cli with your teams own commands

• Overriding the behavior of existing commands

• Contributions and Feedback

• FAQ

Samples

Samples show how to do many common development tasks.

• Samples

Blades

The primary UI building block is a called a blade. A blade is like a page. It generally takes up the full screen, has a presence in the portal breadcrumb, and has an 'X' button to close it.

• Overview

• Declarative Views

• React Views

• TemplateBlade

• MenuBlade

• ResourceMenuBlade

• FrameBlade

• Advanced TemplateBlade topics

• Blade with tiles

Ask a question about blades on StackOverflow

Parts

If you want your experience to have a presence on Azure dashboards then you will want to build parts (a.k.a. tiles).

• Developing parts

Ask a question about parts on StackOverflow

Navigation

Navigating between topics or other resources is a core element of interactivity with the portal.

• Opening and closing blades programmatically

Ask a question about navigation on StackOverflow

Focus management

While the portal does autofocus management with default rules that should match most scenarios, sometimes it is better for extension to guide the focus to an appropriate location.

• How focus is managed and how to set focus programmatically

Ask a question about focus management on StackOverflow

Building UI with HTML templates and Fx controls

Any template based UI in the portal (e.g. template blades or template parts can make use of a rich controls library maintained by the Ibiza team.

• Controls overview

• Controls list and design guidance

• Controls playground

Ask a controls related question on StackOverflow

Styling and theming

When using HTML and framework controls you have some control over styling. These documents walk through the relevant topics.

• Styling and theming

• HTML, CSS, and SVG sanitization

• Adding custom CSS

• Blade Layout patterns

• Theming

• Typography

• Iconography

• Printing

Forms

Many experiences require the user to enter data into a form. The Ibiza controls library provides support for forms. It also provides a TypeScript based section model that lets you build your form in code without expressing all the fields in an html template.

• Develop forms

Ask a forms related question on StackOverflow

Common scenarios and integration points

• Blades that create or provision resources and services

• Add your resource or service into the 'All services' (browse) menu

Ask about browse integration on StackOverflow

Ask about create scenarios on StackOverflow

Other UI concepts

• Context panes

• Dialogs

• Notifications

• Iris Notifications

Loading and managing data

Because your extension is Web code, you can make AJAX calls to various services to load data into your UI. The framework provides a data library you can use to manage this data.

• Making authenticated and batched calls to Azure Resource Manager (ARM) and other endpoints

• Legacy data management features

Ask about data management on StackOverflow

Advanced development topics

• Memory management (LifetimeManager)

• Sharing blades and parts across extensions

• Custom domains (e.g. aad.portal.azure.com)

• Persistent Storage

Debugging

• Using debug mode

• Debugging extension load failures

• Debugging console errors

• Debugging javascript

• Debugging knockout

• Debugging the data stack

Performance

• Performance profiling

Testing

The Ibiza team provides limited testing support. Due to resource constraints the C# and Node.js frameworks are inner source, so that partners can unblock themselves if the Ibiza team cannot make requested improvements as quickly as you might expect.

• Unit testing support

• Node.js test framework (Inner source)

• C# test framework (Inner source)

When asking for assistance with a debugging UI (not unit test) test framework specific issues on stackoverflow, please include the following (if applicable):

• Screenshot of the test as it fails taken via the portal.takeScreenshot()/webdriver.takeScreenshot() API (usually via a try/catch block)
• Call stack
• Exception message
• Code snippet where the test is failing
• Version of the test framework being used

Ask a test-related question on StackOverflow

Telemetry and alerting

The Ibiza team collects standard telemetry for generic actions like blade opening and command execution. We also collect performance, reliability, and user feedback information that facilitates the operation of your extension. You can also write your own events by using the telemetry system. Ibiza supports alerting for common operations scenarios.

• Portal telemetry overview

• Set up and verify telemetry logging from your extension

• Getting access to raw portal telemetry data

• Consuming telemetry via pre-built Power BI dashboards

• Performance and reliability monitoring

Ask about telemetry on StackOverflow

Ask about performance and reliability on StackOverflow

Experimentation and flighting

It is common for teams to want to experiment with new capabilities. We offer framework features that make this possible.

• Flighting a new version of your extension in MPAC

• Feature flags to enable or disable individual features within an environment

Localization and globalization

The Azure portal supports multiple languages and locales. You will need to localize your content.

• Localization overview and supported languages

• Setting up localization for your extension

• Setting up localization for your gallery package

• Testing localization with side-loading

• Handling localization for links to documentation

• Formatting numbers, currencies and dates

Ask about localization / globalization on StackOverflow

Accessibility

The Azure Portal strives to meet high accessibility standards to ensure the product is accessible to to users of all levels of ability. There is regular testing and a process with SLAs for getting issues addressed quickly.

• Accessibility guidelines

• Accessibility testing and SLAs

Ask about accessibility on StackOverflow

Deploying your extension

Learn how to deploy your extension to the various clouds and environments.

• Extension registration, environments, clouds and Ibiza team SLAs

• Moving an extension from private preview to public preview to GA

Ask a deployment question on Stackoverflow

Deployment using the Extension Hosting Service

The Ibiza team provides and operates a common Extension Hosting Service that makes it easy to get your bits into a globally distributed system without having to manage your own infrastructure.

• Extension Hosting Service overview

• Onboarding your extension to the Extension Hosting Service

• Registring your extension with the Extension Hosting Service

• Deploying a new version of an extension

• Deploying your extension using Express V2 and the Extension Hosting Service

• SLA for registering an extension with the Extension Hosting Service

Custom extension deployment infrastructure

You should strive to use the Extension Hosting Service. If for some reason this is not possible then learn how to build a custom extension deployment infrastructure.

Legacy features

These features are supported, but have had no recent investment. No additional investment is planned. There are modern capabilities that should be used instead if you are developing new features.

• PDL-based programming

• Legacy parts

• Legacy data management feature

• Controls in the MsPortalFx namespace

• EditScope

Marketplace/Gallery developer resources

1. Gallery overview

2. Gallery item specifications

3. Gallery item metadata

4. Gallery item field to UI element mappings

5. Gallery package development and debugging

6. Legacy OneBox development approach

7. Using the "Add to Resource" blade

8. Your icon tile for the Azure store

9. Developer tooling and productivity

10. Gallery frequently asked questions

This is our new index which contains our refreshed docs. If you do not like our new index/docs, you can find the old index here.