Skip to content

Latest commit

 

History

History
153 lines (112 loc) · 14.7 KB

top-extensions-packages.md

File metadata and controls

153 lines (112 loc) · 14.7 KB
Raw

Azure Portal SDK packages

Updating your extension to a newer version of the SDK

Updating your extensions version of the Azure Portal SDK simply involves updating the versions of the NuGet packages and node modules that the extension references and updating any content files, such as *.d.ts and *.pde, that those packages deliver.

Updating your NuGet Packages

  • In Visual Studio
  1. In Visual Studio open your Solution and select Tools > NuGet Package Manager > Manage NuGet packages for Solution….
  2. Select all Microsoft.Portal.* NuGet packages.
  3. Click Update.
  4. Copy over /Content files to get latest *.d.ts and *.pde files.
  5. Build and fix any breaking changes, as described in Breaking changes.
  • In Visual Studio Code
  1. If you want to be specific about what packages and versions to update
    • update your /Extension/packages.config to contain the target versions you want to consume
    • delete your /packages folder that contains the old versions expanded packages
    • in vs code run npm run restore task run
    • update your *.csproj with references to the new package path where you are referencing them. (this is required as versions are in the folder names).
  2. If you want to update everything and have your *.csproj automatically updated
    • run nuget.exe update ./Extension/packages.config supplying the path to your package config. NuGet CLI details are here
  3. Copy over /Content files to get latest *.d.ts and *.pde files.
  4. Build and fix any breaking changes, as described in Breaking changes.
  • In CoreXT
  1. Find the latest SDK version number for your target environment from the SDK downloads document.
  2. Update your package.config to the latest version of the SDK.
  3. Run init.cmd. NOTE: Your $(Pkg*) references in your csproj file should automatically update to point at the newest restored NuGet.
  4. Copy over /Content files to get latest *.d.ts and *.pde files. NOTE: CoreXT does not copy content files. Typically, internal teams use either a <Target /> or a NuGetContentRestore task to rehydrate the Content files from their CxCache.
  5. Build and fix any breaking changes, as described in Breaking changes.

Package References

The Azure Portal SDK ships framework assemblies, tools and test framework files as NuGet packages and node modules. In addition extension teams ship PDE files as NuGet packages that allow extensions to invoke blades and parts from other extensions at runtime. For more information about sharing extension PDE files as NuGet packages, see portalfx-pde-publish.md.

Configure NuGet package sources for development

In order to download the NuGet packages required for extension development connect to an Azure DevOps Artifact registry choose a configuration that applies to your extension development context.

Microsoft Internal NuGet Feed

Portal SDK NuGet packages are published to an internal Azure DevOps Artifact registry.

NuGet packages are published to the Official feed for internal consumers and then mirrored to the AzurePortal feed. For internal teams depending on your internal build system the configuration of how to consume this feed will vary. For the latest guidance on consuming the feed within your build system, consult your build system's documentation. For those using 1ES systems, see the NuGet in 1ES guide located at https://www.1eswiki.com/wiki/NuGet_in_1ES.

Note that the Official feed only contains NuGet packages, while the AzurePortal feed contains both NuGet packages and node modules.

Third party extensions should use the AzurePortal feed. To connect

  1. navigate to the Azure Portal Artifact feed
  2. Click Connect to Feed
  3. Select NuGet
  4. Follow instructions in Add this feed

Console

One time setup to Configure NPM registry for development

Portal SDK Node Modules are only published to Microsoft internal NPM registries. Once onboarded you will need to add a reference to the Azure Portal Artifact feed.

  1. navigate to the [Azure Portal Artifact feed]
  2. Click Connect to Feed
  3. Select NPM
  4. Follow instructions in Install or restore packages using NPM

Note: Do not commit your Personal Access Token (PAT). If done correctly your PAT will reside in a .npmrc in your %userprofile% not within your repo.

Console

Available Packages

Packages used by extension developers are separated into the following categories.

The following sections describe the various packages by category. All packages are available in the referenced package source. Some packages are shipped as NuGet packages, and others as Node modules. All packages in the following tables are NuGet packages unless they are annotated to be a node module.

Development

After installation, NuGet packages that are used for development can be viewed in the packages.config file or in the NuGet Package Manager tool in Visual Studio. Node modules can be viewed in package.json.

Package Purpose
@microsoft/hostingservice (node module) Contains local version of hosting service for dev/debug runtime used during extension development.
Microsoft.Portal.Tools Contains PDC, Ev2 generator, precompiler, build target files (.target), Definition files, and TypeScript compiler.
Microsoft.Portal.Framework Contains framework assemblies required for extension development.
Microsoft.Portal.Security.AadCore Contains AAD module used for auth.

Publishing in the marketplace

Package Purpose
Microsoft.Azure.Gallery.AzureGalleryUtility Contains tools to package, upload and update gallery items in the Azure Portal marketplace.
Microsoft.Azure.Gallery.Common Common packages used by Microsoft.Azure.Gallery.AzureGalleryUtility

Testing

Package Purpose Document
@microsoft/azureportal-test (node module) Provides APIs for authoring UI-based test cases with Selenium in TypeScript.
@microsoft/azureportal-ut (node module) Provides APIs for authoring Unit Tests against extension code in TypeScript. Includes runtime, APIs, test runner support, trx and junit output for CI and code coverage reporting. See top-extensions-unit-test.md for more details.
Microsoft.Portal.TestFramework Provides APIs for writing UI-based test cases with Selenium authored in CSharp. For more information about using the test framework, see top-extensions-csharp-test-framework.md.
Microsoft.Portal.TestFramework.UnitTest The @microsoft/azureportal-ut node module shipped in a NuGet package for those that cannot consume the internal package source that is located at here, or are on CoreXT or similar IDE's that require offline/disconnected builds. For more information about unit testing, see top-extensions-unit-test.md.

Shared packages

Portal Definition Exports, or PDE's, are extensions that are maintained by teams other than the Ibiza team and your team. These extensions are available for your use. This list of packages are contributed to by extension developers who are exposing functionality from their extension by way of shipping their PDE. The absence of an extension package from the list does not imply that the package does not exist, or does not ship. To verify whether an extension ships a NuGet package, reach out to the respective teams at portalfx-extensions-contacts.md or https://aka.ms/portalfx/uservoice.

Package Purpose Document
Microsoft.Portal.Extensions.KeyVault Blades and parts shared by the KeyVault extension. portalfx-pde-keyvault.md
Microsoft.Portal.Extensions.AAD Blades and parts shared by the AAD extension. portalfx-pde-adrbac.md
Microsoft.Portal.Extensions.Billing Blades and parts shared by the Billing extension. portalfx-pde-billing.md
Microsoft.Portal.Extensions.Hubs Blades and parts shared by the Hubs extension. portalfx-hubsextension-pde.md
Microsoft.Portal.Extensions.Insights Blades and parts shared by the Insights extension. portalfx-pde-azureinsights.md
Microsoft.Portal.Extensions.Monitoring Blades and parts shared by the Monitoring extension. portalfx-pde-monitoring.md

Deprecated packages

The following NuGet packages have been deprecated. Do not use these packages when building new extensions.

Package Purpose
Microsoft.Portal.Azure.Website Sideload your extension instead, as specified in top-extensions-sideloading.md.
Microsoft.Portal.Azure.WebsiteNoAuth Sideload your extension instead, as specified in top-extensions-sideloading.md.
Microsoft.Portal.Framework.Scripts Use Microsoft.Portal.TestFramework.UnitTest instead, as specified in top-extensions-unit-test.md.
Microsoft.Portal.Tools.Etw The recommended practice is to use the Extension Hosting Service as specified in top-extensions-hosting-service.md instead of custom deployment, as specified in top-extensions-custom-deployment.md. If you are self-hosting your extension, then this package provides the EtwRelatedFilesUtility.exe tool and sample configurations.
Microsoft.Portal.TypeMetadata Author typemetadata directly instead of using this package, as specified in portalfx-data-typemetadata.md#non-generated-type-metadata.
Microsoft.Portal.Tools.ContentUnbundler This NuGet has been deprecated. The recommended practice is to generate HostingService artifacts as part of native build. Extension Hosting Service.