Compartir a través de


Referencia del manifiesto de extensión

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Cada extensión tiene un archivo de manifiesto JSON que define información básica sobre la extensión. El archivo también define cómo puede ampliar y mejorar la experiencia. En este artículo se muestra cómo crear un manifiesto para la extensión en Azure DevOps.

Sugerencia

Consulte nuestra documentación más reciente sobre el desarrollo de extensiones mediante el SDK de extensión de Azure DevOps.

Cree un archivo denominado vss-extension.json en la raíz de la carpeta de extensión. Este archivo contiene atributos necesarios, como el identificador de la extensión y sus destinos de instalación, donde se puede ejecutar. También define las contribuciones que realiza la extensión.

Consulte el ejemplo siguiente de un manifiesto típico:

{
    "manifestVersion": 1,
    "id": "tools",
    "version": "0.1.0",
    "name": "Fabrikam Tools",
    "publisher": "fabrikam",
    "description": "Awesome tools to help you and your team do great things everyday.",
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ],
    "icons": {
        "default": "images/fabrikam-logo.png"
    },
    "scopes": [
        "vso.work",
        "vso.code_write",
        "vso.build_execute"
    ],
    "categories": [
        "Azure Boards"
    ],
    "branding": {
        "color": "rgb(34, 34, 34)",
        "theme": "dark"
    },
    "content": {
        "details": {
            "path": "readme.md"
        },
        "license": {
            "path": "eula.md"
        }
    },
    "links": {
        "getstarted": {
            "uri": "https://www.fabrikam-fiber-inc.com/help/getstarted"
        },
        "support": {
            "uri": "https://www.fabrikam-fiber-inc.com/support"
        }
    },
    "repository": {
        "type": "git",
        "uri": "https://github.com/fabrikam-fiber-inc/myextension"
    },
    "contributions": [
        {
            "id": "showCommits",
            "type": "ms.vss-web.action",
            "description": "Adds a menu action from builds grid to show associated items.",
            "targets": [
                "ms.vss-build-web.completed-build-menu"
            ],
            "properties": {
                "title": "View associated items",
                "uri": "launch.html"
            }
        }
    ],
    "files": [
        {
            "path": "launch.html",
            "addressable": true
        },        
        {
            "path": "node_modules/vss-web-extension-sdk/lib",
            "addressable": true,
            "packagePath": "lib"
        }
    ]
}

Atributos requeridos

Estas propiedades son necesarias:

Propiedad Descripción Notas
manifestVersion Número correspondiente a la versión del formato de manifiesto. debe ser 1.
ID Identificador de la extensión. Th ID es una cadena que debe ser única entre las extensiones del mismo publicador. Debe comenzar con un carácter alfabético o numérico y contener "A" a "Z", "a" a "z", "0" a "9" y "-" (guion). Ejemplo: sample-extension.
version Cadena que especifica la versión de una extensión. Debe tener el formato major.minor.patch, por ejemplo 0.1.2 o 1.0.0. También puede agregar un cuarto número para el formato siguiente: 0.1.2.3
name Nombre corto legible de la extensión. Limitado a 200 caracteres. Ejemplo: "Fabrikam Agile Board Extension".
publisher Identificador del publicador. Este identificador debe coincidir con el identificador en el que se publica la extensión. Consulte Creación y administración de un publicador.
Categorías Matriz de cadenas que representan las categorías a las que pertenece la extensión. Se debe proporcionar al menos una categoría y no hay ningún límite para el número de categorías que puede incluir. Valores válidos: Azure Repos, Azure Boards, Azure Pipelines, Azure Test Plansy Azure Artifacts.

Notas:
    - Use la versión >=0.6.3 de tfx-cli si está publicando la extensión mediante programación.
    - Si usa la extensión Azure DevOps Extension Tasks para publicar, asegúrese de que su versión es >= 1.2.8. Es posible que tenga que aprobar la actualización de la extensión debido a cambios recientes en el ámbito.
    - Las categorías mencionadas anteriormente están presentes de forma nativa en Visual Studio Marketplace y Azure DevOps Server 2019 y versiones posteriores. Para las extensiones destinadas a versiones anteriores de TFS:
      - Si los clientes de TFS adquieren la extensión a través de Visual Studio Marketplace (no la galería local) en contexto conectado, use las categorías que se han indicado anteriormente.
      - Si va a compartir la extensión directamente (es decir, no a través de Visual Studio Marketplace) con un cliente con TFS <=2018, use las siguientes categorías en su lugar: Código, Plan y seguimiento, Compilación y versión, Prueba, Colaboración e Integración. Si necesita compartir ambos mediante Visual Studio Marketplace y directamente con un cliente de TFS <= 2018, tendría que tener 2 paquetes de extensión.
destinos Los productos y servicios compatibles con su integración o extensión. Para obtener más información, consulte Destinos de instalación. Matriz de objetos, donde cada objeto tiene un id campo que indica uno de los siguientes:
    - Microsoft.VisualStudio.Services(extensiones que funcionan con Azure DevOps o TFS),
    Microsoft.TeamFoundation.Server- (extensión que funciona con TFS),-
    Microsoft.VisualStudio.Services.Integration (integraciones que funcionan con Azure DevOps o TFS),
    - Microsoft.TeamFoundation.Server.Integration (integraciones que funcionan con TFS)

Ejemplos de atributos necesarios

{
    "manifestVersion": 1,
    "id": "tools",
    "version": "0.1.0",
    "name": "Fabrikam Tools",
    "publisher": "fabrikam",
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ]
}

Atributos opcionales

Atributos en tiempo de ejecución

Propiedad Descripción Notas
scopes Matriz de ámbitos de autorización (cadenas) que enumera los permisos necesarios para la extensión. Por ejemplo, vso.work e vs.code_write indica que la extensión necesita acceso de solo lectura a los elementos de trabajo y acceso de lectura y escritura al código fuente (y recurso relacionado). Los ámbitos se presentan al usuario al instalar la extensión. Para obtener más información, consulte la lista completa de ámbitos.
Demandas Matriz de demandas (cadenas) que enumera las funcionalidades necesarias para la extensión. Por ejemplo, indica que la extensión usa las API de la versión 3.0 y, por tanto, api-version/3.0 no se puede ejecutar en productos anteriores que no admiten esta versión. Para obtener más información, consulte la lista completa de demandas.
Baseuri (Opcional) Dirección URL base para todas las direcciones URL relativas especificadas por las contribuciones de la extensión. Por ejemplo: https://myapp.com/{{account.name}}/. Esta propiedad debe dejarse vacía si el contenido de la extensión se empaqueta con la extensión.
Contribuciones Matriz de contribuciones al sistema.
contributionTypes Matriz de tipos de contribución definidos por la extensión
{
    "scopes": [
        "vso.work",
        "vso.code_write",
        "vso.build_execute"
    ],
    "demands": [
        "api-version/3.0"
    ],
    "contributions": [
        {
            "id": "showCommits",
            "type": "ms.vss-web.action",
            "description": "Adds a menu action from builds grid to show associated items.",
            "targets": [
                "ms.vss-build-web.completed-build-menu"
            ],
            "properties": {
                "title": "View associated items",
                "uri": "launch.html"
            }
        }
    ]
}

Atributos de detección

Estas propiedades opcionales ayudan a los usuarios a detectar y obtener información sobre la extensión:

Propiedad Descripción Notas
descripción Algunas oraciones que describen las extensiones. Limitado a 200 caracteres. La descripción debe ser el "lanzamiento de ascensor" de la extensión: un par de líneas para describir la extensión en Marketplace y hacer que las personas quieran instalarla. Vea el ejemplo siguiente
Iconos Diccionario de iconos que representan la extensión. Claves válidas: default (128 x 128 píxeles) de tipo BMP, GIF, EXIF, JPG, PNG y TIFF). En el futuro se pueden admitir otras claves como large (512 x 512 píxeles). El valor de cada clave es la ruta de acceso al archivo de icono de la extensión.
etiquetas Matriz de etiquetas de cadena para ayudar a los usuarios a encontrar la extensión. Ejemplos: agile, project management, task timer, etc.
Imágenes Matriz de imágenes que no se pudieron incluir en el contenido. Las capturas de pantalla son más valiosas cuando se incluyen en el contenido y deben usarse allí para ayudar a crear una página de detalles de mercado de calidad para la extensión. Use capturas de pantalla para imágenes menos importantes que no aparezcan en el contenido. Cada imagen debe ser de 1366 x 768 píxeles. El path de cada elemento es la ruta de acceso al archivo en la extensión.
content Diccionario de archivos de contenido que describen la extensión a los usuarios. Cada extensión debe incluir contenido sólido. Así es como mostrará a los usuarios lo que puede hacer la extensión. Haga que sea rico, consumible e incluya capturas de pantalla cuando sea necesario. Incluya un overview.md archivo como elemento de contenido base. Se supone que cada archivo está en formato Markdown con sabor a GitHub. El path de cada elemento es la ruta de acceso al archivo Markdown de la extensión. Claves válidas: details. Es posible que se admita otras claves en el futuro.
vínculos Diccionario de vínculos que ayudan a los usuarios a obtener más información sobre la extensión, obtener soporte técnico y mover. Claves válidas: getstarted los primeros pasos, cómo configurar o usar. learn : contenido más profundo para ayudar a los usuarios a comprender mejor su extensión o servicio. license - Contrato de licencia de usuario final. privacypolicy - directiva de privacidad para una extensión. support - obtener ayuda y soporte técnico para una extensión. El valor de cada clave es un objeto con un uri campo, que es la dirección URL absoluta del vínculo.
repositorio Diccionario de propiedades que describen el repositorio de código fuente de la extensión Claves válidas: type tipo de repositorio. Ejemplo: git. uri - Dirección URL absoluta del repositorio.
Insignias Matriz de vínculos a distintivos de metadatos externos, como TravisCI, Appveyor, etc., desde los sitios de distintivos aprobados Claves válidas: href - Vincular el usuario navega a al seleccionar el distintivo. uri : la dirección URL absoluta de la imagen de distintivo que se va a mostrar. description - Descripción del distintivo, que se mostrará al mantener el puntero.
Marca Diccionario de propiedades relacionadas con la marca. Claves válidas: : color color principal de la extensión o publicador; puede ser un hexadecimal (#ff00ff), RGB (rgb(100,200,50)) o nombres de color HTML admitidos (azul). theme- complementa el color; usa oscuro para colores de personalización de marca oscuros o claro para colores de personalización de marca más claros.

Marcar una extensión pública

De forma predeterminada, todas las extensiones de Marketplace de Azure DevOps son privadas. Solo son visibles para el publicador y las cuentas compartidas por el publicador. Si se comprueba el publicador, puede hacer que la extensión sea pública estableciendo la marca en el Public manifiesto de extensión:

{
    "galleryFlags": [
        "Public"
    ]
}            

O:

{
    "public": true
}            

Para obtener más información, consulte Package/Publish/Install.

Marcar una extensión para que esté en versión preliminar

Si la extensión está lista para que los usuarios de Marketplace prueben, pero sigue trabajando con algunos errores o agregando función, puede marcarla como preview:

{
    "galleryFlags": [
        "Preview"
    ]
}            

Marcar una extensión como versión preliminar de pago

Si tiene previsto vender la extensión en Marketplace, marque la versión preliminar de pago. Una extensión marcada como gratuita no se puede cambiar a pago.

{
    "galleryFlags": [
        "Paid",
        "Preview"
    ]
}            

Marcar una extensión como de pago

Si desea vender la extensión en Marketplace, puede marcarla con la marca y __BYOLENFORCED la Paid etiqueta (comienza con dos caracteres de subrayado):

{
    "galleryFlags": [
        "Paid"        
    ],
     "tags": [        
        "__BYOLENFORCED"
    ]
}            

Tanto la marca como __BYOLENFORCED la Paid etiqueta deben estar presentes para marcar una extensión como se paga en Marketplace. Bring-Your-Own-License (BYOL) significa que el publicador de la extensión proporciona el mecanismo de facturación y licencias para la extensión, ya que microsoft no proporciona las extensiones de Azure DevOps. Todas las extensiones de pago son necesarias para definir la directiva de privacidad, la directiva de soporte técnico y un contrato de licencia de usuario final. Además, los publicadores deben proporcionar contenido para la pestaña de precios en Marketplace de la siguiente manera:

{
    "content": {
        "details": {
            "path": "overview.md"
        }, 
        "pricing": {
            "path": "pricing.md"
        }
    }
}          

También debe agregar una nueva sección en el manifiesto de extensión para invalidar las licencias de pago. En el futuro, quitamos la comprobación de licencias de pago y ya no necesitamos la invalidación. Por ahora, asegúrese de que la extensión se muestra según lo previsto. Cada invalidación consta de un "identificador" y un "comportamiento". El "ID" debe coincidir con el identificador de las contribuciones definidas en el manifiesto.

"licensing": {

      "overrides": [

        { "id": "my-hub", "behavior": " AlwaysInclude" }
      ]
    }

Si la extensión BYOL de pago ofrece un período de prueba (se recomienda, por lo tanto), puede especificar la duración de la versión de prueba en días:

{
    "galleryproperties": {
        "trialDays": "30"
    } 
}          

Nota:

Si quiere tener como destino Azure DevOps, pero no desea exponer una opción Descargar para la extensión, agregue la __DoNotDownload etiqueta (comienza con dos caracteres de subrayado) al manifiesto de extensión. Si va a mover una extensión de la facturación y licencias ofrecidas anteriormente de Microsoft al modelo BYOL, póngase en contacto con nosotros para conocer los pasos adecuados.

Ejemplo de más propiedades

{
    "description": "Awesome tools to help you and your team do great things everyday.",
    "icons": {
        "default": "images/fabrikam-logo.png"
    },
    "categories": [
        "Plan and track"
    ],
    "tags": [
        "working",
        "people person",
        "search"
    ],
    "content": {
        "details": {
            "path": "overview.md"
        },
        "license": {
            "path": "license-terms.md"
        }
    },
    "links": {
        "home": {
            "uri": "https://www.fabrikam-fiber-inc.com"
        },
        "getstarted": {
            "uri": "https://www.fabrikam-fiber-inc.com/help/getstarted"
        },
        "learn": {
            "uri": "https://www.fabrikam-fiber-inc.com/features"
        },
        "support": {
            "uri": "https://www.fabrikam-fiber-inc.com/support"
        },
        "repository": {
            "uri": "https://github.com/fabrikam-fiber-inc/tools"
        },
        "issues": {
            "uri": "https://github.com/fabrikam-fiber-inc/tools/issues"
        }
    },
    "repository": {
        "type": "git",
        "uri": "https://github.com/fabrikam-fiber-inc/tools"
    },
    "badges": [
        {
            "href": "https://travis.ci/fabrikam-fiber-inc/myextension",
            "uri": "https://travis.ci/fabrikam-fiber-inc/myextension.svg?branch=master",
            "description": "TravisCI build for the project"
        },
        {
            "href": "https://ci.appveyor.com/projects/fabrikam-fiber-inc/myextension",
            "uri": "https://ci.appveyor.com/api/projects/status/vlg2sgs2y7tsdxpj4c?svg=true",
            "description": "AppVeyor build for the project"
        }
    ],
    "branding": {
        "color": "rgb(34, 34, 34)",
        "theme": "dark"
    },
    "screenshots": [
        {
            "path": "screenshots/screen1.png"
        },
        {
            "path": "screenshots/screen2.png"
        }
    ]
}

Ejemplo de página detalles

  • 1 - descripción
  • 2 - Icono
  • 3 - Categorías
  • 4- Capturas de pantalla
  • 5 - contenido (detalles)
  • 6 - enlaces
  • 7 - personalización de marca

tarjeta

Q & A de Marketplace: propiedad CustomerQnASupport

Todas las extensiones de Visual Studio Marketplace tienen una sección de preguntas y respuestas para permitir conversaciones públicas uno a uno entre los usuarios de la extensión y los editores. Los editores pueden elegir entre preguntas y respuestas de Marketplace, problemas de GitHub o una dirección URL personalizada de preguntas y respuestas. Puede deshabilitar Q&A en Marketplace mediante la propiedad CustomerQnASupport en el manifiesto.

Experiencia predeterminada (no se requieren cambios en el manifiesto)

  • En el caso de las extensiones con un repositorio de GitHub, Marketplace redirige a los usuarios de la sección de preguntas y respuestas a los problemas asociados de GitHub.
  • En el caso de las extensiones sin un repositorio de GitHub, el Q&A de Marketplace está habilitado.

Para obtener una experiencia diferente a una de las opciones predeterminadas, use la propiedad CustomerQnASupport en el manifiesto.

{
    "CustomerQnASupport": {
        "enablemarketplaceqna": true,
        "url": "http://uservoice.visualstudio.com"
    } 
}

Propiedades

Propiedades de la sección Customer Q & A Support ::

  • enablemarketplaceqna - campo booleano, establecido en true para marketplace o Q&A; false para deshabilitar Q&A
  • url : cadena, dirección URL para preguntas y respuestas personalizadas

Ejemplos que muestran el uso de soporte técnico de Q & A

Ejemplo: Extensión con Q & A personalizado

{
     "CustomerQnASupport": {
        "enablemarketplaceqna":"true",
        "url": "http://uservoice.visualstudio.com"
    } 
}

Ejemplo: Extensión con repositorio de GitHub, pero uso de Q y A de Marketplace en lugar de problemas de GitHub

{
     "CustomerQnASupport": {
        "enablemarketplaceqna":"true"
    } 
}

Ejemplo: Extensión deshabilitando la sección Q & A

{
     "CustomerQnASupport": {
        "enablemarketplaceqna":"false"
    } 
}

Ámbitos

En la extensión, puede definir uno o varios ámbitos. Estos ámbitos determinan a qué recursos puede acceder la extensión y a las operaciones que se pueden realizar en esos recursos. Los ámbitos que especifique en el manifiesto de extensión son los ámbitos establecidos en los tokens de acceso emitidos a la extensión. Para obtener más información, consulte Autenticación y seguridad.

Si no se especifica ningún ámbito, las extensiones solo se proporcionan acceso a los datos de perfil de usuario y de extensión.

Ámbitos admitidos

Category Ámbito Nombre Descripción
Grupos de agentes vso.agentpools Grupos de agentes (lectura) Concede la capacidad de ver tareas, grupos, colas, agentes y trabajos actualmente ejecutados o completados recientemente para agentes.
vso.agentpools_manage Grupos de agentes (leer, administrar) Concede la capacidad de administrar grupos, colas y agentes.
vso.environment_manage Entorno (lectura, administración) Concede la capacidad de administrar grupos, colas, agentes y entornos.
Análisis vso.analytics Análisis (lectura) Concede la capacidad de consultar datos de análisis.
Auditoría vso.auditlog Registro de auditoría (lectura) Concede la capacidad de leer el registro de auditoría a los usuarios.
vso.auditstreams_manage Auditar Secuencias (leer) Concede la capacidad de administrar flujos de auditoría a los usuarios.
Compilar vso.build Compilar (leer) Concede la capacidad de acceder a los artefactos de compilación, incluidos los resultados de compilación, las definiciones y las solicitudes, y la capacidad de recibir notificaciones sobre eventos de compilación a través de enlaces de servicio.
vso.build_execute Compilación (lectura y ejecución) Concede la capacidad de acceder a los artefactos de compilación, incluidos los resultados de compilación, las definiciones y las solicitudes, y la capacidad de poner en cola una compilación, actualizar las propiedades de compilación y la capacidad de recibir notificaciones sobre eventos de compilación a través de enlaces de servicio.
Código vso.code Código (leer) Concede la capacidad de leer código fuente y metadatos sobre confirmaciones, conjuntos de cambios, ramas y otros artefactos de control de versiones. También concede la capacidad de buscar código y recibir notificaciones sobre eventos de control de versiones a través de enlaces de servicio.
vso.code_write Código (lectura y escritura) Concede la capacidad de leer, actualizar y eliminar código fuente, acceder a metadatos sobre confirmaciones, conjuntos de cambios, ramas y otros artefactos de control de versiones. También concede la capacidad de crear y administrar solicitudes de incorporación de cambios y revisiones de código y recibir notificaciones sobre eventos de control de versiones a través de enlaces de servicio.
vso.code_manage Código (lectura, escritura y administración) Concede la capacidad de leer, actualizar y eliminar código fuente, acceder a metadatos sobre confirmaciones, conjuntos de cambios, ramas y otros artefactos de control de versiones. También concede la capacidad de crear y administrar repositorios de código, crear y administrar solicitudes de incorporación de cambios y revisiones de código, y recibir notificaciones sobre eventos de control de versiones a través de enlaces de servicio.
vso.code_full Código (completo) Concede acceso completo al código fuente, los metadatos sobre confirmaciones, conjuntos de cambios, ramas y otros artefactos de control de versiones. También concede la capacidad de crear y administrar repositorios de código, crear y administrar solicitudes de incorporación de cambios y revisiones de código, y recibir notificaciones sobre eventos de control de versiones a través de enlaces de servicio. También incluye compatibilidad limitada con las API de OM de cliente.
vso.code_status Código (estado) Concede la capacidad de leer y escribir la confirmación y el estado de la solicitud de incorporación de cambios.
servidor Conectar ed vso.connected_server Servidor conectado Concede la capacidad de acceder a los puntos de conexión necesarios desde un servidor conectado local.
Derechos vso.entitlements Derechos (lectura) Proporciona acceso de solo lectura al punto de conexión de derechos de licencia para obtener derechos de cuenta.
vso.memberentitlementmanagement Administración de MemberEntitlement (lectura) Concede la capacidad de leer usuarios, sus licencias, así como proyectos y extensiones a los que pueden acceder.
vso.memberentitlementmanagement_write Administración de MemberEntitlement (escritura) Concede la capacidad de administrar usuarios, sus licencias, así como proyectos y extensiones a los que pueden acceder.
Extensiones vso.extension Extensiones (lectura) Concede la capacidad de leer extensiones instaladas.
vso.extension_manage Extensiones (leer y administrar) Concede la capacidad de instalar, desinstalar y realizar otras acciones administrativas en las extensiones instaladas.
vso.extension.data Datos de extensión (lectura) Concede la capacidad de leer datos (configuración y documentos) almacenados por extensiones instaladas.
vso.extension.data_write Datos de extensión (lectura y escritura) Concede la capacidad de leer y escribir datos (configuración y documentos) almacenados por extensiones instaladas.
Graph & identity vso.graph Gráfico (lectura) Concede la capacidad de leer información de usuario, grupo, ámbito y pertenencia a grupos.
vso.graph_manage Gráfico (administrar) Concede la capacidad de leer información de usuarios, grupos, ámbito y pertenencia a grupos, y para agregar usuarios, grupos y administrar pertenencias a grupos.
vso.identity Identidad (leer) Concede la capacidad de leer identidades y grupos.
vso.identity_manage Identidad (administrar) Concede la capacidad de leer, escribir y administrar identidades y grupos.
Grupo de máquinas vso.machinegroup_manage Grupo de implementación (lectura, administración) Proporciona capacidad para administrar grupos de agentes y grupos de implementación.
Marketplace vso.gallery Marketplace Concede acceso de lectura a elementos públicos y privados y publicadores.
vso.gallery_acquire Marketplace (adquirir) Concede acceso de lectura y la capacidad de adquirir elementos.
vso.gallery_publish Marketplace (publicación) Concede acceso de lectura y la capacidad de cargar, actualizar y compartir elementos.
vso.gallery_manage Marketplace (administrar) Concede acceso de lectura y la capacidad de publicar y administrar elementos y publicadores.
Notificaciones vso.notification Notificaciones (lectura) Proporciona acceso de lectura a suscripciones y metadatos de eventos, incluidos los valores de campo filtrables.
vso.notification_write Notificaciones (escritura) Proporciona acceso de lectura y escritura a suscripciones y acceso de lectura a metadatos de eventos, incluidos los valores de campo filtrables.
vso.notification_manage Notificaciones (administrar) Proporciona acceso de lectura, escritura y administración a suscripciones y acceso de lectura a metadatos de eventos, incluidos los valores de campo filtrables.
vso.notification_diagnostics Notificaciones (diagnósticos) Proporciona acceso a los registros de diagnóstico relacionados con la notificación y proporciona la capacidad de habilitar diagnósticos para suscripciones individuales.
Empaquetado vso.packaging Empaquetado (lectura) Concede la capacidad de leer fuentes y paquetes.
vso.packaging_write Empaquetado (lectura y escritura) Concede la capacidad de crear y leer fuentes y paquetes.
vso.packaging_manage Empaquetado (lectura, escritura y administración) Concede la capacidad de crear, leer, actualizar y eliminar fuentes y paquetes.
Recursos de canalización vso.pipelineresources_use Recursos de canalización (uso) Concede la capacidad de aprobar la solicitud de una canalización para usar un recurso protegido: grupo de agentes, entorno, cola, repositorio, archivos seguros, conexión de servicio y grupo de variables.
vso.pipelineresources_manage Recursos de canalización (uso y administración) Concede la capacidad de administrar un recurso protegido o la solicitud de una canalización para usar un recurso protegido: grupo de agentes, entorno, cola, repositorio, archivos seguros, conexión de servicio y grupo de variables.
Proyecto y equipo vso.project Proyecto y equipo (leer) Concede la capacidad de leer proyectos y equipos.
vso.project_write Proyecto y equipo (lectura y escritura) Concede la capacidad de leer y actualizar proyectos y equipos.
vso.project_manage Proyecto y equipo (lectura, escritura y administración) Concede la capacidad de crear, leer, actualizar y eliminar proyectos y equipos.
Versión vso.release Versión (lectura) Concede la capacidad de leer artefactos de versión, incluidas las versiones, las definiciones de versión y el entorno de versión.
vso.release_execute Versión (lectura, escritura y ejecución) Concede la capacidad de leer y actualizar artefactos de versión, incluidas las versiones, las definiciones de versión y el entorno de versión, y la capacidad de poner en cola una nueva versión.
vso.release_manage Versión (lectura, escritura, ejecución y administración) Concede la capacidad de leer, actualizar y eliminar artefactos de versión, incluidas las versiones, las definiciones de versión y el entorno de versión, y la capacidad de poner en cola y aprobar una nueva versión.
Proteger archivos vso.securefiles_read Archivos seguros (lectura) Concede la capacidad de leer archivos seguros.
vso.securefiles_write Archivos seguros (leer, crear) Concede la capacidad de leer y crear archivos seguros.
vso.securefiles_manage Archivos seguros (leer, crear y administrar) Concede la capacidad de leer, crear y administrar archivos seguros.
Seguridad vso.security_manage Seguridad (administrar) Concede la capacidad de leer, escribir y administrar permisos de seguridad.
Conexiones de servicio vso.serviceendpoint Puntos de conexión de servicio (lectura) Concede la capacidad de leer puntos de conexión de servicio.
vso.serviceendpoint_query Puntos de conexión de servicio (lectura y consulta) Concede la capacidad de leer y consultar puntos de conexión de servicio.
vso.serviceendpoint_manage Puntos de conexión de servicio (lectura, consulta y administración) Concede la capacidad de leer, consultar y administrar puntos de conexión de servicio.
Configuración vso.settings Configuración (lectura) Concede la capacidad de leer la configuración.
vso.settings_write Configuración (lectura y escritura) Concede la capacidad de crear y leer la configuración.
Symbols vso.symbols Símbolos (lectura) Concede la capacidad de leer símbolos.
vso.symbols_write Símbolos (lectura y escritura) Concede la capacidad de leer y escribir símbolos.
vso.symbols_manage Símbolos (lectura, escritura y administración) Concede la capacidad de leer, escribir y administrar símbolos.
Grupos de tareas vso.taskgroups_read Grupos de tareas (lectura) Concede la capacidad de leer grupos de tareas.
vso.taskgroups_write Grupos de tareas (leer, crear) Concede la capacidad de leer y crear grupos de tareas.
vso.taskgroups_manage Grupos de tareas (leer, crear y administrar) Concede la capacidad de leer, crear y administrar grupos de tareas.
Panel de equipo vso.dashboards Paneles de equipo (lectura) Concede la capacidad de leer la información del panel del equipo.
vso.dashboards_manage Paneles de equipo (administrar) Concede la capacidad de administrar la información del panel del equipo.
Administración de pruebas vso.test Administración de pruebas (lectura) Concede la capacidad de leer planes de prueba, casos, resultados y otros artefactos relacionados con la administración de pruebas.
vso.test_write Administración de pruebas (lectura y escritura) Concede la capacidad de leer, crear y actualizar planes de prueba, casos, resultados y otros artefactos relacionados con la administración de pruebas.
Subprocesos vso.threads_full Subprocesos de pr Concede la capacidad de leer y escribir para extraer subprocesos de comentarios de solicitud.
Tokens vso.tokens Tokens de autorización delegados Concede a los usuarios la capacidad de administrar tokens de autorización delegados.
vso.tokenadministration Token Administración istration Concede la capacidad de administrar (ver y revocar) tokens existentes a los administradores de la organización.
Perfil de usuario vso.profile Perfil de usuario (leer) Concede la capacidad de leer el perfil, las cuentas, las colecciones, los proyectos, los equipos y otros artefactos de la organización de nivel superior.
vso.profile_write Perfil de usuario (escritura) Concede la capacidad de escribir en su perfil.
Grupos de variables vso.variablegroups_read Grupos de variables (lectura) Concede la capacidad de leer grupos de variables.
vso.variablegroups_write Grupos de variables (leer, crear) Concede la capacidad de leer y crear grupos de variables.
vso.variablegroups_manage Grupos de variables (leer, crear y administrar) Concede la capacidad de leer, crear y administrar grupos de variables.
Wiki vso.wiki Wiki (lectura) Concede la capacidad de leer wikis, páginas wiki y datos adjuntos wiki. También concede la capacidad de buscar páginas wiki.
vso.wiki_write Wiki (lectura y escritura) Concede la capacidad de leer, crear y actualizar wikis, páginas wiki y datos adjuntos wiki.
Elementos de trabajo vso.work Elementos de trabajo (leer) Concede la capacidad de leer elementos de trabajo, consultas, paneles, rutas de acceso de área e iteraciones y otros metadatos relacionados con el seguimiento de elementos de trabajo. También concede la capacidad de ejecutar consultas, buscar elementos de trabajo y recibir notificaciones sobre eventos de elementos de trabajo a través de enlaces de servicio.
vso.work_write Elementos de trabajo (leer y escribir) Concede la capacidad de leer, crear y actualizar elementos de trabajo y consultas, actualizar metadatos del panel de actualización, áreas de lectura e iteraciones rutas de acceso a otros metadatos relacionados con el seguimiento de elementos de trabajo, ejecutar consultas y recibir notificaciones sobre eventos de elemento de trabajo a través de enlaces de servicio.
vso.work_full Elementos de trabajo (completos) Concede acceso total a elementos de trabajo, consultas, trabajos pendientes, planes y metadatos de seguimiento de elementos de trabajo. También proporciona la capacidad de recibir notificaciones sobre eventos de elementos de trabajo a través de enlaces de servicio.
Suplantación de usuario user_impersonation Suplantación de usuario Tener acceso completo a las API REST de Visual Studio Team Services. Solicitar o dar su consentimiento a este ámbito con precaución, ya que es muy eficaz!

Cambio del ámbito de la extensión publicada

Puede cambiar el ámbito de una extensión publicada. Si instaló anteriormente la extensión (y autorizó el conjunto anterior de ámbitos), debe autorizar los nuevos ámbitos para poder actualizar a la versión más reciente.

La sección Acción requerida del centro de configuración de extensión muestra un usuario que, si existe, las extensiones instaladas requieren autorización:

cambio de ámbito

A continuación, un administrador puede revisar y autorizar el nuevo conjunto de ámbitos:

scope-change-dialog

Destinos de instalación

Como indica el nombre, los destinos de instalación definen los productos y servicios en los que puede instalar la extensión. Microsoft.VisualStudio.Services es el destino de instalación más común e indica que la extensión se puede instalar en Azure DevOps.

Los destinos de instalación de una extensión o integración se especifican a través del targets campo del manifiesto.

Identificadores admitidos para extensiones:

  • Microsoft.VisualStudio.Services.Cloud: se instala en Azure DevOps Services.
  • Microsoft.TeamFoundation.Server: se instala en Azure DevOps Server.
  • Microsoft.VisualStudio.Services: se instala en ambos. Acceso directo para Microsoft.VisualStudio.Services.Cloud y Microsoft.TeamFoundation.Server versión [14.2,)

Identificadores admitidos para integraciones:

  • Microsoft.VisualStudio.Services.Cloud.Integration: se integra con Azure DevOps Services
  • Microsoft.TeamFoundation.Server.Integration: se integra con Azure DevOps Server
  • Microsoft.VisualStudio.Services.Integration: se integra con ambos. Acceso directo para Microsoft.VisualStudio.Services.Cloud.Integration y Microsoft.TeamFoundation.Server.Integration

Para obtener más información, vea Puntos de extensibilidad.

Ejemplos de destinos de instalación

Ejemplo: extensión que funciona con Azure DevOps

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ]
}

Ejemplo: Extensión que solo funciona con Azure DevOps Services

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Cloud"
        }
    ]
}

Los destinos de instalación también se pueden usar en el manifiesto de integraciones. Por ejemplo, productos, aplicaciones o herramientas con las que funcionan, pero no se instalan en Azure DevOps.

Ejemplo: Integración que funciona con Azure DevOps

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Integration"
        }
    ]
}

Ejemplo: Integración que solo funciona con Azure DevOps Server

{
    "targets": [
        {
            "id": "Microsoft.TeamFoundation.Server.Integration"
        }
    ]
}

Versiones de destino de instalación

Algunos identificadores de destino de instalación, como Microsoft.TeamFoundation.Server y Microsoft.TeamFoundation.Server.Integration, admiten un intervalo de versiones opcional. Este intervalo de versiones opcional aclara aún más las versiones admitidas en las que se admite la extensión o la integración.

La versión o el intervalo de versiones se especifica a través del version campo en el objeto de destino de instalación. Este valor puede ser:

  • Una versión específica, por ejemplo: 15.0 (solo 2017 RTM)
  • Un intervalo de versiones compatibles, por ejemplo: [14.0) (2015 RTM y versiones posteriores), [14.3,15.1] (actualización 3 a 2017 Update 1). Los valores de rango se refinan mediante:
    • [: versión mínima inclusiva
    • ]: versión máxima inclusiva
    • (: versión mínima exclusiva
    • ): versión máxima exclusiva

Números de versión para Azure DevOps Server:

Versión Versiones Versión
2010 Todas las versiones 10.0
2012 Todas las versiones 11.0
2013 RTM y actualizaciones 12.0, 12.1, 12.2, 12.3, 12.4
2015 RTM y actualizaciones 14.0, 14.1, 14.2, 14.3
2017 RTM y actualizaciones 15.0, 15.1
2018 RTM y actualizaciones 16.0
2019 RTM y actualizaciones 17.0
2020 RTM y actualizaciones 18.0

Ejemplos que muestran versiones

Ejemplo: extensión que funciona con Azure DevOps

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Cloud"
        },
        {
            "id": "Microsoft.TeamFoundation.Server",
            "version": "[15.0,)"
        }
    ]
}

Accesos directos

Microsoft.VisualStudio.Services es un acceso directo para Azure DevOps.

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ]
}

equivale a:

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Cloud"
        },
        {
            "id": "Microsoft.TeamFoundation.Server",
            "version": "[14.2,)"
        }
    ]
}

Uso de destinos y demandas de instalación

Los objetivos de instalación y las demandas se usan conjuntamente para presentar a los usuarios una vista correcta de los productos o servicios con los que la extensión o la integración son compatibles. Por ejemplo, especificar un destino de instalación de Microsoft.VisualStudio.Services con una demanda de api-version/3.0 significa que la extensión funciona con Azure DevOps.

Sugerencia

Para obtener más información sobre las API REST, consulte la referencia de la API REST.

Ejemplo: Extensión que usa las API de la versión 3.0

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ],
    "demands": [
        "api-version/3.0"
    ]
}

Se resuelve en los siguientes destinos de instalación:

  1. Microsoft.VisualStudio.Services.Cloud
  2. Microsoft.TeamFoundation.ServerVersión: [15.0,)

Ejemplo: Integración que usa las API de la versión 2.0

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Integration"
        }
    ],
    "demands": [
        "api-version/2.0"
    ]
}

Se resuelve en los siguientes destinos de instalación:

  1. Microsoft.VisualStudio.Services.Cloud.Integration
  2. Microsoft.TeamFoundation.Server.IntegrationVersión: [14.0,)

Peticiones

Las demandas permiten especificar funcionalidades y otras características necesarias para la extensión. Puede usar estas demandas para limitar dónde se puede publicar o instalar la extensión.

Las demandas se usan en Visual Studio Marketplace para enumerar los productos y entornos con los que la extensión es compatible, lo que ayuda a los clientes a comprender si la extensión funciona con su versión de Azure DevOps, por ejemplo.

Consulte el ejemplo siguiente de cómo se especifican las demandas en el manifiesto de extensión.

{
    "demands": [
        "api-version/3.0",
        "contribution/ms.vss-dashboards-web.widget-catalog"
    ]
}

En este ejemplo, la extensión exige la versión 3.0 de las API, lo que significa que solo se puede instalar en Azure DevOps. También requiere que la ms.vss-dashboards-web extensión (y su widget-catalog contribución) se instale (y se habilite) en la colección para poder instalar la extensión.

Demandas admitidas

Tipo Descripción ¿Se comprueba en la publicación? ¿Se comprueba en la instalación?
environment/cloud Requiere la ejecución en un entorno de nube
environment/onprem Requiere la ejecución en un entorno local
api-version/{version} Requiere una versión de API específica (mínimo) No
extension/{id} Requiere que se instale o habilite una extensión específica. No
contribution/{id} Requiere que haya disponible una contribución específica. No
contributionType/{id} Requiere que haya disponible un tipo de contribución específico. No

Nota:

  • Use environment/cloud y environment/onprem solo cuando la extensión tenga requisitos relacionados con la topología que requieren la ejecución en ese entorno determinado.
  • extensionLas demandas , contributiony contributionType se evalúan en tiempo de instalación y requiere que la extensión especificada ya esté instalada y habilitada en la organización o colección.

Archivos

La files sección es donde hace referencia a los archivos que quiera incluir en la extensión. Puede agregar carpetas y archivos individuales:

{
    "files": [
        {
            "path": "hello-world.html", "addressable": true
        },
        {
            "path": "scripts", "addressable": true
        },
        {
            "path": "images/logo.png", "addressable": true, "packagePath": "/"
        }
    ]
}

Propiedades

Propiedades de la sección Archivos:

  • path : ruta de acceso al recurso en el disco, que puede ser relativa al directorio raíz.
  • direccionable : (opcional) Se establece en true si desea que el archivo sea direccionable con dirección URL. El valor predeterminado es false.
  • packagePath : (opcional) Ruta de acceso al recurso dentro del paquete. El valor predeterminado es la ruta de acceso relativa en el disco desde el directorio raíz.
  • contentType : tipo MIME (opcional) del archivo. El valor predeterminado es una mejor estimación en función de la extensión de archivo y la configuración del sistema operativo.
  • assetType : (opcional) Especifique el valor del atributo Type de la entrada de recurso en el manifiesto VSIX. También puede ser una matriz de cadenas, en cuyo caso se agregan varias entradas de recursos para este archivo. El valor predeterminado es packagePath.
  • lang : (opcional) Idioma de este recurso. Los archivos localizados se sirven en función del encabezado Accept-Language. Deje en blanco para indicar que este archivo está en el idioma predeterminado (o reserva). Las versiones localizadas del mismo archivo deben tener el mismo assetType.

Contribuciones

Cada entrada de contribución tiene las siguientes propiedades:

  • id : identificador de referencia (cadena) para la contribución. El identificador de cada contribución debe ser único dentro de una extensión. Consulte referencia a contribuciones y tipos.
  • type : el identificador del valor de contributionType de esta contribución.
  • description : (opcional) Cadena que describe lo que proporciona la contribución.
  • targets : matriz de identificadores de contribución a los que se dirige la contribución (contribuyendo). Consulte Contribuciones de destino.
  • properties : (Opcional) Objeto que incluye propiedades para la contribución tal y como se define en el tipo de contribución.

Para obtener más información, consulte la introducción al modelo de contribución.

Tipos de contribución

Cada entrada de contribución tiene las siguientes propiedades:

  • id : identificador de referencia (cadena) para el tipo de contribución. El identificador de cada tipo de contribución debe ser único dentro de una extensión. Consulte referencia a contribuciones y tipos.
  • name : nombre descriptivo del tipo de contribución.
  • description : (opcional) Cadena que describe con más detalle el tipo de contribución.
  • properties : (Opcional) Diccionario que asigna nombres de propiedad a descripciones de propiedades. Estas propiedades describen las propiedades necesarias y opcionales que pueden usar las contribuciones de este tipo.

Las descripciones de propiedades tienen las siguientes propiedades:

  • description : (opcional) Cadena que describe para qué se usa la propiedad.
  • required : (Opcional) Valor booleano, que si es true indica que la propiedad es necesaria para todas las contribuciones de este tipo.
  • type : el tipo de valor que la propiedad puede tener, que podría ser string, uri, guid, boolean, integer, double, dateTime, array o object.

Para obtener más información, consulte la introducción al modelo de contribución.

Hacer referencia a contribuciones y tipos

Use identificadores únicos para hacer referencia a contribuciones y tipos de contribución. Tipos de referencia con la type propiedad y hacer referencia a otras contribuciones con la targets propiedad .

  • Una referencia de contribución completa incluye el identificador del publicador, el identificador de extensión y el identificador de contribución/tipo, separados por un punto (.). Por ejemplo, ms.vss-web.hub es el identificador completo de la contribución con el identificador de "hub" en la extensión "vss-web" publicada por el publicador "ms" (Microsoft).
  • Las referencias de contribución relativas se pueden usar dentro de un manifiesto de extensión para la referencia de una contribución a otro tipo de contribución o contribución dentro de esa misma extensión. En este caso, los identificadores de editor y extensión NO se incluyen y el identificador es un punto (.) seguido del identificador de contribución. Por ejemplo, ".hub" podría usarse dentro de la extensión "vss-web" mencionada anteriormente como acceso directo para "ms.vss-web.hub".

Contribuciones dirigidas

Algunas contribuciones actúan como contenedores destinados a otras contribuciones.

  • Las contribuciones del centro de conectividad pueden tener como destino grupos concentradores. Cuando se representa una página, la interfaz de usuario web muestra todas las contribuciones del centro de conectividad destinadas al grupo concentrador seleccionado. Los grupos concentradores tienen como destino una colección de grupos concentradores, que define un conjunto de grupos concentradores que aparecen en un área de navegación determinada, por ejemplo, páginas de administración de nivel de proyecto.
  • Los distintos tipos de contribuciones pueden dirigirse a menús: acción, acción de hipervínculo y proveedor de acciones. Las acciones y las acciones de hipervínculo proporcionan entradas de elemento de menú único. Un proveedor de acciones puede proporcionar varios elementos de menú dinámicos. Para un menú determinado, los elementos se agregan en todas las contribuciones (de cualquiera de estos tipos) que tienen como destino esa contribución de menú específica.

Adición de un icono de concentrador

Para obtener información sobre cómo agregar un icono al centro, consulte la guía del icono del centro.

Servicios de distintivo admitidos

Marketplace solo admite distintivos de los siguientes servicios de confianza:

  • api.travis-ci.org/
  • badge.fury.io/
  • badges.frapsoft.com/
  • badges.gitter.im/
  • badges.greenkeeper.io/
  • cdn.travis-ci.org/
  • ci.appveyor.com/
  • codeclimate.com/
  • codecov.io/
  • coveralls.io/
  • david-dm.org/
  • gemnasium.com/
  • img.shields.io/
  • isitmaintained.com/
  • marketplace.visualstudio.com/
  • snyk.io/
  • travis-ci.com/
  • travis-ci.org/
  • vsmarketplacebadges.dev/
  • bithound.io/
  • deepscan.io/
  • githost.io/
  • gitlab.com/
  • opencollective.co/

Nota:

Reemplace "vsmarketplacebadge.apphb.com" por "vsmarketplacebadges.dev".

Para mostrar un distintivo de otro servicio, póngase en contacto con vsmarketplace@microsoft.com.

Manifiesto de ejemplo

La siguiente extensión contribuye a una acción al menú contextual de compilaciones completadas y un centro al grupo Centro de compilación:

{
    "manifestVersion": 1,
    "id": "tools",
    "version": "0.1.0",
    "name": "Fabrikam Tools",
    "publisher": "fabrikam",
    "description": "Awesome tools to help you and your team do great things everyday.",
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ],
    "demands": [
        "api-version/3.0"
    ],
    "icons": {
        "default": "images/fabrikam-logo.png"
    },
    "scopes": [
        "vso.work",
        "vso.code_write"
    ],
    "categories": [
        "Plan and track"
    ],
    "tags": [
        "working",
        "people person",
        "search"
    ],
    "branding": {
        "color": "rgb(34, 34, 34)",
        "theme": "dark"
    },
    "screenshots": [
        {
            "path": "screenshots/screen1.png"
        },
        {
            "path": "screenshots/screen2.png"
        }
    ],
    "content": {
        "details": {
            "path": "overview.md"
        },
        "license": {
            "path": "eula.md"
        }
    },
    "links": {
        "home": {
            "uri": "https://www.fabrikam-fiber-inc.com"
        },
        "getstarted": {
            "uri": "https://www.fabrikam-fiber-inc.com/help/getstarted"
        },
        "learn": {
            "uri": "https://www.fabrikam-fiber-inc.com/features"
        },
        "support": {
            "uri": "https://www.fabrikam-fiber-inc.com/support"
        },
        "repository": {
            "uri": "https://github.com/fabrikam-fiber-inc/tools"
        },
        "issues": {
            "uri": "https://github.com/fabrikam-fiber-inc/tools/issues"
        }
    },
    "repository": {
        "type": "git",
        "uri": "https://github.com/fabrikam-fiber-inc/myextension"
    },
    "badges": [
        {
            "href": "https://travis.ci/fabrikam-fiber-inc/myextension",
            "uri": "https://travis.ci/fabrikam-fiber-inc/myextension.svg?branch=master",
            "description": "TravisCI build for the project"
        },
        {
            "href": "https://ci.appveyor.com/projects/fabrikam-fiber-inc/myextension",
            "uri": "https://ci.appveyor.com/api/projects/status/vlg2sgs2y7tsdxpj4c?svg=true",
            "description": "AppVeyor build for the project"
        }
    ],
    "contributions": [
        {
            "id": "showCommits",
            "type": "ms.vss-web.action",
            "description": "Adds a menu action from builds grid to show associated items.",
            "targets": [
                "ms.vss-build-web.completed-build-menu"
            ],
            "properties": {
                "title": "View associated items",
                "uri": "launch.html"
            }
        }
    ]
}