diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..9eedc0d46 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,13 @@ +## Summary + +Give a description of what your pull request does and what platform[s] it targets. Use the *breaking changes* tag if applicable. Breaking changes can include changes to generated code files which will impact API signature or behaviors, and changes to directory structures which may impact DevOp pipelines and scripts. + +## Generated code differences + +Pull requests that result in changes to generated code and/or directory structures should include example diffs of the resulting changes. This makes code review much easier. + +## Command line arguments to run these changes + +Provide the command line arguments here so that reviewers can quickly repro the results of changes. + +## Links to issues or work items this PR addresses \ No newline at end of file diff --git a/.nuget/nuget.config b/.nuget/nuget.config index 67f8ea046..f74fd2efb 100755 --- a/.nuget/nuget.config +++ b/.nuget/nuget.config @@ -1,6 +1,7 @@  - - - - \ No newline at end of file + + + + + diff --git a/.nuget/nuget.exe b/.nuget/nuget.exe deleted file mode 100755 index 8dd7e45ae..000000000 Binary files a/.nuget/nuget.exe and /dev/null differ diff --git a/.nuget/nuget.targets b/.nuget/nuget.targets deleted file mode 100755 index 757a98cd5..000000000 --- a/.nuget/nuget.targets +++ /dev/null @@ -1,145 +0,0 @@ - - - - $(MSBuildProjectDirectory)\..\ - - - false - - - false - - - true - - - false - - - - - - - - - - - $([System.IO.Path]::Combine($(SolutionDir), ".nuget")) - - - - - $(SolutionDir).nuget - packages.config - - - - $(MSBuildProjectDirectory)\packages.$(MSBuildProjectName.Replace(' ', '_')).config - $(MSBuildProjectDirectory)\packages.$(MSBuildProjectName).config - - - - $(MSBuildProjectDirectory)\packages.config - $(PackagesProjectConfig) - - - - - $(NuGetToolsPath)\NuGet.exe - @(PackageSource) - - "$(NuGetExePath)" - mono --runtime=v4.0.30319 "$(NuGetExePath)" - - $(TargetDir.Trim('\\')) - - -RequireConsent - -NonInteractive - - "$(SolutionDir) " - "$(SolutionDir)" - - - $(NuGetCommand) install "$(PackagesConfig)" -source "$(PackageSources)" $(NonInteractiveSwitch) $(RequireConsentSwitch) -solutionDir $(PaddedSolutionDir) - $(NuGetCommand) pack "$(ProjectPath)" -Properties "Configuration=$(Configuration);Platform=$(Platform)" $(NonInteractiveSwitch) -OutputDirectory "$(PackageOutputDir)" -symbols - - - - RestorePackages; - $(BuildDependsOn); - - - - - $(BuildDependsOn); - BuildPackage; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/.nuget/packages.config b/.nuget/packages.config deleted file mode 100755 index ea5ee11a1..000000000 --- a/.nuget/packages.config +++ /dev/null @@ -1,5 +0,0 @@ - - - - - diff --git a/GraphODataTemplateWriter.Test/ContainmentTests.cs b/GraphODataTemplateWriter.Test/ContainmentTests.cs index 6b7e5523b..386906ced 100644 --- a/GraphODataTemplateWriter.Test/ContainmentTests.cs +++ b/GraphODataTemplateWriter.Test/ContainmentTests.cs @@ -57,7 +57,7 @@ public void TestImplicitEntitySet() var type = model.GetEntityTypes().Where(t => t.Name == "testEntity").First(); var prop = type.Properties.Where(p => p.Name == "testNav").First(); - OdcmProperty result = OdcmModelExtensions.GetServiceCollectionNavigationPropertyForPropertyType(prop); + OdcmProperty result = OdcmModelExtensions.GetServiceCollectionNavigationPropertyForPropertyType(prop, model); var singleton = model.GetEntityTypes().Where(t => t.Name == "testSingleton").First(); Assert.AreEqual(singleton.Name, result.Name); } @@ -72,7 +72,7 @@ public void TestNoValidEntitySet() var type = model.GetEntityTypes().Where(t => t.Name == "testEntity").First(); var prop = type.Properties.Where(p => p.Name == "testInvalidNav").First(); ; - OdcmProperty result = OdcmModelExtensions.GetServiceCollectionNavigationPropertyForPropertyType(prop); + OdcmProperty result = OdcmModelExtensions.GetServiceCollectionNavigationPropertyForPropertyType(prop, model); Assert.IsNull(result); } @@ -86,7 +86,7 @@ public void TestExplicitEntitySet() var type = model.GetEntityTypes().Where(t => t.Name == "testEntity").First(); var prop = type.Properties.Where(p => p.Name == "testExplicitNav").First(); - OdcmProperty result = OdcmModelExtensions.GetServiceCollectionNavigationPropertyForPropertyType(prop); + OdcmProperty result = OdcmModelExtensions.GetServiceCollectionNavigationPropertyForPropertyType(prop, model); var entitySet = model.EntityContainer.Properties.Where(t => t.Name == "testTypes").First(); Assert.AreEqual(entitySet.Name, result.Name); diff --git a/GraphODataTemplateWriter.Test/GraphODataTemplateWriter.Test.csproj b/GraphODataTemplateWriter.Test/GraphODataTemplateWriter.Test.csproj index e3642bfb7..d4b3d215a 100644 --- a/GraphODataTemplateWriter.Test/GraphODataTemplateWriter.Test.csproj +++ b/GraphODataTemplateWriter.Test/GraphODataTemplateWriter.Test.csproj @@ -1,6 +1,6 @@  - + Debug AnyCPU @@ -9,7 +9,7 @@ Properties GraphODataTemplateWriter.Test GraphODataTemplateWriter.Test - v4.6.1 + v4.7.2 512 {3AC096D0-A1C2-E12C-1390-A8335801FDAB};{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC} 15.0 @@ -19,6 +19,7 @@ UnitTest + true @@ -31,10 +32,10 @@ - ..\packages\MSTest.TestFramework.1.1.18\lib\net45\Microsoft.VisualStudio.TestPlatform.TestFramework.dll + ..\packages\MSTest.TestFramework.1.2.1\lib\net45\Microsoft.VisualStudio.TestPlatform.TestFramework.dll - ..\packages\MSTest.TestFramework.1.1.18\lib\net45\Microsoft.VisualStudio.TestPlatform.TestFramework.Extensions.dll + ..\packages\MSTest.TestFramework.1.2.1\lib\net45\Microsoft.VisualStudio.TestPlatform.TestFramework.Extensions.dll @@ -69,8 +70,8 @@ This project references NuGet package(s) that are missing on this computer. Use NuGet Package Restore to download them. For more information, see http://go.microsoft.com/fwlink/?LinkID=322105. The missing file is {0}. - - + + - + \ No newline at end of file diff --git a/GraphODataTemplateWriter.Test/TypeHelperTests.cs b/GraphODataTemplateWriter.Test/TypeHelperTests.cs index 6e797634c..8f7b1ef41 100644 --- a/GraphODataTemplateWriter.Test/TypeHelperTests.cs +++ b/GraphODataTemplateWriter.Test/TypeHelperTests.cs @@ -91,5 +91,65 @@ public void Description_Doesnt_Contain_Uncommented_NewLine_For_PHP() Assert.AreEqual(expectedOutputString, sanitizedString, "GetSanitizedLongDescription is not handling escaped CRLF."); } + + [TestMethod] + public void Namespace_Shouldnt_Contain_Whitespace_For_CSharp() + { + var testNamespace = new OdcmNamespace("Microsoft.OutlookServices"); + + var namespaceName = TypeHelperCSharp.GetNamespaceName(testNamespace); + + Assert.AreEqual(namespaceName, "Microsoft.OutlookServices"); + } + + [TestMethod] + public void Namespace_Should_PascalCase_For_CSharp() + { + var testNamespace = new OdcmNamespace("microsoft.graph"); + + var namespaceName = TypeHelperCSharp.GetNamespaceName(testNamespace); + + Assert.AreEqual(namespaceName, "Microsoft.Graph"); + } + + [TestMethod] + public void PHPMainNamespace_Generated_For_V1() + { + var testNamespace = "microsoft.graph"; + const string expectedPHPNamespace = "Microsoft\\Graph"; + + var actualPHPNamespace = TypeHelperPHP.GetPHPNamespace(testNamespace); + Assert.AreEqual(expectedPHPNamespace, actualPHPNamespace); + } + + [TestMethod] + public void PHPMainNamespace_Generated_For_Beta() + { + var testNamespace = "microsoft.graph"; + const string expectedPHPNamespace = "Beta\\Microsoft\\Graph"; + + var actualPHPNamespace = TypeHelperPHP.GetPHPNamespace(testNamespace, "Beta"); + Assert.AreEqual(expectedPHPNamespace, actualPHPNamespace); + } + + [TestMethod] + public void PHPSubNamespace_Generated_For_V1() + { + var testNamespace = "microsoft.graph.callRecords"; + const string expectedPHPNamespace = "Microsoft\\Graph\\CallRecords"; + + var actualPHPNamespace = TypeHelperPHP.GetPHPNamespace(testNamespace); + Assert.AreEqual(expectedPHPNamespace, actualPHPNamespace); + } + + [TestMethod] + public void PHPSubNamespace_Generated_For_Beta() + { + var testNamespace = "microsoft.graph.callRecords"; + const string expectedPHPNamespace = "Beta\\Microsoft\\Graph\\CallRecords"; + + var actualPHPNamespace = TypeHelperPHP.GetPHPNamespace(testNamespace, "Beta"); + Assert.AreEqual(expectedPHPNamespace, actualPHPNamespace); + } } } diff --git a/GraphODataTemplateWriter.Test/packages.config b/GraphODataTemplateWriter.Test/packages.config index d8c1b9099..83e440374 100644 --- a/GraphODataTemplateWriter.Test/packages.config +++ b/GraphODataTemplateWriter.Test/packages.config @@ -1,5 +1,5 @@  - - + + \ No newline at end of file diff --git a/README-Localized/README-es-es.md b/README-Localized/README-es-es.md new file mode 100644 index 000000000..1d24ec87c --- /dev/null +++ b/README-Localized/README-es-es.md @@ -0,0 +1,195 @@ +[vipr-source-repo]: https://github.com/microsoft/vipr + +[![Estado de la compilación](https://o365exchange.visualstudio.com/O365%20Sandbox/_apis/build/status/Microsoft%20Graph/msgraph-package-typewriter)](https://o365exchange.visualstudio.com/O365%20Sandbox/_build/latest?definitionId=1728) + +# Microsoft Graph SDK Code Generator + +Escritores de código fuente para [VIPR][vipr-source-repo] que usan plantillas T4. El GraphODataTemplateWriter recibe un OdcmModel de VIPR y lo utiliza para rellenar una plantilla T4 que se encuentra en este repositorio. + +Actualmente, el escritor admite los siguientes lenguajes de destino: +- Android +- CSharp +- Java +- Objective-C +- Python +- TypeScript +- PHP + +# Contenidos +- [Requisitos previos](#prerequisites) +- [Introducción](#getting-started) +- [Uso de VIPr con este escritor](#using-vipr-with-this-writer) +- [Colaboradores](#contributing) +- [Licencia](#license) + +## Requisitos previos +- [Visual Studio SDK](https://msdn.microsoft.com/es-es/library/bb166441.aspx) +- [SDK de modelado de Visual Studio](https://msdn.microsoft.com/es-es/library/bb126259.aspx) + +# Introducción + +Este proyecto usa submódulos git para integrar las dependencias ascendentes, específicamente [Vipr][vipr-source-repo]. Si necesita una rama alternativa para incluir correcciones especiales, debe buscarlo manualmente en el submódulo. + +Para que la solución se abra correctamente, asegúrese de que los submódulos están actualizados antes de abrirla en Visual Studio. Cuando clone este repositorio de forma inicial, use `git clone --recursive` para actualizar los submódulos al mismo tiempo. Después, ejecute `actualización de submódulo git` para actualizar manualmente los submódulos. Si no usa el modificador `--recursive` al clonar, ejecute `git submodule init` primero para inicializar el submódulo. + +Una vez completada la configuración, puede trabajar con la solución GraphODataTemplateWriter como siempre. Si se produce algún problema, asegúrese de que los paquetes de NuGet y las referencias de proyecto estén actualizados. + +Para obtener más información sobre los submódulos, lea [este capítulo](http://git-scm.com/book/en/v2/Git-Tools-Submodules) de la libreta de Git y consulte la web. + +## Uso de Typewriter + +Typewriter es una nueva solución para generar archivos de código con GraphODataTemplateWriter y VIPR. Se trata de un ejecutable diseñado para simplificar la creación de archivos de código. Cree la solución para encontrar el ejecutable Typewriter en `\MSGraph-SDK-Code-Generator\src\Typewriter\bin\Release`. Las opciones de ejecución de Typewriter son: + +* **-l**, **-language**: Lenguaje de destino para los archivos de código generados. Los valores pueden ser: `Android`, `Java`, `ObjC`, `CSharp`, `PHP`, `Python`, `TypeScript` o `GraphEndpointList`. El valor predeterminado es `CSharp`. Esto no es aplicable cuando solo se generan metadatos limpios y anotados, tal y como se especifica en la opción `-generationmode Metadata`. +* **-m**, **-metadata**: La dirección URL o ruta de acceso del archivo local a los metadatos de entrada objetivo. El valor predeterminado es `https://graph.microsoft.com/v1.0/$metadata`. Este valor es necesario. +* **-v**, **-verbosity**: El nivel de detalle del registro. Los valores pueden ser: `Minimal`, `Info`, `Debug` o `Trace`. El valor predeterminado es `Minimal`. +* **-o**, **-output**: Especifica la ruta de acceso a la carpeta de salida. El valor predeterminado es el directorio que contiene typewriter.exe. La estructura y el contenido del directorio de resultado serán diferentes en función de las opciones `-generationmode` y `-language`. +* **-d**, **-docs**: Especifica la ruta de acceso a la raíz local del repositorio [microsoft-graph-docs](https://github.com/microsoftgraph/microsoft-graph-docs). El valor predeterminado es el directorio que contiene typewriter.exe. La documentación se analiza para proporcionar anotaciones de documentación a los metadatos, que se usan para agregar comentarios a documentos en los archivos de código generados. Esta opción es necesaria cuando se usan valores `-generationmode` de `Metadata` o `Full`. +* **-g**, **-generationmode**: Especifica el modo de generación. Los valores pueden ser: `Full`, `Metadata` o `Files`. El modo de generación `Full` (predeterminado) genera los archivos de código de salida mediante la limpieza de los metadatos de entrada, el análisis de la documentación y la adición de anotaciones antes de generar los archivos de salida. El modo de generación `Metadata` produce un archivo de metadatos de salida al limpiar metadatos, analizar la documentación y agregar anotaciones de documentación. El modo de generación `Files` genera archivos de código desde un metadato de entrada y omite la limpieza, el análisis de documentación y la adición de anotaciones de documentación. +* **-f**, **-outputMetadataFileName**: El nombre de archivo base de los metadatos de salida. Solo se aplica para `-generationmode Metadata`. El valor predeterminado es `cleanMetadataWithDescriptions` que se usa con el valor de `-endpointVersion` para generar un archivo de metadatos denominado `cleanMetadataWithDescriptionsv1.0.xml`. +* **-e**, **-endpointVersion**: La versión del extremo que se usa para asignar un nombre a un archivo de metadatos. Los valores esperados son `v 1.0` y `beta`. Solo se aplica para `-generationmode Metadata`. +* **-p**, **-properties**: Especifique las propiedades para admitir la lógica de generación en las plantillas T4. Las propiedades deben tener el formato de *key-string:value-string*. Se pueden especificar varias propiedades colocando un espacio entre propiedades. La única propiedad compatible actualmente es la propiedad *php.namespace* para especificar el espacio de nombres del archivo de modelo generado. Esta propiedad es opcional. + +### Ejemplo de uso de Typewriter + +#### Generar términos de TypeScript desde un archivo CSDL (metadatos) sin limpiar o anotar el CSDL. + +El resultado se mostrará en el directorio `outputTypeScript`. + +`.\typewriter.exe -v Info -m D:\cleanMetadataWithDescriptions_v10.xml -o outputTypeScript -l TypeScript -g Files` + +#### Limpiar y realizar anotaciones en un archivo de metadatos con anotaciones de la documentación originales del repositorio de documentación + +El archivo de metadatos resultante pasará al directorio `output2`. El archivo de metadatos resultante se denominará `cleanMetadataWithDescriptionsv1.0.xml` en función de los valores predeterminados. + +`.\typewriter.exe -v Info -m D:\v1.0_2018_10_23_source.xml -o output2 -d D:\repos\microsoft-graph-docs -g Metadata` + +#### Generar archivos de código C# a partir de los metadatos que se limpiarán y anotarán con anotaciones de documentación procedentes del repositorio de documentación. + +Los archivos C# resultantes se enviarán al directorio `output`. + +`.\typewriter.exe -v Info -m D:\v1.0_2018_10_23_source.xml -o output -l CSharp -d D:\repos\microsoft-graph-docs -g Full` + + + +## Uso de VIPr con este editor + +1. Cree la solución en Visual Studio. +2. Vaya a la carpeta `src\GraphODataTemplateWriter\bin\debug` para buscar todos los componentes compilados. +3. En esa carpeta, modifique `.config\TemplateWriterSettings.json` para especificar la asignación de plantilla, vea [configuración del escritor de plantillas](##Template-Writer-Settings) para obtener más información. +4. Abra un símbolo del sistema como administrador en la misma carpeta y ejecute `Vipr.exe --writer="GraphODataTemplateWriter"`. Puede encontrar un archivo de metadatos de ejemplo en la raíz de este proyecto. + +De forma predeterminada, el código fuente de salida se colocará en una carpeta denominada "output" junto al ejecutable Vipr. + +## Configuración del escritor de plantillas +### Lenguajes disponibles + +Por el momento, hay cinco lenguajes entre los que elegir. Java, ObjC, CSharp, TypeScript y Python. Especifique el lenguaje que desea generar en la opción de configuración `TargetLanguage`. + +### Plantillas +Debe especificar un directorio de plantillas en la configuración de `TemplatesDirectory`. El directorio puede ser una ruta de acceso completa o relativa al directorio en ejecución. El directorio tiene que contener un subdirectorio para cada plataforma para la que quiera generar código. Puede ver un ejemplo en el directorio de plantillas. + +### Asignación de plantillas +Debe especificar la asignación de las plantillas T4 a subprocesadores específicos para cada plataforma que quiera generar. La configuración `TemplateMapping` es un diccionario de lenguajes y una lista de plantillas. Cada plantilla debe especificar: + +- `Template`, el nombre de la plantilla sin las extensiones. +- `SubProcessor` el subprocesador de la plantilla, vea [subprocesadores](#SubProcessors) +- `Type` el tipo de plantilla. +- `Name` la cadena de formato del nombre. + +y, opcionalmente: + +- `Include`, una lista delimitada por puntos y coma de objetos para incluirlos en el subproceso. +- `Exclude`, una lista delimitada por puntos y coma de objetos para excluirlos en el subproceso. +- `Ignore`, una lista delimitada por puntos y coma de objetos para ignorar en el subproceso. +- `Matches`, una lista delimitada por puntos y coma de objetos para incluirlos en el subproceso. +- `FileCasing`, `UpperCamel`, `LowerCamel` o `Snake` para el uso de mayúsculas y minúsculas para el archivo específico que se está creando. + +**Nota: Muchos de estos parámetros opcionales se usaban antes de que Vipr tuviera soporte total para las anotaciones. Ahora que se han agregado anotaciones a Vipr, el uso de estos parámetros debería limitarse a escenarios antiguos.** + +Ejemplo : + +` { "Template": "EntityCollectionPage", "SubProcessor": "NavigationCollectionProperty", "Type": "Request", "Name": "CollectionPage", "Matches" : "includeThisType", "Exclude" : "ExcludedTypeName;OtherExcludedTypeName" }` + +Es importante tener en cuenta que los subprocesos se asignan a métodos que consultan el **OdcmModel** y devuelven un conjunto de objetos OData. Esta asignación se mantiene en [TemplateProcess.InitializeSubprocessor()](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/blob/dev/src/GraphODataTemplateWriter/TemplateProcessor/TemplateProcessor.cs#L54). Las asignaciones específicas de lenguaje se encuentran en el [directorio de configuración](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/tree/dev/src/GraphODataTemplateWriter/.config). Cada objeto OData devuelto por el subproceso se aplica a la plantilla asignada, lo que resulta en archivo de código por cada objeto OData. + +En el ejemplo anterior, los objetos en el conjunto de resultados del subproceso NavigationCollectionProperty se aplicarán en la plantilla EntityCollectionPage. Cada resultado será un archivo de código para cada objeto devuelto por el subproceso NavigationCollectionProperty. + +#### Subprocesos + +El subproceso determina qué tipo de objeto OData se pasará a la plantilla que genera el archivo de código. + +- `CollectionMethod` todos los métodos de tipo colecciones +- `CollectionProperty` propiedades de tipo colección +- `CollectionReferenceProperty` todas las propiedades de navegación que son de tipo colección que se usan en colecciones de no contención +- `ComplexType` todos los tipos complejos +- `EntityContainer` el EntityContainer +- `EntityReferenceType` todos los tipos de entidad que se usan en colecciones de no contención +- `EntityType` todos los tipos de entidad +- `EnumType` todos los tipos enumerables +- `MediaEntityType` todos los tipos de entidades multimedia +- `Method` todas las funciones y acciones +- `MethodWithBody` todos los métodos y funciones que envían un cuerpo durante la solicitud http +- `NavigationCollectionProperty` todas las propiedades de navegación que son de tipo colección +- `NonCollectionMethod` todos los métodos y funciones que no devuelven una colección +- `Other` todo el modelo. +- `Property` todos los tipos de propiedades +- `StreamProperty` todos los tipos de propiedades que devuelven cadenas + +#### Tipos + +El tipo de plantilla. + +- `Request` una plantilla que realizará una solicitud +- `Model` un modelo +- `Shared` una plantilla que no dará como resultado ningún código pero se incluye en otras plantillas +- `Client` la plantilla usada para crear el objeto de cliente +- `Other` otro tipo + + +#### Nombre de plantilla + +Para establecer el nombre de la plantilla con la cadena de formato `Name`. Puede insertar ``, ``, `` y ``, los valores se reemplazarán por los nombres del objeto correspondiente. Si inserta un elemento que no existe, se reemplazará por una cadena vacía. +Nota: También puede establecer el nombre de la plantilla en el interior de la plantilla: `host.SetTemplateName("foo");` + +#### Edición de plantillas + +La solución contiene un proyecto en el que no se generan plantillas, para hospedar las plantillas T4 reales y facilitar su búsqueda o edición. Este proyecto detectará automáticamente los nuevos archivos de plantilla. + +#### Incluir/excluir + +Puede haber ocasiones específicas en las que quiera excluir o solo procesar ciertos objetos del subproceso. Para ello, puede establecer una lista delimitada por puntos y comas de los objetos que desea incluir: `Include : foo;bar`. Esto solo procesará objetos cuyos nombres sean foo o bar. Lo opuesto de esto es la opción excluir, en la que el subproceso incluirá todos los objetos, excepto aquellos cuyos nombres se encuentren en la lista excluir, no se pueden usar excluir e incluir conjuntamente. + +#### Ignorar/coincidir +Cuando no pueda usar el nombre de un objeto para incluir o excluir, puede usar el elemento de descripción larga en cualquier objeto. Inserte una descripción larga con una lista delimitada por puntos y coma de cadenas como: `foo;bar;baz`. Si agrega `"Matches" : "foo;baz"` solo se procesarán los objetos que contienen foo y baz en su descripción larga. Lo opuesto se cumple para ignorar. + +Nota: También puede proteger una plantilla si `odcjObject.LongDescriptionContains("foo");` + +**Nota: Los parámetros Incluir/excluir o Ignorar/coincidir se usaban antes de que Vipr tuviera soporte total para las anotaciones. Ahora que se han agregado anotaciones a Vipr, el uso de estos parámetros debería limitarse a escenarios antiguos.** + +## Creación con metadatos de Graph + +En la actualidad, se llevan a cabo varios pasos para formar los metadatos en uno que genere correctamente SDK en la forma que esperamos: + + - Quitar anotaciones de funciones (consulte [\#132](https://github.com/Microsoft/Vipr/issues/132)) + - Agregar una anotación de navegación a la miniatura + ```xml + + ``` + - Quitar propiedades HasStream de ```onenotePage``` y ```onenoteEntityBaseModel``` + - Agregar ```ContainsTarget="true"``` a propiedades de navegación que no tienen un EntitySet correspondiente. Actualmente, esto se aplica a las propiedades de navegación que contienen plannerBucket, plannerTask, plannerPlan y plannerDelta. + - Agregar descripciones largas a los tipos y propiedades de [documentos](https://developer.microsoft.com/es-es/graph/docs/concepts/overview) + +Para compilar en metadatos que no sean los que se almacenan en el directorio [Metadata](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/tree/master/metadata), tendrá que realizar los cuatro primeros apartados en esta lista. + +## Colaboradores + +Antes de que podamos aceptar su solicitud de incorporación de cambios, debe completar el [Contrato de licencia de colaborador](https://cla.microsoft.com/) de Microsoft. Si lo ha hecho en otros proyectos de Microsoft, ya no es necesario. + +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. + +[Por qué un CLA?](https://www.gnu.org/licenses/why-assign.html) (desde la FSF) + +## Licencia + +Copyright (c) Microsoft Corporation. Reservados todos los derechos. Publicado bajo la [licencia MIT](LICENSE). diff --git a/README-Localized/README-fr-fr.md b/README-Localized/README-fr-fr.md new file mode 100644 index 000000000..877f79ec9 --- /dev/null +++ b/README-Localized/README-fr-fr.md @@ -0,0 +1,195 @@ +[vipr-source-repo]: https://github.com/microsoft/vipr + +[![État de création](https://o365exchange.visualstudio.com/O365%20Sandbox/_apis/build/status/Microsoft%20Graph/msgraph-package-typewriter)](https://o365exchange.visualstudio.com/O365%20Sandbox/_build/latest?definitionId=1728) + +# Générateur de code SDK Microsoft Graph + +Auteurs de code source pour [VIPR][vipr-source-repo] à l’aide de modèles T4. Le GraphODataTemplateWriter reçoit un OdcmModel de VIPR et l’utilise pour remplir dans un modèle T4 situé au sein de ce référentiel. + +Pour l’instant, les langues cibles suivantes sont prises en charge par ce rédacteur : +- Android +- CSharp +- Java +- Objective-C +- Python +- TypeScript +- PHP + +# Contenu +- [Conditions préalables](#prerequisites) +- [Prise en main](#getting-started) +- [Utilisation de Vipr avec ce rédacteur](#using-vipr-with-this-writer) +- [Contribution](#contributing) +- [License](#license) + +## Conditions préalables +- [Kit de développement logiciel (SDK) Visual Studio](https://msdn.microsoft.com/fr-fr/library/bb166441.aspx) +- [Kit de développement de modèles Visual Studio](https://msdn.microsoft.com/fr-fr/library/bb126259.aspx) + +# Prise en main + +Ce projet utilise des sous-modules git pour intégrer des dépendances en amont, notamment [VIPR][vipr-source-repo]. Si vous avez besoin d’une autre branche pour inclure des correctifs spéciaux, vous devrez la vérifier manuellement dans le sous-module. + +Pour que la solution s’ouvre correctement, assurez-vous que les sous-modules sont mis à jour avant de les ouvrir dans Visual Studio. Lors du clonage initial de ce référentiel, utilisez `git récursif` pour mettre à jour les sous-modules en même temps. Exécutez ensuite la `mise à jour du sous-module git` pour mettre à jour manuellement les sous-modules. Si vous n’utilisez pas le commutateur de `--récursif` lorsque vous procédez au clonage, exécutez d'abord `sous-module git init` pour initialiser le sous-module. + +Une fois l’installation terminée, vous pouvez utiliser la solution GraphODataTemplateWriter comme d’habitude. Si vous rencontrez des problèmes, assurez-vous que les packages NuGet et les références de projet sont à jour. + +Pour plus d’informations sur les sous-modules, consultez [ce chapitre](http://git-scm.com/book/en/v2/Git-Tools-Submodules) à partir du répertoire git et effectuez une recherche sur le web. + +## Utilisation de la machine à écrire + +Une machine à écrire est une nouvelle solution de génération de fichiers de code à l’aide de GraphODataTemplateWriter et VIPR. Il s’agit d’un exécutable conçu pour simplifier la génération de fichiers de code. Créez la solution pour trouver le fichier exécutable à écrire dans `\MSGraph-SDK-Code-Generator\src\Typewriter\bin\Release`. Les options d’exécution de la machine à écrire sont les suivantes : + +* **-l**, **-langue**: Langue cible pour les fichiers de code générés. Les valeurs possibles sont les suivantes : `Android`, `Java`, `ObjC`, `CSharp`, `PHP`, `Python`, `TypeScript`, ou `GraphEndpointList`. La valeur par défaut est `CSharp`. Cette opération n’est pas applicable lorsque la génération de métadonnées propres et annotées est uniquement spécifiée par l’option `-generationmode Metadata`. +* **-m**, **-métadonnées**: Chemin d’accès du fichier local ou URL vers les métadonnées d’entrée cible. Cette valeur par défaut est `https://graph.microsoft.com/v1.0/$metadata`. Cette valeur est obligatoire. +* **-v**, **-verbosité**: Niveau de verbosité du journal. Les valeurs possibles sont les suivantes : `minimal`, `informations`, `débogage`, ou `suivi`. La valeur par défaut est `Minimal`. +* **-o**, **-sortie**: Spécifie le chemin d'accès au dossier de sortie. La valeur par défaut est le répertoire qui contient typewriter.exe. La structure et le contenu du répertoire de sortie sont différents en fonction des options `-generationmode` et `langue`. +* **-d**, **-documents**: Indique le chemin d’accès à la racine locale du référentiel [microsoft-graph-docs](https://github.com/microsoftgraph/microsoft-graph-docs). La valeur par défaut est le répertoire qui contient typewriter.exe. La documentation est analysée pour fournir des annotations de documentation aux métadonnées qui sont ensuite utilisées pour ajouter des commentaires de document dans les fichiers de code générés. Cette option est requise en cas d'utilisation des valeurs `-generationmode` valeurs de `Metadata` ou `Full`. +* **-g**, **-generationmode**: Spécifie le mode de génération. Les valeurs possibles sont les suivantes : `Full`, `Metadata`, or `Files`. Le mode de génération `Full` (par défaut) génère les fichiers de code de sortie en nettoyant les métadonnées d’entrée, en analysant la documentation et en ajoutant des annotations avant de générer les fichiers de sortie. Le mode de génération `Metadata` génère un fichier de métadonnées de sortie en nettoyant les métadonnées, en analysant la documentation et en ajoutant des annotations de documentation. Le mode de génération `Files` génère des fichiers de code à partir d’une métadonnées d’entrée et ignore le nettoyage, l’analyse de la documentation et l’ajout d’annotations de documentation. +* **-f**, **-outputMetadataFileName**: Nom de fichier des métadonnées de sortie de base. Applicable uniquement pour`-generationmode Metadata`. La valeur par défaut est `cleanMetadataWithDescriptions` qui est utilisée avec la valeur de la `-endpointVersion` pour générer un fichier de métadonnées appelé `cleanMetadataWithDescriptionsv1.0.xml`. +* **-e**, **-endpointVersion**: Version de point de terminaison utilisée lors de la dénomination d’un fichier de métadonnées. Les valeurs attendues sont `v 1.0` et `bêta`. Applicable uniquement pour`-generationmode Metadata`. +* **-p**, **-properties**: Spécifier des propriétés pour prendre en charge la logique de génération dans les modèles T4. Les propriétés doivent prendre la forme de *key-string:value-string*. Vous pouvez spécifier plusieurs propriétés en définissant un espace entre les propriétés. La seule propriété actuellement prise en charge est la propriété *php.namespace* pour spécifier l’espace de noms du fichier de modèle généré. Cette propriété est facultative. + +### Exemple d’utilisation de la machine à écrire + +#### Générer des saisies au format TypeScript à partir d’un fichier CSDL (métadonnées) sans nettoyer ni annoter le langage CSDL. + +La sortie est redirigée vers le répertoire `outputTypeScript`. + +`.\typewriter.exe -v Info -m D:\cleanMetadataWithDescriptions_v10.xml -o outputTypeScript -l TypeScript -g Files` + +#### Nettoyer et annoter un fichier de métadonnées avec des annotations de documentation provenant du référentiel de documentation + +Le fichier de métadonnées de sortie est redirigé vers le répertoire `output2`. Le fichier de métadonnées de sortie s’appelle `cleanMetadataWithDescriptionsv1.0.xml` en fonction des valeurs par défaut. + +`.\typewriter.exe -v Info -m D:\v1.0_2018_10_23_source.xml -o output2 -d D:\repos\microsoft-graph-docs -g Metadata` + +#### Générer des fichiers de code C# à partir des métadonnées qui seront nettoyés et annotés avec des annotations de documentation provenant du référentiel de documentation + +Les fichiers de code C# de sortie sont redirigés vers le répertoire `outputTypeScript`. + +`.\typewriter.exe -v Info -m D:\v1.0_2018_10_23_source.xml -o output -l CSharp -d D:\repos\microsoft-graph-docs -g Full` + + + +## Utilisation de Vipr avec ce rédacteur + +1. Créer la solution dans Visual Studio. +2. Accédez au dossier `src\GraphODataTemplateWriter\bin\debug` pour rechercher tous les composants compilés. +3. Dans ce dossier, modifiez `.config\TemplateWriterSettings.json` pour spécifier le mappage de votre modèle, consultez [paramètres du rédacteur de modèle](##Template-Writer-Settings) pour plus d’informations. +4. Ouvrez une invite de commandes en tant qu’administrateur dans le même dossier et exécutez `Vipr.exe --writer="GraphODataTemplateWriter"`. Un exemple de fichier de métadonnées est disponible à la racine de ce projet. + +Par défaut, le code source de sortie est placé dans un dossier intitulé « Output » à côté du fichier exécutable Vipr. + +## Paramètres du rédacteur de modèle +### Langues disponibles + +Vous avez le choix entre cinq langues. Java, ObjC, CSharp, TypeScript et Python. Spécifiez la langue que vous voulez générer dans le paramètre `TargetLanguage`. + +### Modèles +Vous devez spécifier un répertoire de modèles sous les paramètres `TemplatesDirectory`. Le répertoire peut être un chemin d’accès complet ou relatif au répertoire en cours d’exécution. Le répertoire doit contenir un sous-répertoire pour chaque plateforme pour laquelle vous voulez générer du code. Consultez le répertoire Modèles pour obtenir un exemple. + +### Mappage de modèles +Vous devez spécifier le mappage des modèles T4 aux sous-processus spécifiques de chaque plateforme que vous voulez générer. Le paramètre `TemplateMapping` est un dictionnaire des langues et de la liste des modèles. Chaque modèle doit spécifier : + +- `Modèle`, le nom du modèle sans les extensions. +- `Sous-processus` le sous-traitant du modèle consultez [sous-traitant](#SubProcessors) +- `Type` le type de modèle. +- `Nom` la chaîne de format pour le nom. + +et vous pouvez également : + +- `Inclure`, une liste d’objets séparés par des points-virgules à inclure dans le sous-traitant. +- `Exclure`, une liste d’objets séparés par des points-virgules à exclure du sous-traitant. +- `Ignorer`, une liste d’objets séparés par des points-virgules à ignorer du sous-traitant. +- `Correspondances`, une liste d’objets séparés par des points-virgules à inclure dans le sous-traitant. +- `FileCasing`, `UpperCamel`, `LowerCamel` ou `Snake` pour la casse du fichier en cours de création. + +**Remarque : Bon nombre de ces paramètres facultatifs ont été utilisés avant la prise en charge totale des annotations par Vipr. Maintenant que des annotations ont été ajoutées à Vipr, l’utilisation de ces paramètres doit être limitée aux scénarios hérités** + +Exemple : + +` { "Template": "EntityCollectionPage", "SubProcessor": "NavigationCollectionProperty", "Type": "Request", "Name": "CollectionPage", "Matches" : "includeThisType", "Exclude" : "ExcludedTypeName;OtherExcludedTypeName" }` + +Il est important de comprendre que les sous-traitants sont mappés aux méthodes qui interrogent les **OdcmModel** et retournent un groupe d’objets OData. Ce mappage est conservé dans [TemplateProcess. InitializeSubprocessor ()](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/blob/dev/src/GraphODataTemplateWriter/TemplateProcessor/TemplateProcessor.cs#L54). Les mappages spécifiques à la langue existent dans le [répertoire config](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/tree/dev/src/GraphODataTemplateWriter/.config). Chaque objet OData renvoyé par le sous-traitant est appliqué au modèle mappé, ce qui a pour effet de générer un fichier de code pour chaque objet OData. + +Dans l’exemple ci-dessus, les objets dans le jeu de résultats du sous-traitant NavigationCollectionProperty sont chacun appliqués au modèle EntityCollectionPage. Chaque résultat est un fichier de code pour chaque objet renvoyé par le sous-traitant NavigationCollectionProperty. + +#### Sous-traitants + +Les sous-traitants déterminent le type d’objet OData qui sera transmis dans le modèle qui génère le fichier de code. + +- `CollectionMethod` toutes les méthodes de type collections +- `CollectionProperty` propriétés de type collection +- `CollectionReferenceProperty` toutes les propriétés de navigation de type collection utilisées dans les collections non contenants +- `ComplexType` tous les types complexes +- `EntityContainer` l’EntityContainer +- `EntityReferenceType` tous les types d’entités utilisés dans les collections non contenants +- `EntityType` tous les types d’entités +- `EnumType` tous les types énumérables +- `MediaEntityType` tous les types d’entités multimédias +- `Méthode` toutes les actions et fonctions +- `MethodWithBody` toutes les méthodes et fonctions qui envoient un corps au sein de la demande http +- `NavigationCollectionProperty` toutes les propriétés de navigation de type collection +- `NonCollectionMethod` toutes les méthodes et fonctions qui ne renvoient pas de collection +- `Autre` l’intégralité du modèle. +- `Propriété` tous les types de propriétés +- `StreamProperty` tous les types de propriétés qui retournent des flux + +#### Types + +Le type de modèle. + +- `Demande` un modèle qui fera une demande +- `Modèle` un modèle +- `Partagé` un modèle qui ne génère pas de code, mais qui est inclus dans d’autres modèles +- `Client` le modèle utilisé pour créer l’objet client +- `Autres` tout autre type + + +#### Nom du modèle + +Pour définir le nom du modèle à l'aide de la chaîne de format du `Nom`. Vous pouvez insérer ``, ```` et `` les valeurs seront remplacées par les noms de l'objet correspondant. Si vous insérez un élément qui n’existe pas, celui-ci est remplacé par une chaîne vide. +Remarque : Vous pouvez également choisir le nom du modèle dans le modèle en procédant comme suit : `host.SetTemplateName("foo");` + +#### Modification de modèle + +La solution contient un projet hors bâtiment qui héberge les modèles de T4 actuels et facilite leur navigation et leur modification. Les nouveaux fichiers de modèles sont automatiquement découverts par ce projet. + +#### Inclut/exclut + +Il peut arriver que vous souhaitiez exclure ou uniquement traiter certains objets du sous-traitant. Pour ce faire, vous pouvez créer une liste délimitée par des points-virgules pour les objets que vous voulez inclure : `incluent : foo;bar`. Seules les objets dont les noms sont foo ou bar sont traités. L’inverse est le paramètre Exclure dans lequel le sous-traitant inclut tous les objets, à l’exception de ceux dont les noms figurent dans la liste des exclusions, Exclure et inclure ne peuvent pas être utilisés ensemble. + +#### Ignorer/correspondances +Lorsque vous ne pouvez pas utiliser le nom d’un objet à inclure ou exclure, vous pouvez utiliser l’élément de description longue sur un objet. Insérez une description longue avec une liste de chaînes séparées par des points-virgules telle que : `foo;bar;baz`. Si vous ajoutez un `"Matches" : "foo;baz"` seuls les objets qui contiennent foo et baz dans leur description longue sont traités. L’inverse est vrai pour ignorer. + +Remarque : Vous pouvez également archiver un modèle en `odcjObject. LongDescriptionContains (« foo »);` + +**Remarque : Les mentions/exclusions et ignorer/correspondances ont été utilisés avant la prise en charge totale des annotations par Vipr. Maintenant que des annotations ont été ajoutées à Vipr, l’utilisation de ces paramètres doit être limitée aux scénarios hérités** + +## Créez des métadonnées Graph + +Plusieurs étapes sont nécessaires pour former les métadonnées afin de générer avec succès les kits de développement de programmes dans la forme attendue : + + - Supprimez des annotations de fonction (consultez [\#132](https://github.com/Microsoft/Vipr/issues/132)) + - Ajoutez une annotation de navigation à une miniature + ```xml + + ``` + - Supprimez les propriétés HasStream de ```onenotePage``` et ```onenoteEntityBaseModel``` + - Ajoutez ```ContainsTarget="true"``` aux propriétés de navigation qui n’ont pas un EntitySet correspondant. Cela s’applique actuellement aux propriétés de navigation qui contiennent plannerBucket, plannerTask, plannerPlan et plannerDelta. + - Ajouter des descriptions longues aux types et propriétés de [documentation](https://developer.microsoft.com/fr-fr/graph/docs/concepts/overview) + +Pour construire à partir de métadonnées autres que celles stockées dans le répertoire des [métadonnées](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/tree/master/metadata), vous devrez effectuer les quatre premières de cette liste. + +## Contribution + +Avant de pouvoir accepter votre demande de tirage (pull request), vous devez remplir électroniquement le [contrat de licence de contributeur](https://cla.microsoft.com/) de Microsoft. Si vous avez déjà effectué cette opération pour d’autres projets Microsoft, cela signifie que vous êtes déjà concerné. + +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. + +[Pourquoi une CLA ?](https://www.gnu.org/licenses/why-assign.html) (à partir de FSF) + +## License + +Copyright (c) Microsoft Corporation. Tous droits réservés. Sous [licence MIT](LICENSE). diff --git a/README-Localized/README-ja-jp.md b/README-Localized/README-ja-jp.md new file mode 100644 index 000000000..e52775c95 --- /dev/null +++ b/README-Localized/README-ja-jp.md @@ -0,0 +1,195 @@ +[vipr-source-repo]: https://github.com/microsoft/vipr + +[![ビルドの状態](https://o365exchange.visualstudio.com/O365%20Sandbox/_apis/build/status/Microsoft%20Graph/msgraph-package-typewriter)](https://o365exchange.visualstudio.com/O365%20Sandbox/_build/latest?definitionId=1728) + +# Microsoft Graph SDK Code Generator + +T4 テンプレートを利用した [VIPR][vipr-source-repo] のソース コード ライター。GraphODataTemplateWriter は VIPR から OdcmModel を受け取り、この レポジトリ内の T4 テンプレートへの入力に使用します。 + +現在、このライターは次の対象言語をサポートしています: +- Android +- CSharp +- Java +- Objective-C +- Python +- TypeScript +- PHP + +# コンテンツ +- [前提条件](#prerequisites) +- [概要](#getting-started) +- [このライターで Vipr を使用する](#using-vipr-with-this-writer) +- [投稿](#contributing) +- [ライセンス](#license) + +## 前提条件 +- [Visual Studio SDK](https://msdn.microsoft.com/ja-jp/library/bb166441.aspx) +- [Visual Studio モデリング SDK](https://msdn.microsoft.com/ja-jp/library/bb126259.aspx) + +# 概要 + +このプロジェクトは git サブモジュールを使用して、アップストリームの依存関係、特に [Vipr][vipr-source-repo]を統合します。 特別な修正を含めるために代替ブランチが必要な場合は、サブモジュール内で手動で確認する必要があります。 + +ソリューションを正常に開くには、Visual Studio で開く前にサブモジュールが更新されていることを確認してください。このリポジトリを最初に複製するときは、`git clone --recursive` を使用してサブモジュールを同時に更新します。後で、`git submodule update` を実行して、サブモジュールを手動で更新します。複製するときに `--recursive` スイッチを使用しない場合は、最初に `git submodule init` を実行してサブモジュールを初期化します。 + +セットアップが完了したら、通常どおり GraphODataTemplateWriter ソリューションで操作できます。問題が発生した場合は、NuGet パッケージとプロジェクト参照がすべて最新の状態であることを確認してください。 + +サブモジュールの詳細については、Git ブックから[この章](http://git-scm.com/book/en/v2/Git-Tools-Submodules)を読み、Web を検索してください。 + +## Typewriter の使用 + +Typewriter は、GraphODataTemplateWriter と VIPR を使用してコード ファイルを生成するための新しいソリューションです。これは、コード ファイルの生成を簡素化することを目的とした実行可能ファイルです。ソリューションをビルドして、`\MSGraph-SDK-Code-Generator\src\Typewriter\bin\Release` で、Typewrite の実行可能ファイルを検索します。Typewrite の実行オプションは次のとおりです。 + +* **-l**、**-language**:生成されたコードファイルの対象の言語。値は次のとおりです。`Android`、`Java`、`ObjC`、`CSharp`、`PHP`、`Python`、`TypeScript`、`GraphEndpointList`。既定値は `CSharp` です。`-generationmode メタデータ`オプションで指定された、クリーンアップされた注釈付きのメタデータのみを生成する場合、これは適用されません。 +* **-m**、**-metadata**:ターゲット入力メタデータへのローカル ファイル パスまたは URL。既定値は `https://graph.microsoft.com/v1.0/$metadata` です。この値は必須です。 +* **-v**、**-verbosity**:ログの詳細レベル。値は次のとおりです。`Minimal`、`Info`、`Debug`、`Trace`。既定値は`Minimal` です。 +* **-o**、**-output**:出力フォルダーへのパスを指定します。既定値は、typewriter.exe を含むディレクトリです。出力ディレクトリの構造とコンテンツは、`-generationmode` および `-language` オプションに基づいて異なります。 +* **-d**、**-docs**:[microsoft-graph-docs](https://github.com/microsoftgraph/microsoft-graph-docs) リポジトリのローカル ルートへのパスを指定します。既定値は、typewriter.exe を含むディレクトリです。ドキュメントは、生成されたコード ファイルにドキュメント コメントを追加するために使用されるメタデータにドキュメント注釈を提供するために解析されます。`Metadata` または `Full` の `-generationmode` 値を使用する場合、このオプションは必須です。 +* **-g**、**-generationmode**:生成モードを指定します。値は次のとおりです。`Full`、`Metadata`、`Files`。`Full` (既定値) 生成モードでは、出力ファイルを生成する前に、入力メタデータのクリーンアップ、ドキュメントの解析、注釈の追加によって出力コード ファイルが生成されます。`Metadata` 生成モードでは、メタデータのクリーンアップ、ドキュメントの解析、ドキュメントの注釈の追加により、出力メタデータ ファイルが生成されます。`Files` 生成モードは、入力メタデータからコード ファイルを生成し、クリーンアップ、ドキュメント解析、およびドキュメント注釈の追加をバイパスします。 +* **-f**、**-outputMetadataFileName**:基本出力メタデータ ファイル名。`-generationmode メタデータ`のみに適用されます。既定値は、`cleanMetadataWithDescriptions` で、これは `-endpointVersion` の値とともに使用され、`cleanMetadataWithDescriptionsv1.0.xml` という名前のメタデータ ファイルを生成します。 +* **-e**、**-endpointVersion**:メタデータ ファイルに名前を付けるときに使用されるエンドポイント バージョン。期待される値は `v1.0` および `beta` です。`-generationmode メタデータ`のみに適用されます。 +* **-p**、**-properties**:T4 テンプレートで生成ロジックをサポートするプロパティを指定します。プロパティは *key-string:value-string* の形式をとる必要があります。プロパティ間にスペースを設定することにより、複数のプロパティを指定できます。現在サポートされているプロパティは、生成されたモデルファイルの名前空間を指定する *php.namespace* プロパティのみです。このプロパティは省略可能です。 + +### Typewriter の使用例 + +#### CSDL のクリーンアップや注釈付けを行わずに、CSDL (メタデータ) ファイルから TypeScript タイピングを生成します。 + +出力は `outputTypeScript` ディレクトリに送られます。 + +`.\typewriter.exe -v Info -m D:\cleanMetadataWithDescriptions_v10.xml -o outputTypeScript -l TypeScript -g Files` + +#### ドキュメント リポジトリから取得したドキュメント注釈を使用して、メタデータファイルをクリーンアップして注釈を付けます。 + +出力メタデータファイルは、`output2` ディレクトリに送られます。出力メタデータファイルは、既定値に基づいて `cleanMetadataWithDescriptionsv1.0.xml` という名前になります。 + +`.\typewriter.exe -v Info -m D:\v1.0_2018_10_23_source.xml -o output2 -d D:\repos\microsoft-graph-docs -g Metadata` + +#### クリーンアップされ、ドキュメントリポジトリから提供されるドキュメント注釈で注釈付けされるメタデータから C# コード ファイルを生成します。 + +出力 C# コード ファイルは、`出力`ディレクトリに送られます。 + +`.\typewriter.exe -v Info -m D:\v1.0_2018_10_23_source.xml -o output -l CSharp -d D:\repos\microsoft-graph-docs -g Full` + + + +## このライターで Vipr を使用する + +1. Visual Studio でソリューションをビルドします。 +2. `src\GraphODataTemplateWriter\bin\debug` フォルダーに移動して、コンパイルされたすべてのコンポーネントを確認します。 +3. このフォルダーで、`.config\TemplateWriterSettings.json` を変更して、テンプレート マッピングを指定します。詳細については、「[テンプレート ライターの設定](##Template-Writer-Settings)」を参照してください。 +4. 同じフォルダーで管理者としてコマンド プロンプトを開き、`Vipr.exe --writer="GraphODataTemplateWriter"` を実行します。サンプルのメタデータ ファイルは、このプロジェクトのルートにあります。 + +既定では、出力ソースコードは Vipr 実行可能ファイルの横の "output" という名前のフォルダーに配置されます。 + +## テンプレート ライターの設定 +### 使用可能な言語 + +現時点で選択できる言語は 5 つあります。Java、ObjC、CSharp、TypeScript、および Python。`TargetLanguage` 設定で生成する言語を指定します。 + +### テンプレート +`TemplatesDirectory` 設定でテンプレート ディレクトリを指定する必要があります。ディレクトリは、フルパスでも、実行中のディレクトリからの相対パスでもかまいません。ディレクトリには、コードを生成する各プラットフォームのサブディレクトリが含まれている必要があります。例については、テンプレート ディレクトリを参照してください。 + +### テンプレート マッピング +生成するプラットフォームごとに、特定のサブプロセッサへの T4 テンプレートのマッピングを指定する必要があります。`TemplateMapping` 設定は、言語の辞書とテンプレートのリストです。各テンプレートは以下を指定する必要があります。 + +- `Template`: 拡張子のないテンプレートの名前。 +- `SubProcessor`: テンプレートのサブプロセッサ。「[サブプロセッサ](#SubProcessors)」を参照してください +- `Type`: テンプレートの種類。 +- `Name`: 名前の形式文字列。 + +そして任意で: + +- `Include`: サブプロセッサに含めるオブジェクトのセミコロン区切りリスト。 +- `Exclude`: サブプロセッサから除外するオブジェクトのセミコロン区切りリスト。 +- `Ignore`: サブプロセッサから無視するオブジェクトのセミコロン区切りリスト。 +- `Matches`: サブプロセッサに含めるオブジェクトのセミコロン区切りリスト。 +- `FileCasing`、`UpperCamel`、`LowerCamel`、`Snake` は、作成される特定のファイルのファイル ケーシングに使用します。 + +**注: これらのオプション パラメーターの多くは、Vipr が注釈を完全にサポートする前に使用されていました。 これらのパラメーターの使用は Vipr に追加されたため、従来のシナリオに限定する必要があります** + +例: + +` { "Template":"EntityCollectionPage", "SubProcessor":"NavigationCollectionProperty", "Type":"Request", "Name": "CollectionPage", "Matches" : "includeThisType", "Exclude" :"ExcludedTypeName;OtherExcludedTypeName" }` + +サブプロセッサは、**OdcmModel** をクエリし、OData オブジェクトのセットを返すメソッドにマッピングれることを理解することが重要です。このマッピングは [TemplateProcess.InitializeSubprocessor()](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/blob/dev/src/GraphODataTemplateWriter/TemplateProcessor/TemplateProcessor.cs#L54) で維持されます。言語固有のマッピングは [config ディレクトリ](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/tree/dev/src/GraphODataTemplateWriter/.config)に存在します。サブプロセッサによって返される各 OData オブジェクトは、マッピングされるテンプレートに適用され、各 OData オブジェクトごとにコード ファイルが出力されます。 + +上記の例では、NavigationCollectionProperty サブプロセッサの結果セットのオブジェクトがそれぞれ EntityCollectionPage テンプレートに適用されます。各結果は、NavigationCollectionProperty サブプロセッサによって返される各オブジェクトのコード ファイルになります。 + +#### SubProcessors + +SubProcessors は、コード ファイルを生成するテンプレートに渡される OData オブジェクトの種類を決定します。 + +- `CollectionMethod` コレクション型のすべてのメソッド +- `CollectionProperty` コレクション型のプロパティ +- `CollectionReferenceProperty` 非包含コレクションで使用されるコレクション型のすべてのナビゲーション プロパティ +- `ComplexType` すべての複合型 +- `EntityContainer` エンティティ コンテナ +- `EntityReferenceType` 非包含コレクションで使用されるすべてのエンティティ型 +- `EntityType` すべてのエンティティ型 +- `EnumType` すべての列挙型 +- `MediaEntityType` すべてのメディア エンティティ型 +- `Method` すべてのアクションと機能 +- `MethodWithBody` HTTP リクエスト内で本文を送信するすべてのメソッドと関数 +- `NavigationCollectionProperty` コレクション型のすべてのナビゲーション プロパティ +- `NonCollectionMethod` コレクションを返さないすべてのメソッドと関数 +- `Other` モデル全体。 +- `Property` すべてのプロパティ型 +- `StreamProperty` ストリームを返すすべてのプロパティ型 + +#### 型 + +テンプレート型。 + +- `Request` 要求を行うテンプレート +- `Model` モデル +- `Shared` コードを出力しないが、他のテンプレートに含まれるテンプレート +- `Client` クライアント オブジェクトの作成に使用されるテンプレート +- `Other` その他の型 + + +#### テンプレート名 + +`Name` 形式文字列を使用してテンプレートの名前を設定します。``、``、``、`` を挿入できます。値は対応するオブジェクトの名前に置き換えられます。存在しない項目を挿入すると、空の文字列に置き換えられます。 +注:以下により、テンプレート内からテンプレート名を設定することもできます: `host.SetTemplateName("foo");` + +#### テンプレート編集 + +ソリューションには、実際の T4 テンプレートをホストし、ブラウジング/編集を簡単にする非構築プロジェクトが含まれています。このプロジェクトによって、新しいテンプレート ファイルが自動的に検出されます。 + +#### 包含/除外 + +SubProcessor から特定のオブジェクトを除外したり、特定のオブジェクトのみを処理したりする特定の時間がある場合があります。ここれを行うには、含めるオブジェクトのセミコロン区切りリストを設定します。`以下を含めます: foo;bar`。この場合、名前が foo または bar のオブジェクトだけが処理されます。これの反対は、SubProcessorに含まれるオブジェクトから除外リストにある名前のすべてのオブジェクトを除外する除外設定です。包含と除外を一緒に使用できません。 + +#### 無視/一致 +オブジェクトの名前を使用して包含または除外できない場合は、任意のオブジェクトで長い説明要素を使用できます。以下のようのなセミコロンで区切られた文字列リストを含む長い説明を挿入します: `foo;bar;baz`。`"Matches" : "foo;baz"` を追加すると、長い説明の foo と baz を含むオブジェクトのみが処理されます。無視はこの逆です。 + +注:`odcjObject.LongDescriptionContains("foo");` によってテンプレートをチェック インすることもできます。 + +**注: Vipr が注釈を完全にサポートする前に、包含/除外および無視/一致が使用されました。 これらのパラメーターの使用は Vipr に追加されたため、従来のシナリオに限定する必要があります** + +## グラフ メタデータに対する構築 + +現在、メタデータを期待する形の SDK を正常に生成するメタデータにするために行ういくつかの手順があります。 + + - 機能の注釈を削除します ([\#132](https://github.com/Microsoft/Vipr/issues/132) を参照) + - ナビゲーション注釈をサムネイル + ```xml + + ```に追加します + - ```onenotePage``` および ```onenoteEntityBaseModel``` から HasStream プロパティを削除します + - ```ContainsTarget="true"``` を、対応する EntitySet がないナビゲーションプロパティに追加します。これは現在、plannerBucket、plannerTask、plannerPlan、plannerDelta を含むナビゲーション プロパティに適用されます。 + - [docs](https://developer.microsoft.com/ja-jp/graph/docs/concepts/overview) からのタイプとプロパティに長い説明を追加します + +[メタデータ](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/tree/master/metadata)ディレクトリに保存されているメタデータ以外のメタデータに対してビルドするには、このリストの最初の 4 つを実行する必要があります。 + +## 投稿 + +プル要求が承諾される前に Microsoft の[投稿者のライセンス契約](https://cla.microsoft.com/)を電子的に完了する必要があります。他の Microsoft プロジェクトでこれを行った場合は、既に説明されています。 + +このプロジェクトでは、[Microsoft オープン ソース倫理規定](https://opensource.microsoft.com/codeofconduct/)が採用されています。詳細については、「[倫理規定の FAQ](https://opensource.microsoft.com/codeofconduct/faq/)」を参照してください。また、その他の質問やコメントがあれば、[opencode@microsoft.com](mailto:opencode@microsoft.com) までお問い合わせください。 + +[なぜ CLA なのか?](https://www.gnu.org/licenses/why-assign.html) (FSF から) + +## ライセンス + +Copyright (c) Microsoft Corporation.All Rights Reserved.Licensed under the [MIT license](LICENSE). diff --git a/README-Localized/README-pt-br.md b/README-Localized/README-pt-br.md new file mode 100644 index 000000000..ab2b35244 --- /dev/null +++ b/README-Localized/README-pt-br.md @@ -0,0 +1,195 @@ +[vipr-source-repo]: https://github.com/microsoft/vipr + +[![Status da compilação](https://o365exchange.visualstudio.com/O365%20Sandbox/_apis/build/status/Microsoft%20Graph/msgraph-package-typewriter)](https://o365exchange.visualstudio.com/O365%20Sandbox/_build/latest?definitionId=1728) + +# Gerador de código SDK do Microsoft Graph + +Escritores de código-fonte para [VIPR][vipr-source-repo] utilizando modelos T4. O GraphODataTemplateWriter recebe um OdcmModel de VIPR e o utiliza para preencher um modelo T4 localizado dentro deste repositório. + +Atualmente, as seguintes linguagens de destino são suportadas por este escritor: +- Android +- CSharp +- Java +- Objective-C +- Python +- TypeScript +- PHP + +# Conteúdos +- [Pré-requisitos](#prerequisites) +- [Introdução](#getting-started) +- [Usando o Vipr com este escritor](#using-vipr-with-this-writer) +- [Colaboração](#contributing) +- [Licença](#license) + +## Pré-requisitos +- [Visual Studio SDK](https://msdn.microsoft.com/pt-br/library/bb166441.aspx) +- [SDK de modelagem do Visual Studio](https://msdn.microsoft.com/pt-br/library/bb126259.aspx) + +# Introdução + +Este projeto usa sub-módulos git para integrar dependências upstream, especificamente o [Vipr][vipr-source-repo]. Se você precisar de um branch alternativo para incluir correções especiais, precisará verificar isso manualmente no submódulo. + +Para que a solução seja aberta corretamente, certifique-se de que os submódulos sejam atualizados antes de abri-la no Visual Studio. Ao clonar inicialmente esse repositório, use `clone de git --recursivo` para atualizar submódulos ao mesmo tempo. Mais tarde, execute ` atualizar submódulo de git` para atualizar manualmente os submódulos. Se você não usar a opção `--recursivo` durante a clonagem, execute `submódulo git inicial` primeiro para inicializar o submódulo. + +Quando a instalação estiver concluída, você poderá trabalhar com a solução GraphODataTemplateWriter como de costume. Se você tiver problemas, verifique se pacotes NuGet e referências do projeto estão todos atualizados. + +Para obter mais informações sobre os submódulos, leia [este capítulo](http://git-scm.com/book/en/v2/Git-Tools-Submodules) do livro Git e pesquise na Web. + +## Usando a Máquina de Escrever + +Máquina de Escrever é uma nova solução para gerar arquivos de código usando a GraphODataTemplateWriter e a VIPR. É um executável que pretende simplificar a geração de arquivos de código. Crie a solução para localizar a máquina de escrever executável em `\MSGraph-SDK-Code-Generator\src\Typewriter\bin\Release`. As opções de execução da máquina de escrever são: + +* **-l**, **-linguagem**: O idioma de destino para os arquivos de código gerados. Os valores podem ser: `Android`, `Java`, `ObjC`, `CSharp`, `PHP`, `Python`, `TypeScript` ou `GraphEndpointList`. O valor padrão é `CSharp`. Isso não é aplicável ao gerar apenas metadados limpos e anotados, conforme especificado pela opção `metadados generationmode`. +* **-m**, **-metadados**: O caminho do arquivo local ou a URL para os metadados de entrada de destino. O valor padrão é `https://graph.microsoft.com/v1.0/$metadata`. Esse valor é obrigatório. +* **-v**, **-detalhamento**: O nível de detalhamento do log. Os valores podem ser: `Mínimo`, `Informações`, `Depuração` ou `Rastreamento`. O valor padrão é `Mínimo`. +* **-o**, **-saída**: Especifica o caminho para a pasta de saída. O valor padrão é o diretório que contém typewriter. exe. A estrutura e o conteúdo do diretório de saída serão diferentes com base nas opções `-generationmode` e `-idioma`. +* **-d**, **-documentos**: Especifica o caminho para a raiz local do repositório [microsoft-graph-docs](https://github.com/microsoftgraph/microsoft-graph-docs). O valor padrão é o diretório que contém typewriter. exe. A documentação é analisada para fornecer anotações de documentação aos metadados que são usados ​​para adicionar comentários de documentos nos arquivos de código gerados. Essa opção é necessária ao usar os valores `-generationcmode` de `Metadados` ou `Completo`. +* **-g**, **-generationmode**: Especifica o modo de geração. Os valores podem ser: `Completo`, `Metadados` ou `Arquivos`. O modo de geração `Completo` (padrão) produz os arquivos de código de saída limpando os metadados de entrada, analisando a documentação e adicionando anotações antes de gerar os arquivos de saída. O modo de geração `Metadados` produz um arquivo de metadados de saída limpando metadados, analisando a documentação e adicionando anotações à documentação. O modo de geração `Arquivos` produz arquivos de código a partir de metadados de entrada e ignora a limpeza, a análise de documentação e a adição de anotações de documentação. +* **-f**, **-outputMetadataFileName**: O nome de arquivo de metadados de saída básicos. Aplicável somente a `Metadados -generationmode`. O valor padrão é `cleanMetadataWithDescriptions` que é usado com o valor da `-endpointVersion` para gerar um arquivo de metadados chamado `cleanMetadataWithDescriptionsv1.0.xml`. +* **-e**, **-endpointVersion**: A versão do ponto de extremidade usada ao nomear um arquivo de metadados. Os valores esperados são `v1.0` e `beta`. Aplicável somente a `Metadados -generationmode`. +* **-p**, **-propriedades**: Especifica propriedades para suportar a lógica de geração nos modelos T4. As propriedades devem assumir o formato de *cadeia de chave:cadeia de valor*. Várias propriedades podem ser especificadas, definindo um espaço entre as propriedades. A única propriedade com suporte no momento é a propriedade *php.namespace* para especificar o espaço para nome de arquivo de modelo gerado. Essa propriedade é opcional. + +### Exemplo de uso da máquina de escrever + +#### Gera digitações de TypeScript de um arquivo CSDL (metadados) sem limpar ou fazer anotações sobre o CSDL. + +A saída será direcionada para o diretório `outputTypeScript`. + +`.\typewriter.exe -v Info -m D:\cleanMetadataWithDescriptions_v10.xml -o outputTypeScript -l TypeScript -g Files` + +#### Limpar e fazer anotações em um arquivo de metadados com anotações de documentação provenientes do repositório de documentos + +O arquivo de metadados de saída será direcionado para o diretório `output2`. O arquivo de metadados de saída será denominado `cleanMetadataWithDescriptionsv1.0.xml` com base nos valores padrão. + +`.\typewriter.exe -v Info -m D:\v1.0_2018_10_23_source.xml -o output2 -d D:\repos\microsoft-graph-docs -g Metadata` + +#### Gerar arquivos de código C # a partir dos metadados que serão limpos e anotados com anotações da documentação provenientes do repositório de documentos + +Os arquivos de código C # de saída irão para o diretório de `saída`. + +`.\typewriter.exe -v Info -m D:\v1.0_2018_10_23_source.xml -o output -l CSharp -d D:\repos\microsoft-graph-docs -g Full` + + + +## Usando o Vipr com este Escritor + +1. Crie a solução no Visual Studio. +2. Vá para a pasta `src\GraphODataTemplateWriter\bin\debug` para localizar todos os componentes compilados. +3. Nesta pasta, modifique `.config\TemplateWriterSettings.json` para especificar seu mapeamento de modelo, confira [Configurações do Escritor de Modelo](##Template-Writer-Settings) para obter mais detalhes. +4. Abra um aviso de comando como administrador na mesma pasta e execute `Vipr.exe --writer="GraphODataTemplateWriter"`. Um exemplo de arquivo de metadados pode ser encontrado na raiz deste projeto. + +Por padrão, o código-fonte de saída será colocado em uma pasta chamada "saída" ao lado do executável do Vipr. + +## Configurações do Escritor de Modelos +### Idiomas Disponíveis + +Há cinco idiomas que você pode escolher no momento. Java, ObjC, CSharp, TypeScript e Python. Especifique o idioma que você deseja gerar na configuração `TargetLanguage`. + +### Modelos +Você deve especificar um diretório de modelos nas Configurações do `TemplatesDirectory`. O diretório pode ser um caminho completo ou relativo ao diretório em execução. O diretório deve conter uma subpasta para cada plataforma para a qual você deseja gerar código. Confira o diretório de Modelos para obter um exemplo. + +### Mapeamento de Modelos +Você deve especificar o mapeamento de modelos T4 para Subprocessadores específicos para cada plataforma que deseja gerar. A configuração `TemplateMapping` é um dicionário de idiomas e uma lista de modelos. Cada modelo deve especificar: + +- `Modelo`, o nome do modelo sem as extensões. +- `Subprocessador` O Subprocessador para o modelo confira [Subprocessadores](#SubProcessors) +- `Tipo` O tipo de modelo. +- `Nome` A cadeia de caracteres de formato do nome. + +e opcionalmente: + +- `Incluir`, uma lista de objetos delimitadas por ponto e vírgula a ser incluída no subprocessador. +- `Excluir`, uma lista de objetos delimitadas por ponto e vírgula a ser excluída do subprocessador. +- `Ignorar`, uma lista de objetos delimitadas por ponto e vírgula a ser ignorada do subprocessador. +- `Correspondências`, uma lista de objetos delimitadas por ponto e vírgula a ser incluída no subprocessador. +- `FileCasing`, `UpperCamel`, `LowerCamel` ou `Snake` para o arquivo maíusculas/minúsculas específico que está sendo criado. + +**Observação: Muitos desses parâmetros opcionais foram usados ​​antes do Vipr ter suporte total para anotações; agora que as anotações foram adicionadas ao Vipr, o uso desses parâmetros deve ser limitado aos cenários herdados** + +Exemplo: + +` { "Modelo": "EntityCollectionPage", "Subprocessador": "NavigationCollectionProperty", "Tipo": "Solicitação", "Nome": "CollectionPage", "Correspondência" : "includeThisType", "Excluir" : "ExcludedTypeName;OtherExcludedTypeName" }` + +É importante compreender que os subprocessadores são mapeados para métodos que consultam o **OdcmModel** e retornam um conjunto de objetos OData. Esse mapeamento é mantido no [TemplateProcess.InitializeSubprocessor()](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/blob/dev/src/GraphODataTemplateWriter/TemplateProcessor/TemplateProcessor.cs#L54). Os mapeamentos específicos do idioma existem na [configuração do diretório](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/tree/dev/src/GraphODataTemplateWriter/.config). Cada objeto OData retornado pelo subprocessador é aplicado ao modelo mapeado que resulta em uma saída do arquivo de código para cada objeto OData. + +No exemplo acima, os objetos no conjunto de resultados do subprocessador NavigationCollectionProperty serão aplicados ao modelo EntityCollectionPage. Cada resultado será um arquivo de código para cada objeto retornado pelo subprocessador NavigationCollectionProperty. + +#### Subprocessadores + +Os subprocessadores determinam qual tipo de objeto OData será passado para o modelo que gera o arquivo de código. + +- `CollectionMethod` Todos os métodos que são do tipo Coleções +- `Collectionproperty` Todos os métodos que são do tipo coleção +- `CollectionReferenceProperty` Todas as Propriedades de Navegação que são do tipo Coleção e são usadas em Coleções Sem Contenção +- `ComplexType` Todos os tipos Complexos +- `EntityContainer` O EntityContainer +- `EntityReferencetype` Todos os tipos de Entidade que são usados em Coleções Sem Contenção +- `EntityType` Todos os tipos de Entidade +- `EnumType` Todos os tipos Enumeráveis +- `MediaEntityType` Todos os tipos de Entidade de Mídia +- `Método` Todas as Ações e Funções +- `MethodWithBody` Todos os Métodos e Funções que enviam um corpo dentro da solicitação http +- `NavigationCollectionProperty` Todas as Propriedades de Navegação do tipo Coleção +- `NonCollectionMethod` Todos os Métodos e Funções que não retornam uma coleção +- `Outros` Todo o modelo. +- `Propriedade` Todos os tipos de propriedades +- `Streamproperty` Todos os tipos de Propriedades que retornam fluxos + +#### Tipos + +O tipo de modelo. + +- `Solicitação` Um modelo que fará uma solicitação +- `Modelo` Um modelo +- `Compartilhado` Um modelo que não produz nenhum código, mas é incluído por outros modelos +- `Cliente` O modelo usado para criar o objeto Cliente +- `Outros` Qualquer outro tipo + + +#### Nome do Modelo + +Para definir o nome do modelo usando a cadeia de caracteres de formato de `Nome`. Você pode inserir ``, ``, `` e `` os valores serão substituídos pelos nomes do objeto correspondente. Se você inserir um item que não existe, ele será substituído por uma cadeia de caracteres vazia. +Observação: Você também pode definir o nome do modelo de dentro do modelo por: `host.SetTemplateName("foo");` + +#### Edição de Modelos + +A solução contém um projeto não criado para hospedar os modelos T4 reais, facilitando a navegação/edição. Os novos arquivos de modelo serão automaticamente detectados por esse projeto. + +#### Inclui/Exclui + +Pode haver ocasiões específicas em que você deseja excluir ou processar somente certos objetos do subprocessador. Para Fazer isso, você pode definir uma lista delimitada por ponto e vírgula de objetos que você deseja incluir: `Inclui: foo;bar`. Isso só processará objetos cujos nomes sejam foo ou bar. O oposto disso é a configuração de exclusão, na qual o Subprocessador incluirá todos os objetos, exceto aqueles cujos nomes estão na lista de exclusões, excluir e incluir não podem ser usados ​​juntos. + +#### Ignorar/Correspondências +Quando não é possível usar o nome de um objeto para incluí-lo ou excluí-lo, você pode usar o elemento descrição longa em qualquer objeto. Insira uma descrição longa com uma lista de cadeias de caracteres delimitadas por ponto e vírgula, como: `foo; bar;baz`. Se você adicionar uma `"Correspondências" : "foo;baz"` apenas objetos que contenham foo e baz na descrição longa serão processados. O oposto é verdadeiro para Ignorar. + +Observação: Você também pode fazer o check-in de um modelo por `odcjObject.LongDescriptionContains("foo");` + +**Observação: Inclui/Exclui e Ignorar/Correspondências foram usadas antes do Vipr ter suporte total para anotações; agora que as anotações foram adicionadas ao Vipr, o uso desses parâmetros deve estar limitado a cenários herdados** + +## Construir em Metadados de Gráfico + +Atualmente, há várias etapas que usamos para formar os metadados em um que gerará SDKs com sucesso da forma esperada: + + - Remover anotações de recursos (confira [\#132](https://github.com/Microsoft/Vipr/issues/132)) + - Adicionar anotação de navegação à miniatura + ```xml + + ``` + - Remover as propriedades do HasStream de ```onenotePage``` e ```onenoteEntityBaseModel``` + - Adicione ```ContainsTarget="true"``` às propriedades de navegação que não têm um EntitySet correspondente. Atualmente, isso se aplica a propriedades de navegação que contêm plannerBucket, plannerTask, plannerPlan e plannerDelta. + - Adicionar descrições longas aos tipos e propriedades de [documentos](https://developer.microsoft.com/pt-br/graph/docs/concepts/overview) + +Para criar metadados diferentes dos armazenados no diretório de [metadados](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/tree/master/metadata), você precisará executar os primeiros quatro nesta lista. + +## Colaboração + +Antes de aceitar a solicitação pull, você precisará concluir eletronicamente o [Contrato de Licença de Colaborador](https://cla.microsoft.com/) da Microsoft. Caso tenha feito isso para outros projetos da Microsoft, você já estará coberto. + +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 entre em contato pelo [opencode@microsoft.com](mailto:opencode@microsoft.com) se tiver outras dúvidas ou comentários. + +[Por que um CLA?](https://www.gnu.org/licenses/why-assign.html) (da FSF) + +## Licença + +Copyright (c) Microsoft Corporation. Todos os direitos reservados. Licenciada sob a [Licença do MIT](LICENSE). diff --git a/README-Localized/README-ru-ru.md b/README-Localized/README-ru-ru.md new file mode 100644 index 000000000..30a54454c --- /dev/null +++ b/README-Localized/README-ru-ru.md @@ -0,0 +1,195 @@ +[vipr-source-repo]: https://github.com/microsoft/vipr + +[![Состояние сборки](https://o365exchange.visualstudio.com/O365%20Sandbox/_apis/build/status/Microsoft%20Graph/msgraph-package-typewriter)](https://o365exchange.visualstudio.com/O365%20Sandbox/_build/latest?definitionId=1728) + +# Средство создания кода SDK Microsoft Graph + +Средства записи исходного кода для [VIPR][vipr-source-repo] с использованием шаблонов Т4. GraphODataTemplateWriter получает OdcmModel из VIPR и использует его для заполнения шаблона Т4, расположенного в этом репозитории. + +В настоящее время в этом средстве записи поддерживаются следующие целевые языки: +- Android +- CSharp +- Java +- Objective-C +- Python +- TypeScript +- PHP + +# Содержимое +- [Предварительные требования](#prerequisites) +- [Начало работы](#getting-started) +- [Использование Vipr с этим средством записи](#using-vipr-with-this-writer) +- [Участие](#contributing) +- [Лицензия](#license) + +## Предварительные требования +- [Пакет SDK для Visual Studio](https://msdn.microsoft.com/ru-ru/library/bb166441.aspx) +- [Пакет SDK моделирования для Visual Studio](https://msdn.microsoft.com/ru-ru/library/bb126259.aspx) + +# Начало работы + +В этом проекте используются подмодули git для интеграции восходящих зависимостей, в частности [Vipr][vipr-source-repo]. Если вам требуется другое ответвление, чтобы включить специальные исправления, понадобится извлечь его вручную в подмодуле. + +Чтобы решение открывалось правильно, перед его открытием в Visual Studio убедитесь, что подмодули обновлены. При исходном копировании этого репозитория используйте команду `git clone --recursive` для одновременного обновления подмодулей. Позже выполните команду `git submodule update`, чтобы обновить подмодули вручную. Если вы не используете параметр `--recursive` при клонировании, сначала выполните команду `git submodule init`, чтобы инициализировать подмодуль. + +Завершив настройку, вы сможете работать в решении GraphODataTemplateWriter обычным образом. Если у вас возникли проблемы, обновите пакеты NuGet и ссылки проекта. + +Чтобы получить сведения о подмодулях, обратитесь к [этой главе](http://git-scm.com/book/en/v2/Git-Tools-Submodules) из книги по Git и поиску в Интернете. + +## Использование Typewriter + +Typewriter — это новое решение для создания файлов кода с использованием GraphODataTemplateWriter и VIPR. Это исполняемое решение, предназначенное для упрощения создания файлов кода. Создайте решение, чтобы найти исполняемый файл typewriter в `\MSGraph-SDK-Code-Generator\src\Typewriter\bin\Release`. Параметры запуска typewriter: + +* **-l**, **-language**. Целевой язык для создаваемых файлов кода. Возможные значения: `Android`, `Java`, `ObjC`, `CSharp`, `PHP`, `Python`, `TypeScript` или `GraphEndpointList`. По умолчанию установлено значение `CSharp`. Это неприменимо только при создании пустых и аннотированных метаданных, указываемых с помощью параметра `-generationmode Metadata`. +* **-m**, **-metadata**. Локальный путь к файлу или URL-адрес целевых входных метаданных. Значение по умолчанию — `https://graph.microsoft.com/v1.0/$metadata`. Это обязательное значение. +* **-v**, **-verbosity**. Уровень детализации журнала. Возможные значения: `Minimal`, `Info`, `Debug` или `Trace`. По умолчанию установлено значение `Minimal`. +* **-o**, **-output**. Указывает путь к выходной папке. Значением по умолчанию является каталог, содержащий файл typewriter.exe. Структура и содержимое выходного каталога зависит от параметров `-generationmode` и `-language`. +* **-d**, **-docs**. Указывает путь к локальной корневой папке репозитория [microsoft-graph-docs](https://github.com/microsoftgraph/microsoft-graph-docs). Значением по умолчанию является каталог, содержащий файл typewriter.exe. Выполняется разбор документации для предоставления аннотаций к метаданным, которые затем применяются для добавления комментариев документов в созданных файлах кода. Этот параметр требуется при использовании значений `Metadata` или `Full` для `-generationmode`. +* **-g**, **-generationmode**. Указывает режим создания. Возможные значения: `Full`, `Metadata` или `Files`. В режиме создания `Full` (по умолчанию) создаются выходные файлы кода путем очистки исходных метаданных, разбора документации и добавления аннотаций перед созданием выходных файлов. В режиме создания `Metadata` создаются выходные файлы метаданных путем очистки метаданных, разбора документов и добавления аннотаций к документам. В режиме создания `Files` создаются файлы кода из исходных метаданных и пропускается очистка, разбор документации и добавление аннотаций к документам. +* **-f**, **-outputMetadataFileName**. Имя файла с основными выходными метаданными. Применимо только для режима `-generationmode Metadata`. Значение по умолчанию — `cleanMetadataWithDescriptions`, используемое со значением `-endpointVersion` для создания файла метаданных `cleanMetadataWithDescriptionsv1.0.xml`. +* **-e**, **-endpointVersion**. Версия конечной точки, используемая при именовании файла метаданных. Предполагаемые значения: `v1.0` и `beta`. Применимо только для режима `-generationmode Metadata`. +* **-p**, **-properties**. Определите свойства, поддерживающие логику создания в шаблонах T4. Свойства должны быть представлены в формате *строка-ключа:строка-значения*. Можно настроить несколько свойств, указывая пробел между ними. В настоящее время поддерживается единственное свойство *php.namespace* для указания пространства имен файлов создаваемой модели. Это необязательное свойство. + +### Пример использования typewriter + +#### Создание вводимых элементов TypeScript из файла CSDL (метаданные) без очистки или добавления аннотаций к CSDL. + +Выходные данные будут добавлены в каталог `outputTypeScript`. + +`.\typewriter.exe -v Info -m D:\cleanMetadataWithDescriptions_v10.xml -o outputTypeScript -l TypeScript -g Files` + +#### Очистка и добавление аннотаций в файл метаданных с использованием аннотаций к документации, полученных из репозитория документации + +Выходной файл метаданных добавляется в каталог `output2`. Выходной файл метаданных будет называться `cleanMetadataWithDescriptionsv1.0.xml` на основе значений, используемых по умолчанию. + +`.\typewriter.exe -v Info -m D:\v1.0_2018_10_23_source.xml -o output2 -d D:\repos\microsoft-graph-docs -g Metadata` + +#### Создание файлов кода C# из метаданных, которые будут очищены с добавлением аннотаций документов из репозитория документации + +Выходные файлы кода C# будут добавлены в каталог `output`. + +`.\typewriter.exe -v Info -m D:\v1.0_2018_10_23_source.xml -o output -l CSharp -d D:\repos\microsoft-graph-docs -g Full` + + + +## Использование Vipr с этим средством записи + +1. Создайте решение в Visual Studio. +2. Перейдите в папку `src\GraphODataTemplateWriter\bin\debug`, чтобы найти все скомпилированные компоненты. +3. В этой папке измените файл `.config\TemplateWriterSettings.json`, чтобы указать сопоставление шаблона. Дополнительные сведения см. в разделе [Параметры средства записи шаблонов](##Template-Writer-Settings). +4. Откройте командную строку в качестве администратора из той же папки и выполните команду `Vipr.exe --writer="GraphODataTemplateWriter"`. Пример файла метаданных можно найти в корне этого проекта. + +По умолчанию выходной исходный код помещается в папку с именем output рядом с исполняемым файлом Vipr. + +## Параметры средства записи шаблонов +### Доступные языки + +В настоящее время можно выбирать из пяти языков: Java, ObjC, CSharp, TypeScript и Python. Укажите нужный язык для создания в параметре `TargetLanguage`. + +### Шаблоны +Вы должны указать каталог шаблона в параметрах `TemplatesDirectory`. Это может быть полный путь или путь относительно текущего каталога. Каталог должен содержать вложенный каталог для каждой платформы, для которой нужно создать код. Пример см. в каталоге шаблонов. + +### Сопоставление шаблонов +Требуется сопоставить шаблоны T4 с определенными субобработчиками для каждой платформы, которую нужно создать. Параметр `TemplateMapping` — это словарь языков и список шаблонов. В каждом шаблоне должно быть указаны следующие параметры: + +- `Template`. Имя шаблона без расширений. +- `SubProcessor`. Субобработчик для шаблона. См. раздел [Субобработчики](#SubProcessors). +- `Type`. Тип шаблона. +- `Name`. Строка формата для имени. + +и при необходимости: + +- `Include`. Разделенный точками с запятой список объектов для включения в субобработчик. +- `Exclude`. Разделенный точками с запятой список объектов для исключения из субобработчика. +- `Ignore`. Разделенный точками с запятой список объектов для игнорирования субобработчиком. +- `Matches`. Разделенный точками с запятой список объектов для включения в субобработчик. +- `FileCasing`, `UpperCamel`, `LowerCamel` или `Snake` для стиля регистра определенного создаваемого файла. + +**Примечание. Многие из этих необязательных параметров использовались до полной поддержки аннотаций в Vipr. Теперь, после добавления аннотаций в Vipr, использование этих параметров должно ограничиваться устаревшими сценариями.** + +Пример: + +` { "Template": "EntityCollectionPage", "SubProcessor": "NavigationCollectionProperty", "Type": "Request", "Name": "CollectionPage", "Matches" : "includeThisType", "Exclude" : "ExcludedTypeName;OtherExcludedTypeName" }` + +Важно понимать, что субобработчики сопоставлены с методами, запрашивающими объект **OdcmModel** и возвращающими набор объектов OData. Это сопоставление обеспечивается в методе [TemplateProcess.InitializeSubprocessor()](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/blob/dev/src/GraphODataTemplateWriter/TemplateProcessor/TemplateProcessor.cs#L54). В [каталоге конфигурации](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/tree/dev/src/GraphODataTemplateWriter/.config) существуют сопоставления для конкретных языков. Каждый объект OData, возвращаемый субобработчиком, применяется к сопоставленному шаблону, что приводит к созданию выходного файла кода для каждого объекта OData. + +В примере выше каждый объект итогового набора субобработчика NavigationCollectionProperty будет применяться к шаблону EntityCollectionPage. Каждый результат будет файлом кода для каждого объекта, возвращаемого субобработчиком NavigationCollectionProperty. + +#### Субобработчики + +Субобработчики определяют, какой тип объекта OData будет передан в шаблон, создающий файл кода. + +- `CollectionMethod`. Все методы, являющиеся типом коллекций +- `CollectionProperty`. Свойства, являющиеся типом коллекции +- `CollectionReferenceProperty`. Все свойства навигации, являющиеся типом коллекции, применяемым в неавтономных коллекциях +- `ComplexType`. Все сложные типы +- `EntityContainer`. Контейнер объекта +- `EntityReferenceType`. Все типы объектов, используемые в неавтономных коллекциях +- `EntityType`. Все типы объектов +- `EnumType`. Все перечисляемые типы +- `MediaEntityType`. Все типы объектов мультимедиа +- `Method`. Все действия и функции +- `MethodWithBody`. Все методы и функции, отправляющие текст в HTTP-запросе +- `NavigationCollectionProperty`. Все свойства навигации, являющиеся типом коллекции +- `NonCollectionMethod`. Все методы и функции, не возвращающие коллекцию +- `Other`. Вся модель. +- `Property`. Все типы свойств +- `StreamProperty`. Все типы свойств, возвращающие потоки + +#### Типы + +Тип шаблона. + +- `Request`. Шаблон, выполняющий запрос +- `Model`. Модель +- `Shared`. Шаблон, не создающий выходного кода, но включаемый другими шаблонами +- `Client`. Шаблон, используемый для создания объекта Client +- `Other`. Любой другой тип + + +#### Имя шаблона + +Чтобы задать имя шаблона, используется строка формата `Name`. Вы можете вставить элементы ``, ``, `` и ``, значения которых будут заменены именами соответствующих объектов. Если вставить отсутствующий элемент, он будет заменен пустой строкой. Примечание. Также можно настроить имя шаблона изнутри шаблона с помощью +параметра: `host.SetTemplateName("foo");` + +#### Редактирование шаблона + +Решение содержит несобираемый проект для размещения фактических шаблонов T4 и упрощения их просмотра и изменения. Этот проект автоматически обнаруживает новые файлы шаблонов. + +#### Включение и исключение + +В определенные моменты вам может понадобиться исключить или обработать только некоторые объекты в субобработчике. Для этого вы можете настроить разделенный точками с запятой список объектов, которые нужно включать: `Include : foo;bar`. При этом обрабатываются только объекты с именами foo или bar. Противоположностью является параметр исключения, при использовании которого субобработчик включает все объекты, кроме содержащихся в списке исключения. Параметры исключения и включения нельзя применять совместно. + +#### Игнорирование и совпадения +Если нельзя использовать имя объекта для включения или исключения, можно применить элемент длинного описания для любого объекта. Вставьте длинное описание с разделенным точками с запятой списком строк, например: `foo;bar;baz`. Если добавить `"Matches" : "foo;baz"`, будут обрабатываться только объекты, содержащие foo и baz в своем длинном описании. Противоположные действия применяются при использовании параметра Ignore. + +Примечание. Вы также можете вернуть шаблон с помощью параметра `odcjObject.LongDescriptionContains("foo");` + +**Примечание. Параметры включения/исключения и игноирования/соответствия использовались до полной поддержки аннотаций в Vipr. Теперь, после добавления аннотаций в Vipr, использование этих параметров должно ограничиваться устаревшими сценариями.** + +## Сборка с использованием метаданных Graph + +В настоящее время необходимо выполнить несколько действий, чтобы сформировать метаданные в виде объекта, который успешно создает нужные пакеты SDK: + + - Удалите аннотации к возможностям (см. [\#132](https://github.com/Microsoft/Vipr/issues/132)) + - Добавьте навигационную аннотацию к эскизу + ```xml + + ``` + - Удалите свойства HasStream из объектов ```onenotePage``` и ```onenoteEntityBaseModel``` + - Добавьте параметр ```ContainsTarget="true"``` в свойства навигации, не содержащие соответствующего объекта EntitySet. В настоящее время это относится к свойствам навигации, содержащим объекты plannerBucket, plannerTask, plannerPlan и plannerDelta. + - Добавьте длинные описания для типов и свойств из [документации](https://developer.microsoft.com/ru-ru/graph/docs/concepts/overview) + +Чтобы выполнить сборку с использованием метаданных, отличных от сохраненных в каталоге [metadata](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/tree/master/metadata), вам потребуется выполнить первые четыре действия этого списка. + +## Участие + +Перед принятием запроса на включение внесенных изменений вам потребуется в электронном виде принять [лицензионное соглашение участника](https://cla.microsoft.com/) от корпорации Майкрософт. Если вы сделали это для других проектов Майкрософт, повторное действие не требуется. + +Этот проект соответствует [правилам поведения разработчиков открытого кода Майкрософт](https://opensource.microsoft.com/codeofconduct/). Дополнительные сведения см. в разделе [часто задаваемых вопросов о правилах поведения](https://opensource.microsoft.com/codeofconduct/faq/). Если у вас возникли вопросы или замечания, напишите нам по адресу [opencode@microsoft.com](mailto:opencode@microsoft.com). + +[Почему CLA?](https://www.gnu.org/licenses/why-assign.html) (из FSF) + +## Лицензия + +© Корпорация Майкрософт. Все права защищены. Предоставляется по [лицензии MIT](LICENSE). diff --git a/README-Localized/README-zh-cn.md b/README-Localized/README-zh-cn.md new file mode 100644 index 000000000..df6b6d2d0 --- /dev/null +++ b/README-Localized/README-zh-cn.md @@ -0,0 +1,195 @@ +[vipr-source-repo]: https://github.com/microsoft/vipr + +[![生成状态](https://o365exchange.visualstudio.com/O365%20Sandbox/_apis/build/status/Microsoft%20Graph/msgraph-package-typewriter)](https://o365exchange.visualstudio.com/O365%20Sandbox/_build/latest?definitionId=1728) + +# Microsoft Graph SDK 代码生成器 + +适用于使用 T4 模板的 [VIPR][vipr-source-repo] 的源代码编写器。GraphODataTemplateWriter 从 VIPR 接收 OdcmModel，并将其用于填充此存储库内的 T4 模板。 + +此编写器当前支持以下目标语言： +- Android +- CSharp +- Java +- Objective-C +- Python +- TypeScript +- PHP + +# 内容 +- [先决条件](#prerequisites) +- [入门](#getting-started) +- [将 Vipr 与此编写器结合使用](#using-vipr-with-this-writer) +- [参与](#contributing) +- [许可证](#license) + +## 先决条件 +- [Visual Studio SDK](https://msdn.microsoft.com/zh-cn/library/bb166441.aspx) +- [Visual Studio 建模 SDK](https://msdn.microsoft.com/zh-cn/library/bb126259.aspx) + +# 入门 + +此项目使用 git 子模块来集成上游依赖项，尤其是 [Vipr][vipr-source-repo]。如果需要备用分支以包含特殊修补程序，则需要在子模块中手动将该分支签出。 + +为了正确打开解决方案，请确保在 Visual Studio 中打开解决方案之前已更新子模块。最初克隆此存储库时，请使用 `git clone --recursive` 在同一时间更新子模块。稍后，请运行 `git submodule update` 以手动更新子模块。如果在进行克隆时不使用 `--recursive` 开关，请先运行`git submodule init` 以初始化子模块。 + +设置完成后，可照常使用 GraphODataTemplateWriter 解决方案。如果遇到问题，请确保 NuGet 包和项目引用均为最新版本。 + +有关子模块的详细信息，请参阅 Git 手册中的[本章](http://git-scm.com/book/en/v2/Git-Tools-Submodules)并在网上搜索。 + +## 使用 Typewriter + +Typewriter 是使用 GraphODataTemplateWriter 和 VIPR 来生成代码文件的新解决方案。这是一种旨在简化代码文件生成过程的可执行文件。请生成该解决方案以便在 `\MSGraph-SDK-Code-Generator\src\Typewriter\bin\Release` 中查找 Typewriter 可执行文件。Typewriter 运行选项包括： + +* **-l**，**-language**：所生成的代码文件的目标语言。值可以是：`Android`、`Java`、`ObjC`、`CSharp`、`PHP`、`Python`、`TypeScript` 或 `GraphEndpointList`。默认值为 `CSharp`。仅生成由 `-generationmode Metadata` 选项指定的经过清理和批注的元数据时，此选项不适用。 +* **-m**，**-metadata**：目标输入元数据的本地文件路径或 URL。默认值为 `https://graph.microsoft.com/v1.0/$metadata`。此值是必需的。 +* **-v**，**-verbosity**：日志详细级别。值可以是：`Minimal`、`Info`、`Debug` 或 `Trace`。默认值为 `Minimal`。 +* **-o**，**-output**：指定输出文件夹的路径。默认值为包含 typewriter.exe 的目录。输出目录的结构和内容将因 `-generationmode` 和 `-language` 选项而异。 +* **-d**，**-docs**：指定 [microsoft-graph-docs](https://github.com/microsoftgraph/microsoft-graph-docs) 存储库的本地根目录的路径。默认值为包含 typewriter.exe 的目录。系统会分析文档以将文档批注提供给元数据，随后用于在生成的代码文件中添加文档注释。当 `-generationmode` 的值为 `Metadata` 或 `Full` 时，此选项是必需的。 +* **-g**，**-generationmode**：指定生成模式。值可以是：`Full`、`Metadata` 或 `Files`。`Full`（默认值）生成模式将生成输出代码文件，方法是清理输入元数据、分析文档以及在生成输出文件前添加批注。`Metadata` 生成模式将生成输出元数据文件，方法是清理元数据、分析文档以及添加文档批注。`Files` 生成模式将从输入元数据生成代码文件，并绕过清理、文档分析和添加文档批注的过程。 +* **-f**，**-outputMetadataFileName**：基本输出元数据文件名。仅适用于 `-generationmode Metadata`。默认值为 `cleanMetadataWithDescriptions`，与 `-endpointVersion` 值一起使用，以生成名为 `cleanMetadataWithDescriptionsv1.0.xml` 的元数据文件。 +* **-e**，**-endpointVersion**：命名元数据文件时使用的终结点版本。期望的值是 `v1.0` 和 `beta`。仅适用于 `-generationmode Metadata`。 +* **-p**，**-properties**：指定属性以支持 T4 模板中的生成逻辑。属性必须采用 *key-string:value-string* 的形式。可通过在属性之间设置空格来指定多个属性。目前唯一支持的属性是 *php.namespace* 属性，用于指定生成的模型文件命名空间。此属性是可选的。 + +### Typewriter 使用示例 + +#### 在不清理或添加 CSDL 批注的情况下从 CSDL（元数据）文件生成 TypeScript 打字。 + +输出将进入 `outputTypeScript` 目录。 + +`.\typewriter.exe -v Info -m D:\cleanMetadataWithDescriptions_v10.xml -o outputTypeScript -l TypeScript -g Files` + +#### 清理元数据文件以及使用源于文档存储库的文档批注为元数据文件添加批注 + +输出元数据文件将进入 `output2` 目录。输出元数据文件将根据默认值命名为 `cleanMetadataWithDescriptionsv1.0.xml`。 + +`.\typewriter.exe -v Info -m D:\v1.0_2018_10_23_source.xml -o output2 -d D:\repos\microsoft-graph-docs -g Metadata` + +#### 从将要进行清理以及使用源于文档存储库的文档批注进行批注的元数据生成 C# 代码文件 + +输出 C# 代码文件将进入 `output` 目录。 + +`.\typewriter.exe -v Info -m D:\v1.0_2018_10_23_source.xml -o output -l CSharp -d D:\repos\microsoft-graph-docs -g Full` + + + +## 将 Vipr 与此编写器结合使用 + +1. 在 Visual Studio 中生成解决方案。 +2. 转到 `src\GraphODataTemplateWriter\bin\debug` 文件夹，查找所有已编译的组件。 +3. 在该文件夹中，修改 `.config\TemplateWriterSettings.json` 以指定模板映射。有关更多详细信息，请参阅[模板编写器设置](##Template-Writer-Settings)。 +4. 在同一文件夹中以管理员身份打开命令提示窗口，然后运行 `Vipr.exe --writer="GraphODataTemplateWriter"`。可在此项目的根目录中找到一个示例元数据文件。 + +默认情况下，输出源代码将放入到名为“output”的文件夹（在 Vipr 可执行文件旁边）。 + +## 模板编写器设置 +### 可用语言 + +目前有五种语言可供选择。Java、ObjC、CSharp、TypeScript 和 Python。在 `TargetLanguage` 设置中指定要生成的语言。 + +### 模板 +必须在 `TemplatesDirectory` 设置下指定模板目录。该目录可以是完整路径或相对于运行目录的路径。该目录必须包含要生成代码的每个平台的子目录。请查看 Templates 目录中的示例。 + +### 模板映射 +必须为想要生成的每个平台指定 T4 模板到特定子处理器的映射。`TemplateMapping` 设置是语言和模板列表的字典。每个模板都必须指定： + +- `Template`：不含扩展名的模板名称。 +- `SubProcessor`：模板的子处理器，请参阅[子处理器](#SubProcessors)。 +- `Type`：模板类型。 +- `Name`：名称的格式字符串。 + +并可指定（可选）： + +- `Include`：要包含在子处理器中的以分号分隔的对象列表。 +- `Exclude`：要从子处理器中排除的以分号分隔的对象列表。 +- `Ignore`：要从子处理器中忽略的以分号分隔的对象列表。 +- `Matches`：要包含在子处理器中的以分号分隔的对象列表。 +- `FileCasing`、`UpperCamel`、`LowerCamel` 或 `Snake`：所要创建的特定文件的文件大小写。 + +**注意：许多这些可选参数都是在 Vipr 完全支持批注前使用的；现在，由于已向 Vipr 添加了批注，因此这些参数的使用应仅限于旧方案** + +示例： + +` { "Template":"EntityCollectionPage", "SubProcessor":"NavigationCollectionProperty", "Type":"Request", "Name": "CollectionPage", "Matches" : "includeThisType", "Exclude" :"ExcludedTypeName;OtherExcludedTypeName" }` + +请务必了解子处理器会映射到用于查询 **OdcmModel** 并返回一组 OData 对象的方法。此映射保留在 [TemplateProcess.InitializeSubprocessor()](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/blob/dev/src/GraphODataTemplateWriter/TemplateProcessor/TemplateProcessor.cs#L54) 中。特定于语言的映射存在于[配置目录](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/tree/dev/src/GraphODataTemplateWriter/.config)中。子处理器返回的每个 OData 对象会应用于映射的模板，这会为每个 OData 对象产生代码文件输出。 + +在上面的示例中，NavigationCollectionProperty 子处理器的结果集中的对象将分别应用于 EntityCollectionPage 模板。每个结果将是 NavigationCollectionProperty 子处理器返回的每个对象的代码文件。 + +#### 子处理器 + +子处理器决定了要将什么类型的 OData 对象传递给模板以生成代码文件。 + +- `CollectionMethod`：属于集合类型的所有方法 +- `CollectionProperty`：集合类型的属性 +- `CollectionReferenceProperty`：在非包容集合中使用的集合类型的所有导航属性 +- `ComplexType`：所有复杂类型 +- `EntityContainer`：EntityContainer +- `EntityReferenceType`：在非包容集合中使用的所有实体类型 +- `EntityType`：所有实体类型 +- `EnumType`：所有枚举类型 +- `MediaEntityType`：所有媒体实体类型 +- `Method`：所有操作和函数 +- `MethodWithBody`：在 http 请求中发送主体的所有方法和函数 +- `NavigationCollectionProperty`：属于集合类型的所有导航属性 +- `NonCollectionMethod`：不返回集合的所有方法和函数 +- `Other`：整个模型 +- `Property`：所有属性类型 +- `StreamProperty`：返回 Streams 的所有属性类型 + +#### 类型 + +模板的类型。 + +- `Request`：将发出请求的模板 +- `Model`：模型 +- `Shared`：不会输出任何代码但由其他模板包含的模板 +- `Client`：用于创建客户端对象的模板 +- `Other`：任何其他类型 + + +#### 模板名称 + +使用 `Name` 格式字符串设置模板的名称。你可以插入 ``、``、`` 和 ``，值将替换为相应对象的名称。如果插入的某一项不存在，它将被替换为空字符串。 +注意：还可以通过 `host.SetTemplateName("foo");` 从模板内设置模板名称。 + +#### 模板编辑 + +该解决方案包含一个非生成项目，用于托管实际的 T4 模板并简化这些模板的浏览/编辑操作。此项目将自动发现新模板文件。 + +#### 包含/排除 + +在特定情况中可能会希望排除或仅处理子处理器的某些对象。若要执行此操作，可以设置一个要包含的对象列表（以分号分隔各个对象）：`Include : foo;bar`。这种情况将仅处理名称为 foo 或 bar 的对象。与此相反的是排除设置，即子处理器将包含除名称位于排除列表中的对象之外的所有对象，包含和排除不能一起使用。 + +#### 忽略/匹配 +无法使用对象名称来包含或排除时，可对任何对象使用详细描述元素。使用以分号分隔的字符串列表（如：`foo;bar;baz`）插入详细描述。如果添加 `"Matches" : "foo;baz"`，则仅会处理在详细描述中包含 foo 和 baz 的对象。反之对于忽略 (Ignore) 也是如此。 + +注意：还可以通过 `odcjObject.LongDescriptionContains("foo");` 签入模板 + +**注意：包含/排除和忽略/匹配是在 Vipr 完全支持批注前使用的；现在，由于已向 Vipr 添加了批注，因此这些参数的使用应仅限于旧方案** + +## 根据图形元数据生成 + +当前，我们采取以下几个步骤将元数据形成一个可以成功生成期望格式的 SDK 的元数据： + + - 删除功能批注（请参阅 [\#132](https://github.com/Microsoft/Vipr/issues/132)） + - 向缩略图 + ```xml + + ``` 添加导航批注 + - 从 ```onenotePage``` 和 ```onenoteEntityBaseModel``` 删除 HasStream 属性 + - 向不具有相应 EntitySet 的导航属性添加 ```ContainsTarget="true"```。这目前适用于包含 plannerBucket、plannerTask、plannerPlan 和 plannerDelta 的导航属性 + - 向[文档](https://developer.microsoft.com/zh-cn/graph/docs/concepts/overview)中的类型和属性添加详细描述 + +为了根据未存储在 [metadata](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/tree/master/metadata) 目录中的其他元数据进行生成，需执行此列表中的前四个步骤。 + +## 参与 + +为了能够接受你的拉取请求，你需要以电子方式填写 Microsoft 的[参与者许可协议](https://cla.microsoft.com/)。如果你已对其他 Microsoft 项目执行此操作，则表示你已经符合条件。 + +此项目遵循 [Microsoft 开放源代码行为准则](https://opensource.microsoft.com/codeofconduct/)。有关详细信息，请参阅[行为准则常见问题解答](https://opensource.microsoft.com/codeofconduct/faq/)。如有其他任何问题或意见，也可联系 [opencode@microsoft.com](mailto:opencode@microsoft.com)。 + +[为何需要 CLA？](https://www.gnu.org/licenses/why-assign.html)（来自 FSF） + +## 许可证 + +版权所有 (c) Microsoft Corporation。保留所有权利。根据 MIT [许可证](LICENSE)获得许可。 diff --git a/README.md b/README.md index 24ae4c7ab..7a08bbc67 100755 --- a/README.md +++ b/README.md @@ -7,7 +7,6 @@ Source code writers for [VIPR][vipr-source-repo] utilizing T4 templates. The GraphODataTemplateWriter receives an OdcmModel from VIPR and uses it to fill in a T4 template located within this repository. Currently the following target languages are supported by this writer: -- Android - CSharp - Java - Objective-C @@ -40,18 +39,31 @@ For more information on submodules read [this chapter](http://git-scm.com/book/e Typewriter is a new solution for generating code files using the GraphODataTemplateWriter and VIPR. It is an executable that is intended to simplify the generation of code files. Build the solution to find the typewriter executable in `\MSGraph-SDK-Code-Generator\src\Typewriter\bin\Release`. The typewriter run options are: -* **-l**, **-language**: The target language for the generated code files. The values can be: `Android`, `Java`, `ObjC`, `CSharp`, `PHP`, `Python`, `TypeScript`, or `GraphEndpointList`. The default value is `CSharp`. This is not applicable when only generating clean and annotated metadata as specified by the `-generationmode Metadata` option. +* **-l**, **-language**: The target language for the generated code files. The values can be: `Java`, `ObjC`, `CSharp`, `PHP`, `Python`, `TypeScript`, or `GraphEndpointList`. The default value is `CSharp`. This is not applicable when only generating clean and annotated metadata as specified by the `-generationmode Metadata` option. * **-m**, **-metadata**: The local file path or URL to the target input metadata. The default value is `https://graph.microsoft.com/v1.0/$metadata`. This value is required. * **-v**, **-verbosity**: The log verbosity level. The values can be: `Minimal`, `Info`, `Debug`, or `Trace`. The default value is `Minimal`. * **-o**, **-output**: Specifies the path to the output folder. The default value is the directory that contains typewriter.exe. The structure and contents of the output directory will be different based on the `-generationmode` and `-language` options. -* **-d**, **-docs**: Specifies the path to the local root of the [microsoft-graph-docs](https://github.com/microsoftgraph/microsoft-graph-docs) repo. The default value is the directory that contains typewriter.exe. The documentation is parsed to provide documentation annotations to the metadata which is then used to add doc comments in the generated code files. This option is required when using `-generationmode` values of `Metadata` or `Full`. -* **-g**, **-generationmode**: Specifies the generation mode. The values can be: `Full`, `Metadata`, or `Files`. `Full` (default) generation mode produces the output code files by cleaning the input metadata, parsing the documentation, and adding annotations before generating the output files. `Metadata` generation mode produces an output metadata file by cleaning metadata, documentation parsing, and adding documentation annotations. `Files` generation mode produces code files from an input metadata and bypasses the cleaning, documentation parsing, and adding documentation annotations. +* **-d**, **-docs**: Specifies the path to the local root of the [microsoft-graph-docs](https://github.com/microsoftgraph/microsoft-graph-docs) repo. The default value is the directory that contains typewriter.exe. The documentation is parsed to provide documentation annotations to the metadata which is then used to add doc comments in the generated code files. This option is required when using `-generationmode` values of `Metadata`, `Full`, or `TransformWithDocs`. +* **-g**, **-generationmode**: Specifies the generation mode. The values can be: `Full`, `Metadata`, `Files`, `Transform` or `TransformWithDocs`. `Full` (default) generation mode produces the output code files by cleaning the input metadata, parsing the documentation, and adding annotations before generating the output files. `Metadata` generation mode produces an output metadata file by cleaning metadata, documentation parsing, and adding documentation annotations. `Files` generation mode produces code files from an input metadata and bypasses the cleaning, documentation parsing, and adding documentation annotations. `Transform` generation mode processes the metadata according to the XSLT provided with the -t option. `TransformWithDocs` generation mode processes the metadata according to the XSLT and adds documentation annotations. `Transform` and `TransformWithDocs` require the -t argument to specify the XSLT file. * **-f**, **-outputMetadataFileName**: The base output metadata filename. Only applicable for `-generationmode Metadata`. The default value is `cleanMetadataWithDescriptions` which is used with the value of the `-endpointVersion` to generate a metadata file named `cleanMetadataWithDescriptionsv1.0.xml`. * **-e**, **-endpointVersion**: The endpoint version used when naming a metadata file. Expected values are `v1.0` and `beta`. Only applicable for `-generationmode Metadata`. * **-p**, **-properties**: Specify properties to support generation logic in the T4 templates. Properties must take the form of *key-string:value-string*. Multiple properties can be specified by setting a space in between property. The only property currently supported is the *php.namespace* property to specify the generated model file namespace. This property is optional. +* **-t**, **-transform**: Specify the URI to the XSLT that will preprocess the metadata. Only applicable for `-generationmode Transform` or `-generationmode TransformWitDocs`. ### Example typewriter usage +#### Transform metadata with XSLT. + +The output `cleanMetadata.xml` will be located in the same directory as typewriter.exe. + +`.\typewriter.exe -v Info -m https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/v1.0_metadata.xml -g Transform -t https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/transforms/csdl/preprocess_csdl.xsl` + +#### Transform metadata with XSLT and add documentation annotations. + +The output `cleanMetadataWithDescriptionsv1.0.xml` will be located in the same directory as typewriter.exe. + +`.\typewriter.exe -v Info -m https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/v1.0_metadata.xml -g TransformWithDocs -t https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/transforms/csdl/preprocess_csdl.xsl -d D:\repos\microsoft-graph-docs` + #### Generate TypeScript typings from a CSDL (metadata) file without cleaning or annotating the CSDL. The output will go in to the `outputTypeScript` directory. @@ -70,7 +82,26 @@ The output C# code files will go in to the `output` directory. `.\typewriter.exe -v Info -m D:\v1.0_2018_10_23_source.xml -o output -l CSharp -d D:\repos\microsoft-graph-docs -g Full` +## Use Typewriter to test your beta metadata + +We assume that the metadata you are using is based off the beta metadata file. + +1. Download the [latest Typewriter release](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/releases). +2. Run Typewriter to generate a clean metadata file from your test metadata file. The output file will be `cleanMetadata.xml`. + +`.\typewriter.exe -v Info -m -g Transform -t https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/transforms/csdl/preprocess_csdl.xsl` + + + +3. Generate .NET code files with Typewriter using the generated `cleanMetadata.xml`. + +`.\typewriter.exe -v Info -m D:\cleanMetadata.xml -o outputDirectory -g Files` + +4. Clone the Beta .NET SDK https://github.com/microsoftgraph/msgraph-beta-sdk-dotnet. +5. Replace the files under `src/Microsoft.Graph/Requests/Generated` and `src/Microsoft.Graph/Models/Generated` in the Beta .Net SDK with the generated files. +6. Build the Beta .Net SDK to validate that the generated files compile. +At this point you should have a valid SDK. ## Using Vipr with this Writer @@ -113,7 +144,7 @@ Example : It is important to understand that subprocessors are mapped to methods that query the **OdcmModel** and return a set of OData objects. This mapping is maintained in [TemplateProcess.InitializeSubprocessor()](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/blob/dev/src/GraphODataTemplateWriter/TemplateProcessor/TemplateProcessor.cs#L54). The language specific mappings exist in the [config directory](https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator/tree/dev/src/GraphODataTemplateWriter/.config). Each OData object returned by the subprocessor is applied to the mapped template which results in a code file output per each OData object. -In the above example, the objects in result set of the NavigationCollectionProperty subprocessor will each be applied to the EntityCollectionPage template. Each result will be a code file for each object returned by the NavigationCollectionProperty subprocessor. +In the above example, the objects in result set of the NavigationCollectionProperty subprocessor will each be applied to the EntityCollectionPage template. Each result will be a code file for each object returned by the NavigationCollectionProperty subprocessor. #### SubProcessors diff --git a/Templates/Android/BaseModel.template.tt b/Templates/Android/BaseModel.template.tt deleted file mode 100644 index 88416f03b..000000000 --- a/Templates/Android/BaseModel.template.tt +++ /dev/null @@ -1,862 +0,0 @@ -<# // Copyright (c) Microsoft Corporation. All Rights Reserved. Licensed under the MIT License. See License in the project root for license information. #> -<#@ template debug="true" hostspecific="true" language="C#" #> -<#@ output extension="\\" #> -<# - - CustomT4Host host = (CustomT4Host) Host; - var model = host.CurrentModel; - CodeWriterAndroid writer = (CodeWriterAndroid) host.CodeWriter; - bool logTemplateSrc = false; - var c = host.CurrentType; -#> -<# if (logTemplateSrc) { #> -// Template Source: <#= TemplateName(host.TemplateFile) #> -<# } #> -<#+ - - /// Choose an intermediate class type based on GETs/POSTs - public string RequestBuilderSuperClass(OdcmObject currentType) { - return currentType.AsOdcmMethod().IsFunction ? - "BaseFunctionRequestBuilder" : "BaseActionRequestBuilder"; - } - - /// - /// Get the name of the current template being processed - /// - /// The full path of the current template - /// The template name, relative to the Templates directory. - public string TemplateName(string templateFile) { - return templateFile.Substring(templateFile.LastIndexOf("Templates")); - } - - public string TypeName(OdcmObject c) { - if (c is OdcmMethod) { - return ((OdcmMethod)c).Class.Name.ToUpperFirstChar() + c.Name.Substring(c.Name.IndexOf(".") + 1).ToUpperFirstChar(); - } else if (c is OdcmProperty && c.AsOdcmProperty().IsCollection) { - return c.AsOdcmProperty().Projection.Type.Name.ToUpperFirstChar(); - } else if (c is OdcmProperty && c.AsOdcmProperty().Projection.Type is OdcmPrimitiveType) { - return ClassTypeName(c) + c.AsOdcmProperty().Projection.Type.Name.ToUpperFirstChar(); - } else if (c is OdcmProperty) { - return c.AsOdcmProperty().Projection.Type.Name.ToUpperFirstChar(); - } - return c.Name.ToUpperFirstChar(); - } - - public string MethodName(OdcmObject c) { - return c.Name.Substring(c.Name.IndexOf(".") + 1).ToUpperFirstChar(); - } - - public string MethodFullName(OdcmObject c) { - if (c is OdcmMethod){ - return String.Format("{0}.{1}", ((OdcmMethod)c).Class.Namespace.Name, - c.Name.Substring(c.Name.IndexOf(".") + 1)); - } - return c.Name.Substring(c.Name.IndexOf(".") + 1).ToUpperFirstChar(); - } - - public string ITypeName(OdcmObject c) { - return "I" + TypeName(c); - } - - public string BaseTypeName(OdcmObject c) { - return "Base" + TypeName(c); - } - - public string IBaseTypeName(OdcmObject c) { - return "I" + BaseTypeName(c); - } - - public string TypeStreamRequest(OdcmObject c) { - if (TypeName(c).EndsWith("stream", StringComparison.InvariantCultureIgnoreCase)){ - return TypeName(c) + "Request"; - } - return TypeName(c) + "StreamRequest"; - } - - public string ITypeStreamRequest(OdcmObject c) { - return "I" + TypeStreamRequest(c); - } - - public string BaseTypeStreamRequest(OdcmObject c) { - return "Base" + TypeStreamRequest(c); - } - - public string IBaseTypeStreamRequest(OdcmObject c) { - return "I" + BaseTypeStreamRequest(c); - } - - public string TypeStreamRequestBuilder(OdcmObject c) { - return TypeStreamRequest(c) + "Builder"; - } - - public string ITypeStreamRequestBuilder(OdcmObject c) { - return "I" + TypeStreamRequestBuilder(c); - } - - public string BaseTypeStreamRequestBuilder(OdcmObject c) { - return "Base" + TypeStreamRequestBuilder(c); - } - - public string IBaseTypeStreamRequestBuilder(OdcmObject c) { - return "I" + BaseTypeStreamRequestBuilder(c); - } - - public string TypeRequest(OdcmObject c) { - if(c is OdcmProperty && c.AsOdcmProperty().IsReference()){ - return TypeWithReferencesRequest(c); - }else{ - return TypeName(c) + "Request"; - } - } - - public string BaseTypeRequest(OdcmObject c) { - return "Base" + TypeRequest(c); - } - - public string ITypeRequest(OdcmObject c) { - return "I" + TypeRequest(c); - } - - public string IBaseTypeRequest(OdcmObject c) { - return "I" + BaseTypeRequest(c); - } - - public string TypeRequestBuilder(OdcmObject c) { - return TypeRequest(c) + "Builder"; - } - - public string ITypeRequestBuilder(OdcmObject c) { - return "I" + TypeRequestBuilder(c); - } - - public string BaseTypeRequestBuilder(OdcmObject c) { - return "Base" + TypeRequestBuilder(c); - } - - public string IBaseTypeRequestBuilder(OdcmObject c) { - return "I" + BaseTypeRequestBuilder(c); - } - - public string TypeWithReferencesRequest(OdcmObject c) { - return TypeName(c) + "WithReferenceRequest"; - } - - public string BaseTypeWithReferencesRequest(OdcmObject c) { - return "Base" + TypeWithReferencesRequest(c); - } - - public string ITypeWithReferencesRequest(OdcmObject c) { - return "I" + TypeWithReferencesRequest(c); - } - - public string IBaseTypeWithReferencesRequest(OdcmObject c) { - return "I" + BaseTypeWithReferencesRequest(c); - } - - public string TypeWithReferencesRequestBuilder(OdcmObject c) { - return TypeWithReferencesRequest(c) + "Builder"; - } - - public string ITypeWithReferencesRequestBuilder(OdcmObject c) { - return "I" + TypeWithReferencesRequestBuilder(c); - } - - public string BaseTypeWithReferencesRequestBuilder(OdcmObject c) { - return "Base" + TypeWithReferencesRequestBuilder(c); - } - - public string IBaseTypeWithReferencesRequestBuilder(OdcmObject c) { - return "I" + BaseTypeWithReferencesRequestBuilder(c); - } - - public string TypeReferenceRequest(OdcmObject c) { - return TypeName(c) + "ReferenceRequest"; - } - - public string BaseTypeReferenceRequest(OdcmObject c) { - return "Base" + TypeReferenceRequest(c); - } - - public string ITypeReferenceRequest(OdcmObject c) { - return "I" + TypeReferenceRequest(c); - } - - public string IBaseTypeReferenceRequest(OdcmObject c) { - return "I" + BaseTypeReferenceRequest(c); - } - - public string TypeReferenceRequestBuilder(OdcmObject c) { - return TypeReferenceRequest(c) + "Builder"; - } - - public string ITypeReferenceRequestBuilder(OdcmObject c) { - return "I" + TypeReferenceRequestBuilder(c); - } - - public string BaseTypeReferenceRequestBuilder(OdcmObject c) { - return "Base" + TypeReferenceRequestBuilder(c); - } - - public string IBaseTypeReferenceRequestBuilder(OdcmObject c) { - return "I" + BaseTypeReferenceRequestBuilder(c); - } - - public string TypeCollectionPage(OdcmObject c) { - return TypeName(c) + "CollectionPage"; - } - - public string ITypeCollectionPage(OdcmObject c) { - return "I" + TypeCollectionPage(c); - } - - public string TypeCollectionWithReferencesPage(OdcmObject c) { - return TypeName(c) + "CollectionWithReferencesPage"; - } - - public string ITypeCollectionWithReferencesPage(OdcmObject c) { - return "I" + TypeCollectionWithReferencesPage(c); - } - - public string BaseTypeCollectionPage(OdcmObject c) { - return "Base" + TypeCollectionPage(c); - } - - public string IBaseTypeCollectionPage(OdcmObject c) { - return "I" + BaseTypeCollectionPage(c); - } - - public string BaseTypeCollectionWithReferencesPage(OdcmObject c) { - return "Base" + TypeCollectionWithReferencesPage(c); - } - - public string IBaseTypeCollectionWithReferencesPage(OdcmObject c) { - return "I" + BaseTypeCollectionWithReferencesPage(c); - } - - public string BaseTypeCollectionResponse(OdcmObject c) { - return "Base" + TypeName(c) + "CollectionResponse"; - } - - public string TypeCollectionRequest(OdcmObject c) { - if(c is OdcmProperty && c.AsOdcmProperty().IsReference()){ - return TypeCollectionWithReferencesRequest(c); - }else{ - return TypeName(c) + "CollectionRequest"; - } - } - - public string ITypeCollectionRequest(OdcmObject c) { - return "I" + TypeCollectionRequest(c); - } - - public string BaseTypeCollectionRequest(OdcmObject c) { - return "Base" + TypeCollectionRequest(c); - } - - public string IBaseTypeCollectionRequest(OdcmObject c) { - return "I" + BaseTypeCollectionRequest(c); - } - - public string TypeCollectionRequestBuilder(OdcmObject c) { - return TypeCollectionRequest(c) + "Builder"; - } - - public string ITypeCollectionRequestBuilder(OdcmObject c) { - return "I" + TypeCollectionRequestBuilder(c); - } - - public string BaseTypeCollectionRequestBuilder(OdcmObject c) { - return "Base" + TypeCollectionRequestBuilder(c); - } - - public string IBaseTypeCollectionRequestBuilder(OdcmObject c) { - return "I" + BaseTypeCollectionRequestBuilder(c); - } - - public string TypeCollectionWithReferencesRequest(OdcmObject c) { - return TypeName(c) + "CollectionWithReferencesRequest"; - } - - public string ITypeCollectionWithReferencesRequest(OdcmObject c) { - return "I" + TypeCollectionWithReferencesRequest(c); - } - - public string BaseTypeCollectionWithReferencesRequest(OdcmObject c) { - return "Base" + TypeCollectionWithReferencesRequest(c); - } - - public string IBaseTypeCollectionWithReferencesRequest(OdcmObject c) { - return "I" + BaseTypeCollectionWithReferencesRequest(c); - } - - public string TypeCollectionWithReferencesRequestBuilder(OdcmObject c) { - return TypeCollectionWithReferencesRequest(c) + "Builder"; - } - - public string ITypeCollectionWithReferencesRequestBuilder(OdcmObject c) { - return "I" + TypeCollectionWithReferencesRequestBuilder(c); - } - - public string BaseTypeCollectionWithReferencesRequestBuilder(OdcmObject c) { - return "Base" + TypeCollectionWithReferencesRequestBuilder(c); - } - - public string IBaseTypeCollectionWithReferencesRequestBuilder(OdcmObject c) { - return "I" + BaseTypeCollectionWithReferencesRequestBuilder(c); - } - - public string TypeCollectionReferenceRequest(OdcmObject c) { - return TypeName(c) + "CollectionReferenceRequest"; - } - - public string ITypeCollectionReferenceRequest(OdcmObject c) { - return "I" + TypeCollectionReferenceRequest(c); - } - - public string BaseTypeCollectionReferenceRequest(OdcmObject c) { - return "Base" + TypeCollectionReferenceRequest(c); - } - - public string IBaseTypeCollectionReferenceRequest(OdcmObject c) { - return "I" + BaseTypeCollectionReferenceRequest(c); - } - - public string TypeCollectionReferenceRequestBuilder(OdcmObject c) { - return TypeCollectionReferenceRequest(c) + "Builder"; - } - - public string ITypeCollectionReferenceRequestBuilder(OdcmObject c) { - return "I" + TypeCollectionReferenceRequestBuilder(c); - } - - public string BaseTypeCollectionReferenceRequestBuilder(OdcmObject c) { - return "Base" + TypeCollectionReferenceRequestBuilder(c); - } - - public string IBaseTypeCollectionReferenceRequestBuilder(OdcmObject c) { - return "I" + BaseTypeCollectionReferenceRequestBuilder(c); - } - - public string TypeBody(OdcmObject c) { - return TypeName(c) + "Body"; - } - - public string BaseTypeBody(OdcmObject c) { - return "Base" + TypeBody(c); - } - - /// Creates an 'm' prepended name for a field - /// based on its name as defined by the service $metadata - public string FieldName(OdcmParameter c) { - return "m" + ParamName(c).ToUpperFirstChar(); - } - - /// Returns the name of the service with the first char lowercase - public string ParamName(OdcmParameter c) { - return c.Name.ToLowerFirstChar(); - } - - /// The Type of this param, as a string - public string ParamType(OdcmParameter c) { - var typeString = c.Type.GetTypeString(); - if (c.IsCollection){ - typeString = String.Format("java.util.List<{0}>", c.Type.GetTypeString()); - } else if (typeString.Equals("Stream")) { - - // Excel introduced the use of "Edm.Stream" types - // normally this would be addressed at the TypeHelper level - // but because streams will use different data containers - // for outgoing vs. incoming streams I'm going to apply the type - // here. Outbound Streams will use byte[] - - typeString = "byte[]"; - } - return typeString; - } - - public string ReturnType(OdcmObject c) { - var returnType = c.AsOdcmMethod().ReturnType; - if (returnType != null) { - var returnTypeString = returnType.GetTypeString(); - - // Excel introduced the use of "Edm.Stream" types - // normally this would be addressed at the TypeHelper level - // but because streams will use different data containers - // for outgoing vs. incoming streams I'm going to apply the type - // here. Inbound Streams will use java.io.InputStream - - if (returnTypeString.Equals("Stream")) { - returnTypeString = "java.io.InputStream"; - } - return returnTypeString; - } - return "Void"; - } - - public string MethodParametersSignature(OdcmMethod method) { - var parameterSignatureBuilder = new StringBuilder(); - foreach (var p in method.Parameters) - { - parameterSignatureBuilder.AppendFormat(", final {0} {1}", ParamType(p), ParamName(p)); - } - return parameterSignatureBuilder.ToString(); - } - - public string MethodParametersValues(OdcmMethod method) { - var parameterValuesBuilder = new StringBuilder(); - foreach (var p in method.Parameters) - { - parameterValuesBuilder.AppendFormat(", {0}", ParamName(p)); - } - return parameterValuesBuilder.ToString(); - } - - public string MethodFieldValues(OdcmObject c) { - var parameterValuesBuilder = new StringBuilder(); - foreach (var p in c.AsOdcmMethod().Parameters) - { - parameterValuesBuilder.AppendFormat(", {0}", FieldName(p)); - } - return parameterValuesBuilder.ToString(); - } - - public string MethodPageValues(OdcmObject c) { - var pageValuesBuilder = new StringBuilder(); - foreach (var param in c.AsOdcmMethod().Parameters) - { - var paramName = param.Name.ToLowerFirstChar(); - pageValuesBuilder.AppendFormat(", /* {0} */ null", paramName); - } - return pageValuesBuilder.ToString(); - } - - public string ClassTypeName(OdcmObject c) { - if (c is OdcmMethod) { - return c.AsOdcmMethod().Class.Name.ToUpperFirstChar(); - } else if (c is OdcmProperty && c.AsOdcmProperty().Class is OdcmServiceClass) { - return c.AsOdcmProperty().Projection.Type.Name.ToUpperFirstChar(); - } else if (c is OdcmProperty) { - return c.AsOdcmProperty().Class.Name.ToUpperFirstChar(); - } - return c.Name.ToUpperFirstChar(); - } - - public string ClientType(OdcmObject c) { - return ((CustomT4Host)Host).CurrentModel.EntityContainer.Name.ToUpperFirstChar() + "Client"; - } - - public string IClientType(OdcmObject c) { - return "I" + ClientType(c); - } - - public string BaseClientType(OdcmObject c) { - return "Base" + ClientType(c); - } - - public string IBaseClientType(OdcmObject c) { - return "I" + BaseClientType(c); - } - - public string IBaseClientType() { - return "IBaseClient"; - } - - public string BaseClassName(OdcmObject o){ - var baseClass = BaseClass(o); - if (baseClass != null) { - return TypeName(baseClass); - } - return String.Empty; - } - - public OdcmClass BaseClass(OdcmObject o){ - var odcmClass = o.AsOdcmClass(); - if (odcmClass != null) { - return odcmClass.Base; - } - return null; - } - - public string OdcmMethodReturnType(OdcmMethod method) { - return method.ReturnType is OdcmPrimitiveType - ? method.ReturnType.GetTypeString() : method.ReturnType.Name.ToCheckedCase(); - } - - public string CollectionPageGeneric(OdcmObject c) { - if (c is OdcmMethod) { - string returnType = OdcmMethodReturnType(c as OdcmMethod); - return "<" + returnType + ", " + ITypeCollectionRequestBuilder(c) + ">"; - } - return "<" + TypeName(c) + ", " + ITypeCollectionRequestBuilder(c) + ">"; - } - - public string CollectionPageWithReferencesGeneric(OdcmObject c) { - if (c is OdcmMethod) { - return "<" + ClassTypeName(c) + ", " + ITypeWithReferencesRequestBuilder(c) + ">"; - } - return "<" + TypeName(c) + ", " + ITypeCollectionWithReferencesRequestBuilder(c) + ">"; - } - - public string CollectionRequestGeneric(OdcmObject c) { - if (c is OdcmMethod) { - return "<" + BaseTypeCollectionResponse(c) + ", " + ITypeCollectionPage(c) + ">"; - } - return "<" + BaseTypeCollectionResponse(c) + ", " + ITypeCollectionPage(c) + ">"; - } - - public string CreatePackageDef(CustomT4Host host) - { - var format = @"package {0}.{1}; - -import {0}.concurrency.*; -import {0}.core.*; -import {0}.extensions.*; -import {0}.http.*; -import {0}.generated.*; -import {0}.options.*; -import {0}.serializer.*; - -import java.util.Arrays; -import java.util.EnumSet;"; - return string.Format(format, - host.CurrentModel.NamespaceName(), - host.TemplateInfo.OutputParentDirectory); - } - - /// Creates a class declaration - /// name = the name of the class - /// extends = the class it extends - /// implements = the interface it extends - public string CreateClassDef(string name, string extends = null, string implements = null) - { - return this.CreateClassOrInterface(name, true, extends, implements); - } - - public string CreateInterfaceDef(string name, string extends = null) - { - return this.CreateClassOrInterface(name, false, extends, null); - } - - public string CreateClassOrInterface(string name, bool isClass = true, string extends = null, string implements = null) - { - var extendsStr = string.Empty; - if (!string.IsNullOrEmpty(extends)) - { - extendsStr = string.Format(" extends {0}", extends); - } - - var implementsStr = string.Empty; - if (!string.IsNullOrEmpty(implements)) - { - implementsStr = string.Format(" implements {0}", implements); - } - - var format = @" - -/** - * The {1} for the {0}. - */ -public {1} {2}{3}{4} {{"; - string declaration = string.Format(format, - isClass ? name.SplitCamelCase() : name.SplitCamelCase().Remove(0, 1), - isClass ? "class" : "interface", - name, - extendsStr, - implementsStr); - - if (name.StartsWith("Base") || name.StartsWith("IBase")) - { - return CreatAutogeneratedWarning() + declaration; - } - - return CreateExtensiblityMessage() + declaration; - } - - public string GenericRequest(OdcmObject c){ - var extends = "{0}<{1}>"; - var @class = c.AsOdcmClass(); - if (@class != null && @class.Base != null){ - var b = @class.Base; - return String.Format(extends, ITypeRequest(b), TypeName(c)); - } - return String.Empty; - } - - public string GenericTypeConstraint(OdcmObject c){ - return ""; - } - - public string GenericTypeNameConstraint(String constraint, String extends){ - return String.Format("<{0} extends {1}>", constraint, extends); - } - - public string GenericBaseType(String extends, String constraint){ - return String.Format("{0}<{1}>", extends, constraint); - } - - public string GenericTypeCollectionPageConstraint(OdcmObject c){ - var @class = c.AsOdcmClass(); - if (@class != null && @class.Derived.Any()){ - return ""; - } - return String.Empty; - } - - public string GenericClassConstraint(String s){ - return String.Format("", s); - } - - public string GenericType(){ - return ""; - } - - public string GenericTypeWithType(String s){ - return String.Format("<{0}>", s); - } - - public string CreatePropertyDef(IEnumerable properties, bool isComplexType = false) - { - var sb = new StringBuilder(); - - var format = -@" /** - * The {0}. - * {4} - */ - @SerializedName(""{1}"") - @Expose - public {2} {3}; - -"; - var collectionFormat = -@" /** - * The {0}. - * {4} - */ - public transient {2} {3}; - -"; - - foreach (var property in properties.Where(p => !p.Projection.Type.Name.Equals("Stream"))) - { - var propertyName = property.Name.ToUpperFirstChar(); - var propertyType = ""; - var propertyFormat = format; - if (property.IsCollection) - { - if (!property.IsNavigation()) - { - propertyType = "java.util.List<" + property.GetTypeString() + ">"; - } - else - { - propertyType = TypeCollectionPage(property); - propertyFormat = collectionFormat; - } - } - else - { - propertyType = property.GetTypeString(); - } - - sb.AppendFormat(propertyFormat, - propertyName.SplitCamelCase(), - property.Name, - propertyType, - property.Name.SanitizePropertyName(property).ToLowerFirstChar(), - property.LongDescription); - } - return sb.ToString(); - } - - public string CreateParameterDef(IEnumerable parameters) - { - var sb = new StringBuilder(); - - var format = -@" /** - * The {0}. - * {1} - */ - @SerializedName(""{2}"") - @Expose - public {3} {4}; - -"; - foreach (var p in parameters) - { - sb.AppendFormat( - format, - ParamName(p).SplitCamelCase(), - p.LongDescription, - ParamName(p), - ParamType(p), - ParamName(p).SanitizePropertyName(p).ToLowerFirstChar() - ); - } - return sb.ToString(); - } - - public string CreateRawJsonObject() { - return -@" /** - * The raw representation of this class - */ - private transient JsonObject mRawObject; - - /** - * The serializer - */ - private transient ISerializer mSerializer; - - /** - * Gets the raw representation of this class - * @return the raw representation of this class - */ - public JsonObject getRawObject() { - return mRawObject; - } - - /** - * Gets serializer - * @return the serializer - */ - protected ISerializer getSerializer() { - return mSerializer; - } - - /** - * Sets the raw json object - * - * @param serializer The serializer - * @param json The json object to set this object to - */ - public void setRawObject(final ISerializer serializer, final JsonObject json) { - mSerializer = serializer; - mRawObject = json; -"; - } - - public string UpdatePropertiesWithinSetRawObject(IEnumerable properties = null, bool isComplexType = false) - { - var sb = new StringBuilder(); - if (!isComplexType && properties != null) - { - foreach (var property in properties.Where(p => p.IsCollection() && p.IsNavigation())) { - sb.AppendFormat( -@" - if (json.has(""{0}"")) {{ - final {1} response = new {1}(); - if (json.has(""{0}@odata.nextLink"")) {{ - response.nextLink = json.get(""{0}@odata.nextLink"").getAsString(); - }} - - final JsonObject[] sourceArray = serializer.deserializeObject(json.get(""{0}"").toString(), JsonObject[].class); - final {3}[] array = new {3}[sourceArray.length]; - for (int i = 0; i < sourceArray.length; i++) {{ - array[i] = serializer.deserializeObject(sourceArray[i].toString(), {3}.class); - array[i].setRawObject(serializer, sourceArray[i]); - }} - response.value = Arrays.asList(array); - {0} = new {2}(response, null); - }} -", - property.Name.SanitizePropertyName(property), - BaseTypeCollectionResponse(property), - TypeCollectionPage(property), - property.GetTypeString()); - } - } - sb.Append(" }"); - return sb.ToString(); - } - - public string UpdateListPropertiesWithinSetRawObject(IEnumerable listProperties) - { - var sb = new StringBuilder(); - foreach (var property in listProperties) - { - sb.AppendFormat( -@" - if (json.has(""{0}"")) {{ - final JsonArray array = json.getAsJsonArray(""{0}""); - for (int i = 0; i < array.size(); i++) {{ - {0}.get(i).setRawObject(mSerializer, (JsonObject) array.get(i)); - }} - }} -", - property); - } - sb.Append(" }"); - return sb.ToString(); - } - - public string CreateExtensiblityMessage() { - return -@"// This file is available for extending, afterwards please submit a pull request."; - } - - public string CreatAutogeneratedWarning() { - return -@"// **NOTE** This file was generated by a tool and any changes will be overwritten."; - } - - /* - * Add additional methods to a generated class - * @param className The class that you will be adding methods to - * @return The additional text to add to the generated file - */ - public string AddCustomCode(string className) { - CustomMethods customMethods = new CustomMethods(); - var type = customMethods.GetType(); - var property = type.GetFields().Where(x => x.Name == className).FirstOrDefault(); - - if (property != null) { - return "\r\n\r\n" + property.GetValue(customMethods).ToString(); - } else { - return string.Empty; - } - } - - /* - * Add additional import statements to a generated class - * @param className The class that you will be adding methods to - * @return The additional text to add to the generated file - */ - public string AddCustomImport(string className) { - CustomImports customImports = new CustomImports(); - var type = customImports.GetType(); - var property = type.GetFields().Where(x => x.Name == className).FirstOrDefault(); - - return property != null ? property.GetValue(customImports).ToString() : string.Empty; - } - - /* - * Find and replace overwrite values for the given class - * @param className The class that you will be applying overwrites to - * @return An empty string (does not write anything new to the file) - */ - public string PostProcess(string className) - { - //Load the StringBuilder with the file contents - var strb = this.GenerationEnvironment; - - //Get the list of available classes to overwrite - CustomOverwrites customOverwrites = new CustomOverwrites(); - var type = customOverwrites.GetType(); - - //Load the dictionary that corresponds to the current class - var results = type.GetFields().Where(x => x.Name == className).FirstOrDefault(); - - if (results != null) { - var dictionary = (Dictionary)results.GetValue(this); - //Find and replace for each item in the dictionary - foreach (var item in dictionary) { - strb.Replace(item.Key, item.Value); - } - } - //This seems to be a requirement of the template builder - //Specifying a return type of "void" throws an error - return string.Empty; - } -#> diff --git a/Templates/Android/extensions/ChunkedUploadRequest.java.tt b/Templates/Android/extensions/ChunkedUploadRequest.java.tt deleted file mode 100644 index d6a87edbf..000000000 --- a/Templates/Android/extensions/ChunkedUploadRequest.java.tt +++ /dev/null @@ -1,130 +0,0 @@ -<# // Copyright (c) Microsoft Corporation. All Rights Reserved. Licensed under the MIT License. See License in the project root for license information. #> -<#@ template debug="true" hostspecific="true" language="C#" #> -<#@ include file="BaseModel.template.tt"#> -<#@ output extension="\\" #> -<#=writer.WriteHeader()#> -package com.microsoft.graph.extensions; - -import com.microsoft.graph.concurrency.ChunkedUploadResponseHandler; -import com.microsoft.graph.core.ClientException; -import com.microsoft.graph.core.GraphErrorCodes; -import com.microsoft.graph.http.BaseRequest; -import com.microsoft.graph.http.HttpMethod; -import com.microsoft.graph.options.Option; - -import java.util.List; - -/** - * The chunk upload request. - */ -public class ChunkedUploadRequest { - - /** - * Content Range header name. - */ - private static final String CONTENT_RANGE_HEADER_NAME = "Content-Range"; - - /** - * Content Range value format. - */ - private static final String CONTENT_RANGE_FORMAT = "bytes %1$d-%2$d/%3$d"; - - /** - * The seconds for retry delay. - */ - private static final int RETRY_DELAY = 2 * 1000; - - /** - * The chunk data sent to the server. - */ - private final byte[] mData; - - /** - * The base request. - */ - private final BaseRequest mBaseRequest; - - /** - * The max retry for single request. - */ - private final int mMaxRetry; - - /** - * The retry counter. - */ - private int mRetryCount; - - /** - * Construct the ChunkedUploadRequest - * - * @param requestUrl The upload url. - * @param client The OneDrive client. - * @param options The query options. - * @param chunk The chunk byte array. - * @param chunkSize The chunk array size. - * @param maxRetry The limit on retry. - * @param beginIndex The begin index of this chunk in the input stream. - * @param totalLength The total length of the input stream. - */ - public ChunkedUploadRequest(final String requestUrl, - final IGraphServiceClient client, - final List