This commit is contained in:
Bertan Aygun 2021-08-18 20:56:07 -07:00
Родитель 9c85811ee6
Коммит c7c7fb7d04
11 изменённых файлов: 52 добавлений и 74 удалений

Просмотреть файл

@ -1,16 +0,0 @@
---
title: API reference
description: A reference for the Visual Studio and Community Toolkit APIs
date: 2021-5-25
---
There are several sets of API reference documentation that you might find relevant to check out.
## The Community Visual Studio Toolkit
When using the Community Visual Studio Toolkit, make sure to check out its [API reference](https://vsixcommunity.github.io/Community.VisualStudio.Toolkit/v1/api/).
## The official SDK reference
The official API reference contain basic information about all the types found in the entire public SDK. Find it at
[Visual Studio SDK reference](https://docs.microsoft.com/visualstudio/extensibility/visual-studio-sdk-reference)

Просмотреть файл

@ -1,23 +1,50 @@
---
title: VS Extensibility
description: Welcome to Visual Studio Extensibility
description: Welcome to Visual Studio Out-of-Proc Extensibility
date: 2021-8-16
---
This site will help you write successful Visual Studio extensions and there's something for absolute beginners to experts alike!
# Visual Studio Out-Of-Process Extensibility SDK
## Pick your starting point
While the existing model loads extensions in-process, the new extensibility model brings Visual Studio extensions out-of-process. This out-of-proc model gives you the opportunity to create more reliable, secure, and easier-to-write extensions while still providing the in-depth functionality the old model provides. The following documentation describes:
Based on your experience level, pick where to begin.
* The general architecture of the new extensibility model
* How to take advantage of the new extensibility models APIs
* How to compile and F5 debug an extension with the new model
* Resources and code samples to get started writing an extension with the new model
### Learn how to get started
For future updates please bookmark our [announcements](announcements.md) page
If you are new to extension development, you want to start at the beginning to ensure you're not missing any information up front. Head on over to the [getting started guide](getting-started/).
## Getting Started
* [Introduction to new out-of-process extensibility](new-extensibility-model/getting-started/oop-extensibility-model-overview.md)
* [Create your first extension](new-extensibility-model/getting-started/create-your-first-extension.md)
### Walk me through typical scenarios
## Extension Guides
* [Parts of a new Visual Studio extension](new-extensibility-model/inside-the-sdk/extension-anatomy.md)
* [Parts of the SDK](new-extensibility-model/inside-the-sdk/inside-the-sdk.md)
* [Commands](new-extensibility-model/extension-guides/command/command.md)
* [Editor components](new-extensibility-model/extension-guides/editor/editor.md)
* [Rule based conditions](new-extensibility-model/inside-the-sdk/activation-constraints.md)
Once you know the basics of the Visual Studio extensibility model, it is time to explore what type of features to extend. To do that, check out the [recipe section](recipes/) for inspiration and step-by-step walkthroughs.
## Samples and walkthroughs
A Visual Studio solution containing all samples can be found at [Samples.sln](https://github.com/microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/Samples.sln).
### Publishing the finished extension
* [Simple command handler](new-extensibility-model/getting-started/create-your-first-extension.md) ([Source](https://github.com/microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/SimpleRemoteCommandSample))
* [Markdown Linter](new-extensibility-model/extension-guides/markdown-linter-sample.md) ([Source](https://github.com/microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/MarkdownLinter))
* [Insert guid extension sample](https://github.com/microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/InsertGuidExtension)
* [Command registration, localization sample](https://github.com/microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/CommandRegistrationsSample)
When you've written your extension, it is time to publish it. Whether you want to share it with just a few friends, your company, or the whole world, you want to check out the [publishing section](publish/).
## API Docs
The following two namespaces are primary extensibility surface provided by the SDK:
* [Microsoft.VisualStudio.Extensibility](new-extensibility-model/api/Microsoft.VisualStudio.Extensibility.md)
* [Microsoft.VisualStudio.Extensibility.Editor](new-extensibility-model/api/Microsoft.VisualStudio.Extensibility.Editor.md)
The following assemblies contain classes related to infrastructure and underlying implementation for the wrappers in the SDK:
* [Microsoft.VisualStudio.Extensibility.Framework](new-extensibility-model/api/Microsoft.VisualStudio.Extensibility.Framework.md)
* [Microsoft.VisualStudio.Extensibility.Contracts](new-extensibility-model/api/Microsoft.VisualStudio.Extensibility.Contracts.md)
* [Microsoft.VisualStudio.Extensibility.EditorHostService](new-extensibility-model/api/Microsoft.VisualStudio.Extensibility.EditorHostService.md)
* [Microsoft.VisualStudio.ProjectSystem.Query](new-extensibility-model/api/Microsoft.VisualStudio.ProjectSystem.Query.md)

Просмотреть файл

@ -10,10 +10,7 @@ Commands trigger actions in Visual Studio. They manifest as buttons parented to
## Creating new commands
To get started:
* Add a reference to the [Microsoft.VisualStudio.Extensibility](https://www.nuget.org/TODO-add-real-link) and [Microsoft.VisualStudio.Extensibility.Build](https://www.nuget.org/TODO-add-real-link) NuGet packages to your project.
* Change your project's `TargetFramework` from `net6.0` to `net6.0-windows`.
To get started, follow the [create the project](../getting-started/create-your-first-extension.md) section in Getting Started section.
### Registering a command
@ -28,7 +25,7 @@ The attribute `Microsoft.VisualStudio.Extensibility.Commands.CommandAttribute` h
| DisplayName | String | Yes | The default display name of your command. Surround this string with the '%' character to enable localizing this string. See more on this at [Localizing a command](#localizing-a-command). |
| ContainerType | Type? | No | The type that is to act as the CommandSet for this command. Setting this parameter to null automatically generates a default CommandSet for your command. |
| Placement | KnownCommandPlacement | No | Indicates where within Visual Studio your command should be parented. If no placement is provided the command defaults to being parented to the Standard toolbar. |
| ClientContext | String | No | Client contexts requested by the command, separated by ','. By default the Shell and Editor contexts are returned. A client context is a snapshot of specific IDE states at the time a command was originally executed. Since these commands are executed asynchronously this state could change between the time the user executed the command and the command handler running. See more on this at [Client contexts](./../../Inside_the_SDK/Activation_Constraints.md/#client-contexts). |
| ClientContext | String | No | Client contexts requested by the command, separated by ','. By default the Shell and Editor contexts are returned. A client context is a snapshot of specific IDE states at the time a command was originally executed. Since these commands are executed asynchronously this state could change between the time the user executed the command and the command handler running. See more on this at [Client contexts](../../inside-the-sdk/activation-constraints.md/#client-contexts). |
```csharp
[Command(CommandName, CommandId, "Sample Remote Command", placement: KnownCommandPlacement.ToolsMenu)]
@ -80,7 +77,7 @@ An example of such an expression can be seen here:
```
To see more information on valid term values:
- [Using rule based activation constraints](./../../Inside_the_SDK/Activation_Constraints.md/#rule-based-activation-constraints)
- [Using rule based activation constraints](../../inside-the-sdk/activation-constraints.md/#rule-based-activation-constraints)
### Controlling command Enabled/Disabled state
@ -98,7 +95,7 @@ An example of such an expression can be seen here:
```
To see more information on valid term values:
- [Using rule based activation constraints](./../../Inside_the_SDK/Activation_Constraints.md/#rule-based-activation-constraints)
- [Using rule based activation constraints](../../inside-the-sdk/activation-constraints.md/#rule-based-activation-constraints)
### Localizing a command

Просмотреть файл

@ -26,7 +26,7 @@ The extension consist of a single code file that defines a command and its prope
The first `Command` attribute registers the command using the unique name `Microsoft.VisualStudio.InsertGuidExtension.InsertGuidCommand` and id `1`. The command is placed in `Extensions` top menu and uses `OfficeWebExtension` icon moniker.
`CommandVisibleWhen` attribute defines when the command is visible in `Extensions` menu. You can refer to [Activation Constraints]() to learn about different options that you can use to determine command visibility and state. In this case, the command is enabled anytime there is an active editor in the IDE.
`CommandVisibleWhen` attribute defines when the command is visible in `Extensions` menu. You can refer to [Activation Constraints](../inside-the-sdk/activation-constraints.md/) to learn about different options that you can use to determine command visibility and state. In this case, the command is enabled anytime there is an active editor in the IDE.
## Getting the active editor view
@ -54,4 +54,4 @@ await this.Extensibility.Editor().MutateAsync(
## Logging errors
Each extension part including command sets is assigned a `TraceSource` instance that can be utilized to log diagnostic errors. Please see [Logging](../Inside_the_SDK/Logging.md) section for more information.
Each extension part including command sets is assigned a `TraceSource` instance that can be utilized to log diagnostic errors. Please see [Logging](../inside-the-sdk/logging.md) section for more information.

Просмотреть файл

@ -27,7 +27,7 @@ Different to previous samples, this extension implements its own class that inhe
There are 2 interesting points in the implementation of `MarkdownLinterExtension`:
* `ResourceManager` property points to the resource dictionary that contains localized entries that would be used for creating an output window pane.
* `InitializeServices` method is used to add local services to the dependency injection graph. As noted in [local services section](../Inside_the_SDK/ExtensionAnatomy.md#local-extension-services), the extension utilizes a scoped `MarkdownDiagnosticsService` as the service instance injects `VisualStudioExtensibility` object.
* `InitializeServices` method is used to add local services to the dependency injection graph. As noted in [local services section](../inside-the-sdk/extension-anatomy.md#local-extension-services), the extension utilizes a scoped `MarkdownDiagnosticsService` as the service instance injects `VisualStudioExtensibility` object.
## MarkdownDiagnosticsService local service
In this example, this local service acts as the central for managing markdown file diagnostics. It is responsible for running markdown linter on the files requested and forward errors to diagnostic service.

Просмотреть файл

@ -1,15 +0,0 @@
# Visual Studio OOP extensibility model
## Benefits
The new extensibility model is designed with the following goals in mind:
* Ease of use: We like to have well documented, simple paths for most common operations that extensions perform in Visual Studio. This should translate to shorter development time for small productivity extensions that work with existing languages in Visual Studio.
* Reliability: As we move extensions and components out-of-process, we can isolate components from which other increasing overall reliability of Visual Studio and also responsiveness of IDE in certain cases.
* Cross-product: While this is not possible today, a long term goal for this extensibility model is to be cross product compatible as it is primarily based on JsonRPC protocols to communicate with host IDE process.
## Technology
The new extensibility model is primarily built on top remote RPC contracts that are provided as brokered services from Visual Studio. The extensions are hosted in an external ServiceHub process that communicates with Visual Studio via RPC and both utilize services provided by Visual Studio and may also provide services to Visual Studio process in certain cases.
Extensibility packages that are provided as part of the SDK consist of base classes, utility methods and wrapper objects around these RPC contracts with the goal of making extensibility surface area easier to use, easier to discover and also to be able to quickly contribute to Visual Studio ecosystem such as creating a new command handler.

Просмотреть файл

@ -9,7 +9,7 @@ date: 2021-8-16
## Introduction
This document is a quick walkthrough on how to create your first extension using the new out-of-process extensibility model.
The complete project can be found at [SimpleRemoteCommandSample](../..//Samples/SimpleRemoteCommandSample) but these steps will help you understand the requirements and dependencies.
The complete project can be found at [SimpleRemoteCommandSample](https://github.com/microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/SimpleRemoteCommandSample) but these steps will help you understand the requirements and dependencies.
## Prerequisites
@ -30,11 +30,11 @@ Extension can be downloaded from: TBD
* Add `https://pkgs.dev.azure.com/azure-public/vside/_packaging/vs-impl%40Local/nuget/v3/index.json` as an additional package source for Nuget in Visual Studio.
* On the Tools menu, select Options > NuGet Package Manager > Package Sources. Select the green plus in the upper-right corner and enter a name and source URL above.
* Alternatively you can utilize [nuget.config](../../Samples/nuget.config) we provide in samples.
* Alternatively you can utilize [nuget.config](https://github.com/microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/nuget.config) we provide in samples.
* Add references to `Microsoft.VisualStudio.Extensibility.Sdk` Nuget package through [Manage Nuget Projects](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-visual-studio) dialog.
* Add a [source.extension.vsixmanifest](../../Samples/SimpleRemoteCommandSample/source.extension.vsixmanifest) file to describe your extension including name, description and unique identifier. This information in the future will be used to list the extension in the gallery.
* Add a [source.extension.vsixmanifest](https://github.com/microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/SimpleRemoteCommandSample/source.extension.vsixmanifest) file to describe your extension including name, description and unique identifier. This information in the future will be used to list the extension in the gallery.
At this point you are ready to start extending Visual Studio by adding commands and editor components to your extension.
@ -79,7 +79,7 @@ namespace SimpleRemoteCommandSample
}
```
For more information on how to add commands, please refer to [Commands](..\Extension_Guids/Commands/Command.md) section.
For more information on how to add commands, please refer to [Commands](../extension-guides/command/command.md) section.
## Debug your extension

Просмотреть файл

@ -1,15 +0,0 @@
# Visual Studio OOP extensibility model
## Benefits
The new extensibility model is designed with the following goals in mind:
* Ease of use: We like to have well documented, simple paths for most common operations that extensions perform in Visual Studio. This should translate to shorter development time for small productivity extensions that work with existing languages in Visual Studio.
* Reliability: As we move extensions and components out-of-process, we can isolate components from which other increasing overall reliability of Visual Studio and also responsiveness of IDE in certain cases.
* Cross-product: While this is not possible today, a long term goal for this extensibility model is to be cross product compatible as it is primarily based on JsonRPC protocols to communicate with host IDE process.
## Technology
The new extensibility model is primarily built on top remote RPC contracts that are provided as brokered services from Visual Studio. The extensions are hosted in an external ServiceHub process that communicates with Visual Studio via RPC and both utilize services provided by Visual Studio and may also provide services to Visual Studio process in certain cases.
Extensibility packages that are provided as part of the SDK consist of base classes, utility methods and wrapper objects around these RPC contracts with the goal of making extensibility surface area easier to use, easier to discover and also to be able to quickly contribute to Visual Studio ecosystem such as creating a new command handler.

Просмотреть файл

@ -40,5 +40,5 @@ Extensibility packages that are provided as part of the SDK consist of base clas
To get started writing an extension using the new model, here are some docs, walkthroughs, samples, and videos to get you started:
* [Documentation Index](../Index.md)
* [Create your first extension](Getting_Started/Create_Your_First_Extension.md)
* [Documentation Index](../../index.md)
* [Create your first extension](create-your-first-extension.md)

Просмотреть файл

@ -6,7 +6,7 @@ date: 2021-8-16
# Rule based activation constraints
One of the common concepts in Visual Studio Extensibility SDK is use of context based activation rules in code attributes. An example of these would [CommandVisibleWhen](../APIs/Microsoft.VisualStudio.Extensibility.md#T-Microsoft-VisualStudio-Extensibility-Commands-CommandVisibleWhenAttribute) attribute declaring when a command is made visible.
One of the common concepts in Visual Studio Extensibility SDK is use of context based activation rules in code attributes. An example of these would [CommandVisibleWhen](../api/Microsoft.VisualStudio.Extensibility.md#T-Microsoft-VisualStudio-Extensibility-Commands-CommandVisibleWhenAttribute) attribute declaring when a command is made visible.
Our goal is to provide a common way to create such contexts, the current method is based on existing [Rule-based UI contexts](https://docs.microsoft.com/en-us/visualstudio/extensibility/how-to-use-rule-based-ui-context-for-visual-studio-extensions) with a different set of context terms.
@ -67,7 +67,7 @@ Following is the list of terms currently supported by expression engine.
| Building | Solution is building. |
## Client contexts
Activation rules can also utilize the [client context](ExtensionAnatomy.md#client-context) contents as parts of its expression.
Activation rules can also utilize the [client context](extension-anatomy.md#client-context) contents as parts of its expression.
Currently, the client context is limited to a small set of values in IDE state:

Просмотреть файл