Sampel C#: pengiriman aplikasi dengan opsi game dan trailer

  • Artikel

Artikel ini menyediakan contoh kode C# yang menunjukkan cara menggunakan API pengiriman Microsoft Store untuk tugas-tugas ini:

  • Dapatkan token akses Azure AD untuk digunakan dengan API pengiriman Microsoft Store.
  • Membuat pengiriman aplikasi
  • Konfigurasikan data listingan Store untuk pengiriman aplikasi, termasuk opsi daftar lanjutan game dan trailer .
  • Unggah file ZIP yang berisi paket, mencantumkan gambar, dan file trailer untuk pengiriman aplikasi.
  • Terapkan pengiriman aplikasi.

Anda dapat meninjau setiap contoh untuk mempelajari lebih lanjut tugas yang ditunjukkannya, atau Anda dapat membuat semua contoh kode dalam artikel ini ke dalam aplikasi konsol. Untuk membuat contoh, buat aplikasi konsol C# bernama DevCenterApiSample di Visual Studio, salin setiap contoh ke file kode terpisah dalam proyek, dan buat proyek.

Prasyarat

Contoh-contoh ini memiliki persyaratan berikut:

  • Tambahkan referensi ke rakitan System.Web di proyek Anda.
  • Instal paket Newtonsoft.Json NuGet dari Newtonsoft ke proyek Anda.

Membuat pengiriman aplikasi

Kelas mendefinisikan CreateAndSubmitSubmissionExample metode publik Execute yang memanggil metode contoh lain untuk menggunakan API pengiriman Microsoft Store untuk membuat dan melakukan pengiriman aplikasi yang berisi opsi game dan trailer. Untuk menyesuaikan kode ini untuk penggunaan Anda sendiri:

using System;
using System.Threading;
using Newtonsoft.Json.Linq;

namespace DevCenterApiSample
{
    public class CreateAndSubmitSubmissionExample
    {
        public static void Execute()
        {
            // Add your tenant ID, client ID, and client secret here.
            string tenantId = "";
            string clientId = "";
            string clientSecret = "";
            var accessTokenClient = new DevCenterAccessTokenClient(tenantId, clientId, clientSecret);

            string accessToken = accessTokenClient.GetAccessToken("https://manage.devcenter.microsoft.com");
            var devCenter = new DevCenterClient(accessToken);

            // The application ID is taken from your app dashboard page's URI in Dev Center,
            // e.g. https://developer.microsoft.com/en-us/dashboard/apps/{application_id}/
            string applicationId = "{application_id}";

            // Get the application object, and cancel any in progress submissions.
            JObject app = devCenter.GetApplication(applicationId);
            JToken inProgressSubmission = app.GetValue("pendingApplicationSubmission");
            if (inProgressSubmission != null)
            {
                string inProgressSubmissionId = inProgressSubmission.Value<string>("id");
                devCenter.CancelInProgressSubmission(applicationId, inProgressSubmissionId);
            }

            // Create a new submission, based on the last published submission.
            JObject submission = devCenter.CreateSubmission(applicationId);
            string submissionId = submission.GetValue("id").Value<string>();

            // The following fields are required.
            submission["applicationCategory"] = "Games_Fighting";
            submission["listings"] = GetListingsObject();
            submission["pricing"] = GetPricingObject();
            submission["packages"] = new JArray() { GetPackageObject() };
            submission["allowTargetFutureDeviceFamilies"] = GetDeviceFamiliesObject();

            // The app must have the hasAdvancedListingPermission set to True in order for gaming options
            // and trailers to be applied. If that's not the case, you can still update the app and
            // its submissions through the API, but gaming options and trailers won't be saved.
            if (app["hasAdvancedListingPermission"] == null || app["hasAdvancedListingPermission"].Value<bool>() == false)
            {
                Console.WriteLine("This application does not support gaming options or trailers.");
            }
            else
            {
                // Gaming options is an array. A maximum of one value may be provided.
                submission["gamingOptions"] = new JArray(GetGamingOptionsObject());

                // A maximum of 15 trailers may be provided in the trailers array.
                submission["trailers"] = new JArray(GetTrailerObject());
            }                

            // Continue updating the submission_json object with additional options as needed.
            // After you've finished, call the Update API with the code below to save it.
            JObject updatedSubmission = devCenter.UpdateSubmission(applicationId, submissionId, submission);

            // All images and packages should be located in a single ZIP file. In the submission JSON, 
            // the file names for all objects requiring them (icons, packages, etc.) must exactly 
            // match the file names from the ZIP file.
            string zipFilePath = "";
            devCenter.UploadZipFileForSubmission(applicationId, submissionId, zipFilePath);

            // Committing the submission will start the submission process for it. Once committed,
            // the submission can no longer be changed.
            devCenter.CommitSubmission(applicationId, submissionId);

            // After committing, you can poll the commit API for the status of the submission's process using
            // the following code.
            bool waitingForCommitToStart = true;
            while (waitingForCommitToStart)
            {
                string status = devCenter.GetSubmissionStatus(applicationId, submissionId);
                Console.WriteLine($"Submission status: {status}");
                waitingForCommitToStart = status.Equals("CommitStarted");
                if (waitingForCommitToStart)
                {
                    Thread.Sleep(TimeSpan.FromMinutes(1)); // Wait to check Dev Center again.	
                }
            }
        }

        private static JObject GetListingsObject()
        {
            // This structure holds basic information to display in the store.
            var baseListing = new JObject();
            baseListing.Add("copyrightAndTrademarkInfo", "(C) 2017 Microsoft");
            baseListing.Add("licenseTerms", "http://example.com/licenseTerms.aspx");
            baseListing.Add("privacyPolicy", "http://example.com/privacyPolicy.aspx");
            baseListing.Add("supportContact", "support@example.com");
            baseListing.Add("websiteUrl", "http://example.com");
            baseListing.Add("description", "A sample game showing off gameplay options code.");
            baseListing.Add("releaseNotes", "Initial release");

            // The title of the app must match a reserved name for the app in Dev Center.
            // If it doesn't, attempting to update the submission will fail.
            baseListing.Add("title", "Super Game Options API Simulator 2017");

            var keywords = new JArray();
            keywords.Add("SampleApp");
            keywords.Add("SampleFightingGame");
            keywords.Add("GameOptions");
            baseListing.Add("keywords", keywords);

            var features = new JArray();
            features.Add("Doesn't crash");
            features.Add("Likes to eat chips");
            baseListing.Add("features", features);

            // If your app works better with specific hardware (or needs it), you can
            // add or update values here.
            var hardwarePreferences = new JArray()
            {
                "Keyboard",
                "Mouse"
            };
            baseListing.Add("hardwarePreferences", hardwarePreferences);

            var images = new JArray();

            // There are several types of images available; at least one screenshot
            // is required.
            var image = new JObject();

            // The file name is relative to the root of the uploaded ZIP file.
            image.Add("fileName", "img/screenshot.png");
            image.Add("description", "A basic screenshot of the app.");
            image.Add("imageType", "Screenshot");
            images.Add(image);
            baseListing.Add("images", images);

            var listing = new JObject();
            listing.Add("baseListing", baseListing);

            // If there are any specific overrides to above information for Windows 8,
            // Windows 8.1, Windows Phone 7.1, 8.0, or 8.1, you can add information here.
            listing.Add("platformOverrides", new JObject());

            // Each listing is targeted at a specific language-locale code, e.g. EN-US.
            var listings = new JObject();
            listings.Add("en-us", listing);
            return listings;
        }

        private static JObject GetPackageObject()
        {
            var package = new JObject()
            {
                // The file name is relative to the root of the uploaded ZIP file.
                ["fileName"] = "bin/super_dev_ctr_api_sim.appxupload",

                // If you haven't begun to upload the file yet, set this value to "PendingUpload".
                ["fileStatus"] = "PendingUpload"
            };
            return package;
        }

        private static JObject GetPricingObject()
        {
            var pricing = new JObject();

            // How long the trial period is, if one is allowed. Valid values are NoFreeTrial,
            // OneDay, SevenDays, FifteenDays, ThirtyDays, or TrialNeverExpires.
            pricing.Add("trialPeriod", "NoFreeTrial");

            // Maps to the default price for the app.
            pricing.Add("priceId", "Free");

            // If you'd like to offer your app in different markets at different prices, you
            // can provide priceId values per language/locale code.
            pricing.Add("marketSpecificPricing", new JObject());
            return pricing;
        }

        private static JObject GetDeviceFamiliesObject()
        {
            var futureDeviceFamilies = new JObject();

            // Supported values are Desktop, Mobile, Xbox, and Holographic. To make
            // the app available on that specific platform, set the value to True.
            futureDeviceFamilies.Add("Desktop", true);
            futureDeviceFamilies.Add("Mobile", false);
            futureDeviceFamilies.Add("Xbox", true);
            futureDeviceFamilies.Add("Holographic", false);
            return futureDeviceFamilies;
        }
        
        private static JObject GetTrailerObject()
        {
            // Add an example trailer.
            var trailer = new JObject();

            // This is the filename of the trailer. The file name is a relative path to the
            // root of the ZIP file to be uploaded to the API.
            trailer["VideoFileName"] = "trailers/main/my_awesome_trailer.mpeg";

            // Aside from the video itself, a trailer can have image assets such as screenshots
            // or alternate images.
            var trailerAssets = new JObject();
            trailer["TrailerAssets"] = trailerAssets;

            // Add trailer assets for the EN-US market.
            var trailerAsset = new JObject();
            trailerAssets["en-us"] = trailerAsset;

            // The title of the trailer to display in the store.
            trailerAsset["Title"] = "Main Trailer";

            // The list of images provided with the trailer that are shown
            // when the trailer isn't playing.
            var imageList = new JArray();
            trailerAsset["ImageList"] = imageList;

            // Add a few images to the image list.
            var thumbnailImage = new JObject()
            {
                // The file name of the image. The file name is a relative
                // path to the root of the ZIP
                // file to be uploaded to the API.
                ["FileName"] = "trailers/main/thumbnail.png",

                // A plaintext description of what the image represents.
                ["Description"] = "The thumbnail for the trailer shown " + "before the user clicks play"
            };
            imageList.Add(thumbnailImage);

            var altImage = new JObject()
            {
                ["FileName"] = "trailers/main/alt-img.png",
                ["Description"] = "The image to show after the trailer plays"
            };
            imageList.Add(altImage);

            return trailer;
        }

        private static JObject GetGamingOptionsObject()
        {
            var gamingOptions = new JObject();

            // The genres of your game.
            var genres = new JArray();
            genres.Add("Games_Fighting");
            gamingOptions["genres"] = genres;

            // Set this to true if your game supports local multiplayer. This field
            // is required.
            gamingOptions["isLocalMultiplayer"] = true;

            // If local multiplayer is supported, you must provide the minimum and
            // maximum players supported. Valid values are between 2 and 1000 inclusive.
            gamingOptions["localMultiplayerMinPlayers"] = 2;
            gamingOptions["localMultiplayerMaxPlayers"] = 4;

            // Set this to True if your game supports local co-op play. This field is required.
            gamingOptions["isLocalCooperative"] = true;

            // If local co-op is supported, you must provide the minimum and maximum players
            // supported. Valid values are between 2 and 1000 inclusive.			
            gamingOptions["localCooperativeMinPlayers"] = 2;
            gamingOptions["localCooperativeMaxPlayers"] = 4;

            // Set this to True if your game supports online multiplayer. This field is required.
            gamingOptions["isOnlineMultiplayer"] = true;

            // If online multiplayer is supported, you must provide the minimum and maximum players
            // supported. Valid values are between 2 and 1000 inclusive.
            gamingOptions["onlineMultiplayerMinPlayers"] = 2;
            gamingOptions["onlineMultiplayerMaxPlayers"] = 4;

            // Set this to true if your game supports online co-op play. This field is required. 
            gamingOptions["isOnlineCooperative"] = true;

            // If online co-op is supported, you must provide the minimum and maximum players
            // supported. Valid values are between 2 and 1000 inclusive.
            gamingOptions["onlineCooperativeMinPlayers"] = 2;
            gamingOptions["onlineCooperativeMaxPlayers"] = 4;

            // If your game supports broadcasting a stream to other players, set this field to True.
            // This field is required.
            gamingOptions["isBroadcastingPrivilegeGranted"] = true;

            // If your game supports cross-device play (e.g. a player can play on an Xbox One with
            // their friend who's playing on a PC), set this field to True. This field is required.
            gamingOptions["isCrossPlayEnabled"] = true;

            // If your game supports Kinect usage, set this field to "Enabled", otherwise, set it to
            // "Disabled". This field is required.
            gamingOptions["kinectDataForExternal"] = "Disabled";

            // Free text about any other peripherals that your game supports. This field is optional.
            gamingOptions["otherPeripherals"] = "Supports the usage of all fighting joysticks.";
            return gamingOptions;
        }
    }
}

Mendapatkan token akses Azure AD

Kelas DevCenterAccessTokenClient menentukan metode pembantu yang menggunakan nilai , , clientId dan clientSecret Anda tenantIduntuk membuat token akses Azure AD untuk digunakan dengan API pengiriman Microsoft Store.

using System.Net.Http;
using System.Text;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

namespace DevCenterApiSample
{
    /// <summary>
    /// A client for getting access tokens to the Dev Center API.
    /// </summary>
    public class DevCenterAccessTokenClient
    {
        private string _tenantId;
        private string _clientId;
        private string _clientSecret;

        /// <summary>
        /// Creates a new instance of the <see cref="DevCenterAccessTokenClient"/> class.
        /// </summary>
        /// <param name="tenantId">The AAD tenant ID.</param>
        /// <param name="clientId">The AAD client ID.</param>
        /// <param name="clientSecret">The AAD client secret.</param>
        public DevCenterAccessTokenClient(string tenantId, string clientId, string clientSecret)
        {
            _tenantId = tenantId;
            _clientId = clientId;
            _clientSecret = clientSecret;
        }

        /// <summary>
        /// Generates an access token to the specified resource URI.
        /// </summary>
        /// <param name="resource">The resource URI.</param>
        /// <returns>An access token for authentication.</returns>
        public string GetAccessToken(string resource)
        {
            // Generate access token. Access token is valid for 1 hour. Regenerate access token when needed
            HttpRequestMessage tokenRequest = new HttpRequestMessage(HttpMethod.Post, $"https://login.microsoftonline.com/{_tenantId}/oauth2/token");
            string tokenRequestBody = $"grant_type=client_credentials&client_id={_clientId}&client_secret={_clientSecret}&resource={resource}";
            tokenRequest.Content = new StringContent(tokenRequestBody, Encoding.UTF8, "application/x-www-form-urlencoded");

            HttpClient client = new HttpClient();
            HttpResponseMessage response = client.SendAsync(tokenRequest).GetAwaiter().GetResult();
            string responseBody = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
            JObject responseJson = (JObject)JsonConvert.DeserializeObject(responseBody);

            tokenRequest.Dispose();
            client.Dispose();
            response.Dispose();

            return responseJson["access_token"].Value<string>() ?? string.Empty;
        }
    }
}

Metode pembantu untuk memanggil API pengiriman dan mengunggah file pengiriman

Kelas ini DevCenterClient mendefinisikan metode pembantu yang memanggil berbagai metode di API pengiriman Microsoft Store dan mengunggah file ZIP yang berisi paket, mencantumkan gambar, dan file trailer untuk pengiriman aplikasi.

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Web;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System.IO;

namespace DevCenterApiSample
{
    /// <summary>
    /// A client for accessing the Dev Center APIs.
    /// </summary>
    public class DevCenterClient
    {
        private string _accessToken;
        private Uri _baseUri;

        /// <summary>
        /// Creates a new instance of the <see cref="DevCenterClient"/> class.
        /// </summary>
        /// <param name="accessToken">The access token to authenticate to the service with.</param>
        public DevCenterClient(string accessToken)
        {
            _baseUri = new Uri("https://manage.devcenter.microsoft.com");
            _accessToken = accessToken;
        }

        /// <summary>
        /// Retrieves the JSON object representing the application from Dev Center.
        /// </summary>
        /// <param name="applicationId">The application ID.</param>
        /// <returns>A JObject that may be navigated.</returns>
        /// <remarks>
        /// The application ID is taken from your app dashboard page's URI in Dev Center,
        /// e.g. https://developer.microsoft.com/en-us/dashboard/apps/{application_id}/
        /// </remarks>
        public JObject GetApplication(string applicationId) 
            => Invoke(HttpMethod.Get, $"/v1.0/my/applications/{applicationId}");

        /// <summary>
        /// Cancels an in-progress submission for the app.
        /// </summary>
        /// <param name="applicationId">The application ID.</param>
        /// <param name="submissionId">The submission ID.</param>
        /// <returns></returns>
        public void CancelInProgressSubmission(string applicationId, string submissionId)
            => Invoke(HttpMethod.Delete, $"/v1.0/my/applications/{applicationId}/submissions/{submissionId}");

        /// <summary>
        /// Creates a new in-progress submission for the application.
        /// </summary>
        /// <param name="applicationId">The application ID.</param>
        /// <returns>A JObject that may navigated.</returns>
        public JObject CreateSubmission(string applicationId)
            => Invoke(HttpMethod.Post, $"/v1.0/my/applications/{applicationId}/submissions");

        /// <summary>
        /// Updates the submission with the new data provided.
        /// </summary>
        /// <param name="applicationId">The application ID.</param>
        /// <param name="submissionId">The submission ID.</param>
        /// <param name="submission">The submission body.</param>
        /// <returns>The updated submission JObject.</returns>
        public JObject UpdateSubmission(string applicationId, string submissionId, JObject submission)
            => Invoke(HttpMethod.Put, $"/v1.0/my/applications/{applicationId}/submissions/{submissionId}", submission);

        /// <summary>
        /// Gets the submission from Dev Center.
        /// </summary>
        /// <param name="applicationId">The application ID.</param>
        /// <param name="submissionId">The submission ID.</param>
        /// <returns>The submission object from Dev Center.</returns>
        public JObject GetSubmission(string applicationId, string submissionId)
            => Invoke(HttpMethod.Get, $"/v1.0/my/applications/{applicationId}/submissions/{submissionId}");

        /// <summary>
        /// Commits the submission to Dev Center.
        /// </summary>
        /// <param name="applicationId">The application ID.</param>
        /// <param name="submissionId">The submission ID.</param>
        /// <remarks>
        /// Once a submission is committed, Dev Center will begin processing and certifying it;
        /// it can no longer be changed after this point.
        /// </remarks>
        public void CommitSubmission(string applicationId, string submissionId)
            => Invoke(HttpMethod.Post, $"/v1.0/my/applications/{applicationId}/submissions/{submissionId}/commit");

        /// <summary>
        /// Returns the current submission commit status.
        /// </summary>
        /// <param name="applicationId">The application ID.</param>
        /// <param name="submissionId">The submission ID.</param>
        /// <returns>The submission status.</returns>
        public string GetSubmissionStatus(string applicationId, string submissionId)
        {
            JObject response = GetSubmission(applicationId, submissionId);
            string status = response.Value<string>("status") ?? "Unknown";
            return status;
        }

        /// <summary>
        /// Uploads the ZIP file containing assets for the submission to the submission in Dev Center.
        /// </summary>
        /// <param name="applicationId">The application ID.</param>
        /// <param name="submissionId">The submission ID.</param>
        /// <param name="zipFilePath">The path to the ZIP file.</param>
        public void UploadZipFileForSubmission(string applicationId, string submissionId, string zipFilePath)
        {
            JObject submission = GetSubmission(applicationId, submissionId);
            string fileUploadUrl = submission["fileUploadUri"].Value<string>();

            HttpRequestMessage uploadRequest = new HttpRequestMessage(HttpMethod.Put, fileUploadUrl.Replace("+", "%2B")); // Encode '+', otherwise it will be decoded as ' ' 
            uploadRequest.Content = new StreamContent(File.OpenRead(zipFilePath));
            uploadRequest.Headers.Add("x-ms-blob-type", "BlockBlob");

            HttpClient httpClient = new HttpClient();
            HttpResponseMessage uploadResponse = httpClient.SendAsync(uploadRequest).GetAwaiter().GetResult();
            uploadResponse.EnsureSuccessStatusCode();

            uploadRequest.Dispose();
            uploadResponse.Dispose();
            httpClient.Dispose();
        }

        private JObject Invoke(HttpMethod method, string path, JObject body = null)
        {
            HttpRequestMessage request = new HttpRequestMessage(method, new Uri(_baseUri, path));
            request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", _accessToken);
            request.Headers.UserAgent.ParseAdd("C-Sharp");
            if (body != null)
            {
                request.Content = new StringContent(body.ToString(), Encoding.UTF8, "application/json");
            }

            HttpClient client = new HttpClient();
            HttpResponseMessage response = client.SendAsync(request).GetAwaiter().GetResult();
            string responseContent = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();

            if (!response.IsSuccessStatusCode)
            {
                string message = string.IsNullOrEmpty(responseContent) ? response.ReasonPhrase : responseContent;
                throw new HttpException((int)response.StatusCode, message);
            }

            if (string.IsNullOrEmpty(responseContent))
            {
                return null;
            }

            client.Dispose();
            request.Dispose();
            response.Dispose();

            JObject responseObject = (JObject)JsonConvert.DeserializeObject(responseContent);
            return responseObject;
        }
    }
}