diff --git a/README-localized/README-es-es.md b/README-localized/README-es-es.md new file mode 100644 index 0000000..052bba9 --- /dev/null +++ b/README-localized/README-es-es.md @@ -0,0 +1,101 @@ +# Tabla de contenido +- [Tabla de contenido](#table-of-contents) +- [Intune-PowerShell-SDK-Code-Generator](#intune-powershell-sdk-code-generator) +- [Colaboradores](#contributing) +- [Diseño](#design) + - [Arquitectura de alto nivel](#high-level-architecture) + - [El paso de generación automática](#the-auto-generation-step) +- [Trabajos futuros](#future-work) +- [Preguntas frecuentes](#faq) + - [¿Dónde está el código generado?](#where-is-the-generated-code) + - [¿Por qué necesitamos este módulo de PowerShell?](#why-do-we-need-this-powershell-module) + - [¿Por qué queremos generar automáticamente el módulo de PowerShell?](#why-do-we-want-to-auto-generate-the-powershell-module) + - [¿Por qué la compilación está siendo realizada por Intune (y por qué no la está realizando el equipo SDK de Graph)?](#why-is-intune-building-it-and-why-isnt-the-graph-sdk-team-building-it) + - [¿Qué es Vipr?](#what-is-vipr) + - [¿Por qué un escritor personalizado?](#why-a-custom-writer) + - [¿Por qué no usar OpenAPI y Swagger?](#why-not-use-openapi-and-swagger) + +# Intune-PowerShell-SDK-Code-Generator +Este repositorio implementa el escritor de Vipr que genera cmdlets de PowerShell para todas las operaciones CRUD, las funciones y las acciones para compatibilidad con la API de Graph en Microsoft Intune. + +# Colaboradores +Este proyecto recibe las contribuciones y las sugerencias. La mayoría de las contribuciones requiere +que acepte un Contrato de Licencia de Colaborador (CLA) donde declara que tiene el derecho, y realmente lo tiene, de otorgarnos los derechos para usar su contribución. +Para obtener más información, visite https://cla.microsoft.com. + +Cuando envíe una solicitud de incorporación de cambios, un bot de CLA determinará automáticamente si necesita proporcionar un CLA y agregar el PR correctamente (por ejemplo, etiqueta, comentario). +Siga las instrucciones proporcionadas por el bot. +Solo debe hacerlo una vez en todos los repositorios que usen nuestro CLA. + +Este proyecto ha adoptado el [Código de conducta de código abierto de Microsoft](https://opensource.microsoft.com/codeofconduct/). +Para obtener más información, vea [preguntas frecuentes sobre el código de conducta](https://opensource.microsoft.com/codeofconduct/faq/) +o póngase en contacto con [opencode@microsoft.com](mailto:opencode@microsoft.com) si tiene otras preguntas o comentarios. + +# Diseño +## Arquitectura de alto nivel +![Arquitectura de alto nivel](Design.jpg) +esta es la información general sobre cómo se junta el módulo de PowerShell. +1. El Vipr.exe es ejecutado con los siguientes argumentos para generar el código que definirá el comportamiento de los cmdlets. +- Los resultados de la compilación del proyecto GraphODataPowerShellWriter (es decir, GraphODataPowerShellWriter.dll). +- Un esquema de Graph (por ejemplo, el resultado de llamar a https://graph.microsoft.com/v1.0/$metadata) - este archivo tiene la extensión ".csdl" y se encuentra en "~/TestGraphSchemas". +2. La documentación generada en la salida de Vipr es extraída en un archivo XML. PowerShell usa el archivo XML para mostrar el resultado del cmdlet "Get-Help". +3. Estos cmdlets se escriben en sus propios módulos, debido a que algunas funcionalidades cobran más sentido al ser escritas a mano en PowerShell. Estos módulos se encuentran en "~/src/PowerShellGraphSDK/PowerShellModuleAdditions/CustomModules". +4. Los resultados de los tres pasos anteriores (es decir, los cmdlets generados, la documentación del cmdlet y los cmdlets escritos a mano) se combinan al usar un archivo de manifiesto de PowerShell. Este archivo tiene la extensión ".psd1". +5. El archivo de manifiesto de PowerShell creado en el paso anterior se utiliza para importar y utilizar el módulo. Por ejemplo, si el archivo de manifiesto se llamó "Intune.psd1", puede ejecutar "Import-Module ./Intune.psd1" en una ventana de PowerShell para importar el módulo. + +## El paso de generación automática +![ genera el módulo binario de PowerShell](Generating_the_PowerShell_Binary_Module.jpg) +este es un examen detallado del paso 1 en la sección de[arquitectura de alto nivel](#high-level-architecture). +- El archivo de definición de esquema (CSDL) se carga en Vipr. +- La v4 del lector OData está incorporada en Vipr y se usa para leer el archivo CSDL. Este lector convierte la definición del esquema en una representación intermedia, denominada modelo ODCM. +- El escritor personalizado se pasó a Vipr para procesar el modelo ODCM. Para convertir el modelo ODCM en los archivos C# finales generados, el escritor consta de 4 pasos: +1. Recorra el modelo de ODCM (es decir, el esquema) para detectar todas las rutas. +2. Cree una representación abstracta de los cmdlets de cada una de las rutas que representan las operaciones en cada una. +3. Convertir todas las representaciones cmdlet abstractas en una representación C# abstracta. +4. Convierta cada representación C# abstracta en una cadena que se escribirá como el contenido de un archivo. + +# Trabajos futuros +- [ ] Mejorar los nombres de los cmdlets generados. + - [ ] Ver si podemos agregar anotaciones al esquema de gráficos que se puedan usar para crear nombres descriptivos para las rutas. +- [ ] Buscar un método para generar y crear cmdlets para todo el esquema de gráficos en una cantidad de tiempo razonable. + - El número de rutas (debido a las propiedades de navegación) aumenta considerablemente una vez que las entidades de AAD son incluidas. +- [ ] Obtener la documentación de ayuda generada del cmdlet para incluir el vínculo a la página correspondiente en la documentación oficial de Graph. +- [x] Implementar la canalización de las salidas del cmdlet en otros cmdlets. +- [ ] Implementar la autenticación no interactiva. + - [ ] Autenticación con certificados. + - [x] Autenticación con un objeto PSCredential. +- [x] Asegurarse de obtener el tiempo de expiración correcto del token de autenticación, el cual se controla cuando es necesaria la actualización automática del token. +- [x] Crear un repositorio independiente para los cmdlets de escenario (que se serán usados como submódulo). +- [ ] Travis CI de integración de GitHub y los casos de prueba. +- [x] Crear un archivo de licencia para el software de terceros usado e incluirlo en el módulo. +- [x] Actualiza el archivo \*.psd1 para incluir los vínculos correctos al correo público de GitHub, el archivo de licencia y el icono. +- [x] Generar cmdlets de la aplicación de ayuda para crear objetos que se puedan serializar para los tipos definidos en el esquema. +- [ ] Obtener las restricciones de capacidad agregadas de OData al esquema de gráficos para que los cmdlets que realizan operaciones no permitidas no sean generados en primer lugar. + +# Preguntas frecuentes +## ¿Dónde está el código generado? +GitHub: https://github.com/Microsoft/Intune-PowerShell-SDK + +## ¿Por qué necesitamos este módulo de PowerShell? +Los clientes han expresado mucho interés en el uso de PowerShell para automatizar las tareas que se ejecutan actualmente con la extensión de Intune en el portal de Azure. + +## ¿Por qué queremos generar automáticamente el módulo de PowerShell? +Si escribimos cada cmdlet manualmente, también tendríamos que actualizar el módulo manualmente cada vez que el esquema del gráfico sea actualizado. + +## ¿Por qué la compilación está siendo realizada por Intune (y por qué no la está realizando el equipo SDK de Graph)? +La mayor parte de la base de usuarios de Intune (profesionales de la tecnología de la información) preferiría trabajar con PowerShell, mientras que el SDK de gráficos está dirigido a desarrolladores que preferirían trabajar con, por ejemplo, C#, Java y Python. Por esto lo necesitamos de forma urgente. La estructura de la sintaxis de PowerShell es incompatible con la estructura del actual generador de SDK de .Net/Java/Python (vea la explicación de por qué tenemos un [escritor personalizado de Vipr](#why-a-custom-writer)). + +## ¿Qué es Vipr? +- La arquitectura es creada en torno a un proyecto de investigación de Microsoft denominado Vipr. +- Generalizando el concepto de transformar la información de una sintaxis a otra. +- Es esencialmente un analizador de texto modular que se adecua especialmente para las definiciones de servicio al estilo OData. +- El ejecutable acepta un montaje de lector y uno de escritor. + - El lector está capacitado para analizar el archivo de entrada de texto en la representación (genérica) intermedia de Vipr. + - El escritor admite la representación intermedia y devuelve una lista de los objetos de archivo, es decir, pares de cadena o ruta de acceso. + - Luego, Vipr escribe estos archivos en la estructura de carpetas que le corresponde a la carpeta de salida. + +## ¿Por qué un escritor personalizado? +No hay ningún escritor existente de PowerShell disponible para Vipr. Asimismo, el escritor del SDK de gráficos .Net/Java/Python no se prestará fácilmente a la sintaxis, el comportamiento o los procedimientos recomendados de PowerShell. + +## ¿Por qué no usar OpenAPI y Swagger? +Esto podría haber sido posible, pero requeriría una transformación adicional del esquema OData de Graph al formato OpenAPI. Cada vez que se realiza una transformación, se corre el riesgo de perder información que podría ser valiosa en el módulo generado de PowerShell. \ No newline at end of file diff --git a/README-localized/README-fr-fr.md b/README-localized/README-fr-fr.md new file mode 100644 index 0000000..e2816d0 --- /dev/null +++ b/README-localized/README-fr-fr.md @@ -0,0 +1,101 @@ +# Table des matières +- [Table des matières](#table-of-contents) +- [Intune-PowerShell-SDK-Code-Generator](#intune-powershell-sdk-code-generator) +- [Contribution](#contributing) +- [Conception](#design) + - [Architecture de haut niveau](#high-level-architecture) + - [Étape de génération automatique](#the-auto-generation-step) +- [Travail futur](#future-work) +- [FAQ](#faq) + - [Où se trouve le code généré ?](#where-is-the-generated-code) + - [Pourquoi ce module PowerShell est-il nécessaire ?](#why-do-we-need-this-powershell-module) + - [Pourquoi générer automatiquement le module PowerShell ?](#why-do-we-want-to-auto-generate-the-powershell-module) + - [Pourquoi est-il élaboré par Intune plutôt que par l’équipe du kit de développement logiciel (SDK) Graph ?](#why-is-intune-building-it-and-why-isnt-the-graph-sdk-team-building-it) + - [Présentation de Vipr](#what-is-vipr) + - [Pourquoi utiliser un rédacteur personnalisé ?](#why-a-custom-writer) + - [Pourquoi ne pas utiliser OpenAPI et Swagger ?](#why-not-use-openapi-and-swagger) + +# Intune-PowerShell-SDK-Code-Generator +Ce référentiel implémente le rédacteur Vipr qui permet de générer des cmdlets PowerShell pour toutes les opérations, fonctions et actions CRUD pour la prise en charge de l’API Microsoft Intune Graph. + +# Contribuer +Ce projet autorise les contributions et les suggestions. +Pour la plupart des contributions, vous devez accepter le contrat de licence de contributeur (CLA, Contributor License Agreement) stipulant que vous êtes en mesure, et que vous vous y engagez, de nous accorder les droits d’utiliser votre contribution. +Pour plus d’informations, visitez https://cla.microsoft.com. + +Lorsque vous soumettez une requête de tirage, un robot CLA détermine automatiquement si vous devez fournir un CLA et si vous devez remplir la requête de tirage appropriée (par exemple, étiquette, commentaire). +Suivez simplement les instructions données par le robot. +Vous ne devrez le faire qu’une seule fois au sein de tous les référentiels à l’aide du CLA. + +Ce projet a adopté le [code de conduite Open Source de Microsoft](https://opensource.microsoft.com/codeofconduct/). +Pour en savoir plus, reportez-vous à la [FAQ relative au code de conduite](https://opensource.microsoft.com/codeofconduct/faq/) +ou contactez [opencode@microsoft.com](mailto:opencode@microsoft.com) pour toute question ou tout commentaire. + +# Conception +## Architecture de haut niveau +![Architecture de haut niveau](Design.jpg) +Voici comment s’articule ce module PowerShell. +1. Vipr.exe est exécuté avec les arguments suivants pour générer le code qui définit le comportement des cmdlets : +– La sortie de génération du projet GraphODataPowerShellWriter (c-à-d : GraphODataPowerShellWriter.dll). +– Un schéma Graph (ex : ce que renvoie https://graph.microsoft.com/v1.0/$metadata) ; l’extension de ce fichier est « .csdl », il est situé dans « ~/TestGraphSchemas ». +2. La documentation générée comme donnée de sortie de Vipr est extraite vers un fichier XML. Ce fichier XML est ensuite utilisé par PowerShell pour afficher le résultat de la cmdlet « Get-Help ». +3. Il est plus cohérent de taper certaines fonctionnalités manuellement dans PowerShell. Ces cmdlets sont donc écrites dans leurs propres modules. Ces modules sont situés dans « ~/src/PowerShellGraphSDK/PowerShellModuleAdditions/CustomModules ». +4. Les résultats des trois étapes précédentes (c-à-d : les cmdlets générées, la documentation des cmdlets et les cmdlets manuelles) sont combinés selon un fichier manifeste PowerShell. L’extension de ce fichier est « .psd1 ». +5. Le fichier manifeste PowerShell créé à l’étape précédente est ensuite utilisé pour importer et utiliser le module. Par exemple, avec un fichier manifeste « Intune.psd1 », exécutez « Import-Module ./Intune.psd1 » dans une fenêtre PowerShell pour importer le module. + +## Étape de génération automatique +![Génération du module binaire PowerShell](Generating_the_PowerShell_Binary_Module.jpg) +Ceci est un aperçu détaillé de l’étape 1 de la section [Architecture de haut niveau](#high-level-architecture). +– Le fichier de schéma de définition (CSDL) est passé à Vipr. +– Le lecteur OData v4 intégré à Vipr est utilisé pour lire ce fichier. Ce lecteur convertit la définition de schéma en une représentation intermédiaire appelée Modèle ODCM. +– Notre rédacteur personnalisé est passé à Vipr pour le traiter. Le rédacteur effectue 4 étapes afin de convertir le modèle ODCM et générer les fichiers C# finaux : +1. Parcours du Modèle ODCM (c-à-d le schéma) pour découvrir chaque route. +2. Pour chaque route, création d’une représentation abstraite des cmdlets représentant chaque opération de la route. +3. Conversion de chaque représentation abstraite de cmdlet en une représentation abstraite C#. +4. Pour chaque représentation abstraite C#, conversion en une chaîne ensuite écrite comme contenu d’un fichier. + +# Travail futur +- [] Améliorer le nommage des cmdlets générées. + - [] Ajouter si possible des annotations au schéma Graph pour la création de noms compréhensibles pour les routes. +- [] Trouver un moyen de générer et intégrer des cmdlets pour le schéma Graph entier dans un délai raisonnable. + - Le nombre de routes augmente énormément lorsque des entités AAD sont incluses (en raison des propriétés de navigation). +- [] Faire en sorte que la documentation d’aide de la cmdlet générée inclue un lien à la page appropriée de la documentation Graph officielle. +- [x] Implémenter la canalisation des sorties vers d’autres cmdlets directement. +- [] Implémenter l’authentification non-interactive. + - [] Authentification avec certificats. + - [x] Authentification avec un objet PSCredential. +- [x] S’assurer d’obtenir la date d’expiration correcte du jeton d’authentification – Possible en rafraîchissant automatiquement le jeton quand c’est nécessaire. +- [x] Créer un référentiel séparé pour les cmdlets de scénario (à fin d’utilisation comme sous-module). +- [] Intégration Travis CI GitHub + cas de tests. +- [x] Créer un fichier de licence pour les logiciels tiers utilisés et l’inclure dans le module. +- [x] Mettre à jour le fichier \*.psd1 pour inclure les liens corrects vers le GitHub publique, le fichier de licence et l’icône. +- [x] Créer des cmdlets d’assistance pour créer des objets pouvant être sérialisés dans des types définis dans le schéma. +- [] Ajouter des Restrictions de Capabilité OData au schéma Graph afin que les cmdlets effectuant des opérations interdites ne soient tout simplement pas générées. + +# FAQ +## Où se trouve le code généré ? +GitHub : https://github.com/Microsoft/Intune-PowerShell-SDK + +## Pourquoi ce module PowerShell est-il nécessaire ? +Les clients ont exprimé un grand intérêt dans l’utilisation de PowerShell pour automatiser des tâches actuellement exécutées par le biais de l’extension Intune dans le Portail Azure. + +## Pourquoi générer automatiquement le module PowerShell ? +En tapant chaque cmdlet manuellement, il faut mettre à jour le module manuellement chaque fois que le schéma Graph est mis à jour. + +## Pourquoi est-il élaboré par Intune plutôt que par l’équipe du kit de développement logiciel (SDK) Graph ? +La plus grande part de la base d’utilisateurs d’Intune (IT Professionals), préfèrent travailler avec PowerShell, alors que le kit de développement logiciel Graph vise les développeurs qui préfèrent travailler avec, par exemple, C#, Java et Python. Voilà pourquoi nous avons urgemment besoin de ce module. La structure syntaxique de PowerShell ne se prête pas à celle du générateur du kit de développement logiciel .Net/Java/Python (voir pourquoi nous avons un [rédacteur Vipr personnalisé](#why-a-custom-writer)). + +## Présentation de Vipr +- L’architecture est construite autour du projet de recherche Microsoft Vipr. +- Vipr généralise le concept de transformation d’informations d’une syntaxe à une autre. +- Vipr est comme un analyseur de texte modulaire spécialement adapté aux définitions des services dans le style d’OData. +- L’exécutable accepte un assembly lecteur et un assembly rédacteur. + - Le lecteur peut analyser le fichier texte d’entrée et le transformer en une représentation (générique) intermédiaire. + - Le rédacteur reçoit cette représentation intermédiaire et renvoie une liste d’objets fichiers, par exemple des paires (chaîne, chemin d’accès). + - Vipr écrit ensuite ces fichiers de la structure du dossier donné au dossier de sortie. + +## Pourquoi utiliser un rédacteur personnalisé ? +Il n’existe aucun rédacteur PowerShell pour Vipr. De même, le rédacteur du kit de développement logiciel Graph pour .Net/Java/Python ne se prête pas facilement à la syntaxe, le comportement ou les bonnes habitudes de PowerShell. + +## Pourquoi ne pas utiliser OpenAPI et Swagger ? +C’est une possibilité, mais cela nécessiterait une transformation supplémentaire du schéma OData de Graph vers le format OpenAPI. À chaque transformation, il y a un risque de perte d’informations précieuses dans le module PowerShell généré. \ No newline at end of file diff --git a/README-localized/README-ja-jp.md b/README-localized/README-ja-jp.md new file mode 100644 index 0000000..4eabb93 --- /dev/null +++ b/README-localized/README-ja-jp.md @@ -0,0 +1,101 @@ +# 目次 +- [目次](#table-of-contents) +- [Intune-PowerShell-SDK-Code-Generator](#intune-powershell-sdk-code-generator) +- [投稿](#contributing) +- [デザイン](#design) + - [アーキテクチャの概要](#high-level-architecture) + - [自動生成ステップ](#the-auto-generation-step) +- [今後の作業](#future-work) +- [FAQ](#faq) + - [生成されたコードはどこにありますか?](#where-is-the-generated-code) + - [この PowerShell モジュールはなぜ必要なのですか?](#why-do-we-need-this-powershell-module) + - [PowerShell モジュールを自動生成した方がよいのはなぜですか?](#why-do-we-want-to-auto-generate-the-powershell-module) + - [Intune によってビルドされるのはなぜですか? (Graph SDK チームによってビルドされないのはなぜですか?)](#why-is-intune-building-it-and-why-isnt-the-graph-sdk-team-building-it) + - [Vipr とは](#what-is-vipr) + - [カスタム ライターを使うのはなぜですか?](#why-a-custom-writer) + - [OpenAPI と Swagger はなぜ使わないのですか?](#why-not-use-openapi-and-swagger) + +# Intune-PowerShell-SDK-Code-Generator +このリポジトリでは、Microsoft Intune Graph API のサポート用のすべての CRUD 操作、関数、アクションの PowerShell コマンドレットを生成する、Vipr ライターが実装されます。 + +# 投稿 +このプロジェクトは投稿や提案を歓迎します。たいていの投稿には、投稿者のライセンス契約 (CLA) に同意することにより、 +投稿内容を使用する権利を Microsoft に付与する権利が自分にあり、 +実際に付与する旨を宣言していただく必要があります。詳細については、https://cla.microsoft.com をご覧ください。 + +プル要求を送信すると、CLA を提供する必要があるかどうかを CLA ボットが自動的に判断してプル要求を適切に修飾 (ラベル、コメントなど) します。 +ボットの指示に従ってください。この操作は、 +CLA を使用してすべてのリポジトリ全体に対して 1 度のみ行う必要があります。 + +このプロジェクトでは、[Microsoft Open Source Code of Conduct (Microsoft オープン ソース倫理規定)](https://opensource.microsoft.com/codeofconduct/) が採用されています。 +詳細については、「[Code of Conduct の FAQ (倫理規定の FAQ)](https://opensource.microsoft.com/codeofconduct/faq/)」 +を参照してください。また、その他の質問やコメントがあれば、[opencode@microsoft.com](mailto:opencode@microsoft.com) までお問い合わせください。 + +# デザイン +## アーキテクチャの概要 +![アーキテクチャの概要](Design.jpg) +PowerShell モジュールがどのように作られているかの概要です。 +1.Vipr.exe は、コマンドレットの動作を定義するコードを生成するために次の引数を使用して実行されます。 +- GraphODataPowerShellWriter プロジェクトのビルド出力 (つまり、GraphODataPowerShellWriter.dll). +- Graph スキーマ (例: https://graph.microsoft.com/v1.0/$metadata の呼び出しの結果) - このファイルは拡張子 ".csdl" を持ち、"~/TestGraphSchemas" にあります。 +2.Vipr の出力で生成されたドキュメントは、XML ファイルに抽出されます。この XML ファイルは、"Get-help" コマンドレットの出力を表示するために PowerShell によって使用されます。 +3.一部の機能は PowerShell で手動で記述する方がより適しているため、これらのコマンドレットはそれぞれ独自のモジュールに記述されます。これらのモジュールは、 "~/src/PowerShellGraphSDK/PowerShellModuleAdditions/CustomModules" にあります。 +4.前の 3 つの手順の出力 (つまり、生成されたコマンドレット、コマンドレットのドキュメント、および手書きのコマンドレット) は、PowerShell マニフェスト ファイルを使用して結合されます。このファイルの拡張子は ".psd1" です。 +5.前の手順で作成した PowerShell マニフェスト ファイルは、モジュールをインポートして使用するために使われます。たとえば、マニフェスト ファイルの名前が "Intune.psd1"である場合は、PowerShell ウィンドウで "Import-Module ./Intune.psd1" を実行してモジュールをインポートできます。 + +## 自動生成ステップ +![Generating the PowerShell Binary Module (PowerShell バイナリ モジュールの生成)](Generating_the_PowerShell_Binary_Module.jpg) +「[アーキテクチャの概要](#high-level-architecture)」セクションの手順 1 を詳細に示したものです。 +- スキーマ定義 (CSDL) ファイルが Vipr に送られます。 +- Vipr に組み込まれている OData v4 リーダーを使用して CSDL ファイルが読み込まれます。リーダーはスキーマ定義を ODCM モデルと呼ばれる中間表現に変換します。 +- この ODCM モデルを処理するために、カスタム ライターが Vipr に渡されます。ライターは、4 つの手順で ODCM モデルを最終的に生成された C# ファイルに変換します。 +1.ODCM モデル (つまり、スキーマ) をスキャンして各ルートを検出します。 +2.ルートごとに、ルート上の各操作を表すコマンドレットの抽象表現を作成します。 +3.それぞれのコマンドレットの抽象表現を C# の抽象表現に変換します。 +4.それぞれの C# の抽象表現を、ファイルのコンテンツとして記述される文字列に変換します。 + +# 今後の作業 +- [ ] 生成されたコマンドレットの名前付けを改善する。 + - [ ] ルートのフレンドリ名を作成するのに使用できる注釈を Graph スキーマに追加できるかどうかを検討する。 +- [ ] Graph スキーマ全体のコマンドレットを合理的な時間内に生成してビルドする方法を見つける。 + - AAD エンティティを含めた場合、(ナビゲーション プロパティによる) ルート数は大幅に増加します。 +- [ ] 生成されたコマンドレットのヘルプドキュメントに、公式の Graph ドキュメント内の正しいページへのリンクを含める。 +- [x] コマンドレット出力のパイプ処理を、他のコマンドレットに直接実装する。 +- [ ] 非対話型認証を実装する。 + - [ ] 証明書を使用して認証を行う。 + - [x] PSCredential オブジェクトを使用して認証を行う。 +- [x] 認証トークンの正しい有効期限を確実に取得できるようにする。これは、必要に応じてトークンを自動的に更新することにより処理します。 +- [x] (サブモジュールとして使用する) シナリオ コマンドレット用に別のレポジトリを作成する。 +- [ ] Travis CI GitHub の統合とテスト ケース。 +- [x] モジュールに含めて使用するサード パーティー製ソフトウェア用のライセンス ファイルを作成する。 +- [x] \*.psd1 ファイルを更新してパブリック GitHub、ライセンス ファイル、およびアイコンへの正しいリンクを含める。 +- [x] スキーマで定義される種類にシリアル化することが可能なオブジェクトを作成する、ヘルパー コマンドレットを作成する。 +- [ ] OData Capability Restrictions を Graph スキーマに追加して、禁止操作を実行するコマンドレットがそもそも生成されないようにする。 + +# FAQ +## 生成されたコードはどこにありますか? +GitHub: https://github.com/Microsoft/Intune-PowerShell-SDK + +## この PowerShell モジュールはなぜ必要なのですか? +現在は Intune 拡張機能を使用して Azure ポータルで実行されている作業を PowerShell を使用して自動化することに対して、お客様から強い関心が寄せられました。 + +## PowerShell モジュールを自動生成した方がよいのはなぜですか? +各コマンドレットを手動で作成した場合、Graph スキーマを更新するたびに、手動でモジュールを更新する必要があります。 + +## Intune によってビルドされるのはなぜですか? (Graph SDK チームによってビルドされないのはなぜですか?) +Intune のユーザー ベース (IT プロフェッショナル) のほとんどが PowerShell を使用して作業することを希望することが予想されます。一方、Graph SDK は C#、Java、および Python を使用することを希望する開発者向けに作られています。PowerShell モジュールを緊急に必要とする理由はここにあります。PowerShell の構文構造は、既存の Net/Java/Python SDK ジェネレーターの構造には適していません ([カスタム Vipr ライター](#why-a-custom-writer)がある理由の説明を参照してください)。 + +## Vipr とは +- このアーキテクチャは、Vipr と呼ばれる Microsoft Research プロジェクトに基づいて構築されています。 +- Vipr は、情報を 1 つの構文から別の構文に変換する概念を一般化します。 +- 本質的には、OData スタイルのサービス定義に最適なモジュール式のテキスト パーサーです。 +- この実行可能ファイルは、リーダー アセンブリとライター アセンブリを受け取ります。 + - リーダーは、入力テキスト ファイルを Vipr の中間 (汎用) 表現に解析できます。 + - ライターは、この中間表現を受け入れ、ファイル オブジェクト (つまり、文字列とパスのペア) のリストを返します。 + - 次に、Vipr は、指定されたフォルダー構造でこれらのファイルを出力フォルダーに書き込みます。 + +## カスタム ライターを使うのはなぜですか? +いずれの既存の PowerShell ライターも、Vipr には使用できません。また、.Net/Java/Python 用 Graph SDK のライターは、PowerShell の構文、動作、または作業には適していません。 + +## OpenAPI と Swagger はなぜ使わないのですか? +使用することは可能ですが、使用するには Graph の OData スキーマから OpenAPI 形式への追加の変換が必要になります。変換を行うたびに、生成された PowerShell モジュールで役立つ可能性のある情報を失う危険が生じます。 \ No newline at end of file diff --git a/README-localized/README-pt-br.md b/README-localized/README-pt-br.md new file mode 100644 index 0000000..70581bb --- /dev/null +++ b/README-localized/README-pt-br.md @@ -0,0 +1,101 @@ +# Sumário +- [Sumário](#table-of-contents) +- [Intune-PowerShell-SDK-Code-Generator](#intune-powershell-sdk-code-generator) +- [Colaboração](#contributing) +- [Design](#design) + - [Arquitetura de Alto Nível](#high-level-architecture) + - [A Etapa de Geração Automática](#the-auto-generation-step) +- [Trabalho futuro](#future-work) +- [Perguntas Frequentes](#faq) + - [Onde está o código gerado?](#where-is-the-generated-code) + - [Por que precisamos deste módulo do PowerShell?](#why-do-we-need-this-powershell-module) + - [Por que queremos gerar automaticamente o módulo do PowerShell?](#why-do-we-want-to-auto-generate-the-powershell-module) + - [Por que o Intune está construindo (e por que a equipe do Graph SDK não está construindo)?](#why-is-intune-building-it-and-why-isnt-the-graph-sdk-team-building-it) + - [O que é o Vipr?](#what-is-vipr) + - [Por que um gravador personalizado?](#why-a-custom-writer) + - [Por que não usar OpenAPI e Swagger?](#why-not-use-openapi-and-swagger) + +# Intune-PowerShell-SDK-Code-Generator +Este repositório implementa o gravador Vipr que gera cmdlets do PowerShell para todas as operações, funções e ações de CRUD para suporte à API do Microsoft Intune e do Microsoft Graph. + +# Colaboração +Este projeto recebe e agradece as contribuições e sugestões. +A maioria das contribuições exige que você concorde com um Contrato de Licença de Colaborador (CLA) declarando que você tem o direito a, nos conceder os direitos de uso de sua contribuição, e de fato o faz. +Para saber mais, acesse https://cla.microsoft.com. + +Quando você envia uma solicitação de pull, um bot de CLA determina automaticamente se você precisa fornecer um CLA e decora o PR adequadamente (por exemplo, rótulo, comentário). +Basta seguir as instruções fornecidas pelo bot. +Você só precisa fazer isso uma vez em todos os repos que usam nosso CLA. + +Este projeto adotou o [Código de Conduta de Código Aberto da Microsoft](https://opensource.microsoft.com/codeofconduct/). +Para saber mais, confira as [Perguntas frequentes sobre o Código de Conduta](https://opensource.microsoft.com/codeofconduct/faq/) +ou contate [opencode@microsoft.com](mailto:opencode@microsoft.com) se tiver outras dúvidas ou comentários. + +# Design +## Arquitetura de Alto Nível +![Arquitetura de Alto Nível](Design.jpg) +Esta é a visão geral de como o módulo do PowerShell é elaborado. +1. O Vipr.exe é executado com os seguintes argumentos para gerar o código que define o comportamento dos cmdlets. +- A saída de compilação do projeto GraphODataPowerShellWriter (ou seja, GraphODataPowerShellWriter.dll). +- Um esquema de gráfico (por exemplo, o resultado da chamada https://graph.microsoft.com/v1.0/$metadata)- esse arquivo tem a extensão ".csdl" e está localizado em "~/TestGraphSchemas". +2. A documentação gerada na saída do Vipr é extraída em um arquivo XML. Esse arquivo XML é usado pelo PowerShell para exibir a saída do cmdlet 'Get-Help'. +3. Algumas funcionalidades fazem mais sentido serem escritas à mão no PowerShell; portanto, esses cmdlets são gravados em seus próprios módulos. Esses módulos estão localizados em "~/src/PowerShellGraphSDK/PowerShellModuleAdditions/CustomModules". +4. As saídas das 3 etapas anteriores (ou seja, os cmdlets gerados, a documentação do cmdlet e os cmdlets escritos à mão) são combinados usando um arquivo de manifesto do PowerShell. Esse arquivo tem a extensão ".psd1". +5. O arquivo de manifesto do PowerShell criado na etapa anterior é usado para importar e usar o módulo. Por exemplo, se o arquivo de manifesto foi chamado "Intune.psd1", em uma janela do PowerShell, você pode executar "Import-Module ./Intune.psd1" para importar o módulo. + +## A Etapa de Geração Automática +![Gerando o Módulo Binário do PowerShell](Generating_the_PowerShell_Binary_Module.jpg) +Essa é uma visão detalhada na etapa 1 da seção [Arquitetura de Alto Nível](#high-level-architecture). +- O arquivo de definição de esquema (CSDL) é alimentado em Vipr. +– O leitor do OData v4, que está integrado ao Vipr, é usado para ler o arquivo CSDL. Este leitor converte a definição de esquema em uma representação intermediária, chamada Modelo ODCM. +- Nosso gravador personalizado é passado para o Vipr para processar esse modelo ODCM. O gravador consiste em 4 etapas para converter o modelo ODCM para os arquivos C# gerados finais: +1. Percorra o modelo ODCM (por exemplo, o esquema) para descobrir cada roteiro. +2. Para cada rota, crie uma representação abstrata dos cmdlets que representem cada operação no roteiro. +3. Converta cada representação de cmdlet abstrata em uma representação abstrata em C#. +4. Para cada representação abstrata em C#, converta-a em uma sequência que será gravada como o conteúdo de um arquivo. + +# Trabalho futuro +- [ ] Melhore a nomeação de cmdlets gerados. + - [ ] Veja se podemos adicionar anotações ao Esquema de gráfico que podem ser usadas para criar nomes amigáveis ​​para os roteiros. +- [ ] Encontre uma maneira de gerar e criar cmdlets para todo o Esquema de gráfico em um período de tempo razoável. + - O número de roteiros (devido às propriedades de navegação) aumenta drasticamente quando as entidades do AAD são incluídas. +- [ ] Obtenha a documentação de ajuda do cmdlet gerada para incluir um link para a página apropriada na documentação oficial do Graph. +- [x] Implemente o pipe de saídas de cmdlets diretamente em outros cmdlets. +- [ ] Implementar autenticação não interativa. + - [ ] Autenticação com certificados. + - [x] Autenticação com um objeto PSCredential. +- [x] Verifique se obtemos o tempo de expiração correto do token de autenticação - isso é tratado ao atualizar automaticamente o token quando necessário. +- [x] Crie um repositório separado para os cmdlets de cenário (a serem usados ​​como um submódulo). +- [ ] Integração Travis CI GitHub + casos de teste. +- [x] Crie um arquivo de licença para o software de terceiros que usamos e inclua-o no módulo. +- [x] Atualize o arquivo \*.psd1 para incluir os links corretos para o GitHub público, arquivo de licença e ícone. +- [x] Crie cmdlets auxiliares que criam objetos que podem ser serializados para os tipos definidos no esquema. +- [ ] Obtenha as Restrições de Capacidade do OData adicionadas ao Esquema de gráfico para que os cmdlets que executam operações não permitidas não sejam gerados em primeiro lugar. + +# Perguntas Frequentes +## Onde está o código gerado? +GitHub: https://github.com/Microsoft/Intune-PowerShell-SDK + +## Por que precisamos deste módulo do PowerShell? +Os clientes expressam muitos interesse no uso do PowerShell para automatizar as tarefas que estão sendo executadas pela extensão do Intune no portal do Azure. + +## Por que queremos gerar automaticamente o módulo do PowerShell? +Se escrevermos cada cmdlet manualmente, precisaremos atualizar manualmente o módulo sempre que o Esquema de gráfico for atualizado. + +## Por que o Intune está construindo (e por que a equipe de SDK do Graph não está construindo)? +A maior parte da base de usuários do Intune (Profissionais de TI) prefere trabalhar com o PowerShell, enquanto o SDK do Graph é direcionado para desenvolvedores que preferem trabalhar com o C#, Java e Python, por exemplo. Esse é o motivo pelo qual precisamos dele urgente. A estrutura da sintaxe do PowerShell não se encaixa na estrutura do gerador SDK .Net/Java/Python existente (confira a explicação de por que temos um [Gravador Vipr Personalizado](#why-a-custom-writer)). + +## O que é o Vipr? +- A arquitetura é construída em torno de um projeto de pesquisa da Microsoft chamado Vipr. +- Ele generaliza o conceito de transformar informações de uma sintaxe para outra. +- Ele é essencialmente um analisador de texto modular especialmente adequado para definições de serviço no estilo OData. +- O executável aceita um assembly Leitor e um assembly Gravador. + - O Leitor é capaz de analisar o arquivo de texto de entrada na representação intermediária (genérica) do Vipr. + - O Gravador aceita essa representação intermediária e retorna uma lista de objetos de arquivo, ou seja, pares (cadeia de caracteres, caminho). + - O Vipr grava esses arquivos na estrutura de pastas especificada para a pasta de saída. + +## Por que um gravador personalizado? +Nenhum gravador do PowerShell existente está disponível para Vipr. Além disso, o gravador SDK do Graph .Net/Java/Python não se prestaria facilmente à sintaxe, comportamento ou práticas recomendadas do PowerShell. + +## Por que não usar OpenAPI e Swagger? +Isso teria sido possível, mas exigiria uma transformação extra do Esquema de gráfico do OData para o formato OpenAPI. A cada transformação, corre-se o risco de perder informações que podem ser valiosas no módulo do PowerShell gerado. \ No newline at end of file diff --git a/README-localized/README-ru-ru.md b/README-localized/README-ru-ru.md new file mode 100644 index 0000000..1a59d8d --- /dev/null +++ b/README-localized/README-ru-ru.md @@ -0,0 +1,101 @@ +# Содержание +- [Содержание](#table-of-contents) +- [Intune-PowerShell-SDK-Code-Generator](#intune-powershell-sdk-code-generator) +- [Участие](#contributing) +- [Проектирование](#design) + - [Высокоуровневая архитектура](#high-level-architecture) + - [Шаг автоматического создания](#the-auto-generation-step) +- [Будущие задачи](#future-work) +- [Вопросы и ответы](#faq) + - [Где создается код?](#where-is-the-generated-code) + - [Зачем нам нужен этот модуль PowerShell?](#why-do-we-need-this-powershell-module) + - [Почему мы хотим автоматически генерировать модуль PowerShell?](#why-do-we-want-to-auto-generate-the-powershell-module) + - [Почему Intune создает его (и почему это не создает команда Graph SDK)?](#why-is-intune-building-it-and-why-isnt-the-graph-sdk-team-building-it) + - [Что такое Vipr?](#what-is-vipr) + - [Почему автор на заказ?](#why-a-custom-writer) + - [Почему не использовать OpenAPI и Swagger?](#why-not-use-openapi-and-swagger) + +# Intune-PowerShell-SDK-Code-Generator +В этом репозитории реализован модуль записи Vipr, который генерирует командлеты PowerShell для всех операций, функций и действий CRUD для поддержки Microsoft Intune Graph Api. + +# Участие +Мы всегда рады предложениям и помощи в работе над проектом. +Обычно для добавления своих вариантов необходимо принять Лицензионное соглашение с участником (CLA), заявив, что вы имеете право предоставлять и предоставляете нам права на использование своего варианта. +Подробности см. на сайте https://cla.microsoft.com. + +Когда вы будете отправлять запрос на вытягивание, CLA-бот автоматически определит, нужно ли вам предоставить CLA и соответствующим образом изменит внешний вид запроса на вытягивание (например, добавит метку, комментарий). +Просто следуйте инструкциям бота. +Это нужно будет сделать всего один раз для добавления своих вариантов во все репозитории, использующие наш CLA. + +Этот проект соответствует [Правилам поведения разработчиков открытого кода Майкрософт](https://opensource.microsoft.com/codeofconduct/). +Дополнительные сведения см. в разделе [часто задаваемых вопросов о правилах поведения](https://opensource.microsoft.com/codeofconduct/faq/). +Если у вас возникли вопросы или замечания, напишите нам по адресу [opencode@microsoft.com](mailto:opencode@microsoft.com). + +# Проектирование +## Высокоуровневая архитектура +![Архитектура высокого уровня](Design.jpg) +Это обзор того, как модуль PowerShell собран вместе. +1. Vipr.exe запускается со следующими аргументами для генерации кода, который определяет поведение командлетов. - Результат сборки проекта GraphODataPowerShellWriter (то есть GraphODataPowerShellWriter.dll). +- Схема Graph (например, результат вызова https://graph.microsoft.com/v1.0/$metadata) +- этот файл имеет расширение «.csdl» и находится в «~ / TestGraphSchemas». +2. Документация, которая была сгенерирована в выходных данных Vipr, извлекается в файл XML. Этот XML-файл используется PowerShell для отображения выходных данных командлета Get-Help. +3. Некоторые функции имеют смысл писать вручную в PowerShell, поэтому эти командлеты пишутся в своих собственных модулях. Эти модули находятся в "~/src/PowerShellGraphSDK/PowerShellModuleAdditions/CustomModules". +4. Выходные данные предыдущих 3 шагов (то есть сгенерированные командлеты, документация по командлетам и рукописные командлеты) объединяются с помощью файла манифеста PowerShell. Этот файл имеет расширение ".psd1". +5. Файл манифеста PowerShell, созданный на предыдущем шаге, затем используется для импорта и использования модуля. Например, если файл манифеста назывался «Intune.psd1», вы можете в окне PowerShell запустить «Import-Module ./Intune.psd1», чтобы импортировать модуль. + +## Шаг автоматического создания +![Генерация двоичного модуля PowerShell](Generating_the_PowerShell_Binary_Module.jpg) +Подробно рассмотрим шаг 1 в разделе [Архитектура высокого уровня](#high-level-architecture). +- Файл определения схемы (CSDL) подается в Vipr. +- Читатель OData v4, который встроен в Vipr, используется для чтения файла CSDL. Этот читатель преобразует определение схемы в промежуточное представление, называемое моделью ODCM. +- Наш пользовательский писатель передается в Vipr для обработки этой модели ODCM. Модуль записи состоит из 4 шагов для преобразования модели ODCM в окончательно сгенерированные файлы C #: +1. Пройдите модель ODCM (то есть схему), чтобы обнаружить каждый маршрут. +2. Для каждого маршрута создайте абстрактное представление командлетов, представляющих каждую операцию на маршруте. +3. Преобразуйте каждое абстрактное представление командлета в абстрактное представление C #. +4. Для каждого абстрактного представления C # преобразуйте его в строку, которая будет записана как содержимое файла. + +# Будущие задачи +- [ ] Улучшение именования сгенерированных командлетов. + - [ ] Посмотрим, сможем ли мы добавить аннотации к схеме Graph, которые можно использовать для создания понятных имен для маршрутов. +- [ ] Найдите способ генерировать и создавать командлеты для всей схемы Graph за разумное время. + - Количество маршрутов (из-за свойств навигации) резко увеличивается после включения объектов AAD. +- [ ] Получите сгенерированную справочную документацию по командлетам, чтобы включить ссылку на соответствующую страницу в официальной документации Graph. +- [x] Реализация передачи выходных данных командлета непосредственно в другие командлеты. +- [ ] Реализовать неинтерактивную аутентификацию. + - [ ] Аутентификация с сертификатами. + - [x] Аутентификация с PSCredential объектом. +- [x] Убедитесь, что мы получили правильное время истечения аутентификационного токена - это обрабатывается автоматическим обновлением токена при необходимости. +- [x] Создайте отдельный репозиторий для командлетов сценария (для использования в качестве подмодуля). +- [ ] Трэвис CI GitHub интеграция + контрольные примеры. +- [x] Создайте файл лицензии для используемого нами программного обеспечения сторонних производителей и включите его в модуль. +- [x] Обновите файл * .psd1, добавив в него правильные ссылки на общедоступный GitHub, файл лицензии и значок. +- [x] Создайте вспомогательные командлеты, которые создают объекты, которые можно сериализовать в типы, определенные в схеме. +- [] Получить ограничения возможностей OData, добавленные в схему Graph, чтобы командлеты, выполняющие запрещенные операции, не создавались в первую очередь. + +# Вопросы и ответы +## Где создается код? +GitHub: https://github.com/Microsoft/Intune-PowerShell-SDK + +## Зачем нам нужен этот модуль PowerShell? +Клиенты проявили большой интерес к использованию PowerShell для автоматизации задач, которые в настоящее время выполняются с помощью расширения Intune на портале Azure. + +## Почему мы хотим автоматически генерировать модуль PowerShell? +Если мы пишем каждый командлет вручную, нам нужно будет вручную обновлять модуль каждый раз, когда обновляется схема Graph. + +## Почему Intune создает его (и почему это не создает команда Graph SDK)? +Большинство пользователей Intune (ИТ-специалисты) предпочитают работать с PowerShell, тогда как Graph SDK ориентирован на разработчиков, которые предпочли бы работать, например, с. C #, Java и Python. Вот почему нам это нужно срочно. Структура синтаксиса PowerShell не поддается структуре существующего генератора SDK .Net / Java / Python (см. Объяснение, почему у нас есть [Custom Vipr Writer](#why-a-custom-writer)). + +## Что такое Vipr? +- Архитектура построена вокруг проекта Microsoft Research под названием Vipr. +- Обобщает концепцию преобразования информации из одного синтаксиса в другой. +- По сути, это модульный анализатор текста, который особенно хорошо подходит для определений сервисов в стиле OData. +- Исполняемый файл принимает сборку Reader и Writer. + - Reader может анализировать входной текстовый файл в промежуточное (универсальное) представление Vipr. + - Writer принимает это промежуточное представление и возвращает список файловых объектов, то есть пар (строка, путь). + - Затем Vipr записывает эти файлы в заданной структуре папок в выходную папку. + +## Почему автор на заказ? +Для Vipr нет доступных средств записи PowerShell. Кроме того, писатель .Net/Java/Python Graph SDK's не может легко приспособиться к синтаксису, поведению и лучшим методикам PowerShell. + +## Почему не использовать OpenAPI и Swagger? +Это было бы возможно, но потребовало бы дополнительного преобразования из схемы OData Graph в формат OpenAPI. С каждым преобразованием возникает риск потери информации, которая может быть полезна в сгенерированном модуле PowerShell. \ No newline at end of file diff --git a/README-localized/README-zh-cn.md b/README-localized/README-zh-cn.md new file mode 100644 index 0000000..1fe0c38 --- /dev/null +++ b/README-localized/README-zh-cn.md @@ -0,0 +1,101 @@ +# 目录 +- [目录](#table-of-contents) +- [Intune-PowerShell-SDK-Code-Generator](#intune-powershell-sdk-code-generator) +- [参与](#contributing) +- [设计](#design) + - [高级体系结构](#high-level-architecture) + - [自动生成步骤](#the-auto-generation-step) +- [未来工作](#future-work) +- [常见问题解答](#faq) + - [生成的代码在哪里？](#where-is-the-generated-code) + - [为什么需要此 PowerShell 模块？](#why-do-we-need-this-powershell-module) + - [为什么要自动生成 PowerShell 模块？](#why-do-we-want-to-auto-generate-the-powershell-module) + - [为什么是 Intune 构建（为什么不是 Graph SDK 团队构建）？](#why-is-intune-building-it-and-why-isnt-the-graph-sdk-team-building-it) + - [什么是 Vipr？](#what-is-vipr) + - [为什么是自定义编写器？](#why-a-custom-writer) + - [为什么不使用 OpenAPI 和 Swagger？](#why-not-use-openapi-and-swagger) + +# Intune-PowerShell-SDK-Code-Generator +此存储库实现的 Vipr 编写器将为 Microsoft Intune Graph Api 支持的所有 CRUD 运算、函数和操作生成 PowerShell cmdlet。 + +# 参与 +本项目欢迎供稿和建议。 +大多数的供稿都要求你同意“参与者许可协议 (CLA)”，声明你有权并确定授予我们使用你所供内容的权利。 +有关详细信息，请访问 https://cla.microsoft.com。 + +在提交拉取请求时，CLA 机器人会自动确定你是否需要提供 CLA 并适当地修饰 PR（例如标记、批注）。 +只需按照机器人提供的说明操作即可。 +只需在所有存储库上使用我们的 CLA 执行此操作一次。 + +此项目已采用 [Microsoft 开放源代码行为准则](https://opensource.microsoft.com/codeofconduct/)。 +有关详细信息，请参阅[行为准则常见问题解答](https://opensource.microsoft.com/codeofconduct/faq/)。 +如有其他任何问题或意见，也可联系 [opencode@microsoft.com](mailto:opencode@microsoft.com)。 + +# 设计 +## 高级体系结构 +![高级体系结构](Design.jpg) +如何组合 PowerShell 模块的概览。 +1.Vipr.exe 运行下列参数，以生成定义 cmdlet 行为的代码。 +- GraphODataPowerShellWriter 项目的生成输出（即 GraphODataPowerShellWriter.dll）。 +- Graph 架构（例如调用 https://graph.microsoft.com/v1.0/$metadata 的结果） - 该文件的扩展名为 ".csdl"，位于"~/TestGraphSchemas"中。 +2.Vipr 输出中生成的文档被提取至 XML 文件中。该 XML 文件由 PowerShell 使用，以显示 'Get-Help' cmdlet 的输出。 +3.某些功能对于在PowerShell中手动编写更有意义，因此在各自的模块中编写这些 cmdlet。这些模块位于 "~/src/PowerShellGraphSDK/PowerShellModuleAdditions/CustomModules"。 +4.前 3 步的输出（即生成的 cmdlet、cmdlet 文档和手动编写的 cmdlet）使用 PowerShell 清单文件进行合并。此文件的扩展名为 ".psd1"。 +5.上一步中创建的 PowerShell 清单文件随后用于导入和使用模块。例如，如果清单文件名称为 "Intune. psd1"，则可以在 PowerShell 窗口中运行 "Import-Module/Intune.psd1" 导入该模块。 + +## 自动生成步骤 +![生成 PowerShell 二进制模块](Generating_the_PowerShell_Binary_Module.jpg) +这是[高级体系结构](#high-level-architecture)部分步骤 +1 的详细信息。- 架构定义（CSDL）文件被输入 Vipr。 +- 内置到 Vipr 的 OData v4 读取器用于读取 CSDL 文件。此读取器将架构定义转换为中间表现形式，称为 ODCM 模型。 +- 传递自定义编写器至 Vipr，以处理此 ODCM 模型。编写器由 4 步组成，以将 ODCM 模型转换为最终生成的 C# 文件： +1.遍历 ODCM 模型（即架构）以发现各路由。 +2.针对各路由，创建 cmdlet 的抽象表现形式来呈现路由上的各操作。 +3.将各 cmdlet 的抽象表示形式，转换为抽象的 C# 表示形式。 +4.对于各抽象的 C# 表示形式，将之转换为写为文件内容的字符串。 + +# 未来工作 +- [ ] 改进所生成 cmdlet 的命名。 + - [ ] 查看是否可以添加批注至用于为路由创建友好名称的 Graph 架构中。 +- [ ] 在合理的时间内找到针对整个 Graph 架构生成并构建 cmdlet 的方法。 + - 包含 AAD 实体后，路由数量（由于导航属性）将显著增加。 +- [ ] 获取生成的 cmdlet 帮助文档，以包含链接至 Graph 官方文档的相应页面。 +- [x] 将 cmdlet 输出管道直接实现到其他 cmdlet。 +- [ ] 实现非交互身份验证。 + - [ ] 使用证书验证身份。 + - [x] 使用 PSCredential 对象验证身份。 +- [x] 确保获得正确的身份验证令牌过期时间 - 需要时通过自动刷新令牌进行处理。 +- [x] 针对方案 cmdlet 创建单独的存储库（常用作子模块）。 +- [ ] Travis CI GitHub 集成 + 测试用例。 +- [x] 针对第三方软件创建许可证文件并包含在模块中。 +- [x] 更新 \*.psd1 文件并包含正确的链接至公共 GitHub、许可证文件和图标。 +- [x] 创建帮助程序 cmdlet，使用它可创建序列化为架构中定义的类型。 +- [] 将 OData 功能限制添加到 Graph 架构中，以便无法在第一位置生成执行不允许的操作的 cmdlet。 + +# 常见问题解答 +## 生成的代码在哪里？ +GitHub: https://github.com/Microsoft/Intune-PowerShell-SDK + +## 为什么需要此 PowerShell 模块？ +客户非常有兴趣使用 PowerShell 自动执行任务，目前这些任务通过扩展 Intune 至 Azure 门户执行。 + +## 为什么要自动生成 PowerShell 模块？ +如果手动编写各 cmdlet，我们需要在每次更新 Graph 架构时，手动更新模块。 + +## 为什么是 Intune 构建（为什么不是 Graph SDK 团队构建）？ +大多数 Intune 用户群体（IT 专业人员）更喜欢使用 PowerShell，而Graph SDK 适合喜欢使用 C#、Java 和 Python 等工作的开发人员。这就是我们迫切需要的原因。PowerShell 语法的结构不适合现有 .Net/Java/Python SDK 生成器的结构（请参阅有关为何我们拥有[自定义 Vipr 编写器](#why-a-custom-writer)的说明。） + +## 什么是 Vipr？ +- 此体系结构围绕 Microsoft Research 项目 Vipr 创建。 +- 它生成将信息从一个语法转换为另一个语法的概念。 +- 本质上是一个模块化文本分析程序，特别适用于 OData 样式服务定义。 +- 可执行文件接受读取器程序集和编写器程序集。 + - 读取器能够将输入文本文件解析为 Vip 的中间（通用）表示形式。 + - 编写器接受此中间表示形式，并返回文件对象列表，即（字符串、路径）对。 + - Vipr 随后写入这些文件至指定的文件夹结构中，以输出文件夹。 + +## 为什么是自定义编写器？ +没有 PowerShell 编写器可供 Vipr 使用。另外 .Net/Java/Python Graph SDK 编写器很难适用于 PowerShell 语法、行为或最佳做法。 + +## 为什么不使用 OpenAPI 和 Swagger？ +可以使用，但需要另外从 Graph 的 OData 架构转换为 OpenAPI 格式。每次转换时，所生成 PowerShell 模块中的有价值的信息，可能出现丢失风险。 \ No newline at end of file