docs: migration guide from Azure Connectors private preview#148
Open
daviburg wants to merge 7 commits into
Open
docs: migration guide from Azure Connectors private preview#148daviburg wants to merge 7 commits into
daviburg wants to merge 7 commits into
Conversation
daviburg
commented
May 14, 2026
daviburg
commented
May 14, 2026
daviburg
commented
May 14, 2026
| @@ -0,0 +1,411 @@ | |||
| # Migrating from Azure Connectors Private Preview | |||
|
|
|||
| > This guide is for developers who used the original `Azure/Connectors` private preview | |||
Member
Author
There was a problem hiding this comment.
Drop 'original' - still suggests a lineage.
daviburg
commented
May 14, 2026
| | 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 | |
Member
Author
There was a problem hiding this comment.
VS Code extension (distinct from the SDK LSP) and portal support are both in the works for the Connector Namespace and contained connections management experience. These, az rest commands and the agent SKILL.md in this repo are all based on the same underlying REST API.
daviburg
commented
May 14, 2026
|
|
||
| | Dimension | Private Preview | Current SDK | | ||
| |-----------|-----------------|-------------| | ||
| | Connection backend | Azure API Connections (`Microsoft.Web/connections`) | Connector Gateway (`Microsoft.Web/connectorGateways`) | |
Member
Author
There was a problem hiding this comment.
Although the namespace is Microsoft.Web/connectorGateways, the new service brand name is Connector Namespace, not Connector Gateway.
…s, 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
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<T>, ClientOptions, RequestFailedException, model factories, extensible enums.
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds a migration guide to help developers move from the 2021–2022 Azure/Connectors private preview to the current Connectors SDK, highlighting infrastructure, auth, setup, and API/namespace differences.
Changes:
- Adds a new end-to-end migration document covering connection backend differences and provisioning steps.
- Documents updated client instantiation patterns for .NET and TypeScript/Node.js (TokenCredential/TokenProvider-based).
- Summarizes tooling changes (VS Code extension → REST/LSP/skills) and includes a renames table.
Comment on lines
+24
to
+37
| | 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 identity passed to client | Opaque connection string | Connection runtime URL | | ||
| | C# client creation | `MicrosoftTeamsConnector.Create("<key>")` | `new TeamsClient(new Uri(runtimeUrl))` | | ||
| | TypeScript client creation | `createMicrosoftTeamsConnector("<key>")` | `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 | | ||
| | 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 | |
|
|
||
| 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). |
Comment on lines
+171
to
+177
| // 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()); |
Comment on lines
+48
to
+49
| 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. |
- 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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a migration guide for developers who used the \Azure/Connectors\ private preview (circa 2021-2022), explaining how the current SDK differs.
What this adds
A new \docs/migration-from-private-preview.md\ covering: