From b517f65e1f966cbe247854479dbdfac4c8300045 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=B6tz=20Jensen?= Date: Sun, 3 Mar 2024 12:05:20 +0100 Subject: [PATCH 1/5] Fix: Trying to get auto version to work --- .github/workflows/build.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index c0418fb..012bfe7 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -18,7 +18,7 @@ jobs: run: .\build\vsts-validate.ps1 shell: powershell - name: Build - run: .\build\vsts-build.ps1 -ApiKey $env:APIKEY + run: .\build\vsts-build.ps1 -ApiKey $env:APIKEY -AutoVersion shell: powershell env: APIKEY: ${{ secrets.ApiKey }} From 8c70f990bbef4f31e57c674ee06548fe008e1577 Mon Sep 17 00:00:00 2001 From: Florian Hopfner <33372796+FH-Inway@users.noreply.github.com> Date: Sun, 3 Mar 2024 12:13:26 +0000 Subject: [PATCH 2/5] Add devcontainer.json file for learning the d365bap.tools module --- .devcontainer/devcontainer.json | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 .devcontainer/devcontainer.json diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..6438273 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,20 @@ +{ + "image": "mcr.microsoft.com/powershell:latest", + "features": { + "ghcr.io/devcontainers/features/git:1": {}, + "ghcr.io/natescherer/devcontainers-custom-features/powershell-resources": { + "resources": "d365bap.tools" + }, + "ghcr.io/devcontainers/features/dotnet:2": { + "version": "8.0" + } + }, + "customizations": { + "vscode": { + "extensions": [ + "ms-vscode.powershell", + "ms-dotnettools.dotnet-interactive-vscode" + ] + } + } +} \ No newline at end of file From ffb1f8b4760e27e1925e618b7a2186df349f0fff Mon Sep 17 00:00:00 2001 From: Florian Hopfner <33372796+FH-Inway@users.noreply.github.com> Date: Sun, 3 Mar 2024 12:13:51 +0000 Subject: [PATCH 3/5] add get started notebook --- learning/notebooks/get-started.ipynb | 475 +++++++++++++++++++++++++++ 1 file changed, 475 insertions(+) create mode 100644 learning/notebooks/get-started.ipynb diff --git a/learning/notebooks/get-started.ipynb b/learning/notebooks/get-started.ipynb new file mode 100644 index 0000000..f8a9203 --- /dev/null +++ b/learning/notebooks/get-started.ipynb @@ -0,0 +1,475 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Get started\n", + "\n", + "This notebook will help you get started with d365bap.tools.\n", + "\n", + "In case you have not done so already, please install the module with the following command:" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": { + "dotnet_interactive": { + "language": "pwsh" + }, + "polyglot_notebook": { + "kernelName": "pwsh" + }, + "vscode": { + "languageId": "polyglot-notebook" + } + }, + "outputs": [], + "source": [ + "Install-Module -Name d365bap.tools" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "If you do not have administrator privileges, you can install it for just your user instead." + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "metadata": { + "dotnet_interactive": { + "language": "pwsh" + }, + "polyglot_notebook": { + "kernelName": "pwsh" + }, + "vscode": { + "languageId": "polyglot-notebook" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "\u001b[95mUntrusted repository\u001b[0m\n", + "You are installing the modules from an untrusted repository. If you trust this repository, change its InstallationPolicy value by running the Set-PSRepository cmdlet. Are you sure you want to install the modules from 'PSGallery'?\n", + "[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help(default is 'N')\u001b[93mWARNING: Version '0.0.10' of module 'd365bap.tools' is already installed at '/usr/local/share/powershell/Modules/d365bap.tools/0.0.10'. To install version '0.0.11', run Install-Module and add the -Force parameter, this command will install version '0.0.11' side-by-side with version '0.0.10'.\u001b[0m\n" + ] + } + ], + "source": [ + "Install-Module -Name d365bap.tools -Scope CurrentUser" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Authenticating Azure account\n", + "\n", + "To use the cmdlets of the module, you first need to authenticate your Azure account." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": { + "dotnet_interactive": { + "language": "pwsh" + }, + "polyglot_notebook": { + "kernelName": "pwsh" + }, + "vscode": { + "languageId": "polyglot-notebook" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\u001b[93mWARNING: Interactive authentication is not supported in this session, please run cmdlet 'Connect-AzAccount -UseDeviceAuthentication'.\u001b[0m\n" + ] + } + ], + "source": [ + "Connect-AzAccount" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Depending on where you run this notebook, you may have to use a different authentication method, e.g. device authentication." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": { + "dotnet_interactive": { + "language": "pwsh" + }, + "polyglot_notebook": { + "kernelName": "pwsh" + }, + "vscode": { + "languageId": "polyglot-notebook" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\u001b[93mWARNING: To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code ABC456789 to authenticate.\u001b[0m\n", + "\u001b[93mWARNING: TenantId 'abcdefgh-1234-5678-90ab-cdefghijklmn' contains more than one active subscription. First one will be selected for further use. To select another subscription, use Set-AzContext. \n", + "To override which subscription Connect-AzAccount selects by default, use `Update-AzConfig -DefaultSubscriptionForLogin 00000000-0000-0000-0000-000000000000`. Go to https://go.microsoft.com/fwlink/?linkid=2200610 for more information.\u001b[0m\n", + "\u001b[93mWARNING: Unable to acquire token for tenant '12345678-abcd-efgh-ijkl-mnopqrstuvwx' with error 'You must use multi-factor authentication to access tenant 12345678-abcd-efgh-ijkl-mnopqrstuvwx, please rerun 'Connect-AzAccount' with additional parameter '-TenantId 12345678-abcd-efgh-ijkl-mnopqrstuvwx'.'\u001b[0m\n", + "\n", + "\u001b[32;1;3mAccount \u001b[0m \u001b[32;1;3mSubscriptionName \u001b[0m \u001b[32;1;3mTenantId \u001b[0m \u001b[32;1;3mEnvi\u001b[0m\n", + "\u001b[32;1;3m \u001b[0m \u001b[32;1;3m \u001b[0m \u001b[32;1;3m \u001b[0m \u001b[32;1;3mronm\u001b[0m\n", + "\u001b[32;1;3m \u001b[0m \u001b[32;1;3m \u001b[0m \u001b[32;1;3m \u001b[0m \u001b[32;1;3ment\u001b[0m\n", + "\u001b[32;1m------- \u001b[0m \u001b[32;1m---------------- \u001b[0m \u001b[32;1m-------- \u001b[0m \u001b[32;1m----\u001b[0m\n", + "me@mycompany.com MySubscriptionName abcdefgh-1234-5678-90ab-cdefghijklmn Azu…\n", + "\n" + ] + } + ], + "source": [ + "Connect-AzAccount -UseDeviceAuthentication" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In case you have access to multiple tenants or subscriptions, the first one will be used. To authenticate with another, use the `-TenantId` and `-SubscriptionId` parameters." + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": { + "dotnet_interactive": { + "language": "pwsh" + }, + "polyglot_notebook": { + "kernelName": "pwsh" + }, + "vscode": { + "languageId": "polyglot-notebook" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\u001b[93mWARNING: To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code ABC456789 to authenticate.\u001b[0m\n", + "\n", + "\u001b[32;1;3mAccount \u001b[0m \u001b[32;1;3mSubscriptionName \u001b[0m \u001b[32;1;3mTenantId \u001b[0m \u001b[32;1;3mEnvi\u001b[0m\n", + "\u001b[32;1;3m \u001b[0m \u001b[32;1;3m \u001b[0m \u001b[32;1;3m \u001b[0m \u001b[32;1;3mronm\u001b[0m\n", + "\u001b[32;1;3m \u001b[0m \u001b[32;1;3m \u001b[0m \u001b[32;1;3m \u001b[0m \u001b[32;1;3ment\u001b[0m\n", + "\u001b[32;1m------- \u001b[0m \u001b[32;1m---------------- \u001b[0m \u001b[32;1m-------- \u001b[0m \u001b[32;1m----\u001b[0m\n", + "me@mycompany.com MySubscriptionName abcdefgh-1234-5678-90ab-cdefghijklmn Azu…\n", + "\n" + ] + } + ], + "source": [ + "$MyTenantId = Read-Host -Prompt \"Enter tenant id\"\n", + "$MySubscriptionId = Read-Host -Prompt \"Enter subscription id\"\n", + "Connect-AzAccount -UseDeviceAuthentication -Tenant $MyTenantId -Subscription $MySubscriptionId" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Running the first commands\n", + "\n", + "Now that you are authenticated, you can start using the d365bap.tools cmdlets.\n", + "\n", + "Let's start with an easy one that gives you an overview of the Dataverse environments you have access to." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": { + "dotnet_interactive": { + "language": "pwsh" + }, + "polyglot_notebook": { + "kernelName": "pwsh" + }, + "vscode": { + "languageId": "polyglot-notebook" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "\u001b[32;1mPpacEnvId \u001b[0m\u001b[32;1m PpacEnvRegion \u001b[0m\u001b[32;1m PpacEnvName \u001b[0m\u001b[32;1m PpacEnvSku\u001b[0m\u001b[32;1m LinkedAppLcsEn\u001b[0m\n", + "\u001b[32;1m \u001b[0m\u001b[32;1m \u001b[0m\u001b[32;1m \u001b[0m\u001b[32;1m \u001b[0m\u001b[32;1m vUri\u001b[0m\n", + "\u001b[32;1m--------- \u001b[0m \u001b[32;1m------------- \u001b[0m \u001b[32;1m----------- \u001b[0m \u001b[32;1m----------\u001b[0m \u001b[32;1m--------------\u001b[0m\n", + "11111111-2222-3333-4444-555555555555 canada DEV_Privat_Preview_… Sandbox https://devpr…\n", + "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee europe D365CE-Demo02 Sandbox \n", + "\n" + ] + } + ], + "source": [ + "Get-BapEnvironment" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To learn more about a cmdlet, use the `Get-Help` cmdlet that is part of the core PowerShell functionality." + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": { + "dotnet_interactive": { + "language": "pwsh" + }, + "polyglot_notebook": { + "kernelName": "pwsh" + }, + "vscode": { + "languageId": "polyglot-notebook" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "NAME\n", + " Get-BapEnvironment\n", + " \n", + "SYNOPSIS\n", + " Get environment info\n", + " \n", + " \n", + "SYNTAX\n", + " Get-BapEnvironment [[-EnvironmentId] ] [-AsExcelOutput] []\n", + " \n", + " \n", + "DESCRIPTION\n", + " This enables the user to query and validate all environments that are available from inside \n", + " PPAC\n", + " \n", + " It utilizes the \"https://api.bap.microsoft.com\" REST API\n", + " \n", + "\n", + "RELATED LINKS\n", + "\n", + "REMARKS\n", + " To see the examples, type: \"Get-Help Get-BapEnvironment -Examples\"\n", + " For more information, type: \"Get-Help Get-BapEnvironment -Detailed\"\n", + " For technical information, type: \"Get-Help Get-BapEnvironment -Full\"\n", + "\n", + "\n" + ] + } + ], + "source": [ + "Get-Help Get-BapEnvironment" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "As the `REMARKS` section at the end says, you can add some switches to the `Get-Help` cmdlet to get additional information. One of the most useful is the `-Examples` switch that shows you how the cmdlet can be used for different scenarios." + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "metadata": { + "dotnet_interactive": { + "language": "pwsh" + }, + "polyglot_notebook": { + "kernelName": "pwsh" + }, + "vscode": { + "languageId": "polyglot-notebook" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "NAME\n", + " Get-BapEnvironment\n", + " \n", + "SYNOPSIS\n", + " Get environment info\n", + " \n", + " \n", + " -------------------------- EXAMPLE 1 --------------------------\n", + " \n", + " PS C:\\>Get-BapEnvironment\n", + " \n", + " This will query for ALL available environments.\n", + " \n", + " Sample output:\n", + " PpacEnvId PpacEnvRegion PpacEnvName PpacEnvSku \n", + " LinkedAppLcsEnvUri\n", + " --------- ------------- ----------- ---------- \n", + " ------------------\n", + " 32c6b196-ef52-4c43-93cf-6ecba51e6aa1 europe new-uat Sandbox \n", + " https://new-uat.sandbox.operatio…\n", + " eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 europe new-test Sandbox \n", + " https://new-test.sandbox.operati…\n", + " d45936a7-0408-4b79-94d1-19e4c6e5a52e europe new-golden Sandbox \n", + " https://new-golden.sandbox.opera…\n", + " Default-e210bc90-e54b-4544-a9b8-b1f… europe New Customer Default\n", + " \n", + " \n", + " \n", + " \n", + " -------------------------- EXAMPLE 2 --------------------------\n", + " \n", + " PS C:\\>Get-BapEnvironment -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6\n", + " \n", + " This will query for the specific environment.\n", + " \n", + " Sample output:\n", + " PpacEnvId PpacEnvRegion PpacEnvName PpacEnvSku \n", + " LinkedAppLcsEnvUri\n", + " --------- ------------- ----------- ---------- \n", + " ------------------\n", + " eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 europe new-test Sandbox \n", + " https://new-test.sandbox.operati…\n", + " \n", + " \n", + " \n", + " \n", + " -------------------------- EXAMPLE 3 --------------------------\n", + " \n", + " PS C:\\>Get-BapEnvironment -AsExcelOutput\n", + " \n", + " This will query for ALL available environments.\n", + " Will output all details into an Excel file, that will auto open on your machine.\n", + " \n", + " \n", + " \n", + " \n", + "\n", + "\n" + ] + } + ], + "source": [ + "Get-Help Get-BapEnvironment -Examples" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The third example of `Get-BapEnvironment` introduces you to the `-AsExcelOutput` switch. This lets you export the results of a cmdlet to an Excel file for further analysis. Many cmdlets of d365bap.tools support this switch.\n", + "\n", + "Note that depending on where you run this cmdlet, it might give you an error when it cannot find an installed Excel to open the file with. The error message will tell you the name of the .xlsx file created. You can use this information to download/copy the file to a location where Excel is available. Or you can use it to open the .xlsx file in another program that can work with Excel files." + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "metadata": { + "dotnet_interactive": { + "language": "pwsh" + }, + "polyglot_notebook": { + "kernelName": "pwsh" + }, + "vscode": { + "languageId": "polyglot-notebook" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\u001b[93mWARNING: Auto-fitting columns is not available with this OS configuration.\u001b[0m\n", + "\u001b[31;1mInvoke-Item: \u001b[0m/usr/local/share/powershell/Modules/ImportExcel/7.8.6/Public/Export-Excel.ps1:694\u001b[0m\n", + "\u001b[31;1m\u001b[0m\u001b[36;1mLine |\u001b[0m\n", + "\u001b[31;1m\u001b[0m\u001b[36;1m\u001b[36;1m 694 | \u001b[0m if ($Show) { \u001b[36;1mInvoke-Item $Path\u001b[0m }\u001b[0m\n", + "\u001b[31;1m\u001b[0m\u001b[36;1m\u001b[36;1m\u001b[0m\u001b[36;1m\u001b[0m\u001b[36;1m | \u001b[31;1m ~~~~~~~~~~~~~~~~~\u001b[0m\n", + "\u001b[31;1m\u001b[0m\u001b[36;1m\u001b[36;1m\u001b[0m\u001b[36;1m\u001b[0m\u001b[36;1m\u001b[31;1m\u001b[31;1m\u001b[36;1m | \u001b[31;1mAn error occurred trying to start process '/tmp/tmpwJFNYb.xlsx' with working directory\u001b[0m\n", + "\u001b[31;1m\u001b[0m\u001b[36;1m\u001b[36;1m\u001b[0m\u001b[36;1m\u001b[0m\u001b[36;1m\u001b[31;1m\u001b[31;1m\u001b[36;1m\u001b[31;1m\u001b[36;1m | \u001b[31;1m'/workspaces/d365bap.tools/learning/notebooks'. No such file or directory\u001b[0m\n" + ] + }, + { + "ename": "Error", + "evalue": "Command failed: SubmitCode: Get-BapEnvironment -AsExcelOutput", + "output_type": "error", + "traceback": [ + "Command failed: SubmitCode: Get-BapEnvironment -AsExcelOutput" + ] + } + ], + "source": [ + "Get-BapEnvironment -AsExcelOutput" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "For example, in this case, you could use the following command to open the `/tmp/tmpwJFNYb.xlsx` file in Visual Studio Code where the [Excel Viewer](https://marketplace.visualstudio.com/items?itemName=GrapeCity.gc-excelviewer) extension is installed.\n", + "\n", + "In your case, the file name will most likely be different. So be sure to change it to the file name of the error message before running this command." + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "metadata": { + "dotnet_interactive": { + "language": "pwsh" + }, + "polyglot_notebook": { + "kernelName": "pwsh" + }, + "vscode": { + "languageId": "polyglot-notebook" + } + }, + "outputs": [], + "source": [ + "code /tmp/tmpwJFNYb.xlsx" + ] + } + ], + "metadata": { + "language_info": { + "name": "csharp" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} From e650b1e9a9b33538d0da248031a09240b631f690 Mon Sep 17 00:00:00 2001 From: Florian Hopfner <33372796+FH-Inway@users.noreply.github.com> Date: Sun, 3 Mar 2024 12:36:57 +0000 Subject: [PATCH 4/5] Add documentation on how to get started with interactive notebook --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 949a0d4..d7d06eb 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,16 @@ Depending on which PowerShell console (v5 / v7+) - you will have different sign- Login-AzAccount -UseDeviceAuthentication -TenantId abd... ``` +## Learn interactively + +We have implemented a **Jupyter Notebook** to help you learn interactively about the different cmdlets / functions available in the module. The notebook is located inside the **'notebooks'** folder in this repository. Click this link [**notebooks**](/learning/notebooks/get-started.ipynb) to jump straight inside. + +While the notebook is already helpful in itself, its interactive nature will help you learn on another level. To do that, open the notebook in Visual Studio Code with the [Polyglot](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-interactive-vscode) extension installed. + +The repository also contains a [devcontainer](.devcontainer/devcontainer.json) that has everything installed to run the notebook. The easiest way to get started is to use GitHub Codespaces. Click the button below to start a new Codespace with the repository. + +[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.dev/d365collaborative/d365bap.tools) + ## Getting help [The wiki](https://github.com/d365collaborative/d365bap.tools/wiki) contains more details about installation and also guides to help you with some common tasks. It also contains documentation for all the module's commands. Expand the wiki's `Pages` control at the top of the content sidebar to view and search the list of command documentation pages. From 2f45f8dc4aea41dcd032fe2f998914553491866f Mon Sep 17 00:00:00 2001 From: Florian Hopfner <33372796+FH-Inway@users.noreply.github.com> Date: Sun, 3 Mar 2024 13:36:36 +0000 Subject: [PATCH 5/5] Update GitHub Codespaces link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d7d06eb..f1e1092 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ While the notebook is already helpful in itself, its interactive nature will hel The repository also contains a [devcontainer](.devcontainer/devcontainer.json) that has everything installed to run the notebook. The easiest way to get started is to use GitHub Codespaces. Click the button below to start a new Codespace with the repository. -[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.dev/d365collaborative/d365bap.tools) +[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/d365collaborative/d365bap.tools) ## Getting help