/portaldocs

This repository contains documents for creating extension in Azure Portal. The SDK and documentation are not supported for teams outside Microsoft.

Primary LanguageJavaScriptCreative Commons Attribution 4.0 InternationalCC-BY-4.0

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

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

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.

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.

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.

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.

Samples

Samples show how to do many common development tasks.

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.

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).

Ask a question about parts on StackOverflow

Navigation

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

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.

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.

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.

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.

Ask a forms related question on StackOverflow

Common scenarios and integration points

Ask about browse integration on StackOverflow

Ask about create scenarios on StackOverflow

Other UI concepts

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.

Ask about data management on StackOverflow

Advanced development topics

Debugging

Performance

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.

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.

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.

Localization and globalization

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

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.

Ask about accessibility on StackOverflow

Deploying your extension

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

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.

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.

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.