diff --git a/config/ModulesMapping.jsonc b/config/ModulesMapping.jsonc index a085e1628a4..6d2635e07cb 100644 --- a/config/ModulesMapping.jsonc +++ b/config/ModulesMapping.jsonc @@ -26,7 +26,7 @@ "Identity.Partner": "^tenantRelationships.delegatedAdminRelationship$|^tenantRelationships.delegatedAdminCustomer$", "Mail": "^users.inferenceClassification$|^users.mailFolder$|^users.message$", "ManagedTenants": "^tenantRelationships.managedTenant$", - "Migrations": "^solutions.migrations", + "Migrations": "^solutions.migrationsRoot", "NetworkAccess": "^networkAccess\\.", "Notes": "^users.onenote$|^groups.onenote$|^sites.onenote$", "People": "^users.person$|^users.profile$|^users.officeGraphInsights$|^users.userAnalytics$", diff --git a/src/Migrations/Migrations.md b/src/Migrations/Migrations.md new file mode 100644 index 00000000000..302a83883c7 --- /dev/null +++ b/src/Migrations/Migrations.md @@ -0,0 +1,41 @@ +# Migrations + +This directory contains common [AutoREST.PowerShell](https://github.com/Azure/autorest.powershell) configurations for Migrations v1.0 and/or beta modules. + +## AutoRest Configuration + +> see + +``` yaml +require: + - $(this-folder)/../readme.graph.md +``` + +### Directives + +> see https://github.com/Azure/autorest/blob/master/docs/powershell/directives.md + +``` yaml +# Directives go here! + +# Rename commands with 'SolutionMigrationCrossTenantMigrationJob' to 'CrossTenantMigrationJob' +directive: + - where: + subject: (^SolutionMigrationCrossTenantMigrationJob)(.*) + set: + subject: CrossTenantMigrationJob$2 +# Remove all the 'DisplayName','SolutionMigration', and 'Count' commands, they are redundant/unsupported + - where: + subject: (DisplayName$|SolutionMigration$|Count$) + remove: true +# Remove extra 'Remove' commands, only jobs can be removed + - where: + verb: Remove + subject: CrossTenantMigrationJob.+$ + remove: true +# Remove New/Update-CrossTenantMigrationJobUser, they are not supported operations + - where: + verb: (New|Update) + subject: CrossTenantMigrationJobUser$ + remove: true +``` diff --git a/src/Migrations/beta/.gitattributes b/src/Migrations/beta/.gitattributes new file mode 100644 index 00000000000..2125666142e --- /dev/null +++ b/src/Migrations/beta/.gitattributes @@ -0,0 +1 @@ +* text=auto \ No newline at end of file diff --git a/src/Migrations/beta/.gitignore b/src/Migrations/beta/.gitignore new file mode 100644 index 00000000000..3c3d57339c8 --- /dev/null +++ b/src/Migrations/beta/.gitignore @@ -0,0 +1,16 @@ +bin +obj +.vs +generated +internal +exports +tools +custom/*.psm1 +custom/autogen-model-cmdlets +test/*-TestResults.xml +/*.ps1 +/*.ps1xml +/*.psm1 +/*.snk +/*.csproj +/*.nuspec \ No newline at end of file diff --git a/src/Migrations/beta/custom/EventExtensions.cs b/src/Migrations/beta/custom/EventExtensions.cs new file mode 100644 index 00000000000..11cf798741c --- /dev/null +++ b/src/Migrations/beta/custom/EventExtensions.cs @@ -0,0 +1,38 @@ +// ------------------------------------------------------------------------------ +// Copyright (c) Microsoft Corporation. All Rights Reserved. Licensed under the MIT License. See License in the project root for license information. +// ------------------------------------------------------------------------------ + +namespace Microsoft.Graph.Beta.PowerShell +{ + using System; + using System.Text.RegularExpressions; + using System.Threading; + using System.Threading.Tasks; + using Microsoft.Graph.Beta.PowerShell.Runtime; + + public static class EventExtensions + { + /// + /// Print event details to the provided stream + /// + /// The event data to print + /// The delegate for signaling events to the runtime + /// The cancellation token for the request + /// The name of the stream to print data to + /// The name of the event to be printed + public static async void Print(this Func getEventData, Func, Task> signal, CancellationToken token, string streamName, string eventName) + { + var eventDisplayName = EventFactory.SplitPascalCase(eventName).ToUpperInvariant(); + var data = EventDataConverter.ConvertFrom(getEventData()); // also, we manually use our TypeConverter to return an appropriate type + if (data.Id != Events.Verbose && data.Id != Events.Warning && data.Id != Events.Debug && data.Id != Events.Information && data.Id != Events.Error) + { + await signal(streamName, token, () => EventFactory.CreateLogEvent($"{eventDisplayName} The contents are '{data?.Id}' and '{data?.Message}'")); + if (data != null) + { + await signal(streamName, token, () => EventFactory.CreateLogEvent($"{eventDisplayName} Parameter: '{data.Parameter}'\n{eventDisplayName} RequestMessage '{data.RequestMessage}'\n{eventDisplayName} Response: '{data.ResponseMessage}'\n{eventDisplayName} Value: '{data.Value}'")); + await signal(streamName, token, () => EventFactory.CreateLogEvent($"{eventDisplayName} ExtendedData Type: '{data.ExtendedData?.GetType()}'\n{eventDisplayName} ExtendedData '{data.ExtendedData}'")); + } + } + } + } +} diff --git a/src/Migrations/beta/custom/EventFactory.cs b/src/Migrations/beta/custom/EventFactory.cs new file mode 100644 index 00000000000..0d6c3488eba --- /dev/null +++ b/src/Migrations/beta/custom/EventFactory.cs @@ -0,0 +1,72 @@ +// ------------------------------------------------------------------------------ +// Copyright (c) Microsoft Corporation. All Rights Reserved. Licensed under the MIT License. See License in the project root for license information. +// ------------------------------------------------------------------------------ + +using System; +using System.Text.RegularExpressions; +using System.Threading.Tasks; +using Microsoft.Graph.Beta.PowerShell.Runtime; + +namespace Microsoft.Graph.Beta.PowerShell +{ + public static class EventFactory + { + /// + /// Create a tracing event containing a string message + /// + /// The string message to include in event data + /// Valid EventData containing the message + public static EventData CreateLogEvent(Task message) + { + return new EventData + { + Id = Guid.NewGuid().ToString(), + Message = message.Result + }; + } + + /// + /// Create a new debug message event + /// + /// The message + /// An event containing the debug message + public static EventData CreateDebugEvent(string message) + { + return new EventData + { + Id = Events.Debug, + Message = message + }; + } + + /// + /// Create a new debug message event + /// + /// The message + /// An event containing the debug message + public static EventData CreateWarningEvent(string message) + { + return new EventData + { + Id = Events.Warning, + Message = message + }; + } + public static string SplitPascalCase(string word) + { + var regex = new Regex("([a-z]+)([A-Z])"); + var output = regex.Replace(word, "$1 $2"); + regex = new Regex("([A-Z])([A-Z][a-z])"); + return regex.Replace(output, "$1 $2"); + } + + public static EventArgs CreateLogEvent(string message) + { + return new EventData + { + Id = Guid.NewGuid().ToString(), + Message = message + }; + } + } +} diff --git a/src/Migrations/beta/custom/FileUploadCmdlet.cs b/src/Migrations/beta/custom/FileUploadCmdlet.cs new file mode 100644 index 00000000000..cacaaa4f3ef --- /dev/null +++ b/src/Migrations/beta/custom/FileUploadCmdlet.cs @@ -0,0 +1,44 @@ +// ------------------------------------------------------------------------------ +// Copyright (c) Microsoft Corporation. All Rights Reserved. Licensed under the MIT License. See License in the project root for license information. +// ------------------------------------------------------------------------------ +namespace Microsoft.Graph.Beta.PowerShell.Cmdlets.Custom +{ + using Microsoft.Graph.PowerShell.Authentication.Common; + using System.IO; + using System.Management.Automation; + + public partial class FileUploadCmdlet : PSCmdlet + { + /// Backing field for property. + private string _inFile; + + /// The path to the file to upload. This SHOULD include the file name and extension. + [Parameter(Mandatory = true, HelpMessage = "The path to the file to upload. This should include a path and file name. If you omit the path, the current location will be used.")] + [Runtime.Info( + Required = true, + ReadOnly = false, + Description = @"The path to the file to upload. This should include a path and file name. If you omit the path, the current location will be used.", + PossibleTypes = new[] { typeof(string) })] + [ValidateNotNullOrEmpty()] + [Category(ParameterCategory.Runtime)] + public string InFile { get => this._inFile; set => this._inFile = value; } + + /// + /// Creates a file stream from the provided input file. + /// + /// A file stream. + internal Stream GetFileAsStream() + { + if (MyInvocation.BoundParameters.ContainsKey(nameof(InFile))) + { + string resolvedFilePath = this.GetProviderPath(InFile, true); + var fileProvider = ProtectedFileProvider.CreateFileProvider(resolvedFilePath, FileProtection.SharedRead, new DiskDataStore()); + return fileProvider.Stream; + } + else + { + return null; + } + } + } +} diff --git a/src/Migrations/beta/custom/HttpMessageLogFormatter.cs b/src/Migrations/beta/custom/HttpMessageLogFormatter.cs new file mode 100644 index 00000000000..04666618c38 --- /dev/null +++ b/src/Migrations/beta/custom/HttpMessageLogFormatter.cs @@ -0,0 +1,193 @@ +// ------------------------------------------------------------------------------ +// Copyright (c) Microsoft Corporation. All Rights Reserved. Licensed under the MIT License. See License in the project root for license information. +// ------------------------------------------------------------------------------ + +namespace Microsoft.Graph.Beta.PowerShell +{ + using Microsoft.Graph.Beta.PowerShell.Models; + using Newtonsoft.Json; + using System; + using System.Collections.Generic; + using System.IO; + using System.Linq; + using System.Net.Http; + using System.Net.Http.Headers; + using System.Text; + using System.Text.RegularExpressions; + using System.Threading.Tasks; + using System.Xml.Linq; + + public static class HttpMessageLogFormatter + { + internal static async Task CloneAsync(this HttpRequestMessage originalRequest) + { + var newRequest = new HttpRequestMessage(originalRequest.Method, originalRequest.RequestUri); + + // Copy requestClone headers. + foreach (var header in originalRequest.Headers) + newRequest.Headers.TryAddWithoutValidation(header.Key, header.Value); + + // Copy requestClone properties. + foreach (var property in originalRequest.Properties) + newRequest.Properties.Add(property); + + // Set Content if previous requestClone had one. + if (originalRequest.Content != null) + { + // Try cloning request content; otherwise, skip due to https://github.com/dotnet/corefx/pull/19082 in .NET 4.x. + try + { + // HttpClient doesn't rewind streams and we have to explicitly do so. + var ms = new MemoryStream(); + await originalRequest.Content.CopyToAsync(ms).ConfigureAwait(false); + ms.Position = 0; + newRequest.Content = new StreamContent(ms); + // Attempt to copy request content headers with a single retry. + // HttpHeaders dictionary is not thread-safe when targeting anything below .NET 7. For more information, see https://github.com/dotnet/runtime/issues/61798. + int retryCount = 0; + int maxRetryCount = 2; + while (retryCount < maxRetryCount) + { + try + { + originalRequest.Content?.Headers?.ToList().ForEach(header => newRequest.Content?.Headers.TryAddWithoutValidation(header.Key, header.Value)); + retryCount = maxRetryCount; + } + catch (InvalidOperationException) + { + retryCount++; + } + } + } + catch + { + } + } + return newRequest; + } + + public static async Task GetHttpRequestLogAsync(HttpRequestMessage request) + { + if (request == null) return string.Empty; + var requestClone = await request.CloneAsync().ConfigureAwait(false); + string body = string.Empty; + try + { + if (requestClone.Content != null) + { + body = FormatString(await requestClone.Content.ReadAsStringAsync()); + } + else if (requestClone.Content == null && request.Content != null) + { + body = "Skipped: Content body was disposed before the logger could access it."; + } + } + catch { } + + StringBuilder stringBuilder = new StringBuilder(); + stringBuilder.AppendLine($"============================ HTTP REQUEST ============================{Environment.NewLine}"); + stringBuilder.AppendLine($"HTTP Method:{Environment.NewLine}{requestClone.Method}{Environment.NewLine}"); + stringBuilder.AppendLine($"Absolute Uri:{Environment.NewLine}{requestClone.RequestUri}{Environment.NewLine}"); + stringBuilder.AppendLine($"Headers:{Environment.NewLine}{HeadersToString(requestClone.Headers)}{Environment.NewLine}"); + stringBuilder.AppendLine($"Body:{Environment.NewLine}{SanitizeBody(body)}{Environment.NewLine}"); + return stringBuilder.ToString(); + } + + public static async Task GetHttpResponseLogAsync(HttpResponseMessage response) + { + if (response == null) return string.Empty; + + string body = string.Empty; + try + { + body = (response.Content == null) ? string.Empty : FormatString(await response.Content.ReadAsStringAsync()); + } + catch { } + + StringBuilder stringBuilder = new StringBuilder(); + stringBuilder.AppendLine($"============================ HTTP RESPONSE ============================{Environment.NewLine}"); + stringBuilder.AppendLine($"Status Code:{Environment.NewLine}{response.StatusCode}{Environment.NewLine}"); + stringBuilder.AppendLine($"Headers:{Environment.NewLine}{HeadersToString(response.Headers)}{Environment.NewLine}"); + stringBuilder.AppendLine($"Body:{Environment.NewLine}{SanitizeBody(body)}{Environment.NewLine}"); + return stringBuilder.ToString(); + } + + public static async Task GetErrorLogAsync(HttpResponseMessage response, IMicrosoftGraphODataErrorsMainError odataError) + { + if (response == null) return string.Empty; + + StringBuilder stringBuilder = new StringBuilder(); + stringBuilder.AppendLine($"{odataError?.Message}{Environment.NewLine}"); + stringBuilder.AppendLine($"Status: {((int)response.StatusCode)} ({response.StatusCode})"); + stringBuilder.AppendLine($"ErrorCode: {odataError?.Code}"); + stringBuilder.AppendLine($"Date: {odataError?.InnerError?.Date}{Environment.NewLine}"); + stringBuilder.AppendLine($"Headers:{Environment.NewLine}{HeadersToString(response.Headers)}{Environment.NewLine}"); + return stringBuilder.ToString(); + } + + internal static string HeadersToString(HttpHeaders headers) + { + return HeadersToString(ConvertHttpHeadersToCollection(headers)); + } + + private static readonly Regex regexPattern = new Regex("(\\s*\"access_token\"\\s*:\\s*)\"[^\"]+\"", RegexOptions.Compiled); + private static object SanitizeBody(string body) + { + IList regexList = new List(); + // Remove access_token:* instances in body. + regexList.Add(regexPattern); + + foreach (Regex matcher in regexList) + { + body = matcher.Replace(body, "$1\"\""); + } + + return body; + } + + private static IDictionary> ConvertHttpHeadersToCollection(HttpHeaders headers) + { + headers.Remove("Authorization"); + return headers.ToDictionary(a => a.Key, a => a.Value); + } + + private static string HeadersToString(IDictionary> headers) + { + StringBuilder stringBuilder = headers.Aggregate(new StringBuilder(), + (sb, kvp) => sb.AppendLine(string.Format("{0,-30}: {1}", kvp.Key, String.Join(",", kvp.Value.ToArray())))); + + if (stringBuilder.Length > 0) + stringBuilder.Remove(stringBuilder.Length - 2, 2); + + return stringBuilder.ToString(); + } + + private static string FormatString(string content) + { + try + { + content = content.Trim(); + if ((content.StartsWith("{") && content.EndsWith("}")) || // object + (content.StartsWith("[") && content.EndsWith("]"))) // array + { + return JsonConvert.SerializeObject(JsonConvert.DeserializeObject(content), Formatting.Indented); + } + if (content.StartsWith("<")) + { + return XDocument.Parse(content).ToString(); + } + } + catch + { + return content; + } + + if (content.Length > Microsoft.Graph.PowerShell.Authentication.Constants.MaxContentLength) + { + return content.Substring(0, Microsoft.Graph.PowerShell.Authentication.Constants.MaxContentLength) + "\r\nDATA TRUNCATED DUE TO SIZE\r\n"; + } + + return content; + } + } +} diff --git a/src/Migrations/beta/custom/JsonExtensions.cs b/src/Migrations/beta/custom/JsonExtensions.cs new file mode 100644 index 00000000000..9fb67dc71ef --- /dev/null +++ b/src/Migrations/beta/custom/JsonExtensions.cs @@ -0,0 +1,95 @@ +namespace Microsoft.Graph.Beta.PowerShell.JsonUtilities +{ + using Newtonsoft.Json.Linq; + using Newtonsoft.Json; + using System; + using System.Linq; + + public static class JsonExtensions + { + /// + /// Converts "null" strings to actual null values, replaces empty objects, and cleans up arrays. + /// + /// The JSON token to process. + /// A cleaned JSON string with unnecessary null values removed. + public static string RemoveDefaultNullProperties(this JToken token) + { + try + { + ProcessToken(token); + + return token.ToString(); + } + catch (Exception) + { + return token.ToString(); // Return original JSON if an error occurs + } + } + + private static JToken ProcessToken(JToken token) + { + if (token is JObject jsonObject) + { + + // Recursively process remaining properties + foreach (var property in jsonObject.Properties().ToList()) + { + JToken cleanedValue = ProcessToken(property.Value); + + // Convert explicit "null" strings to actual null + if (property.Value.Type == JTokenType.String && property.Value.ToString().Equals("null", StringComparison.Ordinal)) + { + property.Value = JValue.CreateNull(); + } + + if (property.Value.ToString().Equals("{\r\n}", StringComparison.Ordinal)) + { + + property.Value = JObject.Parse("{}"); // Convert empty object to {} + } + + } + + // Remove the object itself if ALL properties are removed (empty object) + return jsonObject.HasValues ? jsonObject : null; + } + else if (token is JArray jsonArray) + { + for (int i = jsonArray.Count - 1; i >= 0; i--) + { + JToken item = jsonArray[i]; + + // Process nested objects/arrays inside the array + if (item is JObject || item is JArray) + { + if (item.ToString().Equals("{\r\n}", StringComparison.Ordinal)) + { + JToken cleanedItem = ProcessToken(item); + jsonArray[i] = JObject.Parse("{}"); // Convert empty object to {} + } + else + { + JToken cleanedItem = ProcessToken(item); + jsonArray[i] = cleanedItem; // Update with cleaned version + } + + } + else if (item.Type == JTokenType.String && item.ToString().Equals("null", StringComparison.Ordinal)) + { + jsonArray[i] = JValue.CreateNull(); // Convert "null" string to JSON null + } + else if (item.Type == JTokenType.String && item.ToString().Equals("nullarray", StringComparison.Ordinal)) + { + jsonArray.RemoveAt(i); + i--; + } + + } + + return jsonArray.HasValues ? jsonArray : null; + } + + return token; + } + } +} diff --git a/src/Migrations/beta/custom/ListCmdlet.cs b/src/Migrations/beta/custom/ListCmdlet.cs new file mode 100644 index 00000000000..9eb7bded11b --- /dev/null +++ b/src/Migrations/beta/custom/ListCmdlet.cs @@ -0,0 +1,222 @@ +// ------------------------------------------------------------------------------ +// Copyright (c) Microsoft Corporation. All Rights Reserved. Licensed under the MIT License. See License in the project root for license information. +// ------------------------------------------------------------------------------ +namespace Microsoft.Graph.Beta.PowerShell.Cmdlets.Custom +{ + using System; + using System.Management.Automation; + + public partial class ListCmdlet : PSCmdlet + { + /// Backing field for property. + private int _pageSize; + + /// Sets the page size of results. + [Parameter(Mandatory = false, HelpMessage = "Sets the page size of results.")] + [Runtime.Info( + Required = false, + ReadOnly = false, + Description = @"The page size of results.", + PossibleTypes = new[] { typeof(int) })] + [Category(ParameterCategory.Runtime)] + public int PageSize { get => this._pageSize; set => this._pageSize = value; } + + /// Backing field for property. + private global::System.Management.Automation.SwitchParameter _all; + + /// List All pages + [Parameter(Mandatory = false, HelpMessage = "List all pages.")] + [Runtime.Info( + Required = false, + ReadOnly = false, + Description = @"List all pages.", + PossibleTypes = new[] { typeof(global::System.Management.Automation.SwitchParameter) })] + [Category(ParameterCategory.Runtime)] + public global::System.Management.Automation.SwitchParameter All { get => this._all; set => this._all = value; } + + // Backing field for property. + private string _countVariable; + + /// Specifies a count of the total number of items in a collection. + [Parameter(Mandatory = false, HelpMessage = "Specifies a count of the total number of items in a collection. By default, this variable will be set in the global scope.")] + [Runtime.Info( + Required = false, + ReadOnly = false, + Description = @"Specifies a count of the total number of items in a collection. By default, this variable will be set in the global scope.", + PossibleTypes = new[] { typeof(string) })] + [Category(ParameterCategory.Runtime)] + [global::System.Management.Automation.Alias("CV")] + public string CountVariable { get => this._countVariable; set => this._countVariable = value; } + + /// + /// Maximum number of items per page. + /// + internal const int MaxPageSize = 999; + + /// + /// Total number of pages required to iterate page collections excluding overflow items. + /// + internal int requiredPages = 0; + + /// + /// A count of iterated pages thus far. + /// + internal int iteratedPages = 0; + + /// + /// Total number of overflow items, less than the maximum number of items in a page. + /// Modulus of original page size. + /// + internal int overflowItemsCount = 0; + + /// + /// Total number of fetched items. + /// + internal int totalFetchedItems = 0; + + /// + /// Total number of items to be fetched. + /// + internal int limit = default; + + /// + /// Initializes paging values. + /// + /// A reference to object. + /// A reference to top parameter. + public void InitializeCmdlet(ref global::System.Management.Automation.InvocationInfo invocationInfo, ref int top, ref global::System.Management.Automation.SwitchParameter count) + { + if (invocationInfo.BoundParameters.ContainsKey("PageSize") && (PageSize > MaxPageSize || PageSize == default)) + { + ThrowTerminatingError( + new ErrorRecord( + new ArgumentException($"Invalid page size specified `{PageSize}`. {nameof(PageSize)} must be between 1 and {MaxPageSize} inclusive."), + Guid.NewGuid().ToString(), + ErrorCategory.InvalidArgument, + null)); + } + + if (invocationInfo.BoundParameters.ContainsKey("Top")) + { + if ((top > MaxPageSize) || IsAllPresent(invocationInfo.BoundParameters) || invocationInfo.BoundParameters.ContainsKey("PageSize")) + { + limit = top; + } + + if (top > MaxPageSize) + { + // Remove $top from query parameters, we will handle paging. + top = default; + invocationInfo.BoundParameters.Remove("Top"); + } + + if (invocationInfo.BoundParameters.ContainsKey("PageSize")) + { + invocationInfo.BoundParameters["Top"] = PageSize; + top = PageSize; + } + } + else if (invocationInfo.BoundParameters.ContainsKey("PageSize")) + { + invocationInfo.BoundParameters["Top"] = PageSize; + top = PageSize; + } + + if ((!invocationInfo.BoundParameters.ContainsKey("Count")) && invocationInfo.BoundParameters.ContainsKey("CountVariable")) + { + // Set Count to true when CountVariable is set. + invocationInfo.BoundParameters["Count"] = true; + count = true; + } + } + + public void InitializePageCount(int initialPageSize) + { + if (limit != default && initialPageSize != default) + { + requiredPages = limit / initialPageSize; + overflowItemsCount = limit % initialPageSize; + } + } + + /// + /// Determines whether the cmdlet should follow the OData next link URL. + /// Iteration will only occur when limit/top is not set, or if there a more items to fetch. + /// + /// The bound parameters of the cmdlet. + /// Current page items count. + /// True if it can iterate pages; otherwise False. + public bool ShouldIteratePages(global::System.Collections.Generic.Dictionary boundParameters, int itemsCount) + { + iteratedPages++; + totalFetchedItems += itemsCount; + + return (IsAllPresent(boundParameters) && limit == default) || totalFetchedItems < limit; + } + + /// + /// Gets an OData next link for the overflow items. + /// + /// The OData next link returned by the service. + /// An OData next link URI for the overflow items. + public global::System.Uri GetOverflowItemsNextLinkUri(global::System.Uri requestUri) + { + var nextLinkUri = new global::System.UriBuilder(requestUri); + if (requiredPages == iteratedPages && overflowItemsCount > 0) + { + if (nextLinkUri.Query.Contains("$top")) + { + global::System.Collections.Specialized.NameValueCollection queryString = global::System.Web.HttpUtility.ParseQueryString(nextLinkUri.Query); + queryString["$top"] = global::System.Uri.EscapeDataString(overflowItemsCount.ToString()); + nextLinkUri.Query = queryString.ToString(); + } + else + { + nextLinkUri.Query += $"&$top={System.Uri.EscapeDataString(overflowItemsCount.ToString())}"; + } + } + return nextLinkUri.Uri; + } + + /// + /// Adds quotation mark around $search values if none exists. + /// This is needed to support KQL e.g. "prop:value". + /// + /// The bound parameters of the calling cmdlet. + /// The $search value. + /// A formated search value. + internal string FormatSearchValue(global::System.Collections.Generic.Dictionary boundParameters, string search) + { + if (!boundParameters.ContainsKey("Search")) + { + return null; + } + else if (!string.IsNullOrWhiteSpace(search) && !search.StartsWith("\"")) + { + search = $"\"{search}\""; + } + + return search; + } + + internal void OnBeforeWriteObject(global::System.Collections.Generic.Dictionary boundParameters, global::System.Collections.Generic.IDictionary additionalProperties) + { + // Get odata.count from the response. + if (boundParameters.ContainsKey("CountVariable") && + additionalProperties != null && + additionalProperties.TryGetValue("@odata.count", out var odataCount)) + { + // Save the Count back to the PS environment in a global variable. + // We need to store count in a global variable since these cmdlets are exported as functions. + // i.e. Functions can't modify parent scope. + var psVI = SessionState.PSVariable; + psVI.Set(new PSVariable(CountVariable.Contains(":") ? CountVariable : $"global:{CountVariable}", odataCount)); + } + } + + private bool IsAllPresent(global::System.Collections.Generic.Dictionary boundParameters) + { + return boundParameters.ContainsKey("All") && All.IsPresent; + } + } +} diff --git a/src/Migrations/beta/custom/Module.cs b/src/Migrations/beta/custom/Module.cs new file mode 100644 index 00000000000..4df04cf4b6e --- /dev/null +++ b/src/Migrations/beta/custom/Module.cs @@ -0,0 +1,171 @@ +// ------------------------------------------------------------------------------ +// Copyright (c) Microsoft Corporation. All Rights Reserved. Licensed under the MIT License. See License in the project root for license information. +// ------------------------------------------------------------------------------ + +using System; +using System.Linq; +using System.Management.Automation; +using System.Net.Http; +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Graph.Beta.PowerShell.Runtime; +using Microsoft.Graph.PowerShell.Authentication; +using Microsoft.Graph.PowerShell.Authentication.Helpers; +using static Microsoft.Graph.Beta.PowerShell.Runtime.Extensions; + +namespace Microsoft.Graph.Beta.PowerShell +{ + public partial class Module + { + partial void BeforeCreatePipeline(System.Management.Automation.InvocationInfo invocationInfo, ref Runtime.HttpPipeline pipeline) + { + // Call Init to trigger any custom initialization needed after + // module load and before pipeline is setup and used. + Init(); + pipeline = new Runtime.HttpPipeline(new Runtime.HttpClientFactory(HttpHelpers.GetGraphHttpClient())); + } + + /// + /// Any needed Custom Initialization. + /// + partial void CustomInit() + { + this.EventListener = EventHandler; + } + + /// + /// Common Module Event Listener, allows to handle emitted by CmdLets + /// + /// The ID of the event + /// The cancellation token for the event + /// A delegate to get the detailed event data + /// The callback for the event dispatcher + /// The from the cmdlet + /// The cmdlet's parameterset name + /// the exception that is being thrown (if available) + /// + /// A that will be complete when handling of the event is completed. + /// + public async Task EventHandler(string id, CancellationToken cancellationToken, Func getEventData, Func, Task> signal, InvocationInfo invocationInfo, string parameterSetName, System.Exception exception) + { + switch (id) + { + case Events.CmdletBeginProcessing: + await OnCmdletBeginProcessing(id, cancellationToken, getEventData, signal, invocationInfo); + break; + case Events.BeforeCall: + if (!IsPsCore()) + await OnBeforeCall(id, cancellationToken, getEventData, signal); + break; + case Events.ResponseCreated: + await OnResponseCreated(id, cancellationToken, getEventData, signal); + break; + case Events.CmdletException: + await OnCmdletException(id, cancellationToken, getEventData, signal, exception); + break; + case Events.CmdletEndProcessing: + await OnCmdletEndProcessing(id, cancellationToken, getEventData, signal, invocationInfo); + break; + } + } + + private async Task OnCmdletBeginProcessing(string id, CancellationToken cancellationToken, Func getEventData, Func, Task> signal, InvocationInfo invocationInfo) + { + using (NoSynchronizationContext) + { + string[] commandNameSegment = invocationInfo.MyCommand.Name.Split('_'); + if (commandNameSegment.Length > 1) + { + await signal(Events.Debug, cancellationToken, () => EventFactory.CreateLogEvent($"[{id}]: - {commandNameSegment[0]} begin processing with parameterSet '{commandNameSegment[1]}'.")); + } + else + { + await signal(Events.Debug, cancellationToken, () => EventFactory.CreateLogEvent($"[{id}]: - {invocationInfo.MyCommand.Name} begin processing.")); + } + IAuthContext authContext = Microsoft.Graph.PowerShell.Authentication.GraphSession.Instance.AuthContext; + if (authContext != null) + { + await signal(Events.Debug, cancellationToken, () => EventFactory.CreateLogEvent($"[Authentication]: - AuthType: '{authContext.AuthType}', TokenCredentialType: '{authContext.TokenCredentialType}', ContextScope: '{authContext.ContextScope}', AppName: '{authContext.AppName}'.")); + var scopes = authContext.Scopes == null ? string.Empty : string.Join(", ", authContext.Scopes); + await signal(Events.Debug, cancellationToken, () => EventFactory.CreateLogEvent($"[Authentication]: - Scopes: [{scopes}].")); + } + } + } + + private async Task OnBeforeCall(string id, CancellationToken cancellationToken, Func getEventData, Func, Task> signal) + { + using (NoSynchronizationContext) + { + var eventData = EventDataConverter.ConvertFrom(getEventData()); + var request = eventData?.RequestMessage as HttpRequestMessage; + if (request != null) + { + await signal(Events.Debug, cancellationToken, + () => EventFactory.CreateLogEvent(HttpMessageLogFormatter.GetHttpRequestLogAsync(request))); + } + } + } + + private async Task OnResponseCreated(string id, CancellationToken cancellationToken, Func getEventData, Func, Task> signal) + { + using (NoSynchronizationContext) + { + var eventData = EventDataConverter.ConvertFrom(getEventData()); + var response = eventData?.ResponseMessage as HttpResponseMessage; + if (response != null) + { + if (response.Headers.Warning != null && response.Headers.Warning.Any()) + { + string warningHeader = response.Headers.Warning.ToString(); + await signal(Events.Warning, cancellationToken, + () => EventFactory.CreateWarningEvent(warningHeader)); + } + if (IsPsCore()) + { + // Log request after response since all our request header are set via middleware pipeline. + var request = response?.RequestMessage; + if (request != null) + { + await signal(Events.Debug, cancellationToken, + () => EventFactory.CreateLogEvent(HttpMessageLogFormatter.GetHttpRequestLogAsync(request))); + } + } + + await signal(Events.Debug, cancellationToken, + () => EventFactory.CreateLogEvent(HttpMessageLogFormatter.GetHttpResponseLogAsync(response))); + } + } + } + + private async Task OnCmdletException(string id, CancellationToken cancellationToken, Func getEventData, Func, Task> signal, Exception exception) + { + using (NoSynchronizationContext) + { + var eventData = EventDataConverter.ConvertFrom(getEventData()); + await signal(Events.Debug, cancellationToken, () => EventFactory.CreateLogEvent($"[{id}]: Received exception with message '{eventData?.Message}'")); + } + } + + private async Task OnCmdletEndProcessing(string id, CancellationToken cancellationToken, Func getEventData, Func, Task> signal, InvocationInfo invocationInfo) + { + using (NoSynchronizationContext) + { + string[] commandNameSegment = invocationInfo.MyCommand.Name.Split('_'); + if (commandNameSegment.Length > 1) + { + await signal(Events.Debug, cancellationToken, () => EventFactory.CreateLogEvent($"[{id}]: - {commandNameSegment[0]} end processing.")); + } + else + { + await signal(Events.Debug, cancellationToken, () => EventFactory.CreateLogEvent($"[{id}]: - {invocationInfo.MyCommand.Name} end processing.")); + } + } + } + + private bool IsPsCore() + { + var psCoreVersion = new Version(6,0,0); + return GraphSession.Instance.AuthContext.PSHostVersion >= psCoreVersion; + } + } +} diff --git a/src/Migrations/beta/custom/PSCmdletExtensions.cs b/src/Migrations/beta/custom/PSCmdletExtensions.cs new file mode 100644 index 00000000000..a254c6243ce --- /dev/null +++ b/src/Migrations/beta/custom/PSCmdletExtensions.cs @@ -0,0 +1,212 @@ +// ------------------------------------------------------------------------------ +// Copyright (c) Microsoft Corporation. All Rights Reserved. Licensed under the MIT License. See License in the project root for license information. +// ------------------------------------------------------------------------------ +namespace Microsoft.Graph.Beta.PowerShell +{ + using Microsoft.Graph.PowerShell.Authentication; + using Microsoft.Graph.PowerShell.Authentication.Common; + using Microsoft.Graph.Beta.PowerShell.Models; + using System; + using System.Collections.ObjectModel; + using System.IO; + using System.Linq; + using System.Management.Automation; + using System.Net.Http; + using System.Threading; + using System.Threading.Tasks; + using System.Text.RegularExpressions; + + internal static class PSCmdletExtensions + { + private static readonly char[] PathSeparators = new char[] { Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar }; + + // Converts a string to its unescaped form. The method also replaces '+' with spaces. + internal static string UnescapeString(this PSCmdlet cmdlet, string value) + { + if (value == null) + return null; + + try + { + var unescapedString = Uri.UnescapeDataString(value); + return (value.EndsWith("'") || value.EndsWith("')")) ? unescapedString: unescapedString.Replace('+', ' '); + } + catch (UriFormatException ex) + { + cmdlet.ThrowTerminatingError(new ErrorRecord(ex, string.Empty, ErrorCategory.InvalidArgument, value)); + return null; + } + } + + /// + /// Gets a resolved or unresolved path from PSPath. + /// + /// The calling . + /// The file path to get a provider path for. + /// Determines whether get a resolved or unresolved provider path. + /// The provider path from PSPath. + internal static string GetProviderPath(this PSCmdlet cmdlet, string filePath, bool isResolvedPath) + { + string providerPath = null; + ProviderInfo provider; + try + { + var paths = new Collection(); + if (isResolvedPath) + { + paths = cmdlet.SessionState.Path.GetResolvedProviderPathFromPSPath(filePath, out provider); + } + else + { + paths.Add(cmdlet.SessionState.Path.GetUnresolvedProviderPathFromPSPath(filePath, out provider, out _)); + } + + if (provider.Name != "FileSystem" || paths.Count == 0) + { + cmdlet.ThrowTerminatingError(new ErrorRecord(new Exception($"Invalid path {filePath}."), string.Empty, ErrorCategory.InvalidArgument, filePath)); + } + if (paths.Count > 1) + { + cmdlet.ThrowTerminatingError(new ErrorRecord(new Exception("Multiple paths not allowed."), string.Empty, ErrorCategory.InvalidArgument, filePath)); + } + providerPath = paths[0]; + } + catch (Exception ex) + { + cmdlet.ThrowTerminatingError(new ErrorRecord(ex, string.Empty, ErrorCategory.InvalidArgument, filePath)); + } + + return providerPath; + } + + /// + /// Saves a stream to a file on disk. + /// + /// The calling . + /// The HTTP response from the service. + /// The stream to write to file. + /// The path to write the file to. This should include the file name and extension. + /// A cancellation token that will be used to cancel the operation by the user. + internal static void WriteToFile(this PSCmdlet cmdlet, HttpResponseMessage response, Stream inputStream, string filePath, CancellationToken cancellationToken) + { + if (IsPathDirectory(filePath)) + { + // Get file name from content disposition header if present; otherwise throw an exception for a file name to be provided. + var fileName = GetFileName(response); + filePath = Path.Combine(filePath, fileName); + } + if (File.Exists(filePath)) + { + cmdlet.WriteWarning($"{filePath} already exists. The file will be overridden."); + File.Delete(filePath); + } + using (var fileProvider = ProtectedFileProvider.CreateFileProvider(filePath, FileProtection.ExclusiveWrite, new DiskDataStore())) + { + string downloadUrl = response?.RequestMessage?.RequestUri.ToString(); + cmdlet.WriteToStream(inputStream, fileProvider.Stream, downloadUrl, cancellationToken); + } + } + + internal static async Task GetErrorDetailsAsync(this PSCmdlet cmdlet, IMicrosoftGraphODataErrorsMainError odataError, HttpResponseMessage response) + { + var serviceErrorDoc = "https://learn.microsoft.com/graph/errors"; + var recommendedAction = $"See service error codes: {serviceErrorDoc}"; + var errorDetailsMessage = await HttpMessageLogFormatter.GetErrorLogAsync(response, odataError); + return new ErrorDetails(errorDetailsMessage) + { + RecommendedAction = recommendedAction + }; + } + + /// + /// Writes an input stream to an output stream. + /// + /// The calling . + /// The stream to write to an output stream. + /// The stream to write the input stream to. + /// A cancellation token that will be used to cancel the operation by the user. + private static void WriteToStream(this PSCmdlet cmdlet, Stream inputStream, Stream outputStream, string downloadUrl, CancellationToken cancellationToken) + { + Task copyTask = inputStream.CopyToAsync(outputStream); + ProgressRecord record = new ProgressRecord( + activityId: 0, + activity: $"Downloading {downloadUrl ?? "file"}", + statusDescription: $"{outputStream.Position} of {outputStream.Length} bytes downloaded."); + try + { + do + { + cmdlet.WriteProgress(GetProgress(record, outputStream)); + + Task.Delay(1000, cancellationToken).Wait(cancellationToken); + } while (!copyTask.IsCompleted && !cancellationToken.IsCancellationRequested); + + if (copyTask.IsCompleted) + { + cmdlet.WriteProgress(GetProgress(record, outputStream)); + } + } + catch (OperationCanceledException) + { + } + } + + private static bool IsPathDirectory(string path) + { + if (path == null) throw new ArgumentNullException("path"); + bool isDirectory = false; + path = path.Trim(); + + if (Directory.Exists(path)) + isDirectory = true; + + if (File.Exists(path)) + isDirectory = false; + + // If path has a trailing slash then it's a directory. + if (PathSeparators.Contains(path.Last())) + isDirectory = true; + + // If path has an extension then its a file. + if (Path.HasExtension(path)) + isDirectory = false; + + return isDirectory; + } + + private static string GetFileName(HttpResponseMessage responseMessage) + { + if (responseMessage.Content.Headers.ContentDisposition != null + && !string.IsNullOrWhiteSpace(responseMessage.Content.Headers.ContentDisposition.FileName)) + { + var fileName = responseMessage.Content.Headers.ContentDisposition.FileNameStar ?? responseMessage.Content.Headers.ContentDisposition.FileName; + if (!string.IsNullOrWhiteSpace(fileName)) + return SanitizeFileName(fileName); + } + throw new ArgumentException(ErrorConstants.Message.CannotInferFileName, "-OutFile"); + } + + /// + /// When Inferring file names from content disposition header, ensure that only valid path characters are in the file name + /// + /// + private static string SanitizeFileName(string fileName) + { + var illegalCharacters = Path.GetInvalidFileNameChars().Concat(Path.GetInvalidPathChars()).ToArray(); + return string.Concat(fileName.Split(illegalCharacters)); + } + + /// + /// Calculates and updates the progress record of the provided stream. + /// + /// The to update. + /// The stream to calculate its progress. + /// An updated . + private static ProgressRecord GetProgress(ProgressRecord currentProgressRecord, Stream stream) + { + currentProgressRecord.StatusDescription = $"{stream.Position} of {stream.Length} bytes downloaded."; + currentProgressRecord.PercentComplete = (int)Math.Round((double)(100 * stream.Position) / stream.Length); + return currentProgressRecord; + } + } +} diff --git a/src/Migrations/beta/custom/README.md b/src/Migrations/beta/custom/README.md new file mode 100644 index 00000000000..2c71cb21a02 --- /dev/null +++ b/src/Migrations/beta/custom/README.md @@ -0,0 +1,41 @@ +# Custom +This directory contains custom implementation for non-generated cmdlets for the `Microsoft.Graph.Beta.Migrations` module. Both scripts (`.ps1`) and C# files (`.cs`) can be implemented here. They will be used during the build process in `build-module.ps1`, and create cmdlets into the `..\exports` folder. The only generated file into this folder is the `Microsoft.Graph.Beta.Migrations.custom.psm1`. This file should not be modified. + +## Info +- Modifiable: yes +- Generated: partial +- Committed: yes +- Packaged: yes + +## Details +For `Microsoft.Graph.Beta.Migrations` to use custom cmdlets, it does this two different ways. We **highly recommend** creating script cmdlets, as they are easier to write and allow access to the other exported cmdlets. C# cmdlets *cannot access exported cmdlets*. + +For C# cmdlets, they are compiled with the rest of the generated low-level cmdlets into the `./bin/Microsoft.Graph.Beta.Migrations.private.dll`. The names of the cmdlets (methods) and files must follow the `[cmdletName]_[variantName]` syntax used for generated cmdlets. The `variantName` is used as the `ParameterSetName`, so use something appropriate that doesn't clash with already created variant or parameter set names. You cannot use the `ParameterSetName` property in the `Parameter` attribute on C# cmdlets. Each cmdlet must be separated into variants using the same pattern as seen in the `generated/cmdlets` folder. + +For script cmdlets, these are loaded via the `Microsoft.Graph.Beta.Migrations.custom.psm1`. Then, during the build process, this module is loaded and processed in the same manner as the C# cmdlets. The fundamental difference is the script cmdlets use the `ParameterSetName` attribute and C# cmdlets do not. To create a script cmdlet variant of a generated cmdlet, simply decorate all parameters in the script with the new `ParameterSetName` in the `Parameter` attribute. This will appropriately treat each parameter set as a separate variant when processed to be exported during the build. + +## Purpose +This allows the modules to have cmdlets that were not defined in the REST specification. It also allows combining logic using generated cmdlets. This is a level of customization beyond what can be done using the [readme configuration options](https://github.com/Azure/autorest/blob/master/docs/powershell/options.md) that are currently available. These custom cmdlets are then referenced by the cmdlets created at build-time in the `..\exports` folder. + +## Usage +The easiest way currently to start developing custom cmdlets is to copy an existing cmdlet. For C# cmdlets, copy one from the `generated/cmdlets` folder. For script cmdlets, build the project using `build-module.ps1` and copy one of the scripts from the `..\exports` folder. After that, if you want to add new parameter sets, follow the guidelines in the `Details` section above. For implementing a new cmdlets, at minimum, please keep these parameters: +- Break +- DefaultProfile +- HttpPipelineAppend +- HttpPipelinePrepend +- Proxy +- ProxyCredential +- ProxyUseDefaultCredentials + +These provide functionality to our HTTP pipeline and other useful features. In script, you can forward these parameters using `$PSBoundParameters` to the other cmdlets you're calling within `Microsoft.Graph.Beta.Migrations`. For C#, follow the usage seen in the `ProcessRecordAsync` method. + +### Attributes +For processing the cmdlets, we've created some additional attributes: +- `Microsoft.Graph.Beta.PowerShell.DescriptionAttribute` + - Used in C# cmdlets to provide a high-level description of the cmdlet. This is propagated to reference documentation via [help comments](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comment_based_help) in the exported scripts. +- `Microsoft.Graph.Beta.PowerShell.DoNotExportAttribute` + - Used in C# and script cmdlets to suppress creating an exported cmdlet at build-time. These cmdlets will *not be exposed* by `Microsoft.Graph.Beta.Migrations`. +- `Microsoft.Graph.Beta.PowerShell.InternalExportAttribute` + - Used in C# cmdlets to route exported cmdlets to the `..\internal`, which are *not exposed* by `Microsoft.Graph.Beta.Migrations`. For more information, see [README.md](..\internal/README.md) in the `..\internal` folder. +- `Microsoft.Graph.Beta.PowerShell.ProfileAttribute` + - Used in C# and script cmdlets to define which Azure profiles the cmdlet supports. This is only supported for Azure (`--azure`) modules. \ No newline at end of file diff --git a/src/Migrations/beta/docs/README.md b/src/Migrations/beta/docs/README.md new file mode 100644 index 00000000000..5b97a8903c3 --- /dev/null +++ b/src/Migrations/beta/docs/README.md @@ -0,0 +1,11 @@ +# Docs +This directory contains the documentation of the cmdlets for the `Microsoft.Graph.Beta.Migrations` module. To run documentation generation, use the `generate-help.ps1` script at the root module folder. Files in this folder will *always be overridden on regeneration*. To update documentation examples, please use the `..\examples` folder. + +## Info +- Modifiable: no +- Generated: all +- Committed: yes +- Packaged: yes + +## Details +The process of documentation generation loads `Microsoft.Graph.Beta.Migrations` and analyzes the exported cmdlets from the module. It recognizes the [help comments](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comment_based_help) that are generated into the scripts in the `..\exports` folder. Additionally, when writing custom cmdlets in the `..\custom` folder, you can use the help comments syntax, which decorate the exported scripts at build-time. The documentation examples are taken from the `..\examples` folder. \ No newline at end of file diff --git a/src/Migrations/beta/examples/README.md b/src/Migrations/beta/examples/README.md new file mode 100644 index 00000000000..ac871d71fc7 --- /dev/null +++ b/src/Migrations/beta/examples/README.md @@ -0,0 +1,11 @@ +# Examples +This directory contains examples from the exported cmdlets of the module. When `build-module.ps1` is ran, example stub files will be generated here. If your module support Azure Profiles, the example stubs will be in individual profile folders. These example stubs should be updated to show how the cmdlet is used. The examples are imported into the documentation when `generate-help.ps1` is ran. + +## Info +- Modifiable: yes +- Generated: partial +- Committed: yes +- Packaged: no + +## Purpose +This separates the example documentation details from the generated documentation information provided directly from the generated cmdlets. Since the cmdlets don't have examples from the REST spec, this provides a means to add examples easily. The example stubs provide the markdown format that is required. The 3 core elements are: the name of the example, the code information of the example, and the description of the example. That information, if the markdown format is followed, will be available to documentation generation and be part of the documents in the `..\docs` folder. \ No newline at end of file diff --git a/src/Migrations/beta/how-to.md b/src/Migrations/beta/how-to.md new file mode 100644 index 00000000000..4fa4fdc3562 --- /dev/null +++ b/src/Migrations/beta/how-to.md @@ -0,0 +1,58 @@ +# How-To +This document describes how to develop for `Microsoft.Graph.Beta.Migrations`. + +## Building `Microsoft.Graph.Beta.Migrations` +To build, run the `build-module.ps1` at the root of the module directory. This will generate the proxy script cmdlets that are the cmdlets being exported by this module. After the build completes, the proxy script cmdlets will be output to the `exports` folder. To read more about the proxy script cmdlets, look at the [README.md](exports/README.md) in the `exports` folder. + +## Creating custom cmdlets +To add cmdlets that were not generated by the REST specification, use the `custom` folder. This folder allows you to add handwritten `.ps1` and `.cs` files. Currently, we support using `.ps1` scripts as new cmdlets or as additional low-level variants (via `ParameterSet`), and `.cs` files as low-level (variants) cmdlets that the exported script cmdlets call. We do not support exporting any `.cs` (dll) cmdlets directly. To read more about custom cmdlets, look at the [README.md](custom/README.md) in the `custom` folder. + +## Generating documentation +To generate documentation, the process is now integrated into the `build-module.ps1` script. If you don't want to run this process as part of `build-module.ps1`, you can provide the `-NoDocs` switch. If you want to run documentation generation after the build process, you may still run the `generate-help.ps1` script. Overall, the process will look at the documentation comments in the generated and custom cmdlets and types, and create `.md` files into the `docs` folder. Additionally, this pulls in any examples from the `examples` folder and adds them to the generated help markdown documents. To read more about examples, look at the [README.md](examples/README.md) in the `examples` folder. To read more about documentation, look at the [README.md](docs/README.md) in the `docs` folder. + +## Testing `Microsoft.Graph.Beta.Migrations` +To test the cmdlets, we use [Pester](https://github.com/pester/Pester). Tests scripts (`.ps1`) should be added to the `test` folder. To execute the Pester tests, run the `test-module.ps1` script. This will run all tests in `playback` mode within the `test` folder. To read more about testing cmdlets, look at the [README.md](examples/README.md) in the `examples` folder. + +## Packing `Microsoft.Graph.Beta.Migrations` +To pack `Microsoft.Graph.Beta.Migrations` for distribution, run the `pack-module.ps1` script. This will take the contents of multiple directories and certain root-folder files to create a `.nupkg`. The structure of the `.nupkg` is created so it can be loaded part of a [PSRepository](https://learn.microsoft.com/powershell/module/powershellget/register-psrepository). Additionally, this package is in a format for distribution to the [PSGallery](https://www.powershellgallery.com/). For signing an Azure module, please contact the [Azure PowerShell](https://github.com/Azure/azure-powershell) team. + +## Module Script Details +There are multiple scripts created for performing different actions for developing `Microsoft.Graph.Beta.Migrations`. +- `build-module.ps1` + - Builds the module DLL (`./bin/Microsoft.Graph.Beta.Migrations.private.dll`), creates the exported cmdlets and documentation, generates custom cmdlet test stubs and exported cmdlet example stubs, and updates `./Microsoft.Graph.Beta.Migrations.psd1` with Azure profile information. + - **Parameters**: [`Switch` parameters] + - `-Run`: After building, creates an isolated PowerShell session and loads `Microsoft.Graph.Beta.Migrations`. + - `-Test`: After building, runs the `Pester` tests defined in the `test` folder. + - `-Docs`: After building, generates the Markdown documents for the modules into the `docs` folder. + - `-Pack`: After building, packages the module into a `.nupkg`. + - `-Code`: After building, opens a VSCode window with the module's directory and runs (see `-Run`) the module. + - `-Release`: Builds the module in `Release` configuration (as opposed to `Debug` configuration). + - `-NoDocs`: Supresses writing the documentation markdown files as part of the cmdlet exporting process. + - `-Debugger`: Used when attaching the debugger in Visual Studio to the PowerShell session, and running the build process without recompiling the DLL. This suppresses running the script as an isolated process. +- `run-module.ps1` + - Creates an isolated PowerShell session and loads `Microsoft.Graph.Beta.Migrations` into the session. + - Same as `-Run` in `build-module.ps1`. + - **Parameters**: [`Switch` parameters] + - `-Code`: Opens a VSCode window with the module's directory. + - Same as `-Code` in `build-module.ps1`. +- `generate-help.ps1` + - Generates the Markdown documents for the modules into the `docs` folder. + - Same as `-Docs` in `build-module.ps1`. +- `test-module.ps1` + - Runs the `Pester` tests defined in the `test` folder. + - Same as `-Test` in `build-module.ps1`. +- `pack-module.ps1` + - Packages the module into a `.nupkg` for distribution. + - Same as `-Pack` in `build-module.ps1`. +- `generate-help.ps1` + - Generates the Markdown documents for the modules into the `docs` folder. + - Same as `-Docs` in `build-module.ps1`. + - This process is now integrated into `build-module.ps1` automatically. To disable, use `-NoDocs` when running `build-module.ps1`. +- `export-surface.ps1` + - Generates Markdown documents for both the cmdlet surface and the model (class) surface of the module. + - These files are placed into the `resources` folder. + - Used for investigating the surface of your module. These are *not* documentation for distribution. +- `check-dependencies.ps1` + - Used in `run-module.ps1` and `test-module.ps1` to verify dependent modules are available to run those tasks. + - It will download local (within the module's directory structure) versions of those modules as needed. + - This script *does not* need to be ran by-hand. \ No newline at end of file diff --git a/src/Migrations/beta/license.txt b/src/Migrations/beta/license.txt new file mode 100644 index 00000000000..b9f3180fb9a --- /dev/null +++ b/src/Migrations/beta/license.txt @@ -0,0 +1,227 @@ +MICROSOFT SOFTWARE LICENSE TERMS + +MICROSOFT AZURE POWERSHELL + +These license terms are an agreement between Microsoft Corporation (or based on where you live, one of its affiliates) and you. Please read them. They apply to the software named above, which includes the media on which you received it, if any. + +BY USING THE SOFTWARE, YOU ACCEPT THESE TERMS. IF YOU DO NOT ACCEPT THEM, DO NOT USE THE SOFTWARE. + + +-----------------START OF LICENSE-------------------------- + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + +-------------------END OF LICENSE------------------------------------------ + + +----------------START OF THIRD PARTY NOTICE-------------------------------- + + +The software includes the AutoMapper library ("AutoMapper"). The MIT License set out below is provided for informational purposes only. It is not the license that governs any part of the software. + +Provided for Informational Purposes Only + +AutoMapper + +The MIT License (MIT) +Copyright (c) 2010 Jimmy Bogard + + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + + + + + + +*************** + +The software includes Newtonsoft.Json. The MIT License set out below is provided for informational purposes only. It is not the license that governs any part of the software. + +Newtonsoft.Json + +The MIT License (MIT) +Copyright (c) 2007 James Newton-King +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +-------------END OF THIRD PARTY NOTICE---------------------------------------- + diff --git a/src/Migrations/beta/readme.md b/src/Migrations/beta/readme.md new file mode 100644 index 00000000000..186c480f9b5 --- /dev/null +++ b/src/Migrations/beta/readme.md @@ -0,0 +1,33 @@ + +# Microsoft.Graph.Beta.Migrations +This directory contains the PowerShell module for the Migrations service. + +--- +## Status +[![Microsoft.Graph.Beta.Migrations](https://img.shields.io/powershellgallery/v/Microsoft.Graph.Beta.Migrations.svg?style=flat-square&label=Microsoft.Graph.Beta.Migrations "Microsoft.Graph.Beta.Migrations")](https://www.powershellgallery.com/packages/Microsoft.Graph.Beta.Migrations/) + +## Info +- Modifiable: yes +- Generated: all +- Committed: yes +- Packaged: yes + +--- +## Detail +This module was primarily generated via [AutoRest](https://github.com/Azure/autorest) using the [PowerShell](https://github.com/Azure/autorest.powershell) extension. + +## Development +For information on how to develop for `Microsoft.Graph.Beta.Migrations`, see [how-to.md](how-to.md). + + +### AutoRest Configuration + +> see https://aka.ms/autorest + +``` yaml +require: + - $(this-folder)/../Migrations.md +title: $(service-name) +subject-prefix: 'Beta' +namespace: Microsoft.Graph.Beta.PowerShell +``` diff --git a/src/Migrations/beta/resources/README.md b/src/Migrations/beta/resources/README.md new file mode 100644 index 00000000000..937f07f8fec --- /dev/null +++ b/src/Migrations/beta/resources/README.md @@ -0,0 +1,11 @@ +# Resources +This directory can contain any additional resources for module that are not required at runtime. This directory **does not** get packaged with the module. If you have assets for custom implementation, place them into the `..\custom` folder. + +## Info +- Modifiable: yes +- Generated: no +- Committed: yes +- Packaged: no + +## Purpose +Use this folder to put anything you want to keep around as part of the repository for the module, but is not something that is required for the module. For example, development files, packaged builds, or additional information. This is only intended to be used in repositories where the module's output directory is cleaned, but tangential resources for the module want to remain intact. \ No newline at end of file diff --git a/src/Migrations/beta/test/README.md b/src/Migrations/beta/test/README.md new file mode 100644 index 00000000000..7c752b4c8c4 --- /dev/null +++ b/src/Migrations/beta/test/README.md @@ -0,0 +1,17 @@ +# Test +This directory contains the [Pester](https://www.powershellgallery.com/packages/Pester) tests to run for the module. We use Pester as it is the unofficial standard for PowerShell unit testing. Test stubs for custom cmdlets (created in `..\custom`) will be generated into this folder when `build-module.ps1` is ran. These test stubs will fail automatically, to indicate that tests should be written for custom cmdlets. + +## Info +- Modifiable: yes +- Generated: partial +- Committed: yes +- Packaged: no + +## Details +We allow three testing modes: *live*, *record*, and *playback*. These can be selected using the `-Live`, `-Record`, and `-Playback` switches respectively on the `test-module.ps1` script. This script will run through any `.Tests.ps1` scripts in the `test` folder. If you choose the *record* mode, it will create a `.Recording.json` file of the REST calls between the client and server. Then, when you choose *playback* mode, it will use the `.Recording.json` file to mock the communication between server and client. The *live* mode runs the same as the *record* mode; however, it doesn't create the `.Recording.json` file. + +## Purpose +Custom cmdlets generally encompass additional functionality not described in the REST specification, or combines functionality generated from the REST spec. To validate this functionality continues to operate as intended, creating tests that can be ran and re-ran against custom cmdlets is part of the framework. + +## Usage +To execute tests, run the `test-module.ps1`. To write tests, [this example](https://github.com/pester/Pester/blob/8b9cf4248315e44f1ac6673be149f7e0d7f10466/Examples/Planets/Get-Planet.Tests.ps1#L1) from the Pester repository is very useful for getting started. \ No newline at end of file diff --git a/src/Migrations/beta/test/loadEnv.ps1 b/src/Migrations/beta/test/loadEnv.ps1 new file mode 100644 index 00000000000..91500e8f6b2 --- /dev/null +++ b/src/Migrations/beta/test/loadEnv.ps1 @@ -0,0 +1,19 @@ +# ---------------------------------------------------------------------------------- +# Code generated by Microsoft (R) AutoRest Code Generator (autorest: 3.10.4, generator: @autorest/powershell@) +# Changes may cause incorrect behavior and will be lost if the code is regenerated. +# ---------------------------------------------------------------------------------- +$envFile = 'env.json' +if ($TestMode -eq 'live') { + $envFile = 'localEnv.json' +} + +if (Test-Path -Path (Join-Path $PSScriptRoot $envFile)) { + $envFilePath = Join-Path $PSScriptRoot $envFile +} else { + $envFilePath = Join-Path $PSScriptRoot '..\$envFile' +} +$env = @{} +if (Test-Path -Path $envFilePath) { + $env = Get-Content (Join-Path $PSScriptRoot $envFile) | ConvertFrom-Json + $PSDefaultParameterValues=@{"*:SubscriptionId"=$env.SubscriptionId; "*:Tenant"=$env.Tenant} +} \ No newline at end of file diff --git a/src/Migrations/beta/utils/Unprotect-SecureString.ps1 b/src/Migrations/beta/utils/Unprotect-SecureString.ps1 new file mode 100644 index 00000000000..cb05b51a622 --- /dev/null +++ b/src/Migrations/beta/utils/Unprotect-SecureString.ps1 @@ -0,0 +1,16 @@ +#This script converts securestring to plaintext + +param( + [Parameter(Mandatory, ValueFromPipeline)] + [System.Security.SecureString] + ${SecureString} +) + +$ssPtr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($SecureString) +try { + $plaintext = [System.Runtime.InteropServices.Marshal]::PtrToStringBSTR($ssPtr) +} finally { + [System.Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ssPtr) +} + +return $plaintext \ No newline at end of file