From 828270a7efb02e11ff72bedf5c5c3e532f023a71 Mon Sep 17 00:00:00 2001 From: David Burg Date: Thu, 14 May 2026 14:48:50 -0700 Subject: [PATCH 1/7] docs: add migration guide from Azure Connectors private preview --- docs/migration-from-private-preview.md | 396 +++++++++++++++++++++++++ 1 file changed, 396 insertions(+) create mode 100644 docs/migration-from-private-preview.md diff --git a/docs/migration-from-private-preview.md b/docs/migration-from-private-preview.md new file mode 100644 index 0000000..6b42b00 --- /dev/null +++ b/docs/migration-from-private-preview.md @@ -0,0 +1,396 @@ +# Migrating from Azure Connectors Private Preview + +> This guide is for developers who used the original `Azure/Connectors` private preview +> (circa 2021–2022). It explains what changed, what was renamed, and how to update your code. +> +> The private `Azure/Connectors` repo is no longer the active development surface. +> All SDK work has moved to the public repos listed in [What Changed at a Glance](#what-changed-at-a-glance). + +--- + +## What Changed at a Glance + +| Old (Private Preview) | New (Current SDK) | +|-----------------------|-------------------| +| "Azure API Connections" | "Connector Gateway" | +| VS Code extension creates connection → copies connection string | `az rest` commands create Connector Gateway + connection → OAuth consent → runtime URL | +| `MicrosoftTeamsConnector.Create("")` | `new TeamsClient(new Uri(connectionRuntimeUrl))` | +| `createMicrosoftTeamsConnector("")` | `new TeamsClient(connectionRuntimeUrl, tokenProvider)` | +| Per-connector NuGet packages (`Azure.Connectors.MicrosoftTeams`) | Single package: `Azure.Connectors.Sdk` | +| Per-connector npm packages (`@azure/microsoftteams-connector`) | Single package: `@azure/connectors` | +| GitHub Package Registry (private, PAT required) | NuGet.org / PyPI / npm (public) | +| AutoRest V2 from `sdk/swaggers/` | Internal `CodefulSdkGenerator` (not user-facing) | +| `vscode-azureAPIConnections` VS Code extension | `Connectors-NET-LSP` language server | +| `ITokenProvider` interface | `Azure.Core.TokenCredential` | +| `Microsoft.Azure.Connectors.Sdk` namespace | `Azure.Connectors.Sdk` namespace | + +--- + +## Infrastructure Rename + +The old private preview called the backend service **Azure API Connections**. The service exposed a +per-connector REST runtime that accepted a "connection key" as an opaque string — the VS Code +extension was the primary tool for provisioning those keys. + +The service has been rebranded and re-architected as the **Connector Gateway** — a first-class ARM +resource type (`Microsoft.Web/connectorGateways`). Each Connector Gateway is a resource in your +subscription that acts as a namespace for one or more named connections. You provision and manage +it through the Azure CLI (`az rest`) rather than through a VS Code extension. + +```text +Old: "Azure API Connections" → New: "Connector Gateway" + (opaque connection key) (ARM resource + connection runtime URL) +``` + +See [docs/concepts.md](concepts.md) for a full architecture diagram. + +--- + +## Connection Setup + +### Old workflow + +The VS Code extension `vscode-azureAPIConnections` was the entry point for creating connections. +After completing the OAuth flow inside the extension, you received a connection string (an opaque +key), which you pasted into your code or configuration: + +```json +// local.settings.json (old) +{ + "Values": { + "TeamsConnectionKey": "" + } +} +``` + +### New workflow + +Connections are now ARM resources provisioned via `az rest`. The general sequence is: + +1. **Create a Connector Gateway** (`Microsoft.Web/connectorGateways`) +2. **Create a connection** (`/connections/{name}`) inside the gateway +3. **Complete OAuth consent** (browser flow or portal) +4. **Retrieve the connection runtime URL** from the ARM resource +5. **Set environment variables** in `local.settings.json` + +```powershell +# Create gateway +az rest --method PUT \ + --uri "https://management.azure.com/subscriptions/$sub/resourceGroups/$rg/providers/Microsoft.Web/connectorGateways/$gw?api-version=2026-05-01-preview" \ + --body '{"location":"eastus","identity":{"type":"SystemAssigned"},"properties":{}}' + +# Create connection +az rest --method PUT \ + --uri "https://management.azure.com/subscriptions/$sub/resourceGroups/$rg/providers/Microsoft.Web/connectorGateways/$gw/connections/teams-test?api-version=2026-05-01-preview" \ + --body '{"properties":{"connectorName":"teams"}}' +``` + +After OAuth consent, read the runtime URL: + +```powershell +az rest --method GET \ + --uri "https://management.azure.com/subscriptions/$sub/resourceGroups/$rg/providers/Microsoft.Web/connectorGateways/$gw/connections/teams-test?api-version=2026-05-01-preview" \ + --query "properties.connectionRuntimeUrl" -o tsv +``` + +```json +// local.settings.json (new) — Connector Gateway format +{ + "Values": { + "TeamsConnection__connectorGatewayName": "my-gateway", + "TeamsConnection__connectionName": "teams-test" + } +} +``` + +Or pass the runtime URL directly: + +```json +// local.settings.json (new) — direct format +{ + "Values": { + "TeamsConnection__connectionRuntimeUrl": "https://..." + } +} +``` + +The `ConnectorConnectionResolver.Resolve("TeamsConnection")` helper reads these env vars and +returns a `ConnectorConnectionOptions` that your client construction code can consume. + +For the step-by-step procedure including access policies and trigger setup, see +[docs/connection-setup.md](connection-setup.md) and the +[Connection Setup Skill](.github/skills/connection-setup/SKILL.md). + +--- + +## Client Instantiation + +### Old C# pattern + +```csharp +// Old: per-connector static factory, connection key as plain string +using Azure.Connectors.MicrosoftTeams; +using Azure.Connectors.TextAnalytics; + +var teamsConnector = MicrosoftTeamsConnector.Create(""); +var teams = await teamsConnector.GetAllTeamsAsync(); + +var textAnalytics = TextAnalyticsConnector.Create(""); +``` + +### New C# pattern + +```csharp +// New: constructor injection, connection runtime URL + TokenCredential +using Azure.Connectors.Sdk.Teams; +using Azure.Identity; + +// Defaults to ManagedIdentityCredential (system-assigned) — correct for Azure-hosted apps +using var teamsClient = new TeamsClient(new Uri(connectionRuntimeUrl)); + +// For local development, pass AzureCliCredential explicitly +using var teamsClient = new TeamsClient( + new Uri(connectionRuntimeUrl), + new AzureCliCredential()); + +var teams = await teamsClient.GetAllTeamsAsync(); +``` + +Use `ConnectorConnectionResolver` to read the runtime URL from configuration: + +```csharp +var opts = ConnectorConnectionResolver.Resolve("TeamsConnection"); +using var teamsClient = new TeamsClient( + new Uri(opts.ConnectionRuntimeUrl!), + new AzureCliCredential()); +``` + +Or, with the DI extension methods: + +```csharp +// Program.cs +builder.Services.AddTeamsClient(builder.Configuration, "TeamsConnection"); + +// Function class — resolved from DI +public class MyFunction(TeamsClient teamsClient) { … } +``` + +### Old TypeScript pattern + +```typescript +// Old: per-connector factory function, connection string from VS Code extension +import { createMicrosoftTeamsConnector } from "@azure/microsoftteams-connector"; + +const teamsClient = await createMicrosoftTeamsConnector(""); +const myTeams = await teamsClient.getAllTeams(); +``` + +### New TypeScript/Node.js pattern + +```typescript +// New: class constructor, connection runtime URL + TokenProvider +import { TeamsClient } from "@azure/connectors/generated/TeamsExtensions"; +import { ManagedIdentityTokenProvider } from "@azure/connectors"; + +const tokenProvider = new ManagedIdentityTokenProvider(); +const teamsClient = new TeamsClient(connectionRuntimeUrl, tokenProvider); + +const teams = await teamsClient.getAllTeamsAsync(); +``` + +--- + +## Authentication Model + +### Old model + +Authentication was handled entirely by the VS Code extension during connection setup. The resulting +connection key (an opaque string) was all the client needed. No Azure Identity credential was +required in application code. + +```csharp +// Old: opaque key, no credential object +var connector = MicrosoftTeamsConnector.Create(""); +``` + +### New model + +Authentication uses **Azure.Core `TokenCredential`** (the same identity model as the Azure SDK). +The credential is passed to the client constructor and used to acquire bearer tokens for the +`https://apihub.azure.com/.default` scope on every request. + +| Scenario | Credential | +|----------|-----------| +| Azure-hosted (Function App, App Service) | `ManagedIdentityCredential` (default when none specified) | +| Local development | `AzureCliCredential` (pass explicitly) | +| Service principal / CI | `ClientSecretCredential` | + +> **Why the change?** The old opaque key embedded both the identity and the service +> endpoint, which made credential rotation difficult. The new model separates concerns: +> the connection runtime URL identifies the endpoint, and the `TokenCredential` +> provides a freshly-minted access token at request time. + +--- + +## Code Generation + +### Old approach + +The private preview used **AutoRest V2** to generate per-connector client code from OpenAPI +(Swagger) files stored in the `sdk/swaggers/` directory of the private `Azure/Connectors` repo. +Developers could, in principle, run AutoRest locally to regenerate clients. + +```yaml +# AutoRest V2 configuration (sdk/autorest/readme.md excerpt) +version: V2 +azure-arm: true +# … per-connector swagger inputs … +``` + +### New approach + +Generation is handled by an internal Microsoft tool called **`CodefulSdkGenerator`** +(part of the BPM/Logic Apps Compiler toolchain). It is **not user-facing** — you do not +run it yourself. The output (`*Extensions.cs` files) is checked into the SDK repo and +updated by the SDK team when connector Swagger definitions change. + +If you need a connector that isn't yet included, open an issue in +[Azure/Connectors-NET-SDK](https://github.com/Azure/Connectors-NET-SDK/issues). + +--- + +## Package Distribution + +### Old distribution + +Per-connector packages were published to the **GitHub Package Registry** (private). Each +connector shipped as a separate package, and consumers had to add the private registry as a NuGet +source and authenticate with a Personal Access Token (PAT). + +```powershell +# One-time setup (old) +dotnet nuget add source https://nuget.pkg.github.com/Azure/index.json \ + --name AzureGPR \ + --username \ + --password \ + --store-password-in-clear-text + +# Per-connector install (old) +dotnet add package Azure.Connectors.MicrosoftTeams --version 0.0.2-alpha +dotnet add package Azure.Connectors.TextAnalytics --version 0.0.2-alpha +``` + +### New distribution + +All connectors ship in a **single public package** on NuGet.org — no PAT, no private registry. + +```bash +# .NET +dotnet add package Azure.Connectors.Sdk --prerelease + +# Python +pip install azure-connectors + +# Node.js / TypeScript +npm install @azure/connectors +``` + +--- + +## TypeScript / JavaScript Support + +### Old approach + +TypeScript support shipped as per-connector npm packages (`@azure/microsoftteams-connector`, +etc.) on the GitHub Package Registry. The packages required a private registry login and a +`postinstall` script workaround: + +```json +// package.json (old) +{ + "scripts": { + "postinstall": "npm i @azure/microsoftteams-connector --registry https://npm.pkg.github.com/Azure --save-optional" + }, + "dependencies": { + "@azure/identity": "^1.1.0", + "@azure/ms-rest-js": "^2.0.8", + "@azure/ms-rest-azure-js": "2.0.1" + } +} +``` + +### New approach + +All connectors ship in a single public npm package `@azure/connectors`, available from the +standard npm registry. The SDK is a modern ESM/CJS dual package targeting Node.js ≥ 18. + +```bash +npm install @azure/connectors +``` + +The Node.js SDK lives in [Azure/Connectors-Node-SDK](https://github.com/Azure/Connectors-Node-SDK). +Generated client files (e.g., `TeamsExtensions.ts`, `Office365Extensions.ts`) follow the same +naming conventions as the .NET SDK. + +--- + +## VS Code Extension + +### Old extension + +The old workflow centered on the **`vscode-azureAPIConnections`** VS Code extension. Its primary +purpose was connection management: authenticate to Azure, create connector connections, and copy +the resulting connection strings into your project. + +### New tooling + +The `vscode-azureAPIConnections` extension is no longer maintained. Two distinct tools now +serve different purposes: + +| Tool | Purpose | +|------|---------| +| **[Connectors-NET-LSP](https://github.com/Azure/Connectors-NET-LSP)** | Language Server Protocol server providing IntelliSense, hover docs, and code navigation for SDK development | +| **AI agent skill** ([connection-setup](../.github/skills/connection-setup/SKILL.md)) | Automates the end-to-end connection lifecycle from within VS Code Copilot Chat | + +Connection management (what the old extension did) is now handled via the Azure CLI (`az rest`) +or the AI agent skill — both described in [Connection Setup](#connection-setup) above. + +--- + +## Namespace and Type Renames + +If you were using an early release of the new SDK (before v0.9.0), you may encounter these +additional renames from the `CHANGELOG`: + +| Old | New | +|-----|-----| +| `Microsoft.Azure.Connectors.Sdk.*` namespace | `Azure.Connectors.Sdk.*` namespace | +| `Microsoft.Azure.Connectors.Sdk` NuGet package | `Azure.Connectors.Sdk` NuGet package | +| `ITokenProvider` interface | `Azure.Core.TokenCredential` | +| `DefaultAzureCredential` (old default) | `ManagedIdentityCredential` (new default) | +| `ConnectorClientOptions.MaxRetryAttempts` | `options.Retry.MaxRetries` (Azure.Core) | +| `ConnectorClientOptions.Timeout` | `options.Retry.NetworkTimeout` (Azure.Core) | +| Per-connector exception types (`Office365ConnectorException`) | `ConnectorException` (unified) | + +--- + +## Samples + +Working end-to-end samples for the current SDK are in +[Azure/Connectors-NET-Samples](https://github.com/Azure/Connectors-NET-Samples). Each sample +is an Azure Functions project that demonstrates a real connector operation (send email, +list SharePoint files, post a Teams message, etc.). + +The old `samples/` directory from the private preview repo has no equivalent mapping — the +connection setup and instantiation patterns are different enough that the old samples cannot +be ported by a simple find-and-replace. + +--- + +## Further Reading + +- [README.md](../README.md) — SDK overview, quick start, and validated connectors list +- [docs/concepts.md](concepts.md) — Architecture, glossary, Connector Gateway topology +- [docs/connection-setup.md](connection-setup.md) — Full connection provisioning walkthrough +- [CHANGELOG.md](../CHANGELOG.md) — Version-by-version breaking changes +- [GENERATION.md](../GENERATION.md) — How connector clients are generated From e95f9dad95064334241ef332aa004b3ca941b2e9 Mon Sep 17 00:00:00 2001 From: David Burg Date: Thu, 14 May 2026 15:02:35 -0700 Subject: [PATCH 2/7] docs: rework migration guide - two independent projects, not a rename --- docs/migration-from-private-preview.md | 102 +++++++++++++++---------- 1 file changed, 60 insertions(+), 42 deletions(-) diff --git a/docs/migration-from-private-preview.md b/docs/migration-from-private-preview.md index 6b42b00..b8e0eb7 100644 --- a/docs/migration-from-private-preview.md +++ b/docs/migration-from-private-preview.md @@ -1,48 +1,69 @@ # Migrating from Azure Connectors Private Preview > This guide is for developers who used the original `Azure/Connectors` private preview -> (circa 2021–2022). It explains what changed, what was renamed, and how to update your code. +> (circa 2021–2022). It explains what is different, and how to update your code and +> connection setup to use the current SDK. > > The private `Azure/Connectors` repo is no longer the active development surface. -> All SDK work has moved to the public repos listed in [What Changed at a Glance](#what-changed-at-a-glance). + +--- + +## Two Independent Projects + +The current SDK (`Azure/Connectors-NET-SDK` and its Python and Node.js counterparts) was +built as an independent project by the Azure Functions team. It was **not** a continuation +of the original `Azure/Connectors` private preview, which was a separate effort by a +different team. The two projects happened to solve overlapping problems but made different +choices throughout. + +This matters for the migration: there is no in-place upgrade path. Adopting the current SDK +means provisioning new Azure infrastructure and rewriting the connection and client code from +scratch. --- ## What Changed at a Glance -| Old (Private Preview) | New (Current SDK) | -|-----------------------|-------------------| -| "Azure API Connections" | "Connector Gateway" | -| VS Code extension creates connection → copies connection string | `az rest` commands create Connector Gateway + connection → OAuth consent → runtime URL | -| `MicrosoftTeamsConnector.Create("")` | `new TeamsClient(new Uri(connectionRuntimeUrl))` | -| `createMicrosoftTeamsConnector("")` | `new TeamsClient(connectionRuntimeUrl, tokenProvider)` | -| Per-connector NuGet packages (`Azure.Connectors.MicrosoftTeams`) | Single package: `Azure.Connectors.Sdk` | -| Per-connector npm packages (`@azure/microsoftteams-connector`) | Single package: `@azure/connectors` | -| GitHub Package Registry (private, PAT required) | NuGet.org / PyPI / npm (public) | -| AutoRest V2 from `sdk/swaggers/` | Internal `CodefulSdkGenerator` (not user-facing) | -| `vscode-azureAPIConnections` VS Code extension | `Connectors-NET-LSP` language server | -| `ITokenProvider` interface | `Azure.Core.TokenCredential` | -| `Microsoft.Azure.Connectors.Sdk` namespace | `Azure.Connectors.Sdk` namespace | +| Dimension | Private Preview | Current SDK | +|-----------|-----------------|-------------| +| Connection backend | Azure API Connections (`Microsoft.Web/connections`) | Connector Gateway (`Microsoft.Web/connectorGateways`) | +| Connection setup | VS Code extension (`vscode-azureAPIConnections`) | `az rest` commands + OAuth consent | +| Connection identity passed to client | Opaque connection string | Connection runtime URL | +| C# client creation | `MicrosoftTeamsConnector.Create("")` | `new TeamsClient(new Uri(runtimeUrl))` | +| TypeScript client creation | `createMicrosoftTeamsConnector("")` | `new TeamsClient(runtimeUrl, tokenProvider)` | +| Auth in app code | None — key embedded auth | `Azure.Core.TokenCredential` | +| C# packages | Per-connector on GitHub Package Registry (private) | Single `Azure.Connectors.Sdk` on NuGet.org | +| TypeScript packages | Per-connector on GitHub Package Registry (private) | Single `@azure/connectors` on npm | +| Code generation | AutoRest V2, user-runnable | Internal `CodefulSdkGenerator`, not user-facing | +| VS Code tooling | Connection management extension | LSP server for IntelliSense | --- -## Infrastructure Rename +## Connection Backend: Two Distinct Azure Resource Types -The old private preview called the backend service **Azure API Connections**. The service exposed a -per-connector REST runtime that accepted a "connection key" as an opaque string — the VS Code -extension was the primary tool for provisioning those keys. +**Azure API Connections still exist.** They are the `Microsoft.Web/connections` resource type, +have been in production since the early days of Azure Logic Apps, and continue to power Logic Apps +Consumption and Standard today. The private preview SDK used these connections — the +`vscode-azureAPIConnections` extension was a thin UI over the same ARM resource type. -The service has been rebranded and re-architected as the **Connector Gateway** — a first-class ARM -resource type (`Microsoft.Web/connectorGateways`). Each Connector Gateway is a resource in your -subscription that acts as a namespace for one or more named connections. You provision and manage -it through the Azure CLI (`az rest`) rather than through a VS Code extension. +The current SDK introduces a **completely separate** resource type: the **Connector Gateway** +(`Microsoft.Web/connectorGateways`). These are not a renaming or evolution of API Connections. +They are a distinct ARM resource with their own resource provider path, their own API version, +and their own connection runtime URL format. ```text -Old: "Azure API Connections" → New: "Connector Gateway" - (opaque connection key) (ARM resource + connection runtime URL) +Azure API Connections (still exist, used by Logic Apps): + /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Web/connections/{name} + +Connector Gateway (new, used by the current SDK): + /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Web/connectorGateways/{gw} + /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Web/connectorGateways/{gw}/connections/{name} ``` -See [docs/concepts.md](concepts.md) for a full architecture diagram. +When you migrate, you provision **new** Connector Gateway resources. Your existing Azure API +Connections are not affected and do not need to be deleted or converted. + +See [docs/concepts.md](concepts.md) for a full architecture diagram of the Connector Gateway model. --- @@ -50,9 +71,10 @@ See [docs/concepts.md](concepts.md) for a full architecture diagram. ### Old workflow -The VS Code extension `vscode-azureAPIConnections` was the entry point for creating connections. -After completing the OAuth flow inside the extension, you received a connection string (an opaque -key), which you pasted into your code or configuration: +The VS Code extension `vscode-azureAPIConnections` was the entry point for creating Azure API +Connections (`Microsoft.Web/connections`). After completing the OAuth flow inside the extension, +you received a connection string (an opaque key derived from the API Connection resource), which +you pasted into your code or configuration: ```json // local.settings.json (old) @@ -65,7 +87,8 @@ key), which you pasted into your code or configuration: ### New workflow -Connections are now ARM resources provisioned via `az rest`. The general sequence is: +Connector Gateway connections are ARM resources under a distinct resource type, provisioned via +`az rest`. The general sequence is: 1. **Create a Connector Gateway** (`Microsoft.Web/connectorGateways`) 2. **Create a connection** (`/connections/{name}`) inside the gateway @@ -225,20 +248,15 @@ The credential is passed to the client constructor and used to acquire bearer to | Local development | `AzureCliCredential` (pass explicitly) | | Service principal / CI | `ClientSecretCredential` | -> **Why the change?** The old opaque key embedded both the identity and the service -> endpoint, which made credential rotation difficult. The new model separates concerns: -> the connection runtime URL identifies the endpoint, and the `TokenCredential` -> provides a freshly-minted access token at request time. - --- ## Code Generation -### Old approach +### Private preview approach The private preview used **AutoRest V2** to generate per-connector client code from OpenAPI (Swagger) files stored in the `sdk/swaggers/` directory of the private `Azure/Connectors` repo. -Developers could, in principle, run AutoRest locally to regenerate clients. +Developers could run AutoRest locally to regenerate or customize clients. ```yaml # AutoRest V2 configuration (sdk/autorest/readme.md excerpt) @@ -247,12 +265,12 @@ azure-arm: true # … per-connector swagger inputs … ``` -### New approach +### Current SDK approach -Generation is handled by an internal Microsoft tool called **`CodefulSdkGenerator`** -(part of the BPM/Logic Apps Compiler toolchain). It is **not user-facing** — you do not -run it yourself. The output (`*Extensions.cs` files) is checked into the SDK repo and -updated by the SDK team when connector Swagger definitions change. +The current SDK's generated files (`*Extensions.cs`, `*Extensions.ts`, etc.) are produced by an +internal Microsoft tool called **`CodefulSdkGenerator`** (part of the Logic Apps Compiler +toolchain). It is **not user-facing** — you do not run it yourself. The generated client files +are checked into each SDK repo and updated by the team when connector Swagger definitions change. If you need a connector that isn't yet included, open an issue in [Azure/Connectors-NET-SDK](https://github.com/Azure/Connectors-NET-SDK/issues). From 49b15b169bea28a82ad9f3a9bf914b3cb7921738 Mon Sep 17 00:00:00 2001 From: David Burg Date: Thu, 14 May 2026 15:14:14 -0700 Subject: [PATCH 3/7] docs: remove team names - irrelevant to external customers --- docs/migration-from-private-preview.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/migration-from-private-preview.md b/docs/migration-from-private-preview.md index b8e0eb7..9179921 100644 --- a/docs/migration-from-private-preview.md +++ b/docs/migration-from-private-preview.md @@ -11,10 +11,9 @@ ## Two Independent Projects The current SDK (`Azure/Connectors-NET-SDK` and its Python and Node.js counterparts) was -built as an independent project by the Azure Functions team. It was **not** a continuation -of the original `Azure/Connectors` private preview, which was a separate effort by a -different team. The two projects happened to solve overlapping problems but made different -choices throughout. +built as an independent project by a different Microsoft team. It was **not** a continuation +of the original `Azure/Connectors` private preview. The two projects happened to solve +overlapping problems but made different choices throughout. This matters for the migration: there is no in-place upgrade path. Adopting the current SDK means provisioning new Azure infrastructure and rewriting the connection and client code from From 4ebd5f13c1a5e838e4526ba8557d2a7bfc75f257 Mon Sep 17 00:00:00 2001 From: David Burg Date: Thu, 14 May 2026 15:17:55 -0700 Subject: [PATCH 4/7] docs: remove line implying transition between projects --- docs/migration-from-private-preview.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/migration-from-private-preview.md b/docs/migration-from-private-preview.md index 9179921..7b46b7a 100644 --- a/docs/migration-from-private-preview.md +++ b/docs/migration-from-private-preview.md @@ -3,8 +3,6 @@ > This guide is for developers who used the original `Azure/Connectors` private preview > (circa 2021–2022). It explains what is different, and how to update your code and > connection setup to use the current SDK. -> -> The private `Azure/Connectors` repo is no longer the active development surface. --- From 88507422cfcaad603a2311156a5358aab7fedfe1 Mon Sep 17 00:00:00 2001 From: David Burg Date: Thu, 14 May 2026 15:31:36 -0700 Subject: [PATCH 5/7] docs: address PR review - Connector Namespace branding, tooling status, trigger comparison - Drop 'original' from intro (avoids implying lineage) - Rebrand 'Connector Gateway' to 'Connector Namespace' (service brand name) - VS Code extension and portal for connection management both in progress - Add Trigger Support section (private preview had none; current SDK has Connector Namespace polling triggers with [ConnectorTrigger] binding) - Add trigger row to comparison table --- docs/migration-from-private-preview.md | 106 ++++++++++++++++++------- 1 file changed, 77 insertions(+), 29 deletions(-) diff --git a/docs/migration-from-private-preview.md b/docs/migration-from-private-preview.md index 7b46b7a..e591a3d 100644 --- a/docs/migration-from-private-preview.md +++ b/docs/migration-from-private-preview.md @@ -1,6 +1,6 @@ # Migrating from Azure Connectors Private Preview -> This guide is for developers who used the original `Azure/Connectors` private preview +> This guide is for developers who used the `Azure/Connectors` private preview > (circa 2021–2022). It explains what is different, and how to update your code and > connection setup to use the current SDK. @@ -23,8 +23,8 @@ scratch. | Dimension | Private Preview | Current SDK | |-----------|-----------------|-------------| -| Connection backend | Azure API Connections (`Microsoft.Web/connections`) | Connector Gateway (`Microsoft.Web/connectorGateways`) | -| Connection setup | VS Code extension (`vscode-azureAPIConnections`) | `az rest` commands + OAuth consent | +| Connection backend | Azure API Connections (`Microsoft.Web/connections`) | Connector Namespace (`Microsoft.Web/connectorGateways`) | +| Connection setup | VS Code extension (`vscode-azureAPIConnections`) | REST API (`az rest`, VS Code extension, portal — all planned) | | Connection identity passed to client | Opaque connection string | Connection runtime URL | | C# client creation | `MicrosoftTeamsConnector.Create("")` | `new TeamsClient(new Uri(runtimeUrl))` | | TypeScript client creation | `createMicrosoftTeamsConnector("")` | `new TeamsClient(runtimeUrl, tokenProvider)` | @@ -32,7 +32,8 @@ scratch. | C# packages | Per-connector on GitHub Package Registry (private) | Single `Azure.Connectors.Sdk` on NuGet.org | | TypeScript packages | Per-connector on GitHub Package Registry (private) | Single `@azure/connectors` on npm | | Code generation | AutoRest V2, user-runnable | Internal `CodefulSdkGenerator`, not user-facing | -| VS Code tooling | Connection management extension | LSP server for IntelliSense | +| VS Code tooling | Connection management extension | LSP server for IntelliSense; connection management extension and portal in progress | +| Trigger support | None | Connector Namespace polling triggers with `[ConnectorTrigger]` Azure Functions binding | --- @@ -43,7 +44,7 @@ have been in production since the early days of Azure Logic Apps, and continue t Consumption and Standard today. The private preview SDK used these connections — the `vscode-azureAPIConnections` extension was a thin UI over the same ARM resource type. -The current SDK introduces a **completely separate** resource type: the **Connector Gateway** +The current SDK introduces a **completely separate** resource type: the **Connector Namespace** (`Microsoft.Web/connectorGateways`). These are not a renaming or evolution of API Connections. They are a distinct ARM resource with their own resource provider path, their own API version, and their own connection runtime URL format. @@ -52,15 +53,15 @@ and their own connection runtime URL format. Azure API Connections (still exist, used by Logic Apps): /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Web/connections/{name} -Connector Gateway (new, used by the current SDK): - /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Web/connectorGateways/{gw} - /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Web/connectorGateways/{gw}/connections/{name} +Connector Namespace (new, used by the current SDK): + /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Web/connectorGateways/{ns} + /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Web/connectorGateways/{ns}/connections/{name} ``` -When you migrate, you provision **new** Connector Gateway resources. Your existing Azure API +When you migrate, you provision **new** Connector Namespace resources. Your existing Azure API Connections are not affected and do not need to be deleted or converted. -See [docs/concepts.md](concepts.md) for a full architecture diagram of the Connector Gateway model. +See [docs/concepts.md](concepts.md) for a full architecture diagram of the Connector Namespace model. --- @@ -84,24 +85,25 @@ you pasted into your code or configuration: ### New workflow -Connector Gateway connections are ARM resources under a distinct resource type, provisioned via -`az rest`. The general sequence is: +Connector Namespace connections are ARM resources under a distinct resource type, provisioned via +the underlying REST API. Today the primary tool is `az rest`; a dedicated VS Code extension and +Azure Portal experience are both in development. The general sequence is: -1. **Create a Connector Gateway** (`Microsoft.Web/connectorGateways`) -2. **Create a connection** (`/connections/{name}`) inside the gateway +1. **Create a Connector Namespace** (`Microsoft.Web/connectorGateways`) +2. **Create a connection** (`/connections/{name}`) inside the namespace 3. **Complete OAuth consent** (browser flow or portal) 4. **Retrieve the connection runtime URL** from the ARM resource 5. **Set environment variables** in `local.settings.json` ```powershell -# Create gateway +# Create Connector Namespace az rest --method PUT \ - --uri "https://management.azure.com/subscriptions/$sub/resourceGroups/$rg/providers/Microsoft.Web/connectorGateways/$gw?api-version=2026-05-01-preview" \ + --uri "https://management.azure.com/subscriptions/$sub/resourceGroups/$rg/providers/Microsoft.Web/connectorGateways/$ns?api-version=2026-05-01-preview" \ --body '{"location":"eastus","identity":{"type":"SystemAssigned"},"properties":{}}' # Create connection az rest --method PUT \ - --uri "https://management.azure.com/subscriptions/$sub/resourceGroups/$rg/providers/Microsoft.Web/connectorGateways/$gw/connections/teams-test?api-version=2026-05-01-preview" \ + --uri "https://management.azure.com/subscriptions/$sub/resourceGroups/$rg/providers/Microsoft.Web/connectorGateways/$ns/connections/teams-test?api-version=2026-05-01-preview" \ --body '{"properties":{"connectorName":"teams"}}' ``` @@ -109,15 +111,15 @@ After OAuth consent, read the runtime URL: ```powershell az rest --method GET \ - --uri "https://management.azure.com/subscriptions/$sub/resourceGroups/$rg/providers/Microsoft.Web/connectorGateways/$gw/connections/teams-test?api-version=2026-05-01-preview" \ + --uri "https://management.azure.com/subscriptions/$sub/resourceGroups/$rg/providers/Microsoft.Web/connectorGateways/$ns/connections/teams-test?api-version=2026-05-01-preview" \ --query "properties.connectionRuntimeUrl" -o tsv ``` ```json -// local.settings.json (new) — Connector Gateway format +// local.settings.json (new) — Connector Namespace format { "Values": { - "TeamsConnection__connectorGatewayName": "my-gateway", + "TeamsConnection__connectorGatewayName": "my-namespace", "TeamsConnection__connectionName": "teams-test" } } @@ -359,16 +361,18 @@ the resulting connection strings into your project. ### New tooling -The `vscode-azureAPIConnections` extension is no longer maintained. Two distinct tools now -serve different purposes: +The `vscode-azureAPIConnections` extension is no longer maintained. The current SDK ecosystem +provides multiple tools — some available today, others in progress: -| Tool | Purpose | -|------|---------| -| **[Connectors-NET-LSP](https://github.com/Azure/Connectors-NET-LSP)** | Language Server Protocol server providing IntelliSense, hover docs, and code navigation for SDK development | -| **AI agent skill** ([connection-setup](../.github/skills/connection-setup/SKILL.md)) | Automates the end-to-end connection lifecycle from within VS Code Copilot Chat | +| Tool | Status | Purpose | +|------|--------|--------| +| **[Connectors-NET-LSP](https://github.com/Azure/Connectors-NET-LSP)** | Available | Language Server Protocol server providing IntelliSense, hover docs, and code navigation for SDK development | +| **REST API** (`az rest`, agent skills) | Available | Connector Namespace and connection lifecycle via ARM REST API | +| **VS Code extension** for Connector Namespace management | In progress | Dedicated connection management experience (distinct from the LSP) | +| **Azure Portal** experience | In progress | Connector Namespace management in the Azure Portal | -Connection management (what the old extension did) is now handled via the Azure CLI (`az rest`) -or the AI agent skill — both described in [Connection Setup](#connection-setup) above. +The REST API, upcoming VS Code extension, and portal are all surfaces over the same underlying +Connector Namespace ARM API. For connection setup today, see [Connection Setup](#connection-setup). --- @@ -389,6 +393,50 @@ additional renames from the `CHANGELOG`: --- +## Trigger Support + +The private preview SDK provided **no trigger support**. Connectors were limited to +request-response actions (send email, list files, post a message, etc.). If you needed +event-driven behavior ("when a new email arrives"), you had to implement your own polling +or rely on Logic Apps. + +The current SDK supports **connector triggers** via the Connector Namespace. The Connector +Namespace manages server-side polling infrastructure and delivers events to your Azure Function +through a callback URL. Key components: + +| Component | Description | +|-----------|-------------| +| **Trigger config** | ARM resource (`/triggerConfigs/{name}`) on the Connector Namespace that defines which connector operation to poll and where to send callbacks | +| **`[ConnectorTrigger]` attribute** | Azure Functions binding attribute (from `Microsoft.Azure.Functions.Worker.Extensions.Connector`) that receives trigger callbacks as POCO payloads | +| **`TriggerCallbackPayload`** | SDK envelope type that deserializes the `{"body":{"value":[...]}}` callback structure into typed items | +| **Binary vs metadata triggers** | Some connectors offer two variants: file-content triggers deliver base64-encoded bytes, metadata triggers deliver typed property objects | + +Example: receiving new emails via a connector trigger: + +```csharp +using Azure.Connectors.Sdk.Office365; +using Microsoft.Azure.Functions.Worker; + +public class EmailTrigger(ILogger logger) +{ + [Function("OnNewEmailReceived")] + public void OnNewEmailReceived( + [ConnectorTrigger] Office365OnNewEmailTriggerPayload payload) + { + var emails = payload.Body?.Value ?? []; + foreach (var email in emails) + { + logger.LogInformation("Subject: {Subject}", email.Subject); + } + } +} +``` + +See the [Trigger Registration Skill](../.github/skills/trigger-registration/SKILL.md) for the +full setup procedure including callback URL wiring and trigger parameter discovery. + +--- + ## Samples Working end-to-end samples for the current SDK are in @@ -405,7 +453,7 @@ be ported by a simple find-and-replace. ## Further Reading - [README.md](../README.md) — SDK overview, quick start, and validated connectors list -- [docs/concepts.md](concepts.md) — Architecture, glossary, Connector Gateway topology +- [docs/concepts.md](concepts.md) — Architecture, glossary, Connector Namespace topology - [docs/connection-setup.md](connection-setup.md) — Full connection provisioning walkthrough - [CHANGELOG.md](../CHANGELOG.md) — Version-by-version breaking changes - [GENERATION.md](../GENERATION.md) — How connector clients are generated From d3b058963462f0c8b57eee99a6038b1b29677092 Mon Sep 17 00:00:00 2001 From: David Burg Date: Thu, 14 May 2026 15:34:38 -0700 Subject: [PATCH 6/7] docs: add Azure SDK guidelines comparison section Private preview did not follow Azure SDK guidelines (static factories, simple list pagination, legacy ms-rest-js). Current SDK is built on Azure.Core: AsyncPageable, ClientOptions, RequestFailedException, model factories, extensible enums. --- docs/migration-from-private-preview.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/migration-from-private-preview.md b/docs/migration-from-private-preview.md index e591a3d..8fae851 100644 --- a/docs/migration-from-private-preview.md +++ b/docs/migration-from-private-preview.md @@ -32,6 +32,7 @@ scratch. | C# packages | Per-connector on GitHub Package Registry (private) | Single `Azure.Connectors.Sdk` on NuGet.org | | TypeScript packages | Per-connector on GitHub Package Registry (private) | Single `@azure/connectors` on npm | | Code generation | AutoRest V2, user-runnable | Internal `CodefulSdkGenerator`, not user-facing | +| Azure SDK guidelines | Not followed | Follows [Azure SDK design guidelines](https://azure.github.io/azure-sdk/dotnet_introduction.html) | | VS Code tooling | Connection management extension | LSP server for IntelliSense; connection management extension and portal in progress | | Trigger support | None | Connector Namespace polling triggers with `[ConnectorTrigger]` Azure Functions binding | @@ -249,6 +250,30 @@ The credential is passed to the client constructor and used to acquire bearer to --- +## Azure SDK Design Guidelines + +The private preview SDK did not follow the +[Azure SDK design guidelines](https://azure.github.io/azure-sdk/dotnet_introduction.html). +Clients were created via static factory methods, pagination returned simple lists +(e.g., `teams.Value.FirstOrDefault(…)`), and the TypeScript SDK depended on the legacy +`@azure/ms-rest-js` library. + +The current SDK is built on Azure.Core and follows the guidelines throughout: + +| Guideline | Current SDK Implementation | +|-----------|---------------------------| +| [Client constructors](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-client-constructor-minimal) | `(Uri endpoint, TokenCredential credential, ClientOptions? options)` | +| [Pagination](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-pagination) | `AsyncPageable` with automatic next-link following | +| [Client options](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-client-options) | `ConnectorClientOptions : ClientOptions` — retry, transport, diagnostics via Azure.Core | +| [Exceptions](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-errors) | `ConnectorException : RequestFailedException` | +| [Mocking](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-mocking-factory) | Per-connector model factories, virtual service methods, protected parameterless constructors | +| [Extensible enums](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-enums) | `readonly struct` types with static known-value members, implicit string conversion | + +This means standard Azure SDK patterns (dependency injection, `AzureEventSourceListener` for +diagnostics, `HttpPipelinePolicy` for custom request/response handling) work out of the box. + +--- + ## Code Generation ### Private preview approach From e22e746759f768ba98bd189c863e1d987d39e398 Mon Sep 17 00:00:00 2001 From: David Burg Date: Thu, 14 May 2026 15:57:41 -0700 Subject: [PATCH 7/7] docs: address review round 3 + full-doc accuracy review - Drop remaining 'original' from Two Independent Projects section - Fix 'all planned' wording: az rest is available, extension/portal in progress - Fix Connection Setup Skill relative link (was resolving to docs/.github/) - Split duplicate teamsClient declaration into two compilable code blocks - Add missing 'using Microsoft.Extensions.Logging' in trigger example - Update PR description to use Connector Namespace terminology --- docs/migration-from-private-preview.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/migration-from-private-preview.md b/docs/migration-from-private-preview.md index 8fae851..586e6e5 100644 --- a/docs/migration-from-private-preview.md +++ b/docs/migration-from-private-preview.md @@ -10,8 +10,8 @@ The current SDK (`Azure/Connectors-NET-SDK` and its Python and Node.js counterparts) was built as an independent project by a different Microsoft team. It was **not** a continuation -of the original `Azure/Connectors` private preview. The two projects happened to solve -overlapping problems but made different choices throughout. +of the `Azure/Connectors` private preview. The two projects independently solved overlapping +problems but made different choices throughout. This matters for the migration: there is no in-place upgrade path. Adopting the current SDK means provisioning new Azure infrastructure and rewriting the connection and client code from @@ -24,7 +24,7 @@ scratch. | Dimension | Private Preview | Current SDK | |-----------|-----------------|-------------| | Connection backend | Azure API Connections (`Microsoft.Web/connections`) | Connector Namespace (`Microsoft.Web/connectorGateways`) | -| Connection setup | VS Code extension (`vscode-azureAPIConnections`) | REST API (`az rest`, VS Code extension, portal — all planned) | +| Connection setup | VS Code extension (`vscode-azureAPIConnections`) | REST API via `az rest` (available); VS Code extension and portal (in progress) | | Connection identity passed to client | Opaque connection string | Connection runtime URL | | C# client creation | `MicrosoftTeamsConnector.Create("")` | `new TeamsClient(new Uri(runtimeUrl))` | | TypeScript client creation | `createMicrosoftTeamsConnector("")` | `new TeamsClient(runtimeUrl, tokenProvider)` | @@ -142,7 +142,7 @@ returns a `ConnectorConnectionOptions` that your client construction code can co For the step-by-step procedure including access policies and trigger setup, see [docs/connection-setup.md](connection-setup.md) and the -[Connection Setup Skill](.github/skills/connection-setup/SKILL.md). +[Connection Setup Skill](../.github/skills/connection-setup/SKILL.md). --- @@ -163,19 +163,24 @@ var textAnalytics = TextAnalyticsConnector.Create(""); ### New C# pattern +Azure-hosted (defaults to `ManagedIdentityCredential`): + ```csharp -// New: constructor injection, connection runtime URL + TokenCredential using Azure.Connectors.Sdk.Teams; -using Azure.Identity; -// Defaults to ManagedIdentityCredential (system-assigned) — correct for Azure-hosted apps using var teamsClient = new TeamsClient(new Uri(connectionRuntimeUrl)); +var teams = await teamsClient.GetAllTeamsAsync(); +``` + +Local development (pass `AzureCliCredential` explicitly): + +```csharp +using Azure.Connectors.Sdk.Teams; +using Azure.Identity; -// For local development, pass AzureCliCredential explicitly using var teamsClient = new TeamsClient( new Uri(connectionRuntimeUrl), new AzureCliCredential()); - var teams = await teamsClient.GetAllTeamsAsync(); ``` @@ -441,6 +446,7 @@ Example: receiving new emails via a connector trigger: ```csharp using Azure.Connectors.Sdk.Office365; using Microsoft.Azure.Functions.Worker; +using Microsoft.Extensions.Logging; public class EmailTrigger(ILogger logger) {