### Development guide - Getting started
Source: https://github.com/azure/portaldocs/blob/main/README-OLD.md
Guidance for developing Azure portal extensions, recommending declarative extensions for ease of building and maintenance. Covers supported environments, downloads, release notes, breaking changes, CLI installation, getting started, updating the SDK, and running extensions locally.
```markdown
* [Downloads](/portal-sdk/generated/downloads.md)
* [Release notes](/portal-sdk/generated/breaking-changes.md)
* [Breaking changes](/portal-sdk/generated/breaking-changes.md)
* [Install the CLI](/portal-sdk/generated/top-ap-cli.md#setup-and-installation)
* [Get started](/portal-sdk/generated/top-extensions-getting-started.md)
* [Updating the SDK](/portal-sdk/generated/top-extensions-packages.md#updating-your-extension-to-a-newer-version-of-the-sdk)
* [Running your extension locally (a.k.a. sideloading)](/portal-sdk/generated/top-extensions-sideloading.md)
```
--------------------------------
### Getting Started with Azure Portal Extensions
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/portalfx-extension-development.md
Guides for setting up your development environment and starting to build Azure Portal extensions. Includes information on sample extensions.
```markdown
"gitdown": "include-headings", "file": "../templates/portalfx-howitworks.md"
"gitdown": "include-headings", "file": "../templates/top-extensions-getting-started.md"
"gitdown": "include-headings", "file": "../templates/portalfx-sample-extensions.md"
```
--------------------------------
### Getting Help and Resources
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-extensions-getting-started.md
Information on how to find help and additional resources for Azure Portal extension development. This includes links to official documentation, SDK samples, debugging guides, and community support channels like Stack Overflow.
```APIDOC
Getting Help:
- Documentation: https://aka.ms/portalfx/docs
- SDK Samples: `\My Documents\PortalSDK\FrameworkPortal\Extensions\SamplesExtension` directory, or deployed version at https://aka.ms/portalfx/samples
- Playground: https://aka.ms/portalfx/playground
- Debugging Guide: top-extensions-debugging.md
- Community Support: Stackoverflow Ibiza (https://stackoverflow.microsoft.com/questions/tagged?tagnames=ibiza)
- Supported Tags: https://aka.ms/portalfx/stackoverflow-sla
```
--------------------------------
### Install Azure Portal Developer CLI
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-extensions-getting-started.md
Installs the Azure Portal Developer CLI globally using npm. Supports specifying a version for precise control.
```bash
npm install -g @microsoft/azureportalcli
npm install -g @microsoft/azureportalcli@5.302.64701
```
--------------------------------
### Azure Portal Get Started Experience
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-declarative.md
Describes the 'Get Started' experience, a landing page format for assets that don't directly map to ARM resource types. It presents information through cards and can optionally include a menu.
```APIDOC
Get Started Experience:
- Used for assets not mapping to ARM resource types.
- Provides a landing page with cards for user guidance.
- Can optionally include a menu.
- Focuses on helping users get started with the service.
```
--------------------------------
### Getting Started View Configuration
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/portalfx-declarative-overview.md
This JSON object defines the structure and content for the 'Getting Started' view in the Declarative Resource Overview blade. It includes properties for title, description, learn more links, and a list of features, each with its own configuration for actions and display.
```json
{
"kind": "GetStarted",
"title": {
"property": "tab1Title"
},
"description": {
"property": "tab1Description"
},
"learnMore": {
"url": "https://azure.microsoft.com/en-us/features/azure-portal/",
"ariaLabel": "Learn more about Azure Portal"
},
"features": [
{
"title": {
"property": "tab1feature1Title"
},
"description": {
"property": "tab1feature1Description"
},
"learnMore": {
"url": "https://azure.microsoft.com/en-us/features/azure-portal/",
"ariaLabel": "Learn more about Azure Portal"
},
"icon": {
"file": "../../Content/svg/engine.svg"
},
"action": {
"menu": "tags",
"displayName": {
"property": "tab1feature1actionDisplayName"
}
}
},
{
"title": {
"property": "tab1feature2Title"
},
"description": {
"property": "tab1feature2Description"
},
"learnMore": {
"url": "https://azure.microsoft.com/en-us/features/azure-portal/",
"ariaLabel": "Learn more about Azure Portal"
},
"icon": {
"file": "../../Content/svg/engine.svg"
},
"action": {
"blade": {
"name": "ActiveDirectoryMenuBlade",
"extension": "Microsoft_AAD_IAM"
},
"displayName": {
"property": "tab1feature2actionDisplayName"
}
}
},
{
"title": {
"property": "tab1feature3Title"
},
"description": {
"property": "tab1feature3Description"
},
"learnMore": {
"url": "https://azure.microsoft.com/en-us/features/azure-portal/",
"ariaLabel": "Learn more about Azure Portal"
},
"icon": {
"file": "../../Content/svg/msi.svg"
},
"action": {
"url": "https://www.azure.com",
"displayName": {
"property": "tab1feature3actionDisplayName"
}
}
}
]
}
```
--------------------------------
### Start Azure Portal Extension
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-extensions-getting-started.md
Launches a side-loaded Azure Portal extension. Requires running the command prompt or IDE as administrator.
```bash
# Command Prompt (as administrator)
cd ./src/Default/Extension
ap start
```
```powershell
# Visual Studio Code (as administrator)
# Ctl+Shift+P > Tasks: Run Task > npm: start
```
```powershell
# Visual Studio (as administrator)
# Open /src/Default.sln in Visual Studio *as Admin* > Press F5
```
--------------------------------
### Add Getting Started View to Declarative Resource Overview
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/samples/dx/views/GetStartedTab.md
This JSON configuration snippet demonstrates how to add a 'Getting Started' view to the `properties.tabs` section of the Declarative Resource Overview schema. It defines the structure for a tab, including its title, description, learn more links, and a list of features, each with its own title, description, icon, and action.
```json
{
"kind": "GetStarted",
"title": {
"property": "tab1Title"
},
"description": {
"property": "tab1Description"
},
"learnMore": {
"url": "https://azure.microsoft.com/en-us/features/azure-portal/",
"ariaLabel": "Learn more about Azure Portal"
},
"features": [
{
"title": {
"property": "tab1feature1Title"
},
"description": {
"property": "tab1feature1Description"
},
"learnMore": {
"url": "https://azure.microsoft.com/en-us/features/azure-portal/",
"ariaLabel": "Learn more about Azure Portal"
},
"icon": {
"file": "../../Content/svg/engine.svg"
},
"action": {
"menu": "tags",
"displayName": {
"property": "tab1feature1actionDisplayName"
}
}
},
{
"title": {
"property": "tab1feature2Title"
},
"description": {
"property": "tab1feature2Description"
},
"learnMore": {
"url": "https://azure.microsoft.com/en-us/features/azure-portal/",
"ariaLabel": "Learn more about Azure Portal"
},
"icon": {
"file": "../../Content/svg/engine.svg"
},
"action": {
"blade": {
"name": "ActiveDirectoryMenuBlade",
"extension": "Microsoft_AAD_IAM"
},
"displayName": {
"property": "tab1feature2actionDisplayName"
}
}
},
{
"title": {
"property": "tab1feature3Title"
},
"description": {
"property": "tab1feature3Description"
},
"learnMore": {
"url": "https://azure.microsoft.com/en-us/features/azure-portal/",
"ariaLabel": "Learn more about Azure Portal"
},
"icon": {
"file": "../../Content/svg/msi.svg"
},
"action": {
"url": "https://www.azure.com",
"displayName": {
"property": "tab1feature3actionDisplayName"
}
}
}
]
}
```
--------------------------------
### Onboarding Request Form Details
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/portalfx-telemetry-getting-started.md
This section details the questions and acknowledgements required when submitting an onboarding request for programmatic access to Azure databases. It covers team information, access reasons, database selection, security policies, data handling compliance (PII & GDPR), application load, query examples, service principal details, contact information, and Kusto Client SDK usage.
```APIDOC
Onboarding Request Form:
1. Email Ibiza Telemetry to discuss needs.
2. Team name.
3. Reason for access.
4. Databases required (AzurePortal, AzPtlCosmos, hostingservice).
5. Acknowledge understanding of 'anonymous' access to production logs and usage restrictions.
6. Acknowledge adherence to Microsoft best practices for key storage (e.g., KeyVault).
7. Acknowledge compliance with Microsoft PII & GDPR policies for data access, including restrictions on copying/downloading non-anonymized logs and proxy access.
8. Acknowledge application must not put excessive load on the cluster.
9. Provide query examples and schedule/frequency.
10. AAD App ID or dSTS App Id.
11. If using AAD Service Principal, confirm certificate-based authentication.
12. Provide a team alias for contact during outages or capacity planning.
13. If using Kusto Client SDK, confirm setting ClientRequestProperties.Application or ClientRequestId.
14. If write access is needed (create functions/tables), provide a dedicated database name.
```
--------------------------------
### Get SDK, Docs, and Samples
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-onboarding-old.md
Guidance on how to obtain the necessary SDK, documentation, and samples for Azure Portal extension development. It points to the development guide for detailed information.
```markdown
The [development guide](top-extensions-getting-started.md) located in the main documentation index has all the right pointers.
```
--------------------------------
### Creating a Certificate-backed Partner Service Principal
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/portalfx-telemetry-getting-started.md
Details the prerequisites and steps for creating a certificate-backed service principal for partners in the Azure portal.
```APIDOC
Creating a Certificate-backed Partner Service Principal:
Pre-requisites:
- A Base64-encoded X.509 Certificate (.cer) file with the certificate to be used.
```
--------------------------------
### Create New Azure Portal Extension
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-extensions-getting-started.md
Creates a new Azure Portal extension project with a specified name and output directory using the Azure Portal Developer CLI.
```bash
ap new -n Microsoft_Azure_YourExtension -o ./targetdirectory
```
--------------------------------
### Create and Start a New Azure Portal Extension
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-isv-setup.md
This snippet demonstrates the command-line interface (CLI) commands to create a new Azure portal extension. It includes navigating directories, initializing a new extension with a specified name and output path, and starting the extension for sideloading against the production portal.
```bash
cd c:\ && mkdir dev && cd dev
ap new -d -n CompanyName_MyService -o ./MyService
cd ./MyService/src/default/extension
ap start
```
--------------------------------
### Portal SDK CLI Commands
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-extensions-getting-started.md
Essential commands for developing Azure Portal extensions using the Portal SDK CLI. These commands facilitate building, serving, and watching for changes during development.
```bash
ap build
ap serve
ap watch
```
--------------------------------
### Kusto Query Best Practices
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/portalfx-telemetry-getting-started.md
Provides guidance on optimizing Kusto queries for performance and understanding query history. Includes tips on viewing query cost and accessing past queries.
```APIDOC
Kusto Query Best Practices:
When testing your queries, you can see the performance cost of current query in the Query Summary tab of the results window.
You can also see 30 days of history of queries you have run via *.show* queries command.
*Note:* *where* and other clauses can be applied to the output of the *.show* command.
You can see the statistics and load history for the AzPortalPartner cluster at https://aka.ms/GaugePartnerCluster.
```
--------------------------------
### Getting Started Links Reference
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/dx-getstarted-tutorials-gettingStartedLinksReference.md
Defines the structure for an array of items, where each item represents a link with properties for title, action, and an optional feature.
```APIDOC
getstarted-tutorials-gettingStartedLinksReference:
description: An array of items, where each item is of the type:
- title: (string, required) Title for the tile
- action: (array, required) An array of items where each item is of the type dx-getstarted-gettingStartedActionReference.
- fx.feature: (string, optional) Feature property.
```
--------------------------------
### Azure Portal Onboarding Resources
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-onboarding-old.md
Provides links to key resources for getting started with Azure portal development, including onboarding, architecture, samples, and authentication.
```markdown
| Link | Description |
| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| [Getting Started](https://aka.ms/portalfx/onboarding/gettingstarted) | How To: Getting started with Azure portal SDK |
| [Architecture](https://aka.ms/portalfx/onboarding/architecture) | Azure portal architecture |
| [Onboarding PPT](https://aka.ms/portalfx/onboarding/ppt) | Azure portal Onboarding Powerpoint Slides |
| [Samples Playground](https://aka.ms/portalfx/onboarding/ppt) | Azure portal Samples Playground |
| [Authentication in Azure portal](https://aka.ms/portalfx/auth) | How To: Azure portal authentication |
```
--------------------------------
### Web.config Setting Example
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-extensions-hosting-service-legacy-contentunbundler.md
Demonstrates how to configure a setting in web.config for the Azure portal framework. The framework maps the key format 'Microsoft.Azure.MyExtension.MySetting' to a client-friendly format 'mySetting'.
```xml
```
--------------------------------
### Corext Environments: Setup Commands
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-extensions-unit-test.md
This section provides the necessary commands to execute after updating configuration files for Corext environments, including running Corext Init and Npm install.
```powershell
init
npm run init
```
--------------------------------
### Azure Portal CLI Authentication
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-extensions-getting-started.md
Provides instructions for authenticating with the Azure Portal feed using npm, including steps for configuring the .npmrc file.
```bash
# Connect to feed
# Select npm in the left nav of the dialog that opens
# Follow the instructions in the dialog to add PAT to .npmrc
```
--------------------------------
### QuickStart Icon
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/portalfx-icons-builtin.md
Represents the 'QuickStart' icon in the Azure Portal. This SVG icon is used for quick start guides or initial setup processes.
```svg
```
--------------------------------
### Azure Portal Icon: Quickstart
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/portalfx-icons-builtin.md
Represents a quickstart guide or feature. This SVG icon is used to visually indicate entry points for getting started quickly with a service or feature.
```svg
```
--------------------------------
### A/B Testing Integration with Ibiza
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-onboarding.md
Guidance on integrating extensions with the Ibiza Experimentation Platform for A/B testing and feature flighting. It provides links to the ExP Experimentation Platform and Ibiza Experimentation website.
```markdown
Ibiza offers out-of-the-box A/B testing and feature flighting through the [ExP Experimentation Platform](https://expdocs.azurewebsites.net/azureexp.html).
To learn how you can integrate your extension and learn more, visit the [Ibiza Experimentation website](https://aka.ms/Ibizaexperimentation)
```
--------------------------------
### Install Microsoft.Portal.Extensions.Monitoring
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/portalfx-pde-monitoring.md
Installs the Microsoft.Portal.Extensions.Monitoring NuGet package using the Package Manager Console. Ensure you use the latest version available from the specified source.
```powershell
Install-Package Microsoft.Portal.Extensions.Monitoring -Source https://msazure.pkgs.visualstudio.com/DefaultCollection/_packaging/Official/nuget/v3/index.json -Version 1.0.26.0
```
--------------------------------
### TutorialsTab Configuration Snippet
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/dx-getstarted-TutorialsTab.md
A sample JSON snippet demonstrating how to configure the Tutorials view within the Declarative Resource Overview schema. It includes properties for tiles, videos, and links groups, with examples of how to define display names, icons, descriptions, and actions.
```json
{
"kind": "Tutorials",
"tilesGroup": {
"displayName": {
"property": "freeTrainingsFromMicrosoft"
},
"items": [
{
"title": {
"property": "tile1Title"
},
"icon": "MsPortalFx.Base.Images.Polychromatic.Learn",
"subtitle": {
"property": "tile1Subtitle"
},
"description": {
"property": "tile1Description"
},
"action": {
"url": "https://www.azure.com",
"displayName": {
"property": "start"
}
}
}
]
},
"videosGroup": {
"displayName": {
"property": "tab2videosTitle"
},
"items": [
{
"title": {
"property": "tab2feature1Title"
},
"description": {
"property": "tab2feature1Description"
},
"learnMore": {
"url": "https://www.azure.com",
"ariaLabel": "Learn more about Azure"
},
"video": {
"src": "https://www.youtube.com/watch?v=KXkBZCe699A"
}
}
]
},
"linksGroup": {
"displayName": "Useful links",
"items": [
{
"title": "Concepts",
"action": [
{
"url": "https://azure.microsoft.com/en-us/",
"displayName": "Azure Managed applications overview"
},
{
"url": "https://azure.microsoft.com/en-us/",
"displayName": "Service Catalog applications"
},
{
"url": "https://azure.microsoft.com/en-us/",
"displayName": "Managed applications in Azure Marketplace"
}
]
}
]
}
}
```
--------------------------------
### Azure Portal Onboarding Useful Links
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-onboarding.md
A collection of essential links for Azure portal extension development and onboarding, covering architecture, SDK usage, gallery packages, authentication, and release pipelines.
```APIDOC
Useful Links:
- Architecture: https://aka.ms/portalfx/onboarding/architecture
- Getting Started: https://aka.ms/portalfx/onboarding/gettingstarted
- Gallery Packages: https://github.com/Azure/portaldocs/blob/master/gallery-sdk/generated/index-gallery.md#gallery-overview
- Onboarding PPT: https://aka.ms/portalfx/onboarding/ppt
- Samples Playground: https://aka.ms/portalfx/playground
- Authentication in Azure portal: https://aka.ms/portalfx/auth
- Azure portal Release Pipeline: https://dev.azure.com/msazure/One/_dashboards/dashboard/adf2732d-f4a9-476d-a7a7-7ab7aab4a2ad
- Hosting Service Release Pipeline: https://dev.azure.com/msazure/One/_dashboards/dashboard/25be4cd4-4fbd-45c9-b257-79baf530abbe
- Check Framework Commits: https://commits.azurewebsites.net/#repos/AzureUX-PortalFx/commits
- Check Hosting Service Commits: https://commits.azurewebsites.net/#repos/AzureUX-PortalHostingSvc/commits
- Commit History: https://commits.azurewebsites.net/#repos/AzureUX-PortalHostingSvc/commits
- Simonp-Sites Commits: http://simonp-sites/commits/search
- Simonp-Sites Pipeline: http://simonp-sites/pipeline
- Simonp-Sites Environments: http://simonp-sites/environments
```
--------------------------------
### Install Microsoft.Portal.Extensions.Insights NuGet Package
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/portalfx-pde-azureinsights.md
Installs the Microsoft.Portal.Extensions.Insights NuGet package using the Package Manager Console. It specifies the package source and version. Users are advised to check for the latest version.
```powershell
Install-Package Microsoft.Portal.Extensions.Insights -Source https://msazure.pkgs.visualstudio.com/DefaultCollection/_packaging/Official/nuget/v3/index.json -Version 5.10.0.43
```
--------------------------------
### Declarative Blade Example (JSON)
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-extensions-getting-started.md
An example of a declarative JSON file used to define a common view, such as the Overview blade, within an Azure Portal extension. This approach simplifies the creation of standard UI elements by defining their structure in JSON.
```json
../Client/Assets/Views/ResourceOverviewWithEssentials.Dx.jsonc
```
--------------------------------
### Extension Registration and Naming Conventions
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-onboarding.md
Details on registering extensions with the Azure Portal product configuration, including requirements for extension names and URLs. It references external documentation for EasyStart, naming formats, and CNAME requirements.
```markdown
Use EasyStart to perform initial registration, as well as any registration updates in the future. See top of this document for details.
* **NOTE**: Extension names must use standard extension name format, as in the example located [here](/portal-sdk/generated/top-extensions-configuration.md#configuration-file-locations-and-structure).
* **NOTE**: Extension URLs adhere to the naming requirements located in [portalfx-extensions-cnames.md](portalfx-extensions-cnames.md).
```
--------------------------------
### Install Security Certificate
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-extensions-getting-started.md
Steps to install a security certificate to resolve 'site not secure' or 'your connection is not private' errors in browsers like Edge and Chrome. This involves saving the certificate to disk, opening it, and selecting 'Local Machine' as the store location.
```APIDOC
Install Security Certificate:
1. Save the certificate to disk by clicking the highlighted areas in red.
2. Open the certificate from disk and install it.
3. For 'Store Location', select 'Local Machine' and click Next.
4. Leave remaining defaults and click through to finish.
5. Terminate all browser instances in task manager and refresh the page (F5).
```
--------------------------------
### Getting Started with Azure CDN
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/portalfx-extension-sharing-pde.md
Guides for integrating Azure CDN functionality, including NuGet package import, PDE referencing, and blade integration.
```portalfx
* Importing CDN Extension NuGet Package
* Referencing CDN PDE
* Referencing CDN Integration Blade
* Blade Inputs
* Notes and Tips
* Telemetry and Monitoring
* Contact Us
```
--------------------------------
### Alerting Onboarding for Extensions
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-onboarding.md
Information on onboarding extensions to the Azure Portal's out-of-the-box alerting infrastructure to meet quality standards. It specifies required alerts: Extension SDK Age, Performance, and Availability, and links to further documentation.
```markdown
The following alerts are required:
1. Extension SDK Age (automatically opted-in by default when onboarded to alerting)
1. Performance
1. Availability
```
--------------------------------
### MsPortalFx.Base.Images.AzureQuickstart
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/portalfx-icons-builtin.md
Provides the SVG code for the Azure Quickstart icon. This icon is used to represent quick start guides or resources within the Azure Portal.
```svg
```
--------------------------------
### Get Quick Start Blade Selection
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/portalfx-essentials.md
Provides a function to configure the selection for the 'Quick Start' blade within the Azure Portal's Essentials panel. This enables a consistent design for helping users get started with resources by linking to a custom quick start blade.
```ts
var getQuickStartSelection: MsPortalFx.ViewModels.Parts.ResourceSummary.GetDynamicBladeSelection = (inputs: Def.InputsContract) => {
return {
detailBlade: ExtensionDefinition.BladeNames.engineQuickStartBlade,
detailBladeInputs: {
id: inputs.resourceId
}
}
};
```
--------------------------------
### Azure Portal Extension Development Documentation
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/README.md
This is the main documentation page for Azure portal extension development. It provides an overview and links to various sections like announcements, getting started with default experiences, onboarding a new extension, architecture, and design guides.
```markdown
# 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](https://stackoverflow.microsoft.com/questions/tagged/ibiza-missing-docs).
## Announcements
* Docs in this github are moved to Engineering Hub [Azure Portal Framework (IbizaFx) Documentation](https://eng.ms/docs/products/azure-portal-framework-ibizafx). 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.](https://aka.ms/portalfx/dogfood-simplysecurev2)
## Get started with Default Experiences
If your resource types have public [Azure Rest API specs](https://github.com/Azure/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](https://ms.portal.azure.com) 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](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](https://msazure.visualstudio.com/One/_git/AzureUX-GeneratedExtension?path=/src/views) 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](/portal-sdk/generated/top-extensions-autogeneration.md)
## Onboarding a new extension
* [Overview / Get started](/portal-sdk/generated/top-onboarding.md)
* [Steps that do not involve the Ibiza team](/portal-sdk/generated/top-extensions-onboarding-with-related-teams.md)
* [Managing cloud/environment specific configuration](/portal-sdk/generated/top-extensions-configuration.md)
* [Production-ready metrics](/portal-sdk/generated/top-extensions-production-ready-metrics.md)
* [Partner feature request process](/portal-sdk/generated/top-extensions-partner-request.md)
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](/portal-sdk/generated/top-extensions-architecture.md)
* [Authentication flow](/portal-sdk/generated/top-extensions-authentication-flow.md)
* [Authentication procedures](/portal-sdk/generated/top-extensions-authentication-procedures.md)
## Design Guide
```
--------------------------------
### CORS Preflight Request Example
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-legacy-data.md
Illustrates the sequence of OPTIONS (preflight) and GET (actual) requests made to Azure Resource Manager when using the EntityCache setup. Each unique resource URI triggers a separate preflight request, potentially doubling the number of requests.
```APIDOC
Preflight Request:
URL: https://management.azure.com/subscriptions/74b34cf3-8c42-46d8-ac89-f18c83815ea3/resourceGroups/testresourcemove/providers/Microsoft.PortalSdk/rootResources/aresource?api-version=2014-04-01&_=1447122511837
Method: OPTIONS
Accept: */*
Response:
HTTP/1.1 200 OK
Access-Control-Allow-Methods: GET,POST,PUT,DELETE,PATCH,OPTIONS,HEAD
Access-Control-Allow-Origin: *
Access-Control-Max-Age: 3600
Actual CORS request to resource:
Request
https://management.azure.com/subscriptions/74b34cf3-8c42-46d8-ac89-f18c83815ea3/resourceGroups/somerg/providers/Microsoft.PortalSdk/rootResources/aresource?api-version=2014-04-01&_=1447122511837 HTTP/1.1
Method:GET
Response
HTTP/1.1 200 OK
...some resource data..
```
--------------------------------
### Azure Portal Extension Development Guide
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/portalfx-extensions-onboarding-overview.md
Information on obtaining the SDK, documentation, and samples for developing Azure Portal extensions. It directs users to the main documentation index for detailed guidance.
```markdown
## Get the SDK, docs, and samples to your developers
The [development guide](portalfx-extensions-getting-started.md) located in the main documentation index has all the right pointers.
```
--------------------------------
### Extending Default Experiences with Portal Extensions
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-extensions-autogeneration.md
This guide explains how to extend default Azure Portal experiences by creating a portal extension. It covers copying and adjusting generated artifacts like asset definitions and views from the AzureUX-GeneratedExtension repository to your extension project. It also details how to customize icons, strings, and ship the extension.
```APIDOC
Extending Default Experiences:
1. **Obtain Generated Artifacts:**
- Browse the [AzureUX-GeneratedExtension repo](https://msazure.visualstudio.com/One/_git/AzureUX-GeneratedExtension?path=/src) for your generated asset definition & views.
- Locate your resource provider in the "views" folder.
- Drill into your current API-version folder.
- Copy available asset definitions and dx views into your extension project.
2. **Customize Artifacts:**
- Adjust icons, strings, and make any necessary changes to the copied assets.
3. **Ship Extension:**
- Ship your extension with the customized asset definitions and views.
```
--------------------------------
### Storage Container URL Configuration
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-onboarding.md
Provides instructions for configuring the Storage Container URL, including requirements for public and sovereign clouds, separate accounts per environment, and container access settings.
```markdown
* Please enter a valid **storage container URL**.
* **Dogfood and Production extensions** can create storage accounts in public cloud subscription.
* **Sovereign clouds must always use respective cloud storage account** from the corresponding cloud subscription. **Eg: Fairfax storage account must be created in Fairfax subscription**.
* Create **separate storage account for each environment**
eg: Dogfood, Prod, Mooncake and Fairfax
* **Create a container** under the storage account with **anonymous read access**.
* Upload the [config.json](top-extensions-hosting-service.md#step-6-upload-safe-deployment-config) and the [generated zip file](top-extensions-hosting-service.md#step-1-generate-hosting-service-versioned-zip-file) from your build.
```
--------------------------------
### Alerting Configuration Example
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-telemetry-alerting.md
Example JSON configuration for enabling time zone based alerting. It includes the extension name, business hour start time in UTC, and an enabled flag.
```json
{
"extensionName": "Your_Extension_Name",
"businessHourStartTimeUtc": "4",
"enabled": true,
"environments": [
...
]
...
}
```
--------------------------------
### Azure Portal GET Call Example
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/dx-viewTypeResources-guidance.md
Demonstrates how to make a GET call to an Azure resource and display its properties in the resource overview. This is configured within the 'properties.tabs' section of the GetStarted view schema.
```json
{
"$schema": "../../Definitions/dx.schema.json",
"stringSource": "Resources/MyStrings.resjson",
"view": {
"kind": "GetStarted",
"export": true,
"parameters": [
{
"name": "id",
"type": "key"
}
],
"resources": [
{
"id": "[parameters('id')]",
"apiVersion": "2014-04-01"
},
{
"id": "/subscriptions/2a5aa7f9-d10a-4a12-bf51-a5f8a29cf0b4/resourceGroups/managedAppTest_rg/providers/ Microsoft.Storage/storageAccounts/e2eteststorageaccount",
"apiVersion": "2021-09-01",
"name": "storageAccount"
}
],
"essentials": {},
"commands": [],
"properties": {
"title": "title",
"tabs": [
{
"displayName": "Storage account name",
"value": "[resources('storageAccount').name]"
}
]
}
}
}
```
--------------------------------
### Onboarding a new extension
Source: https://github.com/azure/portaldocs/blob/main/README-OLD.md
Provides links to documentation for onboarding a new Azure portal extension, including overviews, steps not involving the Ibiza team, configuration management, production-ready metrics, and the partner feature request process.
```markdown
* [Overview / Get started](/portal-sdk/generated/top-onboarding.md)
* [Steps that do not involve the Ibiza team](/portal-sdk/generated/top-extensions-onboarding-with-related-teams.md)
* [Managing cloud/environment specific configuration](/portal-sdk/generated/top-extensions-configuration.md)
* [Production-ready metrics](/portal-sdk/generated/top-extensions-production-ready-metrics.md)
* [Partner feature request process](/portal-sdk/generated/top-extensions-partner-request.md)
```
--------------------------------
### CdnIntegrationBlade Inputs
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/portalfx-pde-cdn.md
Defines the input parameters for the CdnIntegrationBlade, including resourceId, location, and originHostname.
```APIDOC
CdnIntegrationBlade:
Inputs:
resourceId: string
Description: The ARM resource ID of the target resource.
Example: "/subscriptions/93456ca3-e4aa-4986-ab1c-98afe7a12345/resourceGroups/rg1/providers/Microsoft.ClassicStorage/storageAccounts/storagetest1"
location: string
Description: The Azure region where the resource is located.
Example: "West US", "East Asia"
originHostname: string
Description: The hostname of the service used as an origin for CDN endpoints. Should not include protocols or slashes.
Example: "storagetest1.blob.core.windows.net", "webapptest2.azurewebsites.net"
```
--------------------------------
### Azure Portal Extension Development Resources
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/portalfx-onboarding.md
Guides and resources for developing Azure Portal extensions, including SDK documentation, samples, and information on the extension hosting service.
```markdown
## Get the SDK, docs, and samples to your developers
The [development guide](top-extensions-getting-started.md) located in the main documentation index has all the right pointers.
# Phase 2 - Development
## Develop your extension
The [development guide](top-extensions-getting-started.md) located in the main documentation index has all the right pointers.
## Learn about the hosting service / plan your deployment strategy
The Ibiza team provides and operates a common extension hosting service that makes it easy to get your extension into a globally distributed system without having to manage your own infrastructure. For more information see [top-extensions-hosting-service.md](top-extensions-hosting-service.md).
For less common scenarios, you might need to do a custom deployment.
For example, if you need to talk to backend services using certificate-based authentication then you'll need controller code on the server. This is not supported with our hosting service. You should be very sure you require a custom hosting solution before going down this path.
**NOTE**: The deployment can be configured in such a way that the client portion of the extension uses the hosting service while the custom controller code can be deployed separately.
For more information, see [top-extensions-custom-deployment.md](top-extensions-custom-deployment.md).
## Register the extension with the portal product configuration
```
--------------------------------
### Community Support and Specific Areas
Source: https://github.com/azure/portaldocs/blob/main/portal-sdk/generated/top-onboarding.md
Information on where to ask developer community questions related to Azure portal extensions, including Stack Overflow tags and specific contact points for Ibiza-related inquiries.
```APIDOC
Community Support:
- Stackoverflow Tag: [ibiza-onboarding](https://stackoverflow.microsoft.com/questions/tagged/ibiza-onboarding)
- Specific Ibiza Areas: Contact relevant teams for detailed support.
```